---
status: closed
closed_date: 2026-03-21
closed_reason: 260320 다형식문서 RAG 계획으로 흡수 또는 구현 완료
tags: [plans, embedding, gemini, rag, robeing, 1차]
---
status: closed
closed_date: 2026-03-21
closed_reason: 260320 다형식문서 RAG 계획으로 흡수 또는 구현 완료

# 임베딩 1차: 로빙 Gemini 2 전환 계획

**작성일**: 2026-03-16

## 상위 원칙

- [0_VALUE 임베딩 정책](../../../../0_VALUE/20_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)

## 상태

- completed

## 결정 확정

- **대상 레포**: `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)
- 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·이미지 임베딩 경로
- Company X 문서 컬렉션과 `rb8001` 메모리 컬렉션의 768d 재정비
- MRL 768d, ChromaDB/pgvector 스키마 호환
- **청킹**: 1차는 기존 Micro 유지. 2단계에서 Macro(2,000~4,000) 검토. [리서치 §8 청킹 단계](../research/rag/260316_임베딩_1차_로빙_현황_SSOT_리서치.md) 참조.

### 제외

- 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](../../../../0_VALUE/20_Governance/embedding-policy.md)

## 적용 순서

### 1. 품질·비용 테스트

- **대상**: `robeing/tests/test_gemini_embedding_2.py` 확장
- **작업**:
  - 텍스트 768d 검증 (output_dimensionality=768)
  - PDF·이미지 멀티모달 샘플 1건 each
  - 1M 토큰 비용 $0.25 이하 확인
  - 대표 질문셋 기준 검색 품질 유지 또는 개선
- **완료 기준**: 테스트 통과, 비용 기준 충족, 품질 검증 기록 생성

### 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면 스키마 변경 없음)
  - Company X 문서 컬렉션과 `rb8001` 메모리 컬렉션을 1차 우선 재정비
  - 청킹: 기존 Micro(300~500 단어) 유지, 코드 변경 없음
- **완료 기준**: 1차 대상 범위에서 ChromaDB·pgvector 768d 통일, 메모리 드리프트 로그 제거 확인

### 4. 적용 및 검증

- **대상**: Company X RAG 또는 NAS RAG 1개 경로 우선
- **작업**:
  - skill-rag-file, rb8001이 기존 `EMBEDDING_SERVICE_URL`/`SKILL_EMBEDDING_URL`로 새 skill-embedding 호출 (URL 변경 없음)
  - Company X 문서 검색과 `rb8001` 메모리 저장/검색을 대표 질문셋으로 수동 검증
  - fallback 발생 시 구조화 로그에 원인과 요청 단위를 기록
  - DOCS `skills/companyx-rag/SKILL.md`, `330_*.md` 필요 시 갱신
- **완료 기준**: Company X 경로와 `rb8001` 메모리 경로가 모두 새 경로로 동작 확인, fallback 제거 확인

### 5. ivada-infra 배포 (서버 관리자)

- **대상**: ivada-infra skill-embedding 배포, 23/24 서버
- **작업**: `.env.deploy` 갱신, skill-embedding 이미지 재빌드·재배포, 관련 서비스 순차 반영
- **실행**: 서버 관리자만 수행
- **완료 기준**: 운영 배포 후 구조화 로그에서 실제 Gemini 2 경로 사용 확인

### 6. worklog 작성 후 닫힘 선언

- worklog에 1~5 완료 기록
- 테스트 결과 문서 또는 섹션에 자동 테스트/질문셋 결과 링크
- 배포/운영 검증 기록 문서 또는 로그 경로 링크
- [문제 오픈](../troubleshooting/260316_임베딩_1차_로빙_Gemini2_전환_문제오픈.md) 닫힘 조건 8개 충족 선언

## 롤백 절차

- skill-embedding: 이전 ONNX ko-sroberta 이미지/코드로 복귀
- workspace-config: `EMBEDDING_MODEL` 제거 또는 이전값 복원
- ChromaDB: migrate 전 백업 있으면 복원. 없으면 768d 신규 컬렉션만 삭제
- 단, 롤백 중 fallback 경로를 사용했다면 해당 로그를 근거 문서에 남김

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

[문제 오픈 닫힘 조건 8개](../troubleshooting/260316_임베딩_1차_로빙_Gemini2_전환_문제오픈.md#닫힘-조건)와 동일:

1. skill-embedding이 Gemini 2, 768d로 동작한다.
2. rb8001·skill-rag-file이 기존 /embed URL로 새 모델을 참조한다.
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에서 주 선언한다.
- 테스트 결과와 배포/운영 검증 근거 링크를 함께 남긴다.
- 본 문서 상태를 `completed`로 갱신하고 worklog 링크를 추가한다.
- [문제 오픈](../troubleshooting/260316_임베딩_1차_로빙_Gemini2_전환_문제오픈.md) 닫힘 조건 8개 전부 충족 후 선언.

## 관련 문서

- [임베딩 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)
- [임베딩 1차 로빙 Gemini 2 전환 배포 및 검증 완료](../worklog/260316_임베딩_1차_로빙_Gemini2_전환_배포및검증완료.md)