Chat & Stream

POST /api/v1/chat · /api/v1/chat/stream (SSE) · feedback · suggestions — roles QTHT | CB | LD | AI_ADMIN

Phiên SSE stream

Gợi ý:

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

Chi tiết phiên

Chọn một phiên để xem lịch sử tin nhắn.

Tài liệu RAG

Upload → ingest → Qdrant; theo dõi trạng thái, reindex, xóa — /api/v1/admin/documents

Tệp Tiêu đề doc_type classification scope organization_id allowed_role_keys allowed_actor_types

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

Cập nhật template (tạo version mới)

name language template note

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/*

Insights (cửa sổ thời gian)

Audit — assistant messages

created_at	intent	degraded	tokens	message_id

Trace

Chọn một message rồi bấm “Trace”.

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á.

Tạo draft mới

asset_key kind title table_names aliases allowed_roles priority

asset_key	ver	kind	title	status	prio	roles

Đánh giá (Eval)

Retrieval recall/precision@K và acceptance suite Text2SQL — /api/v1/admin/eval/*

RAG retrieval eval

top_k

câu hỏi	expected_doc_ids (CSV)

Text2SQL acceptance suite

Kết quả

Chạy một suite để xem kết quả.

Benchmark & drift

Chạy 20 case benchmark (tag benchmark, chấm theo result set với golden SQL) — mất 5–8 phút.

Lịch sử run

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

Liên kết

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)

Quy ước chung

Mọi response JSON: envelope {statusCode, status, error[], data}
Auth: Authorization: Bearer <JWT HS256> — claims sub, 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/stream trả SSE — đọc bằng fetch() + ReadableStream

curl quickstart (bash)

Tham chiếu endpoint (bấm “test” để nhảy tới panel tương ứng)

method	path	roles	mô tả

Swagger UI (nhúng same-origin)

Health

GET /health (liveness) · GET /api/v1/health/ready (dependencies)