ONNX 기반 임베딩 경량화 트러블슈팅 문서 추가

- sentence-transformers 모델을 ONNX로 변환
- PyTorch 없이 동작하는 경량 추론 모듈 개발
- ChromaDB 통합 테스트 완료
- 예상 이미지 크기: 6GB → 500MB

Co-Authored-By: Claude <noreply@anthropic.com>

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

@@ -0,0 +1,121 @@
+# ONNX 기반 임베딩 경량화 작업
+
+작성일: 2025년 8월 4일
+작성자: Claude (51124 서버)
+
+## 작업 배경
+
+rb10508_micro의 컨테이너 이미지가 6.19GB로 매우 크고, 주요 원인이 PyTorch와 sentence-transformers였음. ONNX로 변환하여 경량화 진행.
+
+## 작업 과정
+
+### 오후 3시 15분 - ONNX 변환 시작
+
+1. 작업 디렉토리 생성
+```bash
+mkdir -p /home/admin/ivada_project/onnx_models
+```
+
+2. uv 설치 및 가상환경 생성
+```bash
+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 수정
+```dockerfile
+# 기존
+FROM chroma_vector:1.0
+
+# 변경
+FROM python:3.11-slim
+
+# sentence-transformers, torch 제거
+# onnxruntime만 설치
+RUN pip install onnxruntime transformers
+```
+
+### 2. 코드 수정
+```python
+# 기존
+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. 모델 마운트
+```yaml
+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. 배포 후 실제 메모리 사용량 측정