DOCS/troubleshooting/250731_happybell80_ChromaDB베이스이미지전환.md

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 내용:

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 저장소 생성:

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:

# 변경 전
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

변경 내용:

# 변경 전
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. 문서화의 중요성

   • 이전 결정사항 히스토리 추적
   • 다양한 해결 방안 비교 분석
   • 향후 유사 문제 발생 시 참고 가능