duocthu/docs/pdf-ingestion.md

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:

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:

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.