111 lines
3.5 KiB
Markdown
111 lines
3.5 KiB
Markdown
# Cách lần một request từ người dùng đến evidence
|
|
|
|
## Phân loại
|
|
|
|
**Loại tài liệu:** How-to.
|
|
|
|
**Reader job:** điều tra một câu trả lời chậm, abstain hoặc có citation đáng ngờ
|
|
bằng correlation ID, PostgreSQL, Tempo và Prometheus.
|
|
|
|
## Điều kiện tiên quyết
|
|
|
|
- Có ít nhất một trong ba giá trị: `trace_id`, `correlation_id`, `otel_trace_id`.
|
|
- Có quyền đọc PostgreSQL và Grafana/Tempo production.
|
|
- Biết khoảng thời gian request.
|
|
|
|
Không đưa nội dung query hoặc dữ liệu người dùng vào ticket công khai.
|
|
|
|
## Bước 1 — Thu ID từ response
|
|
|
|
API body trả:
|
|
|
|
```text
|
|
trace_id
|
|
correlation_id
|
|
otel_trace_id
|
|
decision
|
|
reason
|
|
```
|
|
|
|
Headers cũng có `X-Correlation-ID` và `X-Trace-ID`. Ưu tiên giữ cả body lẫn
|
|
headers để phát hiện proxy/version mismatch.
|
|
|
|
## Bước 2 — Tìm business trace trong PostgreSQL
|
|
|
|
```sql
|
|
SELECT created_at, query_text, subject_scope, query_intent, decision, reason,
|
|
resolved_drug_id, citations, correlation_id, otel_trace_id
|
|
FROM rag_retrieval_trace
|
|
WHERE trace_id = '<trace_id>'
|
|
OR correlation_id = '<correlation_id>'
|
|
OR otel_trace_id = '<otel_trace_id>'
|
|
ORDER BY created_at DESC;
|
|
```
|
|
|
|
Xác nhận server đã resolve thuốc nào, decision/reason nào và citation nào thực sự
|
|
được lưu. Không dựa riêng vào UI text.
|
|
|
|
## Bước 3 — Mở distributed trace
|
|
|
|
Trong Grafana → Explore → Tempo, tìm `otel_trace_id`. Đọc các span:
|
|
|
|
- receive;
|
|
- understanding;
|
|
- routing/retrieval;
|
|
- generation;
|
|
- grounding/entailment;
|
|
- persistence;
|
|
- response.
|
|
|
|
Xác định stage chiếm thời gian hoặc stage không xuất hiện. Provider call đang
|
|
chạy không bị RequestBudget hủy giữa chừng; tổng latency có thể vượt budget bởi
|
|
một call đã in-flight.
|
|
|
|
## Bước 4 — Đối chiếu metrics
|
|
|
|
Trong cùng time window, kiểm tra:
|
|
|
|
```promql
|
|
duocthu_requests_total
|
|
duocthu_abstention_total
|
|
duocthu_generation_rejected_total
|
|
duocthu_stage_duration_seconds
|
|
```
|
|
|
|
Reason label giúp phân biệt availability failure (`provider_unavailable`,
|
|
`request_budget_exhausted`) với content/grounding failure
|
|
(`unsupported_claim`, `ungrounded_number`).
|
|
|
|
## Bước 5 — Kiểm tra citation về source
|
|
|
|
Với từng citation:
|
|
|
|
1. lấy `chunk_id`, `drug_id`, `section_key` và `evidence_text`;
|
|
2. xác nhận claim trỏ đúng thuốc và đúng section;
|
|
3. mở `printed_page_start` trong PDF;
|
|
4. nếu có attachment/bbox/crop, review ảnh gốc;
|
|
5. nếu block quarantine, không cố suy số từ text flatten.
|
|
|
|
## Bước 6 — Phân loại kết luận
|
|
|
|
| Kết luận | Bằng chứng cần có |
|
|
|---|---|
|
|
| Retrieval sai | Resolved frame đúng nhưng evidence sai section/drug |
|
|
| Understanding sai | QueryFrame/route chọn sai thuốc, relation hoặc population |
|
|
| Provider outage | Span/provider error và metric availability tương ứng |
|
|
| Grounding reject đúng | Generated claim vi phạm citation/number/entailment |
|
|
| UI mapping sai | Backend response đúng nhưng message/citation render sai |
|
|
| Trace persistence lỗi | Answer trả được nhưng không có PostgreSQL record |
|
|
|
|
## Verify
|
|
|
|
Một incident note hoàn chỉnh phải ghi ID, commit/deployment version, decision,
|
|
reason, stage gây lỗi, evidence/citation liên quan và recovery đã thực hiện.
|
|
|
|
## Liên quan
|
|
|
|
- [Observability reference](../17-observability.md)
|
|
- [Production operations](../24-production-operations.md)
|
|
- [Generation and grounding](../11-generation-and-grounding.md)
|
|
- [Troubleshooting](../25-troubleshooting.md)
|