From 12a0842cc57ca6faadffc875dd15e4ebffceaacc Mon Sep 17 00:00:00 2001
From: happybell80 <goeun2dcc@gmail.com>
Date: Mon, 16 Mar 2026 13:45:15 +0900
Subject: [PATCH] =?UTF-8?q?docs(1=EC=B0=A8):=20=EC=9E=84=EB=B2=A0=EB=94=A9?=
 =?UTF-8?q?=20=EB=AC=B8=EC=A0=9C=C2=B7=EB=A6=AC=EC=84=9C=EC=B9=98=C2=B7?=
 =?UTF-8?q?=EA=B3=84=ED=9A=8D=20=EB=AC=B8=EC=84=9C=20=EB=B3=B4=EA=B0=95,?=
 =?UTF-8?q?=20=EA=B3=84=ED=9A=8D=2095%+=20=EC=99=84=EC=84=B1=EB=8F=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Made-with: Cursor
---
 ...��딩_1차_로빙_Gemini2_전환_계획.md | 92 ++++++++++++++++---
 ...��딩_1차_로빙_현황_SSOT_리서치.md | 29 ++++--
 ...�프로젝트_현황_및_SSOT_리서치.md |  3 +-
 ...1차_로빙_Gemini2_전환_문제오픈.md | 22 +++--
 4 files changed, 116 insertions(+), 30 deletions(-)

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)
 
 ## 이 문서가 여는 리서치