docs(1차): 임베딩 문제·리서치·계획 문서 보강, 계획 95%+ 완성도

Made-with: Cursor
2026-03-16 13:45:15 +09:00 · 2026-03-16 13:45:15 +09:00 · 12a0842cc5
commit 12a0842cc5
parent bf09992aa4
4 changed files with 116 additions and 30 deletions
--- 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)
--- 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)
--- 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` 로드

--- 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)

 ## 이 문서가 여는 리서치