ivada-infra/DOCS

Fork 0

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

2025-08-05 11:22:33 +09:00

4.1 KiB

Raw Blame History

skill-embedding 서비스 구축 및 배포

날짜: 2025-08-05
작업자: happybell80 & Claude
관련 서버: 51124 (skill-embedding 서비스)

오전 10시 30분

임베딩 서비스 분리 결정

배경:

rb10508_micro가 987.9MB 메모리 사용 (ONNX 임베딩 모델 포함)
각 로빙마다 동일한 임베딩 모델 중복 로드
향후 로빙 추가 시 메모리 부담 가중

해결 방안:

중앙 임베딩 서비스 구축 (skill-embedding)
모든 로빙이 HTTP API로 임베딩 요청
메모리 절약: 로빙당 ~500MB 절감 예상

오전 10시 45분

서비스 설계 및 개발

주요 결정사항:

포트 번호: 8600 → 8015 (스킬 서비스 포트 범위)
서비스 이름: embedding_service → skill-embedding
접근 방식: 내부 전용 (nginx 프록시 불필요)

구현 내용:

# FastAPI 엔드포인트
POST /embed - 텍스트 → 임베딩 변환
GET /health - 헬스체크

기술 스택:

FastAPI + Uvicorn
ONNX Runtime
multilingual-MiniLM-L12-v2 모델
384차원 임베딩

오전 11시 00분

51124 서버 사전 준비

서버팀 작업:

# 디렉토리 생성
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로 컨테이너 실행
헬스체크 통과

검증 결과:

# 컨테이너 상태
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 구현:

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: 추후 적용

교훈

서비스 분리의 이점
- 중복 제거로 메모리 효율성 향상
- 중앙 관리로 유지보수 용이
- 확장성 확보 (새 로빙 추가 시 임베딩 서비스 재사용)
내부 서비스 설계
- nginx 프록시 불필요한 내부 API는 복잡도 감소
- localhost 통신으로 충분한 성능
- 보안상 외부 노출 불필요
사전 준비의 중요성
- 서버팀과 긴밀한 협업으로 원활한 배포
- 권한 설정 (logs 777, ONNX 모델 999:999) 필수
- Docker 공간 확보로 빌드 실패 방지
단계적 적용 전략
- 새 서비스 먼저 안정화
- 하나의 로빙(rb10508_micro)에 시범 적용
- 성공 후 다른 로빙들에 확산
모니터링 지표
- 메모리 사용량: 874.4MB (ONNX 모델 포함)
- 응답 시간: 단일 텍스트 ~50ms
- 헬스체크: 30초 간격

현재 상태

skill-embedding 서비스:

✅ 정상 가동 중 (포트 8015)
✅ 메모리 사용량 안정적 (874.4MB)
✅ API 응답 정상
✅ 384차원 임베딩 생성 확인

다음 작업:

rb10508_micro의 memory.py 수정
ONNXEmbeddingFunction → HTTPEmbeddingFunction 교체
메모리 절감 효과 측정

4.1 KiB Raw Blame History