온프레미스 배포 + 모델 연동 가이드 — eval-system-premium

1. 시스템 아키텍처

2. 컴포넌트 인벤토리

3. 모델 연동 — .env.onprem

MODEL_CONFIG_*_ENABLED 스위치로 dev/prod 분기. 온프렘은 전부 TYPE=local + URL=http://localhost:830X.

# LLM — RFP 구조화 + 평가 챗봇
MODEL_CONFIG_qwen3_32b_ENABLED=true
MODEL_CONFIG_qwen3_32b_TYPE=local
MODEL_CONFIG_qwen3_32b_PROVIDER=qwen
MODEL_CONFIG_qwen3_32b_URL=http://localhost:8305
MODEL_CONFIG_qwen3_32b_MODEL_NAME=Qwen/Qwen3-32B
MODEL_CONFIG_qwen3_32b_GPU_INFO_URL=http://localhost:8500
MODEL_CONFIG_qwen3_32b_PURPOSE=rfp-structure

# Vision — 도면/이미지 분석
MODEL_CONFIG_qwen3_vl_8b_instruct_ENABLED=true
MODEL_CONFIG_qwen3_vl_8b_instruct_TYPE=local
MODEL_CONFIG_qwen3_vl_8b_instruct_URL=http://localhost:8303/v1
MODEL_CONFIG_qwen3_vl_8b_instruct_MODEL_NAME=Qwen/Qwen3-VL-8B-Instruct
MODEL_CONFIG_qwen3_vl_8b_instruct_PURPOSE=rfp-image-analysis

# 평가 챗봇 (별도 alias — same vLLM 인스턴스 재사용)
MODEL_CONFIG_qwen3_32b_eval_ENABLED=true
MODEL_CONFIG_qwen3_32b_eval_URL=http://localhost:8305
MODEL_CONFIG_qwen3_32b_eval_PURPOSE=eval-chatbot

# Embedding — 한국어 KURE-v1
MODEL_CONFIG_local_embedding_ENABLED=true
MODEL_CONFIG_local_embedding_TYPE=local
MODEL_CONFIG_local_embedding_PROVIDER=kure
MODEL_CONFIG_local_embedding_URL=http://localhost:8306
MODEL_CONFIG_local_embedding_MODEL_NAME=nlpai-lab/KURE-v1
MODEL_CONFIG_local_embedding_PURPOSE=semantic-search
EMBEDDING_DIM=1536

# 외부 API 키 — 온프렘은 비활성
GEMINI_API_KEY=
OPENROUTER_API_KEY=  # 데모 후 revoke 권장
UPSTAGE_API_KEY=
USE_UPSTAGE_API=false

4. 부팅 절차 (1회성 — start.sh)

1. GPU 모델 서빙 시작 (호스트 systemd 또는 별도 supervisor)

   # Qwen3-32B vLLM
   vllm serve Qwen/Qwen3-32B --port 8305 --tensor-parallel-size 2
   
   # Qwen3-VL-8B
   vllm serve Qwen/Qwen3-VL-8B-Instruct --port 8303 --tensor-parallel-size 1
   
   # KURE-v1 임베딩
   python -m kure_v1.server --port 8306

2. hwpx-intelligence 부팅 (호스트 uvicorn, BFF 보다 먼저)

   cd ~/Github/1_Projects/hwpx-intelligence
   uv sync
   nohup uv run hpwx serve --host 0.0.0.0 --port 8001 > /var/log/hwpx.log 2>&1 &

3. 온프렘 start.sh 실행 (이미지 tar 로드 + .env 자동 복사 + docker compose up)

   cd ~/Github/1_Projects/pps-mono-repo
   git pull origin feat/onprem-h100-deploy   # alpha 최신 squash 머지된 상태
   bash start.sh

   내부 동작:
   1. docker load < docker-images/pps-images.tar (이미지 로드, 첫 부팅만)
   2. cp .env.onprem .env
   3. docker compose up -d --no-build
4. MinIO 버킷 자동 생성 — minio-init 컨테이너가 MINIO_BUCKETS env 의 버킷 자동 생성 (eval-premium-images, pps-rfp-processed, pps-rfp-ingest)
5. postgres 자동 migration — BFF entrypoint 가 alembic upgrade head 실행
6. 헬스체크

   curl localhost:4001/api/health         # {"status":"ok"}
   curl localhost:8001/api/health         # hwpx
   curl localhost:8305/v1/models          # vLLM
   docker compose ps                      # 모두 healthy

5. 데모 5/22 안전 체크리스트

6. 운영 가이드 — 보안·백업·모니터링

7. 트러블슈팅

8. 자주 쓰는 명령

# 전체 재시작
docker compose down && bash start.sh

# 특정 컨테이너 재기동 (BFF)
docker compose up -d --force-recreate eval-system-premium-bff

# 로그
docker compose logs -f eval-system-premium-bff
docker compose logs -f eval-system-premium-frontend

# DB 직접 조회
docker exec pps-postgres-1 psql -U pps_user -d eval_system_premium

# MinIO 객체 목록
docker exec pps-minio-1 mc ls --recursive local/eval-premium-images/

# 마이그레이션 (기존 proposal data_uri → MinIO)
curl -X POST http://localhost:4001/api/admin/migrate-images

# keyset 페이지네이션 테스트
curl "localhost:4001/api/proposals?limit=10&include_raw=false&cursor=..."

9. 참고 링크

• 브랜치: feat/onprem-h100-deploy
• 최근 머지: PR #197 (35 PR squash)
• 이전 분석: 성능·안정성 진단 · 공통기능 분류 기획
• hwpx-intelligence: jodal-eval-ai/hwpx-intelligence (main)