VuQuangBao/duocthu

Fork 0

Files

T

VuQuangBao a1de4715a4 Add read-only production runtime audit

2026-08-17 11:17:40 +07:00

5.5 KiB

Raw Blame History

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

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

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

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

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

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:

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:

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

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

Đặt QDRANT_COLLECTION=duocthu_v2 trên staging/local.
Restart ai-service; startup manifest check phải pass.
Chạy health/readiness.
Chạy routing, grounding và manual battery phù hợp.
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

5.5 KiB Raw Blame History