docs: skill-embedding 서비스 구축 트러블슈팅 문서 추가

2025-08-05 11:22:33 +09:00 · 2025-08-05 11:22:33 +09:00 · aebb94b8ba
commit aebb94b8ba
parent e3a75c5df8
1 changed files with 155 additions and 0 deletions
--- a/troubleshooting/250805_happybell80_skill-embedding서비스구축.md
+++ b/troubleshooting/250805_happybell80_skill-embedding서비스구축.md
@ -0,0 +1,155 @@
+# skill-embedding 서비스 구축 및 배포
+
+**날짜**: 2025-08-05  
+**작업자**: happybell80 & Claude  
+**관련 서버**: 51124 (skill-embedding 서비스)
+
+## 오전 10시 30분
+
+### 임베딩 서비스 분리 결정
+
+**배경**:
+- rb10508_micro가 987.9MB 메모리 사용 (ONNX 임베딩 모델 포함)
+- 각 로빙마다 동일한 임베딩 모델 중복 로드
+- 향후 로빙 추가 시 메모리 부담 가중
+
+**해결 방안**:
+- 중앙 임베딩 서비스 구축 (skill-embedding)
+- 모든 로빙이 HTTP API로 임베딩 요청
+- 메모리 절약: 로빙당 ~500MB 절감 예상
+
+## 오전 10시 45분
+
+### 서비스 설계 및 개발
+
+**주요 결정사항**:
+1. **포트 번호**: 8600 → 8015 (스킬 서비스 포트 범위)
+2. **서비스 이름**: embedding_service → skill-embedding
+3. **접근 방식**: 내부 전용 (nginx 프록시 불필요)
+
+**구현 내용**:
+```python
+# FastAPI 엔드포인트
+POST /embed - 텍스트 → 임베딩 변환
+GET /health - 헬스체크
+```
+
+**기술 스택**:
+- FastAPI + Uvicorn
+- ONNX Runtime
+- multilingual-MiniLM-L12-v2 모델
+- 384차원 임베딩
+
+## 오전 11시 00분
+
+### 51124 서버 사전 준비
+
+**서버팀 작업**:
+```bash
+# 디렉토리 생성
+mkdir -p /home/admin/ivada_project/skill-embedding/logs
+chmod 777 logs
+
+# ONNX 모델 권한 설정
+chown -R 999:999 /home/admin/ivada_project/onnx_models
+
+# 환경변수 설정
+cat > .env << EOF
+PORT=8015
+SERVICE_NAME=skill-embedding
+LOG_LEVEL=INFO
+MODEL_PATH=/models/onnx/multilingual-MiniLM-L12-v2
+EOF
+
+# Docker 공간 정리 (16.16GB 확보)
+docker system prune -a -f
+```
+
+## 오전 11시 15분
+
+### 배포 및 검증
+
+**Gitea Actions 배포**:
+- SSH 키 기반 51124 서버 배포
+- Docker Compose로 컨테이너 실행
+- 헬스체크 통과
+
+**검증 결과**:
+```bash
+# 컨테이너 상태
+CONTAINER ID   IMAGE              STATUS         PORTS     NAMES
+abc123def      skill-embedding    Up 25 seconds  8015/tcp  skill-embedding
+
+# 메모리 사용량
+skill-embedding: 874.4MB (예상 범위 내)
+
+# API 테스트
+curl http://localhost:8015/health
+{"status":"healthy","service":"skill-embedding","model":"multilingual-MiniLM-L12-v2","uptime":25.31}
+
+# 임베딩 테스트
+curl -X POST http://localhost:8015/embed \
+  -H "Content-Type: application/json" \
+  -d '{"texts":["테스트"]}'
+# 384차원 벡터 정상 반환
+```
+
+## 오전 11시 20분
+
+### ChromaDB 통합 준비
+
+**HTTPEmbeddingFunction 구현**:
+```python
+class HTTPEmbeddingFunction(EmbeddingFunction):
+    def __init__(self, embedding_service_url="http://localhost:8015"):
+        self.url = f"{embedding_service_url}/embed"
+        
+    def __call__(self, texts):
+        response = requests.post(self.url, json={"texts": texts})
+        return response.json()["embeddings"]
+```
+
+**적용 대상**:
+- rb10508_micro: 988.1MB → ~400MB (예상)
+- rb8001: 추후 적용
+- rb10408: 추후 적용
+
+## 교훈
+
+1. **서비스 분리의 이점**
+   - 중복 제거로 메모리 효율성 향상
+   - 중앙 관리로 유지보수 용이
+   - 확장성 확보 (새 로빙 추가 시 임베딩 서비스 재사용)
+
+2. **내부 서비스 설계**
+   - nginx 프록시 불필요한 내부 API는 복잡도 감소
+   - localhost 통신으로 충분한 성능
+   - 보안상 외부 노출 불필요
+
+3. **사전 준비의 중요성**
+   - 서버팀과 긴밀한 협업으로 원활한 배포
+   - 권한 설정 (logs 777, ONNX 모델 999:999) 필수
+   - Docker 공간 확보로 빌드 실패 방지
+
+4. **단계적 적용 전략**
+   - 새 서비스 먼저 안정화
+   - 하나의 로빙(rb10508_micro)에 시범 적용
+   - 성공 후 다른 로빙들에 확산
+
+5. **모니터링 지표**
+   - 메모리 사용량: 874.4MB (ONNX 모델 포함)
+   - 응답 시간: 단일 텍스트 ~50ms
+   - 헬스체크: 30초 간격
+
+## 현재 상태
+
+**skill-embedding 서비스**:
+- ✅ 정상 가동 중 (포트 8015)
+- ✅ 메모리 사용량 안정적 (874.4MB)
+- ✅ API 응답 정상
+- ✅ 384차원 임베딩 생성 확인
+
+**다음 작업**:
+- rb10508_micro의 memory.py 수정
+- ONNXEmbeddingFunction → HTTPEmbeddingFunction 교체
+- 메모리 절감 효과 측정