Backend (QNAP) → POST /ocr-upload → OCR Sidecar (Desk-5439:8765)
                                          ↓
                                    PyMuPDF (fast-path: chars > 100)
                                          ↓ (ถ้า chars ≤ 100)
                                    prepare_ocr_messages (typhoon_ocr)
                                    + poppler/pdftoppm (PDF → image)
                                          ↓
                                    np-dms-ocr via Ollama /v1/chat/completions
                                          ↓
                                    JSON → natural_text (Markdown)

Endpoints

Endpoint	Method	Auth	หน้าที่
`/health`	GET	—	ตรวจสอบสถานะ sidecar
`/ocr`	POST	X-API-Key	OCR จาก path (ใช้เมื่อ shared volume mount)
`/ocr-upload`	POST	X-API-Key	OCR จาก multipart file upload
`/embed`	POST	X-API-Key	BGE-M3 embedding (Dense + Sparse) พร้อม CPU fallback
`/rerank`	POST	X-API-Key	BGE-Reranker-Large chunk re-ranker พร้อม CPU fallback

Removed endpoints:

POST /normalize — ลบออกแล้วตาม ADR-040 Phase 8 (ไม่มี consumers)

Environment Variables

Variable	Default	หน้าที่
`OCR_SIDECAR_API_KEY`	(required)	API key สำหรับ authentication (Phase 1)
`OCR_SIDECAR_UPLOAD_BASE`	`/mnt/uploads`	Base path whitelist สำหรับ path traversal protection
`OLLAMA_API_URL`	`http://host.docker.internal:11434`	Ollama API URL
`OCR_MODEL`	`np-dms-ocr:latest`	ชื่อ OCR model ใน Ollama
`OCR_TIMEOUT`	`360`	Timeout วินาทีต่อ request
`OCR_CHAR_THRESHOLD`	`100`	Fast-path threshold (chars > 100 = ใช้ text layer โดยตรง)
`OCR_MAX_PAGES`	`0`	จำนวนหน้าสูงสุด (0 = ทุกหน้า)
`OCR_ACTIVE_PROFILE`	(optional)	ชื่อ profile ใน `ai_execution_profiles`
`VRAM_HEADROOM_THRESHOLD_MB`	`3000.0`	Threshold สำหรับ CPU fallback
`RETRIEVAL_TIMEOUT_SECONDS`	`30.0`	Timeout สำหรับ /embed และ /rerank
`MAX_SYSTEM_PROMPT_LENGTH`	`10000`	ความยาวสูงสุดของ systemPrompt

การ Deploy

# 1. คัดลอก .env.example เป็น .env และกรอกค่า
cp .env.example .env
# แก้ OCR_SIDECAR_API_KEY เป็นค่าจริง

# 2. Build และรัน
docker compose up -d --build

# 3. ตรวจสอบ
curl http://192.168.10.100:8765/health

การทดสอบ

# รันทุก test (จาก project root)
python -m pytest tests/ -v

# รันเฉพาะ unit tests
python -m pytest tests/unit/ocr-sidecar/ -v

# รันเฉพาะ integration tests
python -m pytest tests/integration/ocr-sidecar/ -v

Test Coverage

Test File	หน้าที่
`test_path_traversal.py`	Path traversal protection (US1)
`test_api_key_validation.py`	API key validation (US1)
`test_residency_wiring.py`	Adaptive OCR residency wiring (US2)
`test_cpu_fallback.py`	CPU fallback for /embed and /rerank (US2)
`test_parameter_governance.py`	Runtime parameter governance (US3)
`test_active_prompt.py`	System prompt + DMS tags injection (US3)
`test_async_performance.py`	Async I/O + lifespan + concurrent requests (US4)

ADR-040 Phases

Phase	Status	หน้าที่
Phase 1-2	✅ Complete	Setup + Foundational
Phase 3	✅ Complete	US1: Security Hardening
Phase 4	✅ Complete	US2: GPU Resource Management
Phase 5	✅ Complete	US3: Parameter Governance
Phase 6	✅ Complete	US4: Async I/O Performance
Phase 7	⏳ Blocked	US5: Network Isolation Auth (รอ ADR-041)
Phase 8	✅ Complete	Remove /normalize endpoint
Phase 9	✅ Complete	Polish & documentation

ไฟล์ในโปรเจกต์

ocr-sidecar/
├── app.py              — FastAPI server (async I/O, lifespan)
├── Dockerfile          — Docker image (python:3.10-slim + poppler + curl)
├── docker-compose.yml  — Compose config (ocr-sidecar + ollama-metrics)
├── requirements.txt    — Python dependencies
├── .env.example        — Environment template
├── services/
│   ├── vram_monitor.py     — VRAM headroom monitoring
│   └── residency_policy.py — Adaptive OCR residency calculation
└── tests/
    └── test_retrieval_fallback.py — Retrieval fallback tests