Refine Gemini embedding phase-one closure docs

2026-03-16 22:49:27 +09:00 · 2026-03-16 22:49:27 +09:00 · 0be1fb8eba
commit 0be1fb8eba
parent 12a0842cc5
3 changed files with 93 additions and 22 deletions
--- a/journey/plans/260316_임베딩_1차_로빙_Gemini2_전환_계획.md
+++ b/journey/plans/260316_임베딩_1차_로빙_Gemini2_전환_계획.md
@ -17,6 +17,20 @@ tags: [plans, embedding, gemini, rag, robeing, 1차]

 - planned

+## 결정 확정
+
+- **대상 레포**: `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)
@ -36,12 +50,12 @@ tags: [plans, embedding, gemini, rag, robeing, 1차]
 - **경로 결정**: skill-embedding 교체 (ONNX→Gemini 2). [리서치 §7 경로 설계 결정](../research/rag/260316_임베딩_1차_로빙_현황_SSOT_리서치.md) 참조.
 - 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 청킹 단계](../research/rag/260316_임베딩_1차_로빙_현황_SSOT_리서치.md) 참조.

 ### 제외

- rb8001 메모리 768/384 차원 드리프트 (별도 이슈)
 - StarsAndI, TheGooseCouncil (2차 플랜)

 ## env SSOT
@ -58,8 +72,8 @@ tags: [plans, embedding, gemini, rag, robeing, 1차]
  - 텍스트 768d 검증 (output_dimensionality=768)
  - PDF·이미지 멀티모달 샘플 1건 each
  - 1M 토큰 비용 $0.25 이하 확인
-  - Recall 기존 대비 유지 또는 개선 (선택: ko-sroberta 대비 샘플 비교)
- **완료 기준**: 테스트 통과, 비용·Recall 기준 충족
+  - 대표 질문셋 기준 검색 품질 유지 또는 개선
+- **완료 기준**: 테스트 통과, 비용 기준 충족, 품질 검증 기록 생성

 ### 2. skill-embedding 전환

@ -77,50 +91,60 @@ tags: [plans, embedding, gemini, rag, robeing, 1차]
 - **작업**:
  - output_dimensionality=768로 ChromaDB 컬렉션 생성/마이그레이션
  - intent_prototypes pgvector 768d 확인 (이미 768d면 스키마 변경 없음)
+  - Company X 문서 컬렉션과 `rb8001` 메모리 컬렉션을 1차 우선 재정비
  - 청킹: 기존 Micro(300~500 단어) 유지, 코드 변경 없음
- **완료 기준**: ChromaDB·pgvector 768d 통일, migrate 스크립트 실행 가능
+- **완료 기준**: 1차 대상 범위에서 ChromaDB·pgvector 768d 통일, 메모리 드리프트 로그 제거 확인

 ### 4. 적용 및 검증

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

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

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

 ### 6. worklog 작성 후 닫힘 선언

- worklog에 1~5 완료 기록, [문제 오픈](../troubleshooting/260316_임베딩_1차_로빙_Gemini2_전환_문제오픈.md) 닫힘 조건 6개 충족 선언
+- worklog에 1~5 완료 기록
+- 테스트 결과 문서 또는 섹션에 자동 테스트/질문셋 결과 링크
+- 배포/운영 검증 기록 문서 또는 로그 경로 링크
+- [문제 오픈](../troubleshooting/260316_임베딩_1차_로빙_Gemini2_전환_문제오픈.md) 닫힘 조건 8개 충족 선언

 ## 롤백 절차

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

 ## 검증 기준 (닫힘 조건)

-[문제 오픈 닫힘 조건 6개](../troubleshooting/260316_임베딩_1차_로빙_Gemini2_전환_문제오픈.md#닫힘-조건)와 동일:
+[문제 오픈 닫힘 조건 8개](../troubleshooting/260316_임베딩_1차_로빙_Gemini2_전환_문제오픈.md#닫힘-조건)와 동일:

 1. skill-embedding이 Gemini 2, 768d로 동작한다.
 2. rb8001·skill-rag-file이 기존 /embed URL로 새 모델을 참조한다.
-3. ChromaDB·pgvector 스키마가 768d로 통일된다.
-4. Company X RAG, NAS RAG가 새 경로로 동작한다.
-5. PDF·이미지 직접 임베딩 Recall 유지 또는 개선, 1M 토큰 비용 $0.25 이하.
-6. worklog에서 닫힘 선언한다.
+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에서만 선언한다.
+- worklog에서 주 선언한다.
+- 테스트 결과와 배포/운영 검증 근거 링크를 함께 남긴다.
 - 본 문서 상태를 `completed`로 갱신하고 worklog 링크를 추가한다.
- [문제 오픈](../troubleshooting/260316_임베딩_1차_로빙_Gemini2_전환_문제오픈.md) 닫힘 조건 6개 전부 충족 후 선언.
+- [문제 오픈](../troubleshooting/260316_임베딩_1차_로빙_Gemini2_전환_문제오픈.md) 닫힘 조건 8개 전부 충족 후 선언.

 ## 관련 문서

--- a/journey/research/rag/260316_임베딩_1차_로빙_현황_SSOT_리서치.md
+++ b/journey/research/rag/260316_임베딩_1차_로빙_현황_SSOT_리서치.md
@ -65,13 +65,17 @@ tags: [research, embedding, ssot, robeing, 1차]
 - skill-rag-file은 EMBEDDING_SERVICE_URL로 skill-embedding 호출
 - 기존 데이터 적음 → 전수 교체 기술 부채 낮음
 - 0_VALUE 임베딩 정책: Gemini 2, 768d, 멀티모달
+- `rb8001` 메모리 차원 드리프트가 별도 문서로 열려 있으나, 1차 닫힘 문맥에서는 제외하지 않기로 결정됨
+- 1차 닫힘 근거는 단일 worklog가 아니라 테스트·배포·운영 로그까지 분리 증거로 남겨야 함

 ---

 ## 6. 해석(Interpretation)

 - skill-embedding을 Gemini 2로 전환하면 skill-rag-file·rb8001은 URL만 유지하고 모델은 자동 반영
- skill-rag-file 내부 직접 Gemini API 호출도 가능. 경로 설계 선택 필요
+- skill-rag-file 내부 직접 Gemini API 호출도 가능. 다만 1차는 단일 게이트웨이 유지가 SSOT에 더 맞음
+- 1차를 정말 닫으려면 `RAG만 Gemini 2`가 아니라 `rb8001` 메모리, 기존 데이터, 새 자료 유입 규칙까지 함께 닫아야 함
+- fallback은 배포 안전장치로만 허용할 수 있고, 최종 닫힘 상태의 일부로 남기면 안 됨

 ---

@ -90,14 +94,37 @@ tags: [research, embedding, ssot, robeing, 1차]

 ---

-## 9. ivada-infra 연계
+## 9. 이번 리서치에서 고정된 결정
+
+- 1차 범위는 `skill-embedding`, `skill-rag-file`, `rb8001`, `DOCS`입니다.
+- 공식 임베딩 경로는 `skill-embedding` 단일 게이트웨이입니다.
+- 모델/차원은 `Gemini Embedding 2`, `768d`입니다.
+- 텍스트, PDF, 이미지가 모두 1차 닫힘 범위입니다.
+- `rb8001` 메모리 드리프트는 별도 제외가 아니라 1차 종료 범위에 포함됩니다.
+- 1차 대상 범위에서는 `384/768` 혼재를 허용하지 않습니다.
+- 새 자료 유입은 모두 `Gemini 2 768d`를 필수로 따르며, 다른 경로는 실패 처리와 로그 기록 대상입니다.
+- 실제 운영 배포, 자동 테스트, 질문셋 검증, 운영 로그가 모두 닫힘 근거로 필요합니다.
+- fallback은 배포 도중 임시 허용 가능하지만, 최종 닫힘 상태에는 포함되지 않습니다.
+
+---
+
+## 10. 남은 미확정
+
+- skill-embedding 내부에서 PDF·이미지 입력을 `/embed` 단일 계약으로 어떻게 직렬화할지는 구현 상세가 아직 미확정입니다.
+- Company X 문서 컬렉션과 `rb8001` 메모리 컬렉션을 어떤 배치 단위와 순서로 재임베딩할지는 아직 미확정입니다.
+- 대표 질문셋을 어떤 문서군으로 고정할지, 검색 품질 유지/개선 기준을 어떤 판정표로 남길지는 아직 미확정입니다.
+- 구조화 로그 저장 위치와 필드명을 어떤 서비스에서 동일 포맷으로 맞출지는 아직 미확정입니다.
+
+---
+
+## 11. ivada-infra 연계

 - skill-embedding은 ivada-infra에서 23/24 서버 배포. `.env.deploy`, docker-compose 경로 존재.
 - 1차 전환 시: skill-embedding 레포 Gemini 2 전환 → ivada-infra skill-embedding 배포 설정 갱신 → 23/24 서버 재배포. 서버 관리자 실행.

 ---

-## 10. 관련 문서
+## 12. 관련 문서

 - [임베딩 1차 로빙 Gemini 2 전환 문제 오픈](../../troubleshooting/260316_임베딩_1차_로빙_Gemini2_전환_문제오픈.md)
 - [임베딩 1차 로빙 Gemini 2 전환 계획](../../plans/260316_임베딩_1차_로빙_Gemini2_전환_계획.md)
--- a/journey/troubleshooting/260316_임베딩_1차_로빙_Gemini2_전환_문제오픈.md
+++ b/journey/troubleshooting/260316_임베딩_1차_로빙_Gemini2_전환_문제오픈.md
@ -39,6 +39,20 @@ tags: [troubleshooting, embedding, gemini, rag, robeing, 1차]
 - rb8001 메모리: ChromaDB 768/384 차원 드리프트
 - 기존 데이터: 적음 → 전수 교체 시 기술 부채 거의 없음

+## 1차 결정 고정
+
+- **대상 레포**: `skill-embedding`, `skill-rag-file`, `rb8001`, `DOCS`
+- **공식 경로**: 1차 대상 서비스는 모두 `skill-embedding`만 공식 임베딩 게이트웨이로 사용합니다.
+- **모델/차원**: `Gemini Embedding 2`, `768d`
+- **입력 범위**: 텍스트, PDF, 이미지까지 1차 닫힘 범위에 포함합니다.
+- **메모리 범위**: `rb8001` 메모리 차원 드리프트도 1차에서 함께 닫습니다.
+- **혼재 정책**: 1차 대상 범위 안에서는 `384/768` 혼재를 닫힘 상태로 인정하지 않습니다.
+- **새 자료 정책**: 앞으로 들어오는 새 정보/자료도 모두 같은 경로와 차원을 따라야 합니다.
+- **배포 기준**: 문서·코드·로컬 검증만으로는 닫지 않고, 실제 배포와 운영 검증까지 완료돼야 닫습니다.
+- **검증 강도**: 자동 테스트 + 대표 질문셋 수동 검증 + 운영 구조화 로그를 모두 닫힘 근거로 요구합니다.
+- **fallback 정책**: 배포 중 일시적 구형 임베딩 fallback은 허용할 수 있으나, fallback 발생은 구조화 로그로 남겨야 하며 최종 닫힘 시점에는 제거돼야 합니다.
+- **재임베딩 시작점**: Company X 문서 컬렉션과 `rb8001` 메모리 컬렉션을 우선 정리하고, 이후 1차 대상 레포의 기존 데이터로 확장합니다.
+
 ## 기대 상태 (1차 닫힘 기준)

 | 항목 | 내용 |
@ -50,6 +64,8 @@ tags: [troubleshooting, embedding, gemini, rag, robeing, 1차]
 | env | workspace-config SSOT, 서비스별 오버라이드 금지 |
 | 멀티모달 | PDF·이미지 직접 임베딩 |
 | 청킹 | 1차 Micro 유지, 2단계 Macro 검토 |
+| 운영 데이터 | 1차 대상 범위에서 신규/기존 데이터 모두 768d 단일 경로로 수렴 |
+| 메모리 | `rb8001` 메모리 컬렉션까지 768d로 정리되어 차원 드리프트 로그가 사라짐 |

 ## 영향 범위 (1차)

@ -66,10 +82,12 @@ tags: [troubleshooting, embedding, gemini, rag, robeing, 1차]

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

 ## 재현 조건

@ -88,6 +106,8 @@ tags: [troubleshooting, embedding, gemini, rag, robeing, 1차]

 - **경로**: skill-embedding 교체 (ONNX→Gemini 2). [리서치 §7](../research/rag/260316_임베딩_1차_로빙_현황_SSOT_리서치.md)
 - **청킹**: 1차는 기존 Micro 유지. 2단계에서 Macro 검토. [리서치 §8](../research/rag/260316_임베딩_1차_로빙_현황_SSOT_리서치.md)
+- **메모리**: `rb8001` 메모리 차원 드리프트도 1차 닫힘 범위에 포함
+- **배포/검증**: 실제 배포, 구조화 로그, 대표 질문셋 검증까지 확보해야 닫힘

 ## 이 문서가 여는 리서치