DOCS/troubleshooting/250804_claude_ONNX임베딩경량화.md

ONNX 기반 임베딩 경량화 작업

작성일: 2025년 8월 4일 작성자: Claude (51124 서버)

작업 배경

rb10508_micro의 컨테이너 이미지가 6.19GB로 매우 크고, 주요 원인이 PyTorch와 sentence-transformers였음. ONNX로 변환하여 경량화 진행.

작업 과정

오후 3시 15분 - ONNX 변환 시작

1. 작업 디렉토리 생성

mkdir -p /home/admin/ivada_project/onnx_models

2. uv 설치 및 가상환경 생성

pip install uv
uv venv
source .venv/bin/activate
uv pip install transformers torch onnx onnxruntime

오후 3시 20분 - 변환 스크립트 작성

convert_to_onnx.py 작성하여 paraphrase-multilingual-MiniLM-L12-v2 모델을 ONNX로 변환

주요 문제:

• 첫 시도에서 입력 이름 불일치 (input.3 추가 입력 요구)
• 해결: torch.onnx.export에서 명시적으로 2개 입력만 전달

오후 3시 30분 - 경량 추론 모듈 개발

1. onnx_embedder.py 작성

   • PyTorch 없이 ONNX Runtime만으로 임베딩 생성
   • ChromaDB 호환 인터페이스 제공
   • Mean pooling 구현

2. chroma_onnx_function.py 작성

   • ChromaDB EmbeddingFunction 인터페이스 구현
   • 기존 sentence-transformers 대체 가능

오후 3시 40분 - 테스트 및 검증

테스트 결과:

• 한국어-영어 번역 문장 유사도: 0.970 (매우 높음)
• ChromaDB 통합 테스트 성공
• 한국어 문서 검색 정확도 확인

성능 비교

이미지 크기

• 기존: 6.19GB (PyTorch + sentence-transformers)
• 예상: ~500MB (Python slim + ONNX Runtime)

모델 크기

• ONNX 모델: 449MB (변환 완료)
• 토크나이저 포함 전체: ~500MB

메모리 사용량

• PyTorch 오버헤드 제거로 대폭 감소 예상

로컬 개발자 작업 가이드

1. Dockerfile 수정

# 기존
FROM chroma_vector:1.0

# 변경
FROM python:3.11-slim

# sentence-transformers, torch 제거
# onnxruntime만 설치
RUN pip install onnxruntime transformers

2. 코드 수정

# 기존
from sentence_transformers import SentenceTransformer
embedder = SentenceTransformer(model_name)

# 변경
from onnx_models.chroma_onnx_function import ONNXEmbeddingFunction
embedding_function = ONNXEmbeddingFunction("/path/to/onnx/model")

3. 모델 마운트

volumes:
  - /home/admin/ivada_project/onnx_models:/models/onnx:ro

교훈

1. ONNX 변환 시 입력 명세 주의

   • torch.onnx.export의 input_names와 실제 모델 입력이 일치해야 함
   • 불필요한 입력은 명시적으로 제외

2. ChromaDB API 변경 대응

   • 구 API: chromadb.Client(Settings(...))
   • 신 API: chromadb.PersistentClient(path=...)

3. 경량화의 핵심은 의존성 제거

   • 기능 축소만으로는 한계 (코드는 줄어도 라이브러리는 그대로)
   • 무거운 라이브러리를 경량 대안으로 교체해야 진정한 경량화

4. uv 사용으로 패키지 설치 속도 향상

   • pip 대비 10배 이상 빠른 설치
   • 특히 대용량 패키지(PyTorch 등) 설치 시 효과적

다음 단계

1. 로컬 개발자가 Dockerfile 및 requirements.txt 수정
2. 베이스 이미지를 python:3.11-slim으로 변경
3. GitHub Actions 워크플로우 업데이트
4. 배포 후 실제 메모리 사용량 측정