From edf089b3de610086d6d192d0facfc7dd9d05392f Mon Sep 17 00:00:00 2001
From: happybell80 <happybell80@gmail.com>
Date: Thu, 31 Jul 2025 10:30:55 +0900
Subject: [PATCH] =?UTF-8?q?docs:=20ChromaDB=20=EB=B2=A0=EC=9D=B4=EC=8A=A4?=
 =?UTF-8?q?=20=EC=9D=B4=EB=AF=B8=EC=A7=80=20=EC=A0=84=ED=99=98=20=EB=B0=8F?=
 =?UTF-8?q?=20Python=203.13=20=ED=98=B8=ED=99=98=EC=84=B1=20=ED=8A=B8?=
 =?UTF-8?q?=EB=9F=AC=EB=B8=94=EC=8A=88=ED=8C=85?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- docker-base 저장소 생성 과정
- chroma_vector:1.0 베이스 이미지 구성
- docker-compose → docker compose 전환
- CI/CD 스크립트 수정 내용
---
 ...bell80_ChromaDB베이스이미지전환.md | 181 ++++++++++++++++++
 1 file changed, 181 insertions(+)
 create mode 100644 troubleshooting/250731_happybell80_ChromaDB베이스이미지전환.md

diff --git a/troubleshooting/250731_happybell80_ChromaDB베이스이미지전환.md b/troubleshooting/250731_happybell80_ChromaDB베이스이미지전환.md
new file mode 100644
index 0000000..ec24861
--- /dev/null
+++ b/troubleshooting/250731_happybell80_ChromaDB베이스이미지전환.md
@@ -0,0 +1,181 @@
+# ChromaDB 베이스 이미지 전환 및 Python 3.13 호환성 해결
+
+**날짜**: 2025-07-31  
+**작업자**: happybell80 & Claude  
+**관련 프로젝트**: docker-base, rb8001, rb10508_test, rb10408_test
+
+## 오전 10시 00분
+
+### 문제 상황
+
+**ChromaDB 초기화 실패**:
+- rb10508_test 컨테이너에서 오류 발생
+- `The sentence_transformers python package is not installed`
+- 원인: CI 빌드 시간 단축을 위해 sentence-transformers 제거 (1GB+ 절약)
+
+**배경**:
+- 2025-07-09: 한국어 성능 향상을 위해 sentence-transformers 추가
+- 2025-07-23: 빌드 시간 단축을 위해 torch, sentence-transformers 제거
+- 현재: 프론트엔드-로빙 연결은 정상, 대화 기록만 저장 안됨
+
+## 오전 10시 05분
+
+### 해결 방안 검토
+
+**ChromaDB 임베딩 솔루션 비교분석 문서 확인**:
+1. 베이스 이미지 전략 (선택)
+2. pip wheel 사전 빌드
+3. ChromaDB 기본 임베딩
+4. FastEmbed 경량 라이브러리
+5. sentence-transformers 재추가
+
+**베이스 이미지 전략 선택 이유**:
+- 빌드 시간: 10분 → 30초~1분
+- 한국어 성능 우수
+- 여러 로빙이 공유 가능
+
+## 오전 10시 07분
+
+### docker-base 저장소 생성
+
+**구조**:
+```
+docker-base/
+├── README.md
+├── Dockerfile.chroma_vector
+└── .gitignore
+```
+
+**Dockerfile.chroma_vector 내용**:
+```dockerfile
+FROM python:3.13-slim
+
+# 시스템 패키지 설치
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    curl \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# PyTorch 및 sentence-transformers 설치
+RUN pip install --no-cache-dir \
+    torch==2.5.1 \
+    sentence-transformers==3.3.1 \
+    transformers==4.48.0
+
+WORKDIR /code
+
+LABEL maintainer="ivada_Ro-being" \
+      description="Base image for ChromaDB with Korean embedding support" \
+      version="1.0"
+```
+
+**Gitea 저장소 생성**:
+```bash
+git init
+git remote add origin https://git.ro-being.com/ivada_Ro-being/docker-base.git
+git push -u origin main
+```
+
+## 오전 10시 10분
+
+### 51124 서버에서 베이스 이미지 빌드
+
+**서버 메시지**:
+> 베이스 이미지 빌드가 완료되었습니다. 이제 로컬에서 각 로빙 서비스의 Dockerfile을 수정하여 FROM python:3.13-slim을 FROM chroma_vector:1.0으로 변경하신 후 Gitea에 푸시하시면 자동 배포됩니다.
+
+## 오전 10시 15분
+
+### 로빙 서비스 Dockerfile 수정
+
+**rb10508_test/Dockerfile**:
+```dockerfile
+# 변경 전
+FROM python:3.13-slim
+
+# 변경 후
+FROM chroma_vector:1.0
+```
+
+**rb8001/Dockerfile**:
+- 동일하게 수정
+
+**rb10408_test**:
+- 희재님이 별도로 수정 예정
+
+## 오전 10시 20분
+
+### Python 3.13 호환성 문제 발견
+
+**CI/CD 배포 중 오류**:
+```
+ModuleNotFoundError: No module named 'pipes'
+```
+
+**원인**:
+- Python 3.13에서 pipes 모듈 제거
+- docker-compose가 Python 3.13과 호환되지 않음
+
+## 오전 10시 25분
+
+### CI/CD 스크립트 수정
+
+**해결 방법**:
+- `docker-compose` → `docker compose` 변경
+- Docker 20.10+ 내장 compose 명령 사용
+
+**수정 파일**:
+- rb10508_test/.gitea/workflows/cicd.yml
+- rb8001/.gitea/workflows/cicd.yml
+
+**변경 내용**:
+```bash
+# 변경 전
+docker-compose down
+docker-compose up -d --build
+docker-compose ps
+docker-compose logs
+
+# 변경 후
+docker compose down
+docker compose up -d --build
+docker compose ps
+docker compose logs
+```
+
+## 결과
+
+### 완료된 작업
+1. ✅ docker-base 저장소 생성 (chroma_vector:1.0)
+2. ✅ 51124 서버에 베이스 이미지 빌드
+3. ✅ rb10508_test, rb8001 Dockerfile 수정
+4. ✅ Python 3.13 호환성을 위한 CI/CD 수정
+5. ✅ 모든 변경사항 Gitea에 push
+
+### 개선 효과
+- ChromaDB 벡터 임베딩 정상 작동
+- 빌드 시간: 10분 → 1분
+- 한국어 임베딩 성능 유지
+- Python 3.13 호환성 확보
+
+## 교훈
+
+1. **베이스 이미지 전략의 효과**
+   - 공통 의존성을 베이스 이미지로 분리
+   - CI/CD 빌드 시간 대폭 단축
+   - 여러 서비스가 일관된 환경 공유
+
+2. **Python 버전 업그레이드 시 주의**
+   - deprecated 모듈 사전 확인 필수
+   - docker-compose 같은 도구의 호환성 검토
+   - Docker 내장 명령 우선 사용 권장
+
+3. **단계적 문제 해결**
+   - ChromaDB 문제 → 베이스 이미지로 해결
+   - Python 3.13 문제 → docker compose로 전환
+   - 각 문제를 독립적으로 해결
+
+4. **문서화의 중요성**
+   - 이전 결정사항 히스토리 추적
+   - 다양한 해결 방안 비교 분석
+   - 향후 유사 문제 발생 시 참고 가능
\ No newline at end of file