lcbp3/specs/04-Infrastructure-OPS/04-00-docker-compose/Desk-5439/ocr-sidecar/README.md

OCR Sidecar — Desk-5439

HTTP API server สำหรับสกัดข้อความจาก PDF ผ่าน np-dms-ocr (Ollama) — รันบน Desk-5439 ตาม ADR-023A/ADR-040.

สถาปัตยกรรม

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