169 lines
5.5 KiB
Markdown
169 lines
5.5 KiB
Markdown
# 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)
|