クイックスタート：5分でDoclingを動かす
6ヶ月前、財務レポートに関する質問に答えるRAGシステムを構築しようとして、頭を抱えていた。PDFには密度の高いテーブルが大量にあった――四半期ごとの売上内訳、コストマトリクス、比較グリッドなど。どんなチャンク戦略を試しても、それらのテーブルはゴミデータに変わってしまった。LLMは実際には読めない数字を延々とハルシネーションし続けた。
そこで切り替えたのがDoclingだ。IBM Researchが開発したオープンソースのドキュメント解析ライブラリで、ドキュメントの取り込みに対する考え方が根本から変わった。
インストール：
pip install docling3行で最初のPDFを解析できる：
from docling.document_converter import DocumentConverter
converter = DocumentConverter()
result = converter.convert("report.pdf")
print(result.document.export_to_markdown())これだけだ。Doclingはテーブルを検出し、行と列の構造を保持したまま、きれいなMarkdownにエクスポートする。生のPyMuPDFやpdfplumberの出力と比べてみてほしい――あれらのライブラリは5列の売上テーブルを、文字列が連結された1つの塊に平坦化してしまう。Doclingは実際のセルを返してくれる。
DoclingがテーブルをどのようにX処理するか
ほとんどのPDFパーサーはページを文字のストリームとして扱う。読み取り順にテキストを取得して、あとは運任せだ。テーブルはその前提を打ち砕く――セルは行をまたぎ、ヘッダーは繰り返され、列は見た目には揃っているが意味的には揃っていない。
Doclingは内部でマルチステージのパイプラインを実行している：
- レイアウト検出：深層学習モデル（DocLayNet）が段落・テーブル・図・見出しなどの領域を識別する
- テーブル構造認識：2つ目のモデル（TableFormer）が検出されたテーブル領域から行・列グリッドを再構築する
- テキスト抽出：OCRまたはネイティブPDFテキスト抽出でセルの内容を埋める
- ドキュメント組み立て：すべてが構造化された
DoclingDocumentオブジェクトにパッケージされる
正規表現ヒューリスティックではなく、2つのニューラルモデルを使っている。だからスキャンされたPDF、複数列レイアウト、結合セルをルールベースのパーサーよりもはるかにうまく処理できる。
プログラムでテーブルデータにアクセスする
Markdownエクスポートは出力を目視確認するには便利だが、RAGパイプラインには構造化されたアクセスが必要だ。ドキュメント内のすべてのテーブルをイテレートする方法を示す：
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"テーブル {table_idx}: {table.num_rows} 行 x {table.num_cols} 列")
# pandas DataFrameとしてエクスポート
df = table.export_to_dataframe()
print(df.head())
print("---")この段階ではDataFrameを常に使っている。抽出結果の検証、数値列のサニティチェック――たとえば文字列として解析された売上列を発見するなど――、そしてインデックス化の前にデータをどのようにチャンクするかを決定できる。
テーブルを埋め込み用の構造化テキストにエクスポートする
生のDataFrameは埋め込みに向いていない。コンテキストを保持したテキストに変換する必要がある。私がよく使うアプローチ：
def table_to_context_string(table, doc_title="", page_num=None):
"""Doclingのテーブルを埋め込み用のコンテキスト豊富な文字列に変換する。"""
df = table.export_to_dataframe()
lines = []
if doc_title:
lines.append(f"出典: {doc_title}")
if page_num:
lines.append(f"ページ: {page_num}")
headers = " | ".join(str(col) for col in df.columns)
lines.append(f"列: {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="Q3 2024 Financial Report",
page_num=table.prov[0].page_no if table.prov else None
)
print(context_str[:300])ここに気づきにくいポイントがある――理解するまでに数週間かかった。生のCSV風の文字列を埋め込むよりも、同じデータを自然言語で表現した方が埋め込み精度が明らかに向上する。ドキュメントタイトルとページ番号を追加することも検索精度を高める。私のテストでは、この2つのメタデータフィールドをチャンクテキストに含めるだけで、precision@5が61%から74%に跳ね上がった。
完全なPDFテーブル取り込みパイプラインを構築する
以下は、毎週技術仕様書を取り込むナレッジベース用に本番環境で実行しているパイプラインだ――通常、バッチあたり20〜40本のPDFを処理する。
ステップ1：複数の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 # スキャンPDFの場合はTrueに設定
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 # クラッシュせずに失敗ファイルをスキップ
)
for result in results:
if result.status.name == "SUCCESS":
print(f"成功: {result.input.file.name} — {len(result.document.tables)} テーブル")
else:
print(f"失敗: {result.input.file.name} — {result.status}")ステップ2：ベクトルストアでチャンク化してインデックス化する
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"チャンク総数: {len(all_chunks)}")
print(f"テーブルチャンク数: {sum(1 for _, m in all_chunks if m['is_table'])}")HybridChunkerはDoclingの中で最も過小評価されている機能だ。トークン数で盲目的に分割するのではなく、ドキュメントの階層構造を尊重する。テーブルは行の途中で切断されることなく、1つのチャンクに収まる。社内ベンチマークでは、ナイーブなトークンウィンドウチャンキングと比べて、この1点の変更だけでprecision@5が約18%向上した。
ステップ3：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)
# クエリが明らかに数値的な場合はテーブルチャンクに絞り込む
results = collection.query(
query_texts=["Q3の売上はいくらでしたか？"],
n_results=5,
where={"is_table": True}
)
for doc, meta in zip(results["documents"][0], results["metadatas"][0]):
print(f"[{meta['source']} p.{meta['page']}]")
print(doc[:200])
print()where={"is_table": True}フィルターはきちんと組み込む価値がある。数値的・比較的なクエリに対して、テーブルチャンクに絞ることで無関係な段落のヒットが減る。ChromaDBなどのベクトルデータベースのメタデータフィルタリング機能をうまく活用すれば、私はまずシンプルな分類器を通してクエリをルーティングしている――質問に数字、比較、あるいは「最大」「最小」「合計」といった単語が含まれていれば、テーブル専用のサブセットにアクセスさせる。
6ヶ月の本番運用から得た実践的なヒント
始めた頃は誰もこれを教えてくれなかった。苦労して学んだことを短くまとめる：
1. テーブル抽出品質を必ず検証する
Doclingは優秀だが、完璧ではない。簡単な検証ステップを入れることで、インデックスを汚染する前に明らかな失敗を検知できる：
def validate_table(df):
issues = []
if df.empty:
issues.append("テーブルが空")
if df.shape[1] < 2:
issues.append("列が1つのみ — 誤検知の可能性")
if df.isnull().sum().sum() / df.size > 0.5:
issues.append("50%以上がnull — OCR失敗の可能性")
return issues2. スキャンPDFにはOCRが必要――ただしコストに注意
OCRは本当に必要な場合のみ有効にすること。ネイティブPDFはdo_ocr=Falseで約10倍速く解析できる。解析前に、PyMuPDFが最初の2ページにテキストレイヤーを検出するかチェックしている――検出できればOCRはスキップする。
3. LLMにテーブルを渡すときはMarkdown形式を使う
取得したチャンクをLLMのコンテキストウィンドウに投入する際、Markdownテーブル形式はCSVやJSONより優れたパフォーマンスを発揮する。インストラクションデータで訓練されたモデルは、何千ものGitHub READMEやドキュメントページを見てきており、| col1 | col2 |構文をネイティブに処理できる。
# DoclingのMarkdownエクスポートはテーブルフォーマットを自動的に保持する
markdown_output = result.document.export_to_markdown()
# テーブルは適切な | col1 | col2 | Markdown形式でレンダリングされる4. 解析結果をキャッシュする――これは真剣に
テーブル構造認識を伴うPDF解析は遅い。40ページの技術仕様書は45秒かかることもある。すべてキャッシュしよう：
import json
from pathlib import Path
# 一度保存する
result.document.save_as_json(Path("cache") / f"{pdf_path.stem}.json")
# 次回以降の実行で読み込む（1秒以内）
from docling.datamodel.document import DoclingDocument
cached_doc = DoclingDocument.load_from_json(Path("cache/report.json"))コールドパース：ドキュメントあたり約45秒。ウォームキャッシュ：1秒以内。変更されていないファイルがほとんどを占める30ファイルを週次で取り込むジョブなら、22分のジョブが30秒になる。
5. LangChainやLlamaIndexにドロップイン統合できる
すでにLangChainを使っているなら、パイプラインを書き直す必要はない。公式ローダーを使えばいい：
pip install langchain-docling
pip install llama-index-readers-doclingfrom langchain_docling import DoclingLoader
loader = DoclingLoader(file_path="report.pdf")
docs = loader.load()
# 各Documentにはpage_contentとテーブルマーカー付きのmetadataが含まれる最も手間のかからない方法だ。LangChainのリトリーバーがすでに組み上がっているなら、そのままスロットインできる。
何百もの財務・技術PDFでこれを実行してきた経験から言えば、テーブル抽出の品質こそが、ドキュメント重視のクエリにおけるRAG精度を左右する最大のレバーだ。
ナイーブなチャンキングと適切なDoclingパイプラインとの回答品質の違いは、数値的な質問をして、ハルシネーションではなく正確で出典付きの回答が返ってきた最初の瞬間に明らかになる。Docling v2は私が使い始めた頃のバージョンよりもはるかに安定しており、GitHubのissueが実際にクローズされていっているのも良いサインだ。
