# Vận hành, triển khai và xử lý sự cố

> Loại chính: How-to  
> Phạm vi: EC2 + Docker Compose hiện hành

## Deploy

Trước deploy, ghi commit SHA, yêu cầu CI AI/ingestion/web xanh, kiểm tra secret và
Qdrant manifest tương thích, đồng thời đánh giá migration. Chạy `deploy.yml` theo
path/branch filter hoặc manual dispatch và theo dõi đến khi reconcile xong.

Sau deploy:

1. xác nhận SHA/image đang chạy đúng bản;
2. kiểm tra `/health` và `/ready`;
3. gửi smoke case qua web, gồm answerable có citation và abstain;
4. quan sát error rate, latency, provider failure và decision distribution;
5. ghi lại thời điểm, SHA và kết quả.

CI và deploy độc lập về kỹ thuật; trạng thái CI đỏ không tự động chặn deploy.

## Rollback

Workflow `rollback.yml` nhận `target_sha`. Chọn SHA từng deploy thành công và còn
tương thích với database/corpus. Sau rollback phải xác nhận SHA, health/readiness,
smoke cases và metric qua đủ cửa sổ để thấy lỗi ban đầu biến mất.

Rollback code không tự rollback Qdrant corpus hoặc database migration. Với corpus,
dùng snapshot/migration riêng; không rollback dữ liệu phá huỷ khi chưa có backup.

## Theo dấu request

1. Lấy `trace_id`, `correlation_id`, `otel_trace_id` từ response.
2. Tra `rag_retrieval_trace` để xem query, scope, intent, decision, reason, drug và citations.
3. Kiểm tra Prometheus request/stage duration, decision, provider failure và generation rejection.
4. Nếu OTel bật, tìm trace trong Tempo/Grafana để xác định stage chậm/lỗi.
5. Phân loại nguyên nhân: input/scope, corpus/retrieval, provider/model hoặc grounding.

`/metrics` có thể yêu cầu `Authorization: Bearer <token>` khi `METRICS_TOKEN` được đặt.

## Observability stack

Local stack là Prometheus, OpenTelemetry Collector, Tempo và Grafana. OTel mặc định
tắt. Observability failure không được làm service dừng trả lời; trace write failure
phải xuất hiện trong metric/log. Production monitoring cần readiness và synthetic
query vì health không chứng minh citation pipeline hoạt động end-to-end.

## Troubleshooting

| Triệu chứng | Kiểm tra đầu tiên | Không nên làm |
|---|---|---|
| service không ready | datastore, startup log, manifest/model/dimensions | bỏ qua manifest gate |
| `provider_unavailable` tăng | region, credential, quota, network, stage trace | báo “Dược thư không có dữ liệu” |
| retrieval score thấp | drug/section route, collection và manifest | hạ threshold không qua eval |
| grounding rejection tăng | evidence packet, model output, validator | hiển thị raw output |
| clarify lặp | history, field thiếu, circuit breaker | tăng loop vô hạn |
| citation sai trang | printed-page map, chunk payload, quarantine | thay printed page bằng physical page |

Các reason grounding quan trọng gồm `ungrounded_number`, `invalid_citation`,
`uncited_claim`, `unsupported_claim` và `incomplete_answer`. Giữ fail-closed và
thêm regression test trước khi sửa prompt/parser/validator.