Add read-only production runtime audit

2026-08-17 11:17:40 +07:00
parent 057d4ed9dc
commit a1de4715a4
106 changed files with 6869 additions and 1782 deletions
@@ -0,0 +1,168 @@
+# Cách rebuild và publish corpus Qdrant
+
+## Phân loại
+
+**Loại tài liệu:** How-to.
+
+**Reader job:** tạo corpus mới từ PDF đã thay đổi và đưa nó vào một collection
+mới mà vẫn có đường rollback.
+
+## Khi nào dùng hướng dẫn này
+
+Chỉ rebuild khi PDF, parsing, segmentation, chunk schema hoặc chunk text thay
+đổi. Nếu chỉ chuyển corpus không đổi sang máy khác, dùng Qdrant snapshot/restore;
+không re-embed.
+
+Embedding gọi AWS Bedrock và tốn chi phí. Cần có phê duyệt cụ thể trước bước
+embed/load. Các bước parser và validation local không gọi cloud.
+
+## Điều kiện tiên quyết
+
+- Python và dependencies của `ingestion/` đã cài.
+- PDF nguồn tồn tại tại `ingestion/data/raw/`.
+- Có đủ dung lượng cho artifact trong `ingestion/data/processed/`.
+- Nếu publish: Qdrant target và AWS credentials đã xác định rõ.
+- Đã chọn **collection mới**, ví dụ `duocthu_v2`; không ghi corpus khác vào
+  `duocthu_v1`.
+
+## Bước 1 — Xác định input và lưu baseline
+
+```powershell
+Set-Location ingestion
+Get-FileHash data/raw/duoc-thu-quoc-gia-viet-nam-2018.pdf -Algorithm SHA256
+```
+
+Ghi lại SHA của PDF, commit code, collection hiện tại và count point hiện tại.
+Đây là baseline để audit và rollback.
+
+## Bước 2 — Phát hiện vùng bảng
+
+```powershell
+python -m ingestion.cli detect-tables `
+  --pdf data/raw/duoc-thu-quoc-gia-viet-nam-2018.pdf `
+  --out data/processed/table_regions.json
+```
+
+Bước này chậm. Tái sử dụng artifact nếu PDF và detector không đổi.
+
+## Bước 3 — Extract và segment
+
+```powershell
+python -m ingestion.cli run `
+  --pdf data/raw/duoc-thu-quoc-gia-viet-nam-2018.pdf `
+  --tables data/processed/table_regions.json `
+  --out data/processed/monographs.jsonl
+```
+
+Không bỏ qua lỗi duplicate drug ID hoặc lỗi parsing. Pipeline chủ đích dừng thay
+vì tự merge hai chuyên luận không chắc chắn.
+
+## Bước 4 — Tạo chunk
+
+```powershell
+python -m ingestion.cli chunk `
+  --pdf data/raw/duoc-thu-quoc-gia-viet-nam-2018.pdf `
+  --monographs data/processed/monographs.jsonl `
+  --tables data/processed/table_regions.json `
+  --out data/processed/chunks.jsonl
+```
+
+Chunking yêu cầu page map để mọi record có printed-page provenance.
+
+## Bước 5 — Chạy acceptance gates
+
+```powershell
+python -m ingestion.cli chunk-ready `
+  --monographs data/processed/monographs.jsonl `
+  --chunks data/processed/chunks.jsonl
+```
+
+Chỉ tiếp tục khi exit code bằng `0`. Gate fail không phải cảnh báo để bỏ qua;
+nó cho biết corpus chưa được phép embedding.
+
+Chạy thêm diagnostics khi parsing thay đổi:
+
+```powershell
+python -m ingestion.cli validate `
+  --pdf data/raw/duoc-thu-quoc-gia-viet-nam-2018.pdf `
+  --tables data/processed/table_regions.json
+
+python -m ingestion.cli coverage `
+  --pdf data/raw/duoc-thu-quoc-gia-viet-nam-2018.pdf `
+  --tables data/processed/table_regions.json
+
+python -m ingestion.cli residual-ink `
+  --pdf data/raw/duoc-thu-quoc-gia-viet-nam-2018.pdf `
+  --tables data/processed/table_regions.json
+```
+
+## Bước 6 — Review diff corpus
+
+So sánh ít nhất:
+
+- số monograph và drug ID;
+- số chunk theo `chunk_kind` và `section_key`;
+- số chunk oversized;
+- số block quarantine;
+- SHA-256 của `chunks.jsonl`;
+- các gate count so với baseline.
+
+Một thay đổi count lớn không được giải thích là lý do dừng trước cloud spend.
+
+## Bước 7 — Embed-only trước khi ghi store
+
+Chỉ chạy sau khi được phê duyệt:
+
+```powershell
+python -m ingestion.load.run `
+  --chunks data/processed/chunks.jsonl `
+  --provider cohere-v4 `
+  --collection duocthu_v2 `
+  --qdrant-url http://localhost:6333 `
+  --embed-only
+```
+
+Embedding cache dùng content hash nên chunk không đổi được tái sử dụng.
+
+## Bước 8 — Load vào collection mới
+
+```powershell
+python -m ingestion.load.run `
+  --chunks data/processed/chunks.jsonl `
+  --provider cohere-v4 `
+  --collection duocthu_v2 `
+  --qdrant-url http://localhost:6333
+```
+
+Loader kiểm tra manifest compatibility, vector dimension và point count. Không
+xóa collection cũ sau bước này.
+
+## Bước 9 — Verify runtime với collection mới
+
+1. Đặt `QDRANT_COLLECTION=duocthu_v2` trên staging/local.
+2. Restart `ai-service`; startup manifest check phải pass.
+3. Chạy health/readiness.
+4. Chạy routing, grounding và manual battery phù hợp.
+5. Review citation page và quarantine case.
+
+## Rollback
+
+Đặt lại `QDRANT_COLLECTION` về collection cũ và restart `ai-service`. Vì publish
+dùng tên mới, rollback không cần sửa dữ liệu. Chỉ xóa collection cũ sau thời gian
+quan sát và khi có snapshot đã kiểm tra restore.
+
+## Troubleshooting
+
+| Lỗi | Nguyên nhân thường gặp | Cách xử lý |
+|---|---|---|
+| `CorpusMismatch` | Dùng lại collection cho corpus/model khác | Chọn collection mới; không bypass manifest |
+| Missing printed page | Page map không xác định được provenance | Sửa extraction/page map rồi chunk lại |
+| Vector dimension mismatch | Provider/config khác manifest | Dùng đúng model hoặc collection khác |
+| Count gate fail | Upsert chưa đủ hoặc collection có point ngoài corpus | Dừng publish và kiểm tra report |
+
+## Liên quan
+
+- [Ingestion pipeline](../04-ingestion-pipeline.md)
+- [Document parsing](../05-document-parsing.md)
+- [Chunk schema](../06-document-model-and-chunking.md)
+- [Indexing and storage](../07-indexing-and-storage.md)