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,80 @@
+# Pipeline PDF và xây dựng corpus
+
+> Loại chính: Explanation, kèm runbook xây corpus  
+> Đối tượng: data/RAG engineer
+
+## Logic end-to-end
+
+1. Pipeline đọc PDF theo layout, phát hiện glyph order, cột, heading, bảng và
+   công thức.
+2. Span được sửa thứ tự đọc rồi gắn vào monograph thuốc và section chuẩn.
+3. Mapping physical page → printed page được giữ riêng để tạo citation đúng.
+4. Bảng/công thức 2D được quarantine thành attachment và descriptor; cell value
+   chưa kiểm chứng không đi vào prose.
+5. Monograph được chia theo drug + section + ngữ nghĩa, giữ context label cho liều,
+   đối tượng và đường dùng.
+6. Chunks được embed theo `search_document`, cache theo model/input kind và upsert
+   Qdrant bằng UUID ổn định từ `chunk_id`.
+7. Sidecar manifest ghi hash corpus, model, dimensions và count. Query runtime từ
+   chối startup nếu manifest không tương thích.
+
+## Các cổng chất lượng
+
+- `validate`: đối chiếu recall/precision toàn sách với index.
+- `coverage`: ghi ledger mỗi span đã đi đâu.
+- `residual-ink`: phát hiện nét mực chưa được span giải thích; gate mục tiêu là
+  không còn residual chưa phân loại.
+- `chunk-ready`: kiểm tra điều kiện trước khi corpus được coi là sẵn sàng.
+- Table/formula quarantine: buộc response dùng `verify_pdf` khi evidence phụ thuộc
+  vùng chưa đủ an toàn.
+
+## Xây lại corpus
+
+> Embedding toàn corpus có thể phát sinh chi phí AWS. Không chạy bước cloud khi
+> chưa được duyệt chi phí và collection đích.
+
+Từ thư mục `ingestion`:
+
+```powershell
+python -m ingestion.cli detect-tables --pdf data/raw/source.pdf
+python -m ingestion.cli run --pdf data/raw/source.pdf
+python -m ingestion.cli validate --pdf data/raw/source.pdf
+python -m ingestion.cli coverage --pdf data/raw/source.pdf
+python -m ingestion.cli residual-ink --pdf data/raw/source.pdf
+python -m ingestion.cli chunk --pdf data/raw/source.pdf
+python -m ingestion.cli chunk-ready
+```
+
+Điều tra regression coverage và residual chưa phân loại trước khi embed. Chạy
+`--embed-only` để tạo/kiểm tra cache trước:
+
+```powershell
+python -m ingestion.load.run `
+  --provider cohere-v4 `
+  --collection duocthu_v1_next `
+  --region us-east-1 `
+  --embed-only
+```
+
+Sau khi duyệt, bỏ `--embed-only` để load collection mới. Khởi động ai-service với
+collection đó, yêu cầu manifest check pass, rồi chạy eval trước khi chuyển traffic.
+Không ghi đè corpus production hoặc xoá collection cũ mà chưa có snapshot.
+
+## CLI reference
+
+| Subcommand | Tham số chính | Trạng thái |
+|---|---|---|
+| `run` | `--pdf` bắt buộc, `--out`, `--tables` | hoạt động |
+| `validate` | `--pdf`, `--tables` | hoạt động |
+| `detect-tables` | `--pdf`, `--out` | hoạt động, chậm, có cache |
+| `coverage` | `--pdf`, `--tables`, `--out` | hoạt động |
+| `residual-ink` | `--pdf`, `--tables`, `--pages`, `--out` | hoạt động |
+| `chunk-ready` | `--monographs`, `--chunks` | hoạt động |
+| `chunk` | `--monographs`, `--tables`, `--pdf`, `--out` | hoạt động |
+| `visual-diff` | — | chưa triển khai |
+| `scaffold-golden` | — | chưa triển khai |
+
+Loader `python -m ingestion.load.run` nhận `--chunks`, `--cache`, `--provider`,
+`--collection`, `--region`, `--qdrant-url`, `--slice-size`, `--attempts` và
+`--embed-only`. `--provider` và `--collection` là bắt buộc.
+