138 lines
4.6 KiB
Markdown
138 lines
4.6 KiB
Markdown
# Intent Classification API Playbook
|
|
|
|
## Overview
|
|
|
|
ระบบ Intent Classification ใช้ Hybrid Strategy: Pattern Matching (keyword/regex) → LLM Fallback (Ollama) → FALLBACK intent
|
|
|
|
## API Endpoints
|
|
|
|
### Classification
|
|
|
|
| Method | Endpoint | Auth | Rate Limit | Description |
|
|
|--------|----------|------|------------|-------------|
|
|
| POST | `/ai/intent/classify` | JWT | 30/min | จำแนก Intent จาก query |
|
|
|
|
**Request:**
|
|
```json
|
|
{
|
|
"query": "สรุปเอกสารนี้ให้หน่อย",
|
|
"projectPublicId": "019505a1-...",
|
|
"userPublicId": "019505a1-...",
|
|
"currentDocumentId": "019505a1-..."
|
|
}
|
|
```
|
|
|
|
**Response:**
|
|
```json
|
|
{
|
|
"intentCode": "SUMMARIZE_DOCUMENT",
|
|
"confidence": 1.0,
|
|
"method": "pattern",
|
|
"latencyMs": 3
|
|
}
|
|
```
|
|
|
|
### Admin — Intent Definitions
|
|
|
|
| Method | Endpoint | Auth | Description |
|
|
|--------|----------|------|-------------|
|
|
| GET | `/admin/ai/intent-definitions` | JWT + RBAC | รายการ Intent Definitions |
|
|
| GET | `/admin/ai/intent-definitions/:intentCode` | JWT + RBAC | Intent ตาม code |
|
|
| POST | `/admin/ai/intent-definitions` | JWT + RBAC | สร้าง Intent ใหม่ |
|
|
| PATCH | `/admin/ai/intent-definitions/:intentCode` | JWT + RBAC | อัปเดต Intent |
|
|
|
|
**Query Parameters (GET all):**
|
|
- `category`: `read` | `suggest` | `utility`
|
|
- `isActive`: `true` | `false`
|
|
|
|
### Admin — Intent Patterns
|
|
|
|
| Method | Endpoint | Auth | Description |
|
|
|--------|----------|------|-------------|
|
|
| GET | `/admin/ai/intent-definitions/:code/patterns` | JWT + RBAC | Patterns ของ Intent |
|
|
| POST | `/admin/ai/intent-definitions/:code/patterns` | JWT + RBAC | สร้าง Pattern |
|
|
| GET | `/admin/ai/intent-patterns/:publicId` | JWT + RBAC | Pattern ตาม UUID |
|
|
| PATCH | `/admin/ai/intent-patterns/:publicId` | JWT + RBAC | อัปเดต Pattern |
|
|
| DELETE | `/admin/ai/intent-patterns/:publicId` | JWT + RBAC | Soft delete |
|
|
|
|
---
|
|
|
|
## Classification Methods
|
|
|
|
| Method | Description | Confidence | Latency |
|
|
|--------|-------------|------------|---------|
|
|
| `pattern` | Keyword/regex match | 1.0 | < 10ms |
|
|
| `llm_fallback` | Ollama LLM classification | 0.4-1.0 | < 2000ms |
|
|
| `semaphore_overflow` | LLM queue full | 0 | < 10ms |
|
|
| `llm_error` | LLM unavailable/timeout | 0 | < 5000ms |
|
|
|
|
---
|
|
|
|
## 12 Standard Intents (v1)
|
|
|
|
| Intent Code | Category | Description (TH) |
|
|
|-------------|----------|-------------------|
|
|
| RAG_QUERY | read | ถามคำถามธรรมชาติ ตอบจาก vector + doc context |
|
|
| GET_RFA | read | ดึง RFA ตาม filter |
|
|
| GET_DRAWING | read | ดึง Drawing revision |
|
|
| GET_TRANSMITTAL | read | ดึง Transmittal |
|
|
| GET_CORRESPONDENCE | read | ดึง Correspondence ทั่วไป |
|
|
| GET_CIRCULATION | read | ดึง Circulation |
|
|
| GET_RFA_DRAWINGS | read | ดึง Drawings ที่ผูกกับ RFA |
|
|
| SUMMARIZE_DOCUMENT | read | สรุปเอกสารที่เปิดอยู่ |
|
|
| LIST_OVERDUE | read | รายการ cross-entity ที่เกินกำหนด |
|
|
| SUGGEST_METADATA | suggest | แนะนำ metadata สำหรับเอกสาร |
|
|
| SUGGEST_ACTION | suggest | แจ้งเตือนว่าควรทำอะไรต่อ |
|
|
| FALLBACK | utility | ไม่เข้า intent ไหน / ไม่เกี่ยวกับระบบ |
|
|
|
|
---
|
|
|
|
## Cache Strategy
|
|
|
|
- **Key**: `ai:intent:patterns:active`
|
|
- **TTL**: 300 seconds
|
|
- **Invalidation**: Auto on admin CRUD (create/update/delete pattern)
|
|
- **Fallback**: DB query if Redis unavailable
|
|
|
|
---
|
|
|
|
## Semaphore (LLM Concurrency Control)
|
|
|
|
- **Max concurrent**: 3 (configurable via `INTENT_LLM_MAX_CONCURRENT`)
|
|
- **Behavior on full**: Return `FALLBACK` with method `semaphore_overflow`
|
|
- **Pattern**: Promise-based queue with idempotent release
|
|
|
|
---
|
|
|
|
## Configuration (Environment Variables)
|
|
|
|
```env
|
|
# Ollama
|
|
OLLAMA_BASE_URL=http://192.168.10.5:11434
|
|
OLLAMA_MODEL=gemma4:e4b
|
|
|
|
# Intent Classification
|
|
INTENT_LLM_MAX_CONCURRENT=3
|
|
INTENT_LLM_TIMEOUT_MS=5000
|
|
INTENT_CACHE_TTL_SECONDS=300
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
| Problem | Cause | Solution |
|
|
|---------|-------|----------|
|
|
| All queries return FALLBACK | Redis empty + LLM down | Check Redis + Ollama status |
|
|
| High latency (> 2s) | LLM overloaded | Increase semaphore or add patterns |
|
|
| Pattern not matching | Cache stale | Wait TTL (5min) or restart |
|
|
| 429 Too Many Requests | Rate limit exceeded | Wait 60s or reduce frequency |
|
|
|
|
---
|
|
|
|
## Related
|
|
|
|
- ADR-024: Intent Classification Strategy
|
|
- ADR-023A: Unified AI Architecture (Model Revision)
|
|
- Feature spec: `specs/200-fullstacks/224-intent-classification/spec.md`
|