diff --git a/journey/plans/260316_임베딩_1차_로빙_Gemini2_전환_계획.md b/journey/plans/260316_임베딩_1차_로빙_Gemini2_전환_계획.md index 329bd34..9efb921 100644 --- 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개 전부 충족 후 선언. ## 관련 문서 diff --git a/journey/research/rag/260316_임베딩_1차_로빙_현황_SSOT_리서치.md b/journey/research/rag/260316_임베딩_1차_로빙_현황_SSOT_리서치.md index 19c0671..78b4f84 100644 --- 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) diff --git a/journey/troubleshooting/260316_임베딩_1차_로빙_Gemini2_전환_문제오픈.md b/journey/troubleshooting/260316_임베딩_1차_로빙_Gemini2_전환_문제오픈.md index 589b272..d2c3b6e 100644 --- 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차 닫힘 범위에 포함 +- **배포/검증**: 실제 배포, 구조화 로그, 대표 질문셋 검증까지 확보해야 닫힘 ## 이 문서가 여는 리서치