# 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)