04 Local Run and Operations

로컬 실행과 운영

기본 실행

필수 조건:

• Python 3.11 이상
• uv
• 외부 Provider 없이 실행할 경우 Intent Stub·Rule 경로 사용

uv sync --frozen --extra dev
uv run uvicorn app.main:app --host 127.0.0.1 --port 8000

확인:

• OpenAPI: http://127.0.0.1:8000/docs
• Intent status: GET /internal/v1/intent/status
• Intent readiness: GET /internal/v1/intent/readiness

Internal API Token을 설정했다면 Authorization: Bearer ...를 함께 보냅니다.

설치 프로필

목적	설치
Core 개발·테스트	uv sync --frozen --extra dev
BERT Intent	--extra intent
A.X Adapter	--extra intent-ax
Qdrant·Embedding·Reranker	--extra language-retrieval

A.X는 Linux/CUDA 환경을 우선합니다. 운영 장치와 일치하지 않는 cuda 설정을 사용하지 않습니다.

핵심 환경변수

Intent

• FOWOCO_INTENT_MODEL_ENABLED
• FOWOCO_INTENT_BERT_MODEL_DIR
• FOWOCO_INTENT_BERT_MODEL_REVISION
• FOWOCO_INTENT_ENABLE_AX
• FOWOCO_INTENT_AX_BASE_MODEL
• FOWOCO_INTENT_AX_BASE_REVISION
• FOWOCO_INTENT_AX_ADAPTER_PATH
• FOWOCO_INTENT_AX_ADAPTER_REVISION
• FOWOCO_INTENT_DEVICE
• FOWOCO_INTENT_WARMUP_ON_START
• FOWOCO_INTENT_WARMUP_REQUIRED

Language

• FOWOCO_LLM_PROVIDER
• FOWOCO_LLM_BASE_URL
• FOWOCO_LLM_API_KEY
• FOWOCO_LLM_MODEL
• FOWOCO_QDRANT_URL
• FOWOCO_QDRANT_API_KEY

OCR·Internal API

• FOWOCO_INTERNAL_API_TOKEN
• FOWOCO_CLOVA_OCR_ENABLED
• FOWOCO_CLOVA_OCR_INVOKE_URL
• FOWOCO_CLOVA_OCR_SECRET

전체 예시는 .env.example을 사용합니다.

Secret 원칙

• 실제 Token과 Secret을 .env.example, Issue, PR, Wiki, 로그에 입력하지 않습니다.
• Hugging Face Token은 필요한 모델에 대한 최소 read-only 권한을 사용합니다.
• Kubernetes Secret 변경 시 기존 노출 Token은 폐기하고 새 값으로 교체합니다.
• Provider 오류 로그에 원본 문서, OCR 필드, 안내 evidence, Token을 기록하지 않습니다.

배포

main push 시 다음 흐름이 실행됩니다.

Docker build
→ ghcr.io/fowoco/ai:{sha}, latest push
→ fowoco/infra manifest 적용
→ Kubernetes deployment/ai 이미지 갱신
→ rollout status 확인

현재 rollout timeout은 600초이며 실패 시 Pod·Deployment·로그·Event 진단을 남깁니다.

Health와 readiness

• Intent readiness는 Internal Bearer가 필요한 /internal/v1/intent/readiness입니다.
• 모델 활성화 시 warmup 완료와 BERT/A.X 가용성을 확인합니다.
• 2026-08-16 main에는 인증 없는 범용 liveness/readiness endpoint가 없습니다.
• Kubernetes Probe가 Internal Token 없이 접근해야 한다면 별도의 최소 공개 health endpoint 계약이 필요합니다.

운영 점검 순서

1. 배포 SHA와 실행 이미지 SHA 일치 확인
2. Internal Token 인증 확인
3. Intent status의 model/prompt/ready 확인
4. PLAN smoke
5. ANALYZE providerAttemptCount=0 확인
6. Renewal ask_hr/ask_worker/generate 분기 확인
7. 실 Provider는 별도 Staging에서 OCR·Language·Qdrant smoke