63 lines
3.1 KiB
Markdown
63 lines
3.1 KiB
Markdown
# 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.
|
|
|