# 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.