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

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

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

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

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

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

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

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

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

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

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

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

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

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

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