# Week 2 배포 트랙 패킷 [Stage: Weekend-2] 이 트랙의 핵심은 **모델 서빙 트랙을 선택하고, 실제 공개 URL에서 E2E를 검증하는 것**입니다. **진행 순서:** 1. 이 문서를 읽고 트랙을 결정한다. 2. [`deployment-checklist-lab.md`](./deployment-checklist-lab.md)를 채우며 배포를 완료한다. 3. 막히면 [`deployment.md`](./deployment.md)를 참고한다. --- ## 트랙 목표 - `Ollama 자체 호스팅`과 `OpenAI API 연동`의 배포 차이를 설명할 수 있다. - 선택한 트랙으로 `문서 업로드 → /qa 질의응답` E2E를 외부 URL에서 확인한다. - 장애 상황(모델 다운, API 제한, DB 지연)에 대해 최소 복구 절차를 문서화한다. --- ## 1) 트랙 선택: Ollama vs OpenAI ### A. Ollama 자체 호스팅 트랙 다음에 해당하면 Ollama 트랙이 유리합니다. - 데이터가 외부 API로 나가면 안 되는 환경 - 고정 비용(서버 비용)으로 운영하고 싶은 경우 - 모델 동작 원리를 직접 확인하고 싶은 경우 운영 리스크: - 서버 자원(CPU/GPU/RAM) 부족 시 응답 지연 - 모델 다운로드/업데이트/헬스체크를 직접 운영해야 함 - 클라우드 배포 시 충분한 RAM의 서버 필요 (llama3.1 기준 최소 8GB) ### B. OpenAI API 연동 트랙 다음에 해당하면 OpenAI 트랙이 유리합니다. - 인프라 운영 부담을 줄이고 빠르게 배포하고 싶은 경우 - 트래픽 편차에 따라 탄력적으로 사용하고 싶은 경우 - HF Spaces / Railway 등 무료 클라우드에 배포하고 싶은 경우 운영 리스크: - API rate limit, 쿼터, 비용 급증 관리 필요 - 외부 네트워크 장애에 직접 영향받음 - 시크릿 키 노출 방지와 키 롤테이션 정책 필요 --- ## 2) 트랙별 필수 설정 ### 공통 - `SUPABASE_URL`, `SUPABASE_KEY` 설정 - `document_chunks` 테이블 + `match_documents` RPC + 인덱스 준비 - `GET /health` 및 업로드/질의 E2E 테스트 가능 상태 ### Ollama 트랙 (`PROVIDER=ollama`) - `OLLAMA_BASE` 설정 (로컬/원격 주소) - `OLLAMA_EMBED_MODEL=nomic-embed-text` - `OLLAMA_CHAT_MODEL=llama3.1` - 임베딩 차원: `768` - 모델 서버 헬스 확인: `curl /api/tags` ### OpenAI 트랙 (`PROVIDER=openai`) - `OPENAI_API_KEY` 설정 - `OPENAI_EMBEDDING_MODEL=text-embedding-3-small` - `OPENAI_CHAT_MODEL=gpt-4o-mini` (또는 팀 정책 모델) - 임베딩 차원: `1536` - rate limit/쿼터 초과 시 재시도 및 에러 메시지 기준 정의 --- ## 3) 배포 시나리오 ### 시나리오 A: Docker + Ollama (자체 호스팅) 1. `.env`에서 `PROVIDER=ollama`로 설정 2. `OLLAMA_BASE`를 컨테이너 네트워크에 맞게 지정 (`http://ollama:11434`) 3. `docker-compose up -d`로 앱 + Ollama 동시 실행 4. 공개 URL에서 `/health`, 업로드, `/qa` 테스트 체크 포인트: - Ollama 컨테이너 재시작 후 앱 복구 시간 - 모델 미다운로드 상태에서의 사용자 안내 메시지 - 동시 요청 증가 시 응답 시간 변동 ### 시나리오 B: HF Spaces / Railway + OpenAI API (권장) 1. `.env` 또는 플랫폼 시크릿에 `PROVIDER=openai` 및 API 키 설정 2. Supabase 스키마를 1536차원으로 정합성 확인 3. 앱만 클라우드 배포 (모델 서버 별도 운영 없음) 4. 공개 URL에서 `/health`, 업로드, `/qa` 테스트 체크 포인트: - API 키 누락/오타 시 감지 가능 여부 - rate limit 발생 시 재시도/안내 동작 - 호출 비용 모니터링 지표 수집 여부 > 클라우드 플랫폼별 상세 설정은 [`deployment.md`](./deployment.md)를 참고하세요. --- ## 4) 트랙 선택 기록 (작성 후 팀 문서에 남길 것) ```md ### 모델 서빙 트랙 선택 기록 - 선택 트랙: (ollama / openai) - 선택 이유: (비용, 보안, 운영, 성능 관점 3줄 이상) - 임베딩 차원: (768 / 1536) - 예상 리스크: (최소 2개) - 대응 계획: (리스크별 1개 이상) ``` --- ## Weekend-2 DoD (페어 기준) - [ ] 선택한 모델 서빙 트랙의 근거(비용/운영/성능)를 3줄 이상 작성 - [ ] 벡터 DB 스키마 차원(768 또는 1536)과 실제 설정 일치 확인 - [ ] 공개 URL에서 `GET /health` 성공 - [ ] 공개 URL에서 PDF 업로드 + `/qa` 답변 성공 - [ ] 장애 대응 드릴 3개 수행 및 복구 시간 기록 - [ ] 페어 상대방이 공개 URL에서 직접 E2E 검증 가능한지 확인 ## 검증 명령 ```bash curl /health ```