Add read-only production runtime audit

2026-08-17 11:17:40 +07:00
parent 057d4ed9dc
commit a1de4715a4
106 changed files with 6869 additions and 1782 deletions
@@ -0,0 +1,140 @@
+# Theo một câu hỏi từ API đến trang PDF nguồn
+
+## Phân loại
+
+**Loại tài liệu:** Tutorial.
+
+**Reader job:** học mental model của hệ thống bằng cách gửi một query, đọc
+decision và lần citation về nguồn.
+
+**Kết quả:** bạn phân biệt được answer, evidence, citation và trace.
+
+## Trước khi bắt đầu
+
+Bạn cần một `ai-service` đang chạy đầy đủ với:
+
+- Qdrant có collection và manifest tương thích;
+- PostgreSQL đã migrate;
+- query embedding và answer provider đã cấu hình;
+- endpoint `http://localhost:8000` truy cập được.
+
+Nếu chưa có môi trường, làm theo [Local development](../23-local-development.md).
+Tutorial này không hướng dẫn re-embed corpus vì bước đó tốn chi phí Bedrock.
+
+## Bước 1 — Kiểm tra service
+
+```powershell
+Invoke-RestMethod http://localhost:8000/health
+Invoke-RestMethod http://localhost:8000/ready
+```
+
+Cả hai request cần trả HTTP `200`. `/health` chỉ chứng minh tiến trình sống;
+`/ready` mới là tín hiệu runtime đã sẵn sàng theo cấu hình hiện tại.
+
+## Bước 2 — Gửi một câu hỏi có section rõ
+
+```powershell
+$body = @{
+  query = 'Chống chỉ định của aspirin là gì?'
+  subject_scope = 'human'
+  intent = 'fact_lookup'
+  conversation_id = 'tutorial-first-query'
+} | ConvertTo-Json
+
+$response = Invoke-RestMethod `
+  -Method Post `
+  -Uri http://localhost:8000/v1/rag/query `
+  -ContentType 'application/json; charset=utf-8' `
+  -Body $body
+
+$response | ConvertTo-Json -Depth 8
+```
+
+Kết quả không được đánh giá chỉ bằng việc “có text”. Trước tiên xem:
+
+```powershell
+$response.decision
+$response.reason
+$response.resolved_drug_id
+$response.generated
+```
+
+Một lượt thành công thường có `decision=answerable`. `generated=true` nghĩa là
+LLM paraphrase đã qua grounding; `false` có thể là extractive mode khi generator
+bị tắt có chủ đích.
+
+## Bước 3 — Kiểm tra citation binding
+
+```powershell
+$response.citations | Select-Object `
+  chunk_id, drug_id, section_key, printed_page_start, printed_page_end
+```
+
+Với câu hỏi này, citation phải thuộc thuốc aspirin và section
+`chong_chi_dinh`. `printed_page_start` là số trang in trên sách; `physical_page`
+là index trang trong file PDF và phục vụ viewer.
+
+Đọc evidence thật:
+
+```powershell
+$response.citations | Select-Object -ExpandProperty evidence_text
+```
+
+So claim trong `answer` với `evidence_text`. Các con số trong claim phải xuất
+hiện nguyên văn trong đúng block mà claim trích dẫn; đây là điều
+`rag/grounding.py` kiểm tra bằng code.
+
+## Bước 4 — Nhìn cấu trúc trình bày đã kiểm chứng
+
+```powershell
+$response.blocks | ConvertTo-Json -Depth 6
+$response.answer_plan | ConvertTo-Json -Depth 4
+```
+
+`blocks` được dựng từ section của citation sau verification. Chúng không phải
+heading tự do mà model tự nghĩ ra. `answer_plan` điều khiển layout/verbosity,
+không phải evidence y khoa.
+
+## Bước 5 — Giữ trace ID
+
+```powershell
+$response.trace_id
+$response.correlation_id
+$response.otel_trace_id
+```
+
+Ba ID phục vụ các lớp khác nhau:
+
+- `trace_id`: bản ghi nghiệp vụ trong PostgreSQL;
+- `correlation_id`: nối request giữa web và ai-service;
+- `otel_trace_id`: tìm trace kỹ thuật trong Tempo.
+
+Tiếp tục với [How to trace a request](../how-to/trace-a-request.md) để theo request
+qua understanding, retrieval, generation và entailment.
+
+## Kiểm tra kết quả
+
+Bạn đã hoàn thành tutorial khi xác nhận được:
+
+- service ready;
+- query có decision/reason rõ;
+- thuốc được resolve đúng;
+- citation thuộc đúng section;
+- evidence có trang in;
+- trace/correlation ID tồn tại.
+
+## Khi kết quả khác kỳ vọng
+
+| Hiện tượng | Ý nghĩa đầu tiên cần kiểm tra |
+|---|---|
+| HTTP 503 | Runtime chưa cấu hình retrieval hoặc manifest/provider lỗi |
+| `clarify` | Query understanding cần thêm dữ kiện; đây không phải lỗi |
+| `abstain` | Đọc `reason`, không suy diễn thành “không có trong sách” |
+| `verify_pdf` | Evidence có bảng/công thức cần xem ảnh nguồn |
+| Không có citation | Answer không được coi là grounded; xem `decision` và `reason` |
+
+## Tiếp theo
+
+- [Hiểu structured RAG](../explanation/why-structured-rag.md)
+- [API reference](../12-api-architecture.md)
+- [Generation and grounding](../11-generation-and-grounding.md)