diff --git a/docs/architecture/250730_ChromaDB_임베딩_솔루션_비교분석.md b/docs/architecture/250730_ChromaDB_임베딩_솔루션_비교분석.md new file mode 100644 index 0000000..b01ce28 --- /dev/null +++ b/docs/architecture/250730_ChromaDB_임베딩_솔루션_비교분석.md @@ -0,0 +1,174 @@ +# ChromaDB 임베딩 솔루션 비교분석 + +**날짜**: 2025-07-30 +**작성자**: Claude (51124 서버) +**관련 프로젝트**: rb10508_test, rb8001, rb10408_test + +## 배경 + +### 현재 문제 상황 +- rb10508_test 컨테이너에서 ChromaDB 초기화 실패 +- 오류: `The sentence_transformers python package is not installed` +- 원인: 빌드 시간 단축을 위해 requirements.txt에서 sentence-transformers 제거 (1GB+ 절약) + +### 이전 결정사항 히스토리 +1. **2025-07-09**: 한국어 성능 향상을 위해 sentence-transformers 추가 +2. **2025-07-23**: CI 빌드 시간 단축을 위해 torch, sentence-transformers 제거 +3. **2025-07-28**: 호스트에 패키지 설치 후 모델 파일만 볼륨 마운트 시도 +4. **2025-07-29**: rb8001 배포 시 최적화 확정 + +### 기술적 배경 설명 +- **sentence-transformers**: 텍스트를 벡터로 변환하는 라이브러리 (엔진) +- **모델 파일**: 학습된 가중치 데이터 (/opt/models에 546MB 저장됨) +- 엔진 없이는 모델 파일만으로 작동 불가 (게임 엔진 없이 게임 데이터만 있는 것과 동일) + +## 해결 방안 비교 + +### 1. 베이스 이미지 전략 + +#### 구현 방법 +```dockerfile +# Dockerfile.base +FROM python:3.13-slim +RUN pip install torch sentence-transformers +# 빌드: docker build -f Dockerfile.base -t rb10508_base:latest . + +# Dockerfile (애플리케이션용) +FROM rb10508_base:latest +COPY requirements.txt . +RUN pip install -r requirements.txt +``` + +#### 장단점 +| 항목 | 내용 | +|------|------| +| **장점** | • 첫 빌드 후 torch/sentence-transformers 재설치 불필요
• 여러 서비스가 동일 베이스 이미지 공유 가능
• CI/CD 빌드 시간 30초~1분으로 단축 | +| **단점** | • 베이스 이미지 별도 관리 필요
• 베이스 이미지 업데이트 시 모든 서비스 재빌드
• 첫 베이스 이미지 빌드는 여전히 10분 소요 | + +#### 시간 및 용량 +- 첫 베이스 이미지 빌드: 10분 +- 이후 애플리케이션 빌드: 30초~1분 +- 저장 공간: 베이스 이미지 2GB + 앱 이미지 500MB + +### 2. pip wheel 사전 빌드 방식 + +#### 구현 방법 +```bash +# 호스트에서 한 번만 실행 +mkdir -p /opt/wheels +pip wheel torch sentence-transformers -w /opt/wheels +``` + +```yaml +# docker-compose.yml +volumes: + - /opt/wheels:/wheels:ro +``` + +```dockerfile +# Dockerfile +RUN pip install --find-links /wheels --no-index torch sentence-transformers +``` + +#### 장단점 +| 항목 | 내용 | +|------|------| +| **장점** | • 오프라인 설치 가능 (네트워크 불필요)
• 빌드 시간 3-5분으로 단축
• 여러 컨테이너가 wheel 파일 공유 | +| **단점** | • Python 버전 정확히 일치 필요 (현재 호스트 3.10 vs 컨테이너 3.13)
• wheel 파일 관리 복잡도 증가
• 호스트 디스크 공간 1GB 추가 사용 | + +#### 시간 및 용량 +- wheel 생성: 한 번만 5분 +- 컨테이너 빌드: 3-5분 +- 추가 저장: /opt/wheels에 1GB + +### 3. ChromaDB 기본 임베딩 사용 + +#### 구현 방법 +```python +# app/services/chroma_service.py 수정 +# embedding_function 파라미터 제거 +self.conversations_collection = self.client.get_or_create_collection( + name="conversations", + metadata={"description": "Conversation memories", "robing_id": settings.ROBING_ID} + # embedding_function 제거 - 기본 임베딩 사용 +) +``` + +#### 장단점 +| 항목 | 내용 | +|------|------| +| **장점** | • 추가 패키지 설치 불필요
• 빌드 시간 증가 없음
• 구현 가장 단순 | +| **단점** | • 한국어 성능 크게 저하
• 임베딩 품질 낮음
• 검색 정확도 하락 | + +#### 시간 및 용량 +- 빌드 시간 증가: 0분 +- 추가 용량: 0MB + +### 4. FastEmbed 경량 라이브러리 사용 + +#### 구현 방법 +```python +# requirements.txt +fastembed>=0.1.0 # 50MB, torch 불필요 + +# app/services/chroma_service.py +from chromadb.utils import embedding_functions +embedding_function = embedding_functions.FastEmbedEmbeddingFunction() +``` + +#### 장단점 +| 항목 | 내용 | +|------|------| +| **장점** | • torch 불필요 (ONNX 런타임 사용)
• 설치 크기 50MB로 매우 작음
• 빌드 시간 1분 미만 | +| **단점** | • 모델 선택 제한적
• sentence-transformers보다 기능 적음
• 커뮤니티 지원 적음 | + +#### 시간 및 용량 +- 빌드 시간: 1분 +- 추가 용량: 50MB + +### 5. sentence-transformers 재추가 (원점 회귀) + +#### 구현 방법 +```python +# requirements.txt +sentence-transformers>=2.2.0 +``` + +#### 장단점 +| 항목 | 내용 | +|------|------| +| **장점** | • 검증된 솔루션
• 최고의 한국어 성능
• 풍부한 모델 선택지 | +| **단점** | • 빌드 시간 5-10분
• 이미지 크기 1GB 증가
• CI/CD 부담 | + +## 종합 비교표 + +| 방법 | 첫 빌드 | 이후 빌드 | 추가 용량 | 한국어 성능 | 구현 복잡도 | 유지보수 | +|------|---------|-----------|-----------|-------------|-------------|----------| +| 베이스 이미지 | 10분 | 30초 | 2GB | 우수 | 중간 | 중간 | +| pip wheel | 5분 | 3-5분 | 1GB | 우수 | 높음 | 높음 | +| ChromaDB 기본 | 0분 | 0분 | 0MB | 나쁨 | 낮음 | 낮음 | +| FastEmbed | 1분 | 1분 | 50MB | 보통 | 낮음 | 낮음 | +| 원점 회귀 | 5-10분 | 5-10분 | 1GB | 우수 | 낮음 | 낮음 | + +## 권장사항 + +### 상황별 추천 +1. **빌드 속도 최우선**: ChromaDB 기본 임베딩 +2. **한국어 성능 중요 + CI/CD 최적화**: 베이스 이미지 전략 +3. **균형적 타협안**: FastEmbed +4. **단순함 우선**: sentence-transformers 재추가 + +### 고려사항 +- 현재 /opt/models에 있는 546MB 모델 파일은 sentence-transformers 설치 시 즉시 활용 가능 +- Python 버전 차이 (호스트 3.10 vs 컨테이너 3.13)로 인해 wheel 공유는 제한적 +- 모든 로빙 서비스(rb8001, rb10408, rb10508)에 동일한 솔루션 적용 필요 + +## 결론 + +팀 논의를 통해 다음 사항을 결정해야 합니다: +1. 한국어 임베딩 성능 vs 빌드 시간의 우선순위 +2. CI/CD 파이프라인 복잡도 허용 수준 +3. 장기적 유지보수 관점에서의 선호도 + +현재 프론트엔드 연결은 정상 작동하며, Gemini API를 통한 응답 생성도 가능합니다. +단지 대화 기록이 벡터 DB에 저장되지 않는 상황이므로, 긴급도는 중간 수준입니다. \ No newline at end of file