Troubleshooting

자주 발생하는 문제와 해결 방법입니다.

환경 설정

uv sync 실패

python --version   # 3.10+ 확인
uv --version       # 최신 버전 확인

uv가 없으면: curl -LsSf https://astral.sh/uv/install.sh | sh

CUDA/GPU 관련 오류

nvidia-smi          # 드라이버 확인
nvcc --version      # CUDA 12.x 확인

GPU 없이 개발하려면 .env에 SKIP_MODEL_LOAD=true 설정

런타임

/health가 응답하지 않음

• 포트 충돌 확인: lsof -i :8000
• 로그 레벨 변경: LOG_LEVEL=DEBUG
• .env 파일 존재 여부 확인

/v1/search가 503 반환

• SKIP_MODEL_LOAD=true 상태에서는 추론 불가
• FAISS/BM25 인덱스 경로 확인: FAISS_INDEX_DIR, BM25_INDEX_DIR

vLLM OOM (Out of Memory)

• GPU_UTILIZATION 값 낮추기 (기본 0.8 → 0.6)
• MAX_MODEL_LEN 줄이기 (기본 8192 → 4096)
• 다른 GPU 프로세스 종료: nvidia-smi 확인

CI/CD

mkdocs build --strict 실패

• nav에 없는 페이지 존재 여부 확인
• 상대 링크와 실제 파일 경로 일치 확인

E2E 테스트 실패

• /v1/classify 엔드포인트는 MVP 계약에 미포함
• api-health.spec.ts가 올바른 엔드포인트를 테스트하는지 확인

Docker

컨테이너가 시작되지 않음

cp .env.example .env   # .env 파일 누락 확인
docker compose logs     # 에러 로그 확인

GPU 사용 시 docker-compose.yml의 deploy.resources.reservations.devices 설정 확인

Cloud Run 배포 실패

• GCP_SA_KEY, GCP_PROJECT_ID secret 확인
• GHCR 이미지 정상 발행 여부: docker pull ghcr.io/umyunsang/govon:latest

도움 요청

해결되지 않는 문제는 GitHub Issues에 등록해주세요.

관련 문서

• Getting Started — 설치 가이드
• Development Guide — 개발 규칙