ivada-infra/DOCS
3
0
Fork 0
Code Issues 1 Pull Requests 5 Actions Packages Projects Releases Wiki Activity
DOCS/journey/plans/260316_임베딩_1차_로빙_Gemini2_전환_계획.md
happybell80 60a892e5ab fix: DOCS 내 0_VALUE 참조를 GitHub URL → 로컬 상대경로로 전환, 02_Governance → 20_Governance 수정 #33 #34 
SSOT는 로컬 0_VALUE/. GitHub URL은 복사본 참조로 SSOT 원칙 위반.
02_Governance는 존재하지 않는 구 경로로 전부 깨진 링크.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-30 14:00:21 +09:00

8.4 KiB
Raw Blame History

status, closed_date, closed_reason, tags
status closed_date closed_reason tags
closed 2026-03-21 260320 다형식문서 RAG 계획으로 흡수 또는 구현 완료
plans
embedding
gemini
rag
robeing
1차

status: closed closed_date: 2026-03-21 closed_reason: 260320 다형식문서 RAG 계획으로 흡수 또는 구현 완료

임베딩 1차: 로빙 Gemini 2 전환 계획

작성일: 2026-03-16

상위 원칙

상태

  • completed

결정 확정

  • 대상 레포: skill-embedding, skill-rag-file, rb8001, DOCS
  • 공식 임베딩 경로: skill-embedding 단일 게이트웨이
  • 모델/차원: Gemini Embedding 2, 768d
  • 입력 범위: 텍스트 + PDF + 이미지
  • 메모리 범위: rb8001 메모리 컬렉션 드리프트도 1차 종료 범위에 포함
  • 혼재 정책: 1차 대상 범위 안에서는 384/768 혼재 금지
  • 새 자료 유입: 앞으로 들어오는 새 정보/자료도 모두 Gemini 2 768d를 필수로 사용
  • 배포 기준: 실제 운영 배포 완료 전에는 닫지 않음
  • 검증 기준: 자동 테스트 + 대표 질문셋 수동 검증 + 운영 구조화 로그
  • fallback 정책: 배포 중 임시 fallback 허용 가능. 단, 구조화 로그 필수, 최종 닫힘 전 제거 필수
  • 근거 문서 원칙: 닫힘 증거는 단일 worklog에 몰지 않고 worklog + 테스트 결과 + 배포/운영 로그 기록으로 분리

선행 조건

  • workspace-config/runtime.env에 EMBEDDING_SERVICE_URL, EMBEDDING_DIM, EMBEDDING_MODEL 반영됨 (SSOT)
  • rb8001·skill-rag-file이 EMBEDDING_SERVICE_URL 또는 SKILL_EMBEDDING_URL로 skill-embedding 참조
  • robeing/tests/test_gemini_embedding_2.py 존재, Gemini API 키 로컬 사용 가능

목표

  • 로빙(skill-embedding, skill-rag-file, rb8001)을 Gemini Embedding 2, 768d로 전환한다.
  • 멀티모달(이미지, PDF) 직접 임베딩을 지원한다.
  • 1차 완료 시 해당 문제·리서치·플랜을 완전히 닫는다.

범위

포함

  • 경로 결정: skill-embedding 교체 (ONNX→Gemini 2). 리서치 §7 경로 설계 결정 참조.
  • skill-embedding 내부 Gemini 2 전환, /embed 엔드포인트 유지
  • NAS RAG·Company X RAG PDF·이미지 임베딩 경로
  • Company X 문서 컬렉션과 rb8001 메모리 컬렉션의 768d 재정비
  • MRL 768d, ChromaDB/pgvector 스키마 호환
  • 청킹: 1차는 기존 Micro 유지. 2단계에서 Macro(2,000~4,000) 검토. 리서치 §8 청킹 단계 참조.

제외

  • StarsAndI, TheGooseCouncil (2차 플랜)

env SSOT

  • 원칙: 로빙 전역(rb8001, skill-embedding, skill-rag-file, skill-news, skill-slack 등 모든 스킬)은 workspace-config를 따르고, 임베딩 관련 값을 서비스별로 오버라이드하지 않는다.
  • workspace-config/runtime.env: EMBEDDING_SERVICE_URL, EMBEDDING_DIM, EMBEDDING_MODEL(gemini-embedding-2-preview) — 0_VALUE embedding-policy

적용 순서

1. 품질·비용 테스트

  • 대상: robeing/tests/test_gemini_embedding_2.py 확장
  • 작업:
    • 텍스트 768d 검증 (output_dimensionality=768)
    • PDF·이미지 멀티모달 샘플 1건 each
    • 1M 토큰 비용 $0.25 이하 확인
    • 대표 질문셋 기준 검색 품질 유지 또는 개선
  • 완료 기준: 테스트 통과, 비용 기준 충족, 품질 검증 기록 생성

2. skill-embedding 전환

  • 대상: skill-embedding 레포 전체. 리서치 §3 영향 범위 참조.
  • 작업:
    • ONNX ko-sroberta → Gemini 2 API 호출로 교체
    • EMBEDDING_MODEL, EMBEDDING_DIM env_file에서 workspace-config 로드
    • /embed 엔드포인트 요청/응답 형식 유지 (기존 클라이언트 호환)
    • docker-compose env_file 경로: workspace-config/runtime.env
  • 완료 기준: 로컬 /embed 호출 시 768d 벡터 반환

3. 스키마·청킹

  • 대상: rb8001 migrate_chromadb_collections.py, ChromaDB 컬렉션, intent_prototypes pgvector
  • 작업:
    • output_dimensionality=768로 ChromaDB 컬렉션 생성/마이그레이션
    • intent_prototypes pgvector 768d 확인 (이미 768d면 스키마 변경 없음)
    • Company X 문서 컬렉션과 rb8001 메모리 컬렉션을 1차 우선 재정비
    • 청킹: 기존 Micro(300~500 단어) 유지, 코드 변경 없음
  • 완료 기준: 1차 대상 범위에서 ChromaDB·pgvector 768d 통일, 메모리 드리프트 로그 제거 확인

4. 적용 및 검증

  • 대상: Company X RAG 또는 NAS RAG 1개 경로 우선
  • 작업:
    • skill-rag-file, rb8001이 기존 EMBEDDING_SERVICE_URL/SKILL_EMBEDDING_URL로 새 skill-embedding 호출 (URL 변경 없음)
    • Company X 문서 검색과 rb8001 메모리 저장/검색을 대표 질문셋으로 수동 검증
    • fallback 발생 시 구조화 로그에 원인과 요청 단위를 기록
    • DOCS skills/companyx-rag/SKILL.md, 330_*.md 필요 시 갱신
  • 완료 기준: Company X 경로와 rb8001 메모리 경로가 모두 새 경로로 동작 확인, fallback 제거 확인

5. ivada-infra 배포 (서버 관리자)

  • 대상: ivada-infra skill-embedding 배포, 23/24 서버
  • 작업: .env.deploy 갱신, skill-embedding 이미지 재빌드·재배포, 관련 서비스 순차 반영
  • 실행: 서버 관리자만 수행
  • 완료 기준: 운영 배포 후 구조화 로그에서 실제 Gemini 2 경로 사용 확인

6. worklog 작성 후 닫힘 선언

  • worklog에 1~5 완료 기록
  • 테스트 결과 문서 또는 섹션에 자동 테스트/질문셋 결과 링크
  • 배포/운영 검증 기록 문서 또는 로그 경로 링크
  • 문제 오픈 닫힘 조건 8개 충족 선언

롤백 절차

  • skill-embedding: 이전 ONNX ko-sroberta 이미지/코드로 복귀
  • workspace-config: EMBEDDING_MODEL 제거 또는 이전값 복원
  • ChromaDB: migrate 전 백업 있으면 복원. 없으면 768d 신규 컬렉션만 삭제
  • 단, 롤백 중 fallback 경로를 사용했다면 해당 로그를 근거 문서에 남김

검증 기준 (닫힘 조건)

문제 오픈 닫힘 조건 8개와 동일:

  1. skill-embedding이 Gemini 2, 768d로 동작한다.
  2. rb8001·skill-rag-file이 기존 /embed URL로 새 모델을 참조한다.
  3. skill-rag-file 컬렉션과 rb8001 메모리 컬렉션에서 384/768 혼재가 제거되고, ChromaDB·pgvector가 768d로 통일된다.
  4. Company X RAG와 rb8001 메모리 저장/검색이 새 경로로 동작한다.
  5. PDF·이미지 직접 임베딩이 동작하고, 검색 품질은 대표 질문셋 기준 기존 대비 유지 또는 개선된다.
  6. 자동 테스트, 수동 질문셋 검증, 운영 구조화 로그가 모두 남는다.
  7. 실제 배포 후 fallback 없이 운영 경로가 Gemini 2 단일 경로로 유지된다.
  8. worklog와 배포/검증 근거 문서에서 닫힘 선언한다.

닫힘 선언

  • worklog에서 주 선언한다.
  • 테스트 결과와 배포/운영 검증 근거 링크를 함께 남긴다.
  • 본 문서 상태를 completed로 갱신하고 worklog 링크를 추가한다.
  • 문제 오픈 닫힘 조건 8개 전부 충족 후 선언.

관련 문서