223 lines
13 KiB
Markdown
223 lines
13 KiB
Markdown
# ADR-029: Dynamic Prompt Management for OCR Extraction
|
|
|
|
**Status:** Accepted
|
|
**Date:** 2026-05-25
|
|
**Decision Makers:** Development Team, System Architect
|
|
**Related Documents:**
|
|
- [ADR-027: AI Admin Console and Dynamic Control](./ADR-027-ai-admin-console-and-dynamic-control.md)
|
|
- [ADR-023A: Unified AI Architecture — Model Revision](./ADR-023A-unified-ai-architecture.md)
|
|
- [ADR-009: Database Migration Strategy](./ADR-009-database-migration-strategy.md)
|
|
- [ADR-019: Hybrid Identifier Strategy](./ADR-019-hybrid-identifier-strategy.md)
|
|
|
|
---
|
|
|
|
## บริบทและปัญหา (Context and Problem Statement)
|
|
|
|
`processSandboxExtract` และ `processMigrateDocument` ใน `ai-batch.processor.ts` ต่างมี prompt template แบบ **hardcoded** ที่ไม่สามารถแก้ไขได้โดยไม่ต้อง redeploy:
|
|
|
|
- `processSandboxExtract` สกัด 5 fields (documentNumber, subject, discipline, date, confidence)
|
|
- `processMigrateDocument` สกัด 8 fields (+ category, tags, summary)
|
|
- ทั้งสองใช้ prompt ที่ต่างกัน ทำให้ sandbox ไม่ simulate พฤติกรรมจริงได้แม่นยำ
|
|
|
|
ปัญหาเพิ่มเติมที่พบ:
|
|
1. **Timeout Bug**: `AI_TIMEOUT_MS = 30000ms` (30 วินาที) สั้นเกินไปสำหรับ Ollama ใน OCR Sandbox — การรันครั้งที่สองมักล้มเหลวเพราะ model ต้องโหลดใหม่เข้า VRAM
|
|
2. **ไม่มี version history**: ไม่สามารถ rollback กลับไป prompt เดิมได้
|
|
|
|
---
|
|
|
|
## ปัจจัยขับเคลื่อนการตัดสินใจ (Decision Drivers)
|
|
|
|
- **Admin Control**: Superadmin ต้องแก้ไข prompt ได้ runtime ผ่าน AI Admin Console
|
|
- **Consistency**: Sandbox และ migrate-document ต้องใช้ prompt เดียวกัน ผลลัพธ์ sandbox จึงสะท้อนพฤติกรรมจริง
|
|
- **Auditability**: ต้องมี version history เพื่อ compare ผลลัพธ์ระหว่าง prompt versions
|
|
- **Safety**: ห้ามลบ active version, ต้อง validate placeholder `{{ocr_text}}` ก่อน save
|
|
|
|
---
|
|
|
|
## ทางเลือกที่ถูกพิจารณา (Considered Options)
|
|
|
|
### Option 1: เก็บ prompt ใน `system_settings` (Generic Key-Value)
|
|
- **ข้อดี:** ไม่ต้องสร้างตารางใหม่
|
|
- **ข้อเสีย:** `system_settings` ออกแบบสำหรับ "current value" เท่านั้น ไม่มี version history, ไม่มี result storage
|
|
|
|
### Option 2: ตาราง `ai_prompts` แยกต่างหาก (ตัวเลือกที่ได้รับเลือก)
|
|
- **ข้อดี:** Versioned, immutable snapshots, รองรับ test result storage, ออกแบบตรงกับ use case
|
|
- **ข้อเสีย:** ต้องสร้าง entity/service/controller ใหม่
|
|
|
|
---
|
|
|
|
## ผลการตัดสินใจ (Decision Outcome)
|
|
|
|
**ทางเลือกที่ได้รับเลือก:** Option 2 — ตาราง `ai_prompts` พร้อม versioning
|
|
|
|
---
|
|
|
|
## ข้อตกลงหลัก (Core Decisions — Grilling Session 2026-05-25)
|
|
|
|
| # | ประเด็น | การตัดสินใจ |
|
|
|---|---------|-------------|
|
|
| 1 | Prompt type scope | `prompt_type = 'ocr_extraction'` เดียว (8 fields) ใช้ร่วมกันทั้ง sandbox และ migrate-document |
|
|
| 2 | Activation model | Single `is_active` flag — "นำไปใช้จริง" = activate ทันทีทั้งระบบ (ทั้ง sandbox และ migrate-document) |
|
|
| 3 | Result storage | Auto-save `test_result_json` จาก sandbox run ล่าสุด + `manual_note` สำหรับ admin annotation |
|
|
| 4 | Versioning | Immutable version — ทุก "บันทึก" สร้าง version ใหม่เสมอ, สามารถลบได้ (ยกเว้น active version) |
|
|
| 5 | Template format | Full template พร้อม `{{ocr_text}}` placeholder — backend validate ก่อน save |
|
|
| 6 | Bug fix | เพิ่ม `timeoutMs` เฉพาะ sandbox-extract เป็น 120000ms แทน default 30000ms |
|
|
|
|
---
|
|
|
|
## รายละเอียดเชิงสถาปัตยกรรม (Implementation Details)
|
|
|
|
### 1. โครงสร้างตาราง `ai_prompts`
|
|
|
|
```sql
|
|
CREATE TABLE ai_prompts (
|
|
id INT PRIMARY KEY AUTO_INCREMENT,
|
|
prompt_type VARCHAR(50) NOT NULL
|
|
COMMENT 'ประเภท prompt เช่น ocr_extraction',
|
|
version_number INT NOT NULL
|
|
COMMENT 'เลข version ต่อเนื่องต่อ prompt_type (1, 2, 3...)',
|
|
template TEXT NOT NULL
|
|
COMMENT 'prompt template ที่มี {{ocr_text}} placeholder บังคับ',
|
|
field_schema JSON NULL
|
|
COMMENT 'definition ของ fields ที่คาดหวังในผลลัพธ์ JSON',
|
|
is_active TINYINT(1) DEFAULT 0
|
|
COMMENT '1 = version นี้ใช้งานจริงทั้ง sandbox และ migrate-document',
|
|
test_result_json JSON NULL
|
|
COMMENT 'ผลลัพธ์ JSON จาก sandbox run ล่าสุด (auto-save โดย processor)',
|
|
manual_note TEXT NULL
|
|
COMMENT 'หมายเหตุ/annotation จาก admin (manual input)',
|
|
last_tested_at TIMESTAMP NULL
|
|
COMMENT 'เวลาที่ sandbox รันครั้งล่าสุดสำหรับ version นี้',
|
|
activated_at TIMESTAMP NULL
|
|
COMMENT 'เวลาที่ version นี้ถูก activate เป็น active',
|
|
created_by INT NOT NULL,
|
|
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
|
|
UNIQUE KEY uk_type_version (prompt_type, version_number),
|
|
INDEX idx_prompt_type_active (prompt_type, is_active),
|
|
FOREIGN KEY (created_by) REFERENCES users(user_id)
|
|
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci
|
|
COMMENT='ตาราง versioned prompt templates สำหรับ OCR extraction (ADR-029)';
|
|
```
|
|
|
|
**Seed data** — default active version ที่ migrate มาจาก hardcoded prompt ปัจจุบัน:
|
|
```sql
|
|
INSERT INTO ai_prompts (prompt_type, version_number, template, is_active, created_by)
|
|
VALUES ('ocr_extraction', 1, '<current hardcoded prompt with {{ocr_text}}>', 1, 1);
|
|
```
|
|
|
|
### 2. Validation Rule (backend — ก่อน save)
|
|
|
|
```typescript
|
|
// AiPromptsService.create()
|
|
if (!dto.template.includes('{{ocr_text}}')) {
|
|
throw new BadRequestException(
|
|
'template ต้องมี {{ocr_text}} placeholder เพื่อระบุตำแหน่งที่จะแทรกข้อความจาก OCR'
|
|
);
|
|
}
|
|
```
|
|
|
|
### 3. Prompt Resolution ใน Processor
|
|
|
|
```typescript
|
|
// ใช้ใน processSandboxExtract และ processMigrateDocument
|
|
private async resolvePrompt(ocrText: string): Promise<string> {
|
|
const activePrompt = await this.aiPromptsService.getActive('ocr_extraction');
|
|
if (!activePrompt) {
|
|
throw new Error('ไม่พบ active prompt สำหรับ ocr_extraction');
|
|
}
|
|
return activePrompt.template.replace('{{ocr_text}}', ocrText);
|
|
}
|
|
```
|
|
|
|
- ทั้ง `processSandboxExtract` และ `processMigrateDocument` เรียก `resolvePrompt()` เดียวกัน
|
|
- `processSandboxExtract` auto-save ผล JSON ลงใน `active_prompt.test_result_json` + update `last_tested_at`
|
|
|
|
### 4. Ollama Timeout Fix
|
|
|
|
```typescript
|
|
// processSandboxExtract — ส่ง timeoutMs เฉพาะเพื่อแก้ bug timeout ครั้งที่ 2
|
|
const response = await this.ollamaService.generate(prompt, {
|
|
timeoutMs: 120000, // 2 นาที แทน default 30 วินาที
|
|
});
|
|
```
|
|
|
|
**Root cause ของ bug:** `AI_TIMEOUT_MS = 30000ms` — Ollama unload model จาก VRAM หลังจาก idle ระยะหนึ่ง (default keep_alive = 5 นาที แต่ VRAM pressure อาจเร็วกว่า) การรันครั้งที่สองต้องโหลด model ใหม่ ซึ่งใช้เวลา > 30 วินาที
|
|
|
|
### 5. API Endpoints ใน `ai.controller.ts`
|
|
|
|
| Method | Path | Action | Guard |
|
|
|--------|------|--------|-------|
|
|
| `GET` | `/ai/prompts/:type` | ดึง all versions ของ prompt_type (paginated) | `system.manage_all` |
|
|
| `POST` | `/ai/prompts/:type` | สร้าง version ใหม่ (validate `{{ocr_text}}`) | `system.manage_all` |
|
|
| `DELETE` | `/ai/prompts/:type/:version` | ลบ version (guard: ห้ามลบ active) | `system.manage_all` |
|
|
| `POST` | `/ai/prompts/:type/:version/activate` | Activate version ("นำไปใช้จริง") | `system.manage_all` |
|
|
| `PATCH` | `/ai/prompts/:type/:version/note` | บันทึก manual_note | `system.manage_all` |
|
|
|
|
### 6. UI/UX ใน OCR Sandbox Tab
|
|
|
|
Layout ใหม่ของ OCR Sandbox tab:
|
|
```
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ OCR Sandbox Playground │
|
|
├──────────────────────┬──────────────────────────────┤
|
|
│ Prompt Editor │ Version History │
|
|
│ ┌────────────────┐ │ ┌────────────────────────┐ │
|
|
│ │ textarea │ │ │ v3 (active) ✅ │ │
|
|
│ │ {{ocr_text}} │ │ │ v2 - 2026-05-24 │ │
|
|
│ │ ... │ │ │ v1 - 2026-05-22 │ │
|
|
│ └────────────────┘ │ └────────────────────────┘ │
|
|
│ [บันทึก Version ใหม่]│ [Load] [Activate] [Delete] │
|
|
├──────────────────────┴──────────────────────────────┤
|
|
│ File Upload: [เลือก PDF] │
|
|
│ [เริ่มทำ OCR Sandbox] │
|
|
├─────────────────────────────────────────────────────┤
|
|
│ ผลลัพธ์ JSON + [บันทึก Manual Note] │
|
|
└─────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
**Flow:**
|
|
1. เปิด tab → โหลด active version เข้า textarea อัตโนมัติ
|
|
2. Admin แก้ไข prompt → กด **"บันทึก Version ใหม่"** → สร้าง version ใหม่ (inactive)
|
|
3. Admin upload PDF → กด **"เริ่มทำ OCR Sandbox"** → รันด้วย active version
|
|
4. ผลลัพธ์ auto-save ลง active version's `test_result_json`
|
|
5. Admin ตรวจสอบผล → กด **"นำไปใช้จริง"** บน version ที่ต้องการ → activate
|
|
|
|
---
|
|
|
|
## ผลกระทบ (Consequences)
|
|
|
|
### ผลดี
|
|
- Admin ปรับ prompt ได้ real-time ไม่ต้อง redeploy
|
|
- Sandbox สะท้อนพฤติกรรม migrate-document ได้แม่นยำ (8 fields เหมือนกัน)
|
|
- Version history เปรียบเทียบผลลัพธ์ระหว่าง prompt versions ได้
|
|
- Bug timeout ได้รับการแก้ไข
|
|
|
|
### ผลเสีย / ข้อระวัง
|
|
- ถ้าไม่มี active prompt → processor throw error → ต้องมี seed data พร้อมก่อน deploy
|
|
- `processMigrateDocument` อาจเปลี่ยน prompt กลางชุด batch ถ้า admin activate ระหว่างที่ batch กำลังรัน — **acceptable tradeoff** เนื่องจาก batch มักสั้น และ admin ควร activate เมื่อไม่มี batch running
|
|
- เพิ่ม DB query ต่อ job (query active prompt) — **mitigate** ด้วย Redis cache TTL 60s สำหรับ active prompt
|
|
|
|
---
|
|
|
|
## Redis Cache Strategy สำหรับ Active Prompt
|
|
|
|
```
|
|
Key: ai:prompt:active:ocr_extraction
|
|
TTL: 60 วินาที
|
|
Invalidate: หลัง activate สำเร็จ (AiPromptsService.activate())
|
|
```
|
|
|
|
---
|
|
|
|
## Grilling Session Log
|
|
|
|
```
|
|
2026-05-25 — grilling session ผ่าน Devin Cascade
|
|
Q1: prompt_type scope → 'ocr_extraction' เดียว (8 fields) ร่วมกันทั้งคู่
|
|
Q2: activation model → Option A (single is_active flag)
|
|
Q3: result storage → Option C (auto-save + manual_note)
|
|
Q4: versioning → Option A (immutable, every save = new version, deletable)
|
|
Q5: template format → Option A ({{ocr_text}} placeholder, validated)
|
|
Bug: AI_TIMEOUT_MS 30s too short → fix: timeoutMs: 120000 for sandbox-extract
|
|
```
|