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

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õ

$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:

$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

$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:

$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

$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

$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 để 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`

4.5 KiB Raw Blame History