102 lines
5.0 KiB
Markdown
102 lines
5.0 KiB
Markdown
# HTTP API và decision reference
|
||
|
||
> Loại chính: Reference
|
||
> Backend local thường dùng: `http://localhost:8079`
|
||
|
||
## System endpoints
|
||
|
||
| Method | Path | Mục đích |
|
||
|---|---|---|
|
||
| GET | `/health` | process health |
|
||
| GET | `/ready` | runtime readiness |
|
||
| GET | `/metrics` | Prometheus metrics; có thể yêu cầu Bearer token |
|
||
|
||
## `POST /v1/rag/query`
|
||
|
||
Request:
|
||
|
||
| Field | Kiểu | Ràng buộc |
|
||
|---|---|---|
|
||
| `query` | string | bắt buộc, 1–4000 ký tự |
|
||
| `subject_scope` | enum | `human`, `non_human`, `unknown` |
|
||
| `intent` | enum | `fact_lookup`, `recommendation`, `unknown` |
|
||
| `conversation_id` | string/null | tối đa 128 ký tự |
|
||
| `response_mode` | enum | `ai` (mặc định, trả lời tổng hợp có generation) hoặc `monograph` (duyệt chuyên luận thô, xem `GET /v1/rag/sections` + `/section-text`) |
|
||
|
||
Response:
|
||
|
||
| Field | Ý nghĩa |
|
||
|---|---|
|
||
| `trace_id`, `correlation_id`, `otel_trace_id` | các định danh quan sát |
|
||
| `decision`, `reason` | kết quả policy và mã nguyên nhân |
|
||
| `answer`, `resolved_drug_id` | nội dung và thuốc đã resolve |
|
||
| `citations` | provenance evidence |
|
||
| `generated` | có dùng generator hay không |
|
||
| `quick_replies`, `blocks` | cấu trúc UI/claim |
|
||
| `answer_mode`, `answer_plan` | metadata trình bày |
|
||
| `candidate_assessments` | đánh giá candidate |
|
||
| `disclaimer` | cảnh báo cố định từ backend |
|
||
|
||
Citation có `chunk_id`, printed-page range, `physical_page`, `block_id`, `bbox`,
|
||
`source_crop`, `attachment`, `evidence_text`, drug, section và source document.
|
||
|
||
## `GET /v1/rag/history`
|
||
|
||
Feature-List #25. `conversation_id` bắt buộc (tối đa 128 ký tự) — không có auth
|
||
trong hệ thống nên endpoint chỉ trả về đúng conversation được truyền vào,
|
||
không có nghĩa "list toàn bộ"; rỗng/không truyền → trả `items: []`. Tối đa 50
|
||
dòng, mới nhất trước. Mỗi dòng là một truy vấn cũ (`trace_id`, `query`,
|
||
`decision`, `reason`, `resolved_drug_id`, `created_at`) để UI cho người dùng
|
||
bấm lại — **không** replay lại answer prose, vì answer không được lưu, chỉ
|
||
lưu trace.
|
||
|
||
## `GET /v1/rag/sections?drug_id=...`
|
||
|
||
Feature-List #4. Danh sách section thật có của một thuốc (không phải danh sách
|
||
cố định — đo trên corpus dao động 7–19 section/thuốc), mỗi phần tử có
|
||
`section_key` + `section_title`. Không LLM, đọc thẳng payload đã index;
|
||
`drug_id` không resolve được trả `sections: []`, không phải 404.
|
||
|
||
## `GET /v1/rag/section-text?drug_id=...§ion_key=...`
|
||
|
||
Feature-List #23. Text verbatim của một section, dùng cho `response_mode:
|
||
"monograph"` — không generation/entailment nên không cần validate. Trả
|
||
`parts[]` theo đúng thứ tự sách gốc; mỗi phần có `is_quarantined` — `true`
|
||
nghĩa là phần đó là bảng/công thức bị quarantine, `text` khi đó là câu mô tả
|
||
của chunker ("bảng, trang N...") chứ không phải nội dung bảng, và UI không
|
||
được hiển thị như một trích dẫn verbatim thật.
|
||
|
||
## Endpoint khác
|
||
|
||
- `GET /v1/rag/suggest?q=...`: trả `suggestions` autocomplete.
|
||
- `POST /v1/rag/feedback`: nhận UUID `trace_id`, rating `helpful` hoặc
|
||
`not_helpful`, comment tối đa 2000 ký tự và `conversation_id` tối đa 128 ký tự.
|
||
|
||
Browser gọi BFF `/api/chat`. BFF dùng `API_GATEWAY_URL`, fallback `AI_SERVICE_URL`,
|
||
sau đó `http://localhost:8000`, và map snake_case backend sang shared TypeScript DTO.
|
||
|
||
## Decision và reason
|
||
|
||
| Decision | Hành vi |
|
||
|---|---|
|
||
| `answerable` | hiển thị answer đã kiểm chứng |
|
||
| `clarify` | hỏi thêm thông tin, dùng quick replies nếu có |
|
||
| `verify_pdf` | hiển thị nguồn và yêu cầu đối chiếu PDF |
|
||
| `abstain` | không phát hành answer chuyên môn |
|
||
|
||
| Nhóm reason | Ví dụ |
|
||
|---|---|
|
||
| resolve/input | `drug_not_resolved`, `drug_resolution_ambiguous`, `missing_query_or_drug`, `missing_indication` |
|
||
| scope/intent | `recommendation_out_of_scope`, `out_of_scope_non_human`, `subject_scope_unknown`, `query_intent_unknown`, `out_of_scope` |
|
||
| clarify | `no_drug`, `missing_attribute`, `missing_population`, `missing_pediatric_age_or_weight`, `needs_more_info`, `ambiguous_condition` |
|
||
| retrieval | `query_embedding_unavailable`, `insufficient_retrieval_score`, `no_indication_match`, `no_interaction_evidence`, `parent_hydration_failed` |
|
||
| provenance | `missing_provenance`, `missing_printed_page_provenance` |
|
||
| provider/budget | `provider_unavailable`, `understanding_provider_unavailable`, `request_budget_exhausted`, `malformed_output` |
|
||
| grounding | `evidence_insufficient`, `ungrounded_number`, `invalid_citation`, `uncited_claim`, `unsupported_claim`, `unsupported_drug`, `incomplete_answer` |
|
||
| circuit/relation | `clarify_loop_exhausted`, `unsupported_reverse_relation` |
|
||
| fallback | `generation_unavailable` |
|
||
|
||
Reason code là contract giữa backend, BFF và metric. Không collapse provider hoặc
|
||
grounding error thành “không có dữ liệu”.
|
||
|