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

## 상태

- 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로 전환한다.
- 멀티모달(이미지, PDF) 직접 임베딩을 지원한다.
- 1차 완료 시 해당 문제·리서치·플랜을 완전히 닫는다.

## 범위

### 포함

- **경로 결정**: 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 스키마 호환
- **청킹**: 1차는 기존 Micro 유지. 2단계에서 Macro(2,000~4,000) 검토. [리서치 §8 청킹 단계](../research/rag/260316_임베딩_1차_로빙_현황_SSOT_리서치.md) 참조.

### 제외

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

## env 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](https://github.com/happybell80/0_VALUE/blob/main/02_Governance/embedding-policy.md)

## 적용 순서

### 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 신규 컬렉션만 삭제

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

[문제 오픈 닫힘 조건 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)