Chat & Stream
POST /api/v1/chat · /api/v1/chat/stream (SSE) · feedback · suggestions — roles QTHT | CB | LD | AI_ADMIN
Phiên trò chuyện
CRUD /api/v1/sessions — tạo, xem lịch sử, đổi tên, xóa
| Tiêu đề | session_id | cập nhật |
|---|
Tài liệu RAG
Upload → ingest → Qdrant; theo dõi trạng thái, reindex, xóa — /api/v1/admin/documents
| title | status | chunks | type | classification | error |
|---|
Schema curation
Mô tả tiếng Việt + allowed_roles cho từng cột — /api/v1/admin/schema
| database | table | column | description_vi | allowed_roles |
|---|
Prompts
Phiên bản template kịch hoạt — PUT /api/v1/admin/prompts/{name} tạo version mới
| name | language | version | active |
|---|
Audit & Insights
Giám sát chất lượng câu trả lời: insights aggregation + trace từng answer — /api/v1/admin/insights, /audit/*
| created_at | intent | degraded | tokens | message_id |
|---|
Knowledge Text2SQL
Vòng đời asset: draft → validate → publish → retire; index Qdrant — /api/v1/admin/text2sql/knowledge. sql_example với trusted: true + parameters (slot {name} trong question/SQL) được phục vụ nguyên văn như câu trả lời đã kiểm chứng; measure có thể khai báo expression + dimensions chuẩn hoá.
| asset_key | ver | kind | title | status | prio | roles |
|---|
Đánh giá (Eval)
Retrieval recall/precision@K và acceptance suite Text2SQL — /api/v1/admin/eval/*
| câu hỏi | expected_doc_ids (CSV) |
|---|
Chạy 20 case benchmark (tag benchmark, chấm theo result set với golden SQL) — mất 5–8 phút.
| thời gian | tổng | pass | tỉ lệ | note |
|---|
API & Tài liệu ghép nối
Swagger / ReDoc / OpenAPI spec, bảng tham chiếu endpoint và curl quickstart cho bên tích hợp
- Swagger UI ↗ — thử từng endpoint kèm token
- ReDoc ↗ — bản đọc
- openapi.json ↗ — import vào Postman/Insomnia/codegen
docs/15-api-integration-guide.md— hướng dẫn ghép nối chi tiết (tiếng Việt)docs/08-api-contracts.md— contract thiết kế (envelope, SSE, RBAC)
- Mọi response JSON: envelope
{statusCode, status, error[], data} - Auth:
Authorization: Bearer <JWT HS256>— claimssub,email,roles[] - Agent endpoints: roles
QTHT | CB | LD | AI_ADMIN· Admin:QTHT | AI_ADMIN - Phân trang: query
page,page_size→data.metadata - Stream:
POST /api/v1/chat/streamtrả SSE — đọc bằngfetch()+ReadableStream
data.output trên chat / SSE done / history- Mỗi câu trả lời DATA/DOC kèm output document bất biến (OutputEnvelope v1.0):
blocks[]+resources+references+actions, persist vào history nên one-shot, SSEdonevàGET /sessions/{id}trả cùng một JSON blocks[]:text(role: answer/npv/out_of_scope/permission_refusal/clarification),data_view(view:table | chart | kpi | timeline | checklisttrỏ tới dataset resource),group; blockfallbacktự kích hoạt khi view không hợp lệ — client chỉ cần render theoroot_block_idsthứ tựanswer_outcome:answer | out_of_scope | permission_refusal(scope=all|partial) | clarification— phân nhánh UI bằng máy; full refusal/out_of_scope không kèm resources/actionsfollowups[](tối đa 3): chip gợi ý{id,label,prompt}— chỉ prefill ô hỏi, không auto-send; không phải actioncharts(partner v1): gần Chart.js —labels + datasets, whitelist đóngid/title/type/data/source_refs/truncated, cấm mọi presentation/callback; derive deterministic từ SQL rowsactions: chỉ read-onlydrill_down— replay SQL đã guard kèm binding server-private; token TTL 24 giờ, thiếu/sai binding → 404 generic- Raw SQL và secret không bao giờ xuất hiện trong envelope; số liệu do pipeline deterministic tổng hợp, LLM không tự bịa số
| method | path | roles | mô tả |
|---|
Health
GET /health (liveness) · GET /api/v1/health/ready (dependencies)