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:

xác nhận SHA/image đang chạy đúng bản;
kiểm tra /health và /ready;
gửi smoke case qua web, gồm answerable có citation và abstain;
quan sát error rate, latency, provider failure và decision distribution;
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

Lấy trace_id, correlation_id, otel_trace_id từ response.
Tra rag_retrieval_trace để xem query, scope, intent, decision, reason, drug và citations.
Kiểm tra Prometheus request/stage duration, decision, provider failure và generation rejection.
Nếu OTel bật, tìm trace trong Tempo/Grafana để xác định stage chậm/lỗi.
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.

3.1 KiB Raw Blame History