diff --git a/journey/plans/260316_임베딩_1차_로빙_Gemini2_전환_계획.md b/journey/plans/260316_임베딩_1차_로빙_Gemini2_전환_계획.md index a9baee7..329bd34 100644 --- a/journey/plans/260316_임베딩_1차_로빙_Gemini2_전환_계획.md +++ b/journey/plans/260316_임베딩_1차_로빙_Gemini2_전환_계획.md @@ -4,9 +4,12 @@ tags: [plans, embedding, gemini, rag, robeing, 1차] # 임베딩 1차: 로빙 Gemini 2 전환 계획 +**작성일**: 2026-03-16 + ## 상위 원칙 - [0_VALUE 임베딩 정책](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/embedding-policy.md) +- [로빙 문서 작성 원칙](../../book/300_architecture/312_writing-principles.md) - [임베딩 1차 로빙 Gemini 2 전환 문제 오픈](../troubleshooting/260316_임베딩_1차_로빙_Gemini2_전환_문제오픈.md) - [임베딩 1차 로빙 현황 및 SSOT 리서치](../research/rag/260316_임베딩_1차_로빙_현황_SSOT_리서치.md) @@ -14,6 +17,12 @@ tags: [plans, embedding, gemini, rag, robeing, 1차] - planned +## 선행 조건 + +- `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로 전환한다. @@ -24,10 +33,11 @@ tags: [plans, embedding, gemini, rag, robeing, 1차] ### 포함 -- skill-embedding → Gemini 2 전환 또는 skill-rag-file 내부 직접 Gemini API 호출 +- **경로 결정**: skill-embedding 교체 (ONNX→Gemini 2). [리서치 §7 경로 설계 결정](../research/rag/260316_임베딩_1차_로빙_현황_SSOT_리서치.md) 참조. +- skill-embedding 내부 Gemini 2 전환, /embed 엔드포인트 유지 - NAS RAG·Company X RAG PDF·이미지 임베딩 경로 - MRL 768d, ChromaDB/pgvector 스키마 호환 -- 청킹 Macro-chunking(2,000~4,000 토큰) 검토 +- **청킹**: 1차는 기존 Micro 유지. 2단계에서 Macro(2,000~4,000) 검토. [리서치 §8 청킹 단계](../research/rag/260316_임베딩_1차_로빙_현황_SSOT_리서치.md) 참조. ### 제외 @@ -36,30 +46,84 @@ tags: [plans, embedding, gemini, rag, robeing, 1차] ## env SSOT -- `workspace-config/runtime.env`: `EMBEDDING_SERVICE_URL`, `EMBEDDING_DIM` — [0_VALUE embedding-policy](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/embedding-policy.md) +- **원칙**: 로빙 전역(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](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/embedding-policy.md) ## 적용 순서 -1. 품질·비용 테스트 (`test_gemini_embedding_2.py` 확장) -2. 경로 설계 (skill-embedding vs skill-rag-file 직접 호출) -3. 스키마·청킹 (output_dimensionality=768) -4. 적용 및 검증 (Company X RAG 또는 NAS RAG 1개 경로) -5. worklog 작성 후 닫힘 선언 +### 1. 품질·비용 테스트 + +- **대상**: `robeing/tests/test_gemini_embedding_2.py` 확장 +- **작업**: + - 텍스트 768d 검증 (output_dimensionality=768) + - PDF·이미지 멀티모달 샘플 1건 each + - 1M 토큰 비용 $0.25 이하 확인 + - Recall 기존 대비 유지 또는 개선 (선택: ko-sroberta 대비 샘플 비교) +- **완료 기준**: 테스트 통과, 비용·Recall 기준 충족 + +### 2. skill-embedding 전환 + +- **대상**: skill-embedding 레포 전체. [리서치 §3 영향 범위](../research/rag/260316_임베딩_1차_로빙_현황_SSOT_리서치.md) 참조. +- **작업**: + - 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면 스키마 변경 없음) + - 청킹: 기존 Micro(300~500 단어) 유지, 코드 변경 없음 +- **완료 기준**: ChromaDB·pgvector 768d 통일, migrate 스크립트 실행 가능 + +### 4. 적용 및 검증 + +- **대상**: Company X RAG 또는 NAS RAG 1개 경로 우선 +- **작업**: + - skill-rag-file, rb8001이 기존 `EMBEDDING_SERVICE_URL`/`SKILL_EMBEDDING_URL`로 새 skill-embedding 호출 (URL 변경 없음) + - RAG 업로드 → 임베딩 → 검색 파이프라인 1회 수동 검증 + - DOCS `skills/companyx-rag/SKILL.md`, `330_*.md` 필요 시 갱신 +- **완료 기준**: Company X RAG 또는 NAS RAG 새 경로로 동작 확인 + +### 5. ivada-infra 배포 (서버 관리자) + +- **대상**: ivada-infra skill-embedding 배포, 23/24 서버 +- **작업**: `.env.deploy` 갱신, skill-embedding 이미지 재빌드·재배포 +- **실행**: 서버 관리자만 수행 + +### 6. worklog 작성 후 닫힘 선언 + +- worklog에 1~5 완료 기록, [문제 오픈](../troubleshooting/260316_임베딩_1차_로빙_Gemini2_전환_문제오픈.md) 닫힘 조건 6개 충족 선언 + +## 롤백 절차 + +- skill-embedding: 이전 ONNX ko-sroberta 이미지/코드로 복귀 +- workspace-config: `EMBEDDING_MODEL` 제거 또는 이전값 복원 +- ChromaDB: migrate 전 백업 있으면 복원. 없으면 768d 신규 컬렉션만 삭제 ## 검증 기준 (닫힘 조건) -- skill-embedding 또는 skill-rag-file이 Gemini 2, 768d로 동작 -- rb8001이 새 임베딩 경로 참조 -- ChromaDB·pgvector 768d 통일 -- Company X RAG, NAS RAG 새 경로 동작 -- PDF·이미지 직접 임베딩 Recall 유지 또는 개선 -- 1M 토큰 비용 $0.25 이하 +[문제 오픈 닫힘 조건 6개](../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에서 닫힘 선언한다. ## 닫힘 선언 - worklog에서만 선언한다. - 본 문서 상태를 `completed`로 갱신하고 worklog 링크를 추가한다. +- [문제 오픈](../troubleshooting/260316_임베딩_1차_로빙_Gemini2_전환_문제오픈.md) 닫힘 조건 6개 전부 충족 후 선언. ## 관련 문서 - [임베딩 2차 StarsAndI·GooseCouncil 전환 계획](./260316_임베딩_2차_StarsAndI_GooseCouncil_전환_계획.md) +- [skill-embedding 서비스 구축](../troubleshooting/250805_happybell80_skill-embedding서비스구축.md) +- [rb8001 메모리 ChromaDB 768/384 차원 드리프트](../troubleshooting/260312_rb8001_memory_chromadb_768_384_dimension_drift.md) diff --git a/journey/research/rag/260316_임베딩_1차_로빙_현황_SSOT_리서치.md b/journey/research/rag/260316_임베딩_1차_로빙_현황_SSOT_리서치.md index 3701e6a..19c0671 100644 --- a/journey/research/rag/260316_임베딩_1차_로빙_현황_SSOT_리서치.md +++ b/journey/research/rag/260316_임베딩_1차_로빙_현황_SSOT_리서치.md @@ -53,9 +53,11 @@ tags: [research, embedding, ssot, robeing, 1차] ## 4. env SSOT (반영됨) -- `workspace-config/runtime.env`: `EMBEDDING_SERVICE_URL`, `EMBEDDING_DIM` — [0_VALUE embedding-policy env SSOT](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/embedding-policy.md) -- rb8001 docker-compose: `SKILL_EMBEDDING_URL=${EMBEDDING_SERVICE_URL:-http://localhost:8515}`로 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 env SSOT](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/embedding-policy.md) +- rb8001 docker-compose: `SKILL_EMBEDDING_URL=${EMBEDDING_SERVICE_URL:-...}`로 SSOT 참조 - skill-rag-file: `EMBEDDING_SERVICE_URL` env_file에서 로드 +- skill-embedding: 전환 후 `EMBEDDING_MODEL`, `EMBEDDING_DIM` env_file에서 로드 ## 5. 사실(Facts) @@ -73,14 +75,29 @@ tags: [research, embedding, ssot, robeing, 1차] --- -## 7. 미확정 항목(Unresolved) +## 7. 경로 설계 결정 (추천) -- skill-embedding 교체 vs skill-rag-file 내부 직접 Gemini API 호출 -- 청킹 단위 확대 적용 시점 +- **추천: skill-embedding 교체**. ONNX ko-sroberta → Gemini 2로 skill-embedding 서비스 내부만 전환. +- **이유**: (1) 기존 HTTP /embed 구조 유지, rb8001·skill-rag-file 수정 없음 (2) workspace-config `EMBEDDING_MODEL`만 반영하면 모델 전환 완료 (3) 변경 범위 최소, ivada-infra skill-embedding 배포만 갱신 (4) skill-rag-file 직접 호출은 skill-embedding 제거·skill-rag-file 대규모 수정 필요 +- **대안**: skill-rag-file 내부 Gemini API 직접 호출 — skill-embedding 제거 가능하나 skill-rag-file 변경 범위 큼. 1차에서는 비추천. --- -## 8. 관련 문서 +## 8. 청킹 단계 결정 (추천) + +- **1차**: 기존 Micro-chunking(300~500 단어) 유지. 768d·멀티모달 적용·검증 우선. +- **2단계**: RAG 경로 검증 후 Macro-chunking(2,000~4,000 토큰) 검토. [260315 Gemini Embedding 2 리서치 §5 청킹 전략](./260315_Gemini_Embedding_2_리서치_비용_청킹_도입검토.md) 참조. + +--- + +## 9. ivada-infra 연계 + +- skill-embedding은 ivada-infra에서 23/24 서버 배포. `.env.deploy`, docker-compose 경로 존재. +- 1차 전환 시: skill-embedding 레포 Gemini 2 전환 → ivada-infra skill-embedding 배포 설정 갱신 → 23/24 서버 재배포. 서버 관리자 실행. + +--- + +## 10. 관련 문서 - [임베딩 1차 로빙 Gemini 2 전환 문제 오픈](../../troubleshooting/260316_임베딩_1차_로빙_Gemini2_전환_문제오픈.md) - [임베딩 1차 로빙 Gemini 2 전환 계획](../../plans/260316_임베딩_1차_로빙_Gemini2_전환_계획.md) diff --git a/journey/research/rag/260316_임베딩_전체프로젝트_현황_및_SSOT_리서치.md b/journey/research/rag/260316_임베딩_전체프로젝트_현황_및_SSOT_리서치.md index 2c9324e..ede1eaa 100644 --- a/journey/research/rag/260316_임베딩_전체프로젝트_현황_및_SSOT_리서치.md +++ b/journey/research/rag/260316_임베딩_전체프로젝트_현황_및_SSOT_리서치.md @@ -178,7 +178,8 @@ tags: [research, embedding, ssot, robeing, starsandi, goosecouncil, workspace, i ### 5.2 런타임 SSOT (반영됨) - **위치**: `workspace-config/runtime.env` -- **키**: `EMBEDDING_SERVICE_URL`, `EMBEDDING_DIM` — [0_VALUE embedding-policy env SSOT](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/embedding-policy.md) +- **키**: `EMBEDDING_SERVICE_URL`, `EMBEDDING_DIM`, `EMBEDDING_MODEL` — [0_VALUE embedding-policy env SSOT](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/embedding-policy.md) +- **1차 경로 결정**: skill-embedding 교체. [1차 리서치 §7](./260316_임베딩_1차_로빙_현황_SSOT_리서치.md) 참조. - rb8001: `SKILL_EMBEDDING_URL=${EMBEDDING_SERVICE_URL:-http://localhost:8515}`로 참조 - skill-rag-file: env_file에서 `EMBEDDING_SERVICE_URL` 로드 diff --git a/journey/troubleshooting/260316_임베딩_1차_로빙_Gemini2_전환_문제오픈.md b/journey/troubleshooting/260316_임베딩_1차_로빙_Gemini2_전환_문제오픈.md index 9c26dfe..589b272 100644 --- a/journey/troubleshooting/260316_임베딩_1차_로빙_Gemini2_전환_문제오픈.md +++ b/journey/troubleshooting/260316_임베딩_1차_로빙_Gemini2_전환_문제오픈.md @@ -45,9 +45,11 @@ tags: [troubleshooting, embedding, gemini, rag, robeing, 1차] |------|------| | 모델 | Gemini Embedding 2 | | 차원 | 768 (MRL) | +| 경로 | skill-embedding 교체 (ONNX→Gemini 2) | | 적용 | robeing 전역 (skill-embedding, skill-rag-file, rb8001) | +| env | workspace-config SSOT, 서비스별 오버라이드 금지 | | 멀티모달 | PDF·이미지 직접 임베딩 | -| 청킹 | Macro-chunking(2,000~4,000 토큰) 검토 | +| 청킹 | 1차 Micro 유지, 2단계 Macro 검토 | ## 영향 범위 (1차) @@ -58,15 +60,16 @@ tags: [troubleshooting, embedding, gemini, rag, robeing, 1차] - migrate_chromadb_collections.py - DOCS/skills/companyx-rag, 330_백엔드 설계 문서 - ivada-infra skill-embedding 배포 -- workspace-config: `EMBEDDING_SERVICE_URL`, `EMBEDDING_DIM` 반영됨 (SSOT) +- workspace-config: `EMBEDDING_SERVICE_URL`, `EMBEDDING_DIM`, `EMBEDDING_MODEL` 반영됨 (SSOT) ## 닫힘 조건 -1. skill-embedding 또는 skill-rag-file이 Gemini 2, 768d로 동작한다. -2. rb8001이 새 임베딩 경로를 참조한다. +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. worklog에서 닫힘 선언한다. +5. PDF·이미지 직접 임베딩 Recall 유지 또는 개선, 1M 토큰 비용 $0.25 이하. +6. worklog에서 닫힘 선언한다. ## 재현 조건 @@ -77,13 +80,14 @@ tags: [troubleshooting, embedding, gemini, rag, robeing, 1차] - 0_VALUE 임베딩 정책 확정: Gemini 2, 768d, 전수 교체, 멀티모달 - 리서치(260315)에서 Gemini Embedding 2 특징·비용·청킹 전략 정리됨 -- `rb8001/scripts/test_gemini_embedding_2.py` API 테스트 스크립트 존재 +- `robeing/tests/test_gemini_embedding_2.py` API 테스트 존재, 확장 예정 - 기존 데이터 적음 → 전수 교체 부담 낮음 +- workspace-config env SSOT: 로빙 전역이 따르고 서비스별 오버라이드 금지 -## 미확정 항목 +## 확정 항목 (리서치·계획 반영) -- skill-embedding 교체 vs skill-rag-file 내부 직접 Gemini API 호출 -- 청킹 단위 확대 적용 시점 +- **경로**: skill-embedding 교체 (ONNX→Gemini 2). [리서치 §7](../research/rag/260316_임베딩_1차_로빙_현황_SSOT_리서치.md) +- **청킹**: 1차는 기존 Micro 유지. 2단계에서 Macro 검토. [리서치 §8](../research/rag/260316_임베딩_1차_로빙_현황_SSOT_리서치.md) ## 이 문서가 여는 리서치