Khởi Động Nhanh: Chạy Docling Trong 5 Phút
Sáu tháng trước, tôi gần như bó tay khi cố xây dựng hệ thống RAG để trả lời câu hỏi về các báo cáo tài chính. Các file PDF chứa đầy bảng biểu dày đặc — bảng phân tích doanh thu theo quý, ma trận chi phí, lưới so sánh — và mọi chiến lược chunking tôi thử đều biến những bảng đó thành dữ liệu vô dụng. LLM cứ bịa ra các con số mà nó thực sự không đọc được.
Đó là lúc tôi chuyển sang Docling, một thư viện phân tích tài liệu mã nguồn mở từ IBM Research. Nó thay đổi hoàn toàn cách tôi tiếp cận bài toán xử lý tài liệu.
Cài đặt:
pip install doclingSau đó phân tích file PDF đầu tiên chỉ với ba dòng lệnh:
from docling.document_converter import DocumentConverter
converter = DocumentConverter()
result = converter.convert("report.pdf")
print(result.document.export_to_markdown())Chỉ vậy thôi. Docling tự phát hiện bảng, bảo toàn cấu trúc hàng-cột, và xuất ra Markdown gọn gàng. So sánh với output thô từ PyMuPDF hay pdfplumber — những thư viện đó làm phẳng một bảng doanh thu 5 cột thành một đoạn văn bản dài nối liền. Docling trả về các ô thực sự.
Docling Xử Lý Bảng Khác Biệt Như Thế Nào
Hầu hết các trình phân tích PDF xử lý trang như một luồng ký tự. Chúng lấy văn bản theo thứ tự đọc và hy vọng mọi thứ đúng. Bảng biểu phá vỡ giả định đó — ô kéo dài nhiều hàng, tiêu đề lặp lại, cột căn chỉnh theo mắt nhìn nhưng không theo ngữ nghĩa.
Docling chạy một pipeline nhiều giai đoạn bên dưới:
- Phát hiện bố cục: Mô hình học sâu (DocLayNet) xác định các vùng — đoạn văn, bảng, hình ảnh, tiêu đề
- Nhận dạng cấu trúc bảng: Mô hình thứ hai (TableFormer) tái tạo lưới hàng/cột từ các vùng bảng đã phát hiện
- Trích xuất văn bản: OCR hoặc trích xuất văn bản PDF gốc điền nội dung vào từng ô
- Lắp ráp tài liệu: Tất cả được đóng gói thành đối tượng
DoclingDocumentcó cấu trúc
Hai mô hình neural thay vì dùng heuristic regex. Đó là lý do nó xử lý PDF được scan, bố cục nhiều cột, và ô được gộp tốt hơn nhiều so với các trình phân tích dựa trên quy tắc.
Truy Cập Dữ Liệu Bảng Theo Dạng Lập Trình
Xuất Markdown tiện cho việc xem nhanh, nhưng pipeline RAG cần truy cập có cấu trúc. Dưới đây là cách duyệt qua mọi bảng trong tài liệu:
from docling.document_converter import DocumentConverter
converter = DocumentConverter()
result = converter.convert("annual_report.pdf")
doc = result.document
for table_idx, table in enumerate(doc.tables):
print(f"Bảng {table_idx}: {table.num_rows} hàng x {table.num_cols} cột")
# Xuất dưới dạng pandas DataFrame
df = table.export_to_dataframe()
print(df.head())
print("---")Tôi dùng DataFrame liên tục ở giai đoạn này. Chúng giúp tôi kiểm tra kết quả trích xuất, chạy các bước sanity check trên cột số — chẳng hạn phát hiện cột doanh thu bị parse thành chuỗi — và quyết định cách chunk dữ liệu trước khi đưa vào index.
Xuất Bảng Thành Văn Bản Có Cấu Trúc để Embedding
DataFrame thô không embed tốt. Bạn cần chuyển chúng thành văn bản bảo toàn ngữ cảnh. Cách tôi thường làm:
def table_to_context_string(table, doc_title="", page_num=None):
"""Chuyển bảng Docling thành chuỗi giàu ngữ cảnh để embedding."""
df = table.export_to_dataframe()
lines = []
if doc_title:
lines.append(f"Nguồn: {doc_title}")
if page_num:
lines.append(f"Trang: {page_num}")
headers = " | ".join(str(col) for col in df.columns)
lines.append(f"Cột: {headers}")
for _, row in df.iterrows():
row_parts = [f"{col}: {val}" for col, val in row.items() if str(val).strip()]
lines.append(", ".join(row_parts))
return "\n".join(lines)
for table in doc.tables:
context_str = table_to_context_string(
table,
doc_title="Báo Cáo Tài Chính Q3 2024",
page_num=table.prov[0].page_no if table.prov else None
)
print(context_str[:300])Đây là điều không ai nói cho tôi biết — mất vài tuần tôi mới tự rút ra. Embedding một chuỗi dạng CSV thô cho kết quả tệ hơn đáng kể so với embedding biểu diễn ngôn ngữ tự nhiên của cùng dữ liệu đó. Thêm tiêu đề tài liệu và số trang cũng cải thiện độ chính xác truy xuất: trong các thử nghiệm của tôi, precision@5 nhảy từ 61% lên 74% chỉ bằng cách thêm hai trường metadata đó vào văn bản chunk.
Xây Dựng Pipeline Nạp Bảng PDF Hoàn Chỉnh
Dưới đây là pipeline tôi chạy trong môi trường production cho một knowledge base nạp tài liệu kỹ thuật hàng tuần — thường 20–40 file PDF mỗi lần.
Bước 1: Xử Lý Hàng Loạt Nhiều File PDF
from pathlib import Path
from docling.document_converter import DocumentConverter
from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import PdfPipelineOptions
pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = False # Đặt True cho PDF được scan
pipeline_options.do_table_structure = True
pipeline_options.table_structure_options.do_cell_matching = True
converter = DocumentConverter(
format_options={
InputFormat.PDF: pipeline_options
}
)
pdf_dir = Path("./documents")
results = converter.convert_all(
[str(p) for p in pdf_dir.glob("*.pdf")],
raises_on_error=False # Bỏ qua file lỗi thay vì crash toàn bộ
)
for result in results:
if result.status.name == "SUCCESS":
print(f"OK: {result.input.file.name} — {len(result.document.tables)} bảng")
else:
print(f"LỖI: {result.input.file.name} — {result.status}")Bước 2: Chunk và Index với Vector Store
from docling.chunking import HybridChunker
from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("BAAI/bge-small-en-v1.5")
chunker = HybridChunker(
tokenizer=tokenizer,
max_tokens=512,
merge_peers=True
)
all_chunks = []
for result in results:
if result.status.name != "SUCCESS":
continue
doc = result.document
chunks = list(chunker.chunk(doc))
for chunk in chunks:
chunk_text = chunker.serialize(chunk=chunk)
metadata = {
"source": result.input.file.name,
"page": chunk.meta.doc_items[0].prov[0].page_no
if chunk.meta.doc_items and chunk.meta.doc_items[0].prov
else None,
"is_table": any(
item.label == "table"
for item in chunk.meta.doc_items
)
}
all_chunks.append((chunk_text, metadata))
print(f"Tổng số chunk: {len(all_chunks)}")
print(f"Chunk từ bảng: {sum(1 for _, m in all_chunks if m['is_table'])}")HybridChunker là tính năng bị đánh giá thấp nhất trong Docling. Nó không chia blindly theo số token — nó tôn trọng cấu trúc phân cấp của tài liệu. Một bảng sẽ nằm trọn trong một chunk thay vì bị cắt giữa chừng. Theo benchmark nội bộ của tôi, thay đổi này đơn lẻ cải thiện precision@5 khoảng 18% so với cách chunking theo cửa sổ token thông thường.
Bước 3: Lưu Trữ và Truy Vấn với ChromaDB
import chromadb
from chromadb.utils import embedding_functions
client = chromadb.PersistentClient(path="./chroma_db")
embedding_fn = embedding_functions.SentenceTransformerEmbeddingFunction(
model_name="BAAI/bge-small-en-v1.5"
)
collection = client.get_or_create_collection(
name="pdf_documents",
embedding_function=embedding_fn
)
texts = [c[0] for c in all_chunks]
metadatas = [c[1] for c in all_chunks]
ids = [f"chunk_{i}" for i in range(len(all_chunks))]
collection.add(documents=texts, metadatas=metadatas, ids=ids)
# Lọc theo chunk bảng khi câu hỏi rõ ràng liên quan đến số liệu
results = collection.query(
query_texts=["Doanh thu trong Q3 là bao nhiêu?"],
n_results=5,
where={"is_table": True}
)
for doc, meta in zip(results["documents"][0], results["metadatas"][0]):
print(f"[{meta['source']} tr.{meta['page']}]")
print(doc[:200])
print()Bộ lọc where={"is_table": True} đó đáng để thiết lập đúng cách. Với các câu hỏi về số liệu hay so sánh, giới hạn vào chunk bảng giúp loại bỏ các kết quả khớp đoạn văn không liên quan. Nếu bạn chưa quen với cách cơ sở dữ liệu vector như ChromaDB hoạt động, đây là khái niệm cần nắm trước khi đi sâu vào tối ưu. Tôi định tuyến câu hỏi qua một bộ phân loại đơn giản trước — nếu câu hỏi chứa số, phép so sánh, hay các từ như “cao nhất”/”thấp nhất”/”tổng cộng”, nó sẽ truy vấn vào tập con chỉ gồm bảng.
Mẹo Thực Tế Sau 6 Tháng Chạy Production
Không ai nói với tôi điều này khi tôi bắt đầu. Đây là bản tóm tắt những gì tôi học được theo cách khó khăn nhất:
1. Luôn Kiểm Tra Chất Lượng Trích Xuất Bảng
Docling làm tốt, nhưng không hoàn hảo. Một bước kiểm tra nhanh giúp phát hiện những lỗi rõ ràng trước khi chúng làm ô nhiễm index của bạn:
def validate_table(df):
issues = []
if df.empty:
issues.append("bảng rỗng")
if df.shape[1] < 2:
issues.append("chỉ một cột — có thể nhận diện nhầm")
if df.isnull().sum().sum() / df.size > 0.5:
issues.append("hơn 50% giá trị null — có thể lỗi OCR")
return issues2. PDF Được Scan Cần OCR — Nhưng Tốn Chi Phí
Chỉ bật OCR khi thực sự cần. PDF gốc phân tích nhanh hơn khoảng 10× khi dùng do_ocr=False. Trước khi phân tích, tôi kiểm tra xem PyMuPDF có tìm thấy text layer nào trong hai trang đầu không — nếu có, tôi bỏ qua OCR hoàn toàn.
3. Dùng Định Dạng Markdown Khi Truyền Bảng Vào LLM
Khi các chunk được truy xuất đưa vào context window của LLM, định dạng bảng Markdown vượt trội hơn CSV hay JSON. Các mô hình được huấn luyện trên dữ liệu instruction đã thấy hàng nghìn README GitHub và trang tài liệu — chúng xử lý cú pháp | col1 | col2 | một cách tự nhiên. Đây cũng là một trong những cách đơn giản nhất để giảm thiểu AI hallucination khi LLM đọc dữ liệu số từ tài liệu.
# Xuất Markdown của Docling tự động bảo toàn định dạng bảng
markdown_output = result.document.export_to_markdown()
# Bảng được render thành bảng Markdown đúng chuẩn | col1 | col2 |4. Cache Kết Quả Phân Tích — Thật Sự Quan Trọng
Phân tích PDF với nhận dạng cấu trúc bảng rất chậm. Một tài liệu kỹ thuật 40 trang có thể mất 45 giây. Hãy cache tất cả:
import json
from pathlib import Path
# Lưu một lần
result.document.save_as_json(Path("cache") / f"{pdf_path.stem}.json")
# Tải trong các lần chạy tiếp theo (dưới 1 giây)
from docling.datamodel.document import DoclingDocument
cached_doc = DoclingDocument.load_from_json(Path("cache/report.json"))Phân tích lạnh: ~45 giây mỗi tài liệu. Tải từ cache: dưới một giây. Với một job nạp dữ liệu hàng tuần xử lý 30 file, phần lớn không thay đổi, đây là sự khác biệt giữa một job chạy 22 phút và một job chạy 30 giây.
5. Tích Hợp Trực Tiếp với LangChain hoặc LlamaIndex
Đang dùng LangChain? Không cần viết lại pipeline. Dùng loader chính thức:
pip install langchain-docling
pip install llama-index-readers-doclingfrom langchain_docling import DoclingLoader
loader = DoclingLoader(file_path="report.pdf")
docs = loader.load()
# Mỗi Document bao gồm page_content và metadata với các marker bảngĐây là con đường ít ma sát nhất. Nếu bạn đã có LangChain retriever sẵn, cái này cắm vào ngay lập tức.
Sau khi xử lý hàng trăm file PDF tài chính và kỹ thuật, chất lượng trích xuất bảng là đòn bẩy lớn nhất để cải thiện độ chính xác RAG với các câu hỏi liên quan đến tài liệu nặng.
Sự khác biệt về chất lượng câu trả lời giữa chunking thô và pipeline Docling đúng cách rất rõ ràng ngay lần đầu bạn đặt câu hỏi về số liệu và nhận được câu trả lời chính xác, có trích dẫn nguồn thay vì một con số được bịa ra. Docling v2 ổn định hơn đáng kể so với phiên bản tôi bắt đầu dùng — và các issue trên GitHub đang thực sự được đóng lại, đó là dấu hiệu tốt.
