docling-document-intelligence

Docling ドキュメントインテリジェンススキル

Docling を使用して、ドキュメントの構造と品質を解析、変換、チャンク化、分析します。 ローカルのファイルパスと URL の両方に対応しており、Markdown または 構造化 JSON（DoclingDocument）を出力します。

変換には docling CLI（uv tool install docling でインストール）を使用します。 Python API は、CLI では利用できない機能（チャンク化、 VLM のリモート API エンドポイント設定、ハイブリッドの force_backend_text モード）にのみ使用します。

対象範囲

タスク	対応状況
PDF / DOCX / PPTX / HTML / 画像の解析	✅
Markdown への変換	✅
DoclingDocument JSON としてエクスポート	✅
RAG 用のチャンク化（ハイブリッド：見出し＋トークン）	✅（Python API）
構造の分析（見出し、表、図）	✅（Python API）
スキャン PDF の OCR	✅（自動で有効化）
複数ソースの一括変換	✅

手順

1. 入力を確認する

ユーザーが指定したものが ローカルパス か URL かを判断します。 docling CLI はどちらもそのまま受け付けます。

docling path/to/file.pdf
docling https://example.com/a.pdf

2. パイプラインを選択する

Docling には 2 種類のパイプラインがあります。以下の表を参考に、適切なものを選択します。

ドキュメントの種類	推奨パイプライン	CLI フラグ
デジタル生成 PDF（テキストを選択可能）	Standard（デフォルト）	--pipeline standard
スキャン / 画像のみの PDF	Standard ＋ OCR（自動）	--pipeline standard
複雑なレイアウト、複数段組み、数式	VLM	--pipeline vlm
手書き文字	VLM	--pipeline vlm

Standard パイプライン — GPU は不要で高速です。スキャンしたページでは OCR が自動で有効になります。 VLM パイプライン — GPU が必要で、処理は低速ですが、複雑なレイアウトや手書き文字の再現性が高くなります。

完全な選択基準表、OCR エンジン一覧 （EasyOCR、RapidOCR、Tesseract、macOS）、VLM モデルプリセットについては pipelines.md を参照してください。

3. ドキュメントを変換する

CLI（標準的な変換に推奨）

# --- Output format ---
docling report.pdf --output /tmp/                          # Markdown (default)
docling report.pdf --to json --output /tmp/               # JSON (structured)

# --- Pipeline selection ---
docling report.pdf --pipeline vlm --output /tmp/           # VLM for complex layouts
docling report.pdf --pipeline vlm --vlm-model granite_docling --output /tmp/  # VLM with specific model

# --- OCR options ---
docling report.pdf --ocr-engine tesserocr --output /tmp/  # Custom OCR engine
docling report.pdf --no-ocr --output /tmp/                # Disable OCR (speed)

# --- Speed / feature toggles ---
docling report.pdf --no-tables --output /tmp/             # Skip table extraction

# --- Remote VLM ---
docling report.pdf --pipeline vlm --enable-remote-services --output /tmp/

CLI は --output ディレクトリに、入力ファイル名を基にした名前で出力ファイルを書き込みます （例：report.pdf → report.md または report.json）。

CLI リファレンス： https://docling-project.github.io/docling/reference/cli/

Python API（高度な機能を使う場合）

チャンク化、VLM のリモート API エンドポイント設定、ハイブリッドの force_backend_text モードなど、CLI では利用できない機能が必要な場合は、Python API を使用します。

Docling 2.81 以降の API に関する注意： DocumentConverter(format_options=...) には dict[InputFormat, FormatOption]（例：InputFormat.PDF → PdfFormatOption）を指定します。 {"pdf": PdfPipelineOptions(...)} のような文字列キーを使用すると、実行時に AttributeError: 'PdfPipelineOptions' object has no attribute 'backend' が発生します。

Standard パイプライン（デフォルト）：

from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import PdfPipelineOptions

converter = DocumentConverter()
result = converter.convert("report.pdf")

converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(
            pipeline_options=PdfPipelineOptions(do_ocr=True, do_table_structure=True),
        ),
    }
)
result = converter.convert("report.pdf")

VLM パイプライン — ローカル（HF Transformers 経由の GraniteDocling）：

from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import VlmPipelineOptions
from docling.datamodel import vlm_model_specs
from docling.pipeline.vlm_pipeline import VlmPipeline

pipeline_options = VlmPipelineOptions(
    vlm_options=vlm_model_specs.GRANITEDOCLING_TRANSFORMERS,
    generate_page_images=True,
)
converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(
            pipeline_cls=VlmPipeline,
            pipeline_options=pipeline_options,
        )
    }
)
result = converter.convert("report.pdf")

VLM パイプライン — リモート API（vLLM / LM Studio / Ollama）：

これは Python API でのみ利用できます。CLI ではエンドポイントの URL、モデル名、API キーを設定できません。

from docling.document_converter import DocumentConverter, PdfFormatOption
from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import VlmPipelineOptions
from docling.datamodel.pipeline_options_vlm_model import ApiVlmOptions, ResponseFormat
from docling.pipeline.vlm_pipeline import VlmPipeline

vlm_opts = ApiVlmOptions(
    url="http://localhost:8000/v1/chat/completions",
    params=dict(model="ibm-granite/granite-docling-258M", max_tokens=4096),
    prompt="Convert this page to docling.",
    response_format=ResponseFormat.DOCTAGS,
    timeout=120,
)
pipeline_options = VlmPipelineOptions(
    vlm_options=vlm_opts,
    generate_page_images=True,
    enable_remote_services=True,  # required — gates all outbound HTTP
)
converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(
            pipeline_cls=VlmPipeline,
            pipeline_options=pipeline_options,
        )
    }
)
result = converter.convert("report.pdf")

ハイブリッドモード（force_backend_text）— Python API のみ：

テキスト領域には決定的な PDF テキスト抽出を使用し、画像と表は VLM に処理させます。テキストの多いページでの幻覚を抑えます。

pipeline_options = VlmPipelineOptions(
    vlm_options=vlm_model_specs.GRANITEDOCLING_TRANSFORMERS,
    force_backend_text=True,
    generate_page_images=True,
)

いずれの場合も、result.document は DoclingDocument オブジェクトです。

4. 出力形式を選択する

Markdown（デフォルト、人が読みやすい形式）：

docling report.pdf --to md --output /tmp/

または Python では、result.document.export_to_markdown() を使用します。

JSON / DoclingDocument（構造化され、情報を損失しない形式）：

docling report.pdf --to json --output /tmp/

または Python では、result.document.export_to_dict() を使用します。

ユーザーが形式を指定していない場合は、「Markdown と構造化 JSON（DoclingDocument）のどちらを出力しますか？」と尋ねます。

5. RAG 用のチャンク分割（ハイブリッド戦略）

チャンク分割は Python API からのみ利用できます。

デフォルトはハイブリッドチャンク分割器です。まず見出し階層に基づいて分割し、次にトークン数に応じて大きすぎるセクションをさらに細分化します。これにより、モデルのコンテキスト制限を守りながら、意味上の境界を維持できます。

トークナイザー API は docling-core 2.8.0 で変更されました。生の文字列ではなく、BaseTokenizer オブジェクトを渡してください。

HuggingFace トークナイザー（デフォルト）：

from docling.chunking import HybridChunker
from docling_core.transforms.chunker.tokenizer.huggingface import HuggingFaceTokenizer

tokenizer = HuggingFaceTokenizer.from_pretrained(
    model_name="sentence-transformers/all-MiniLM-L6-v2",
    max_tokens=512,
)
chunker = HybridChunker(tokenizer=tokenizer, merge_peers=True)
chunks = list(chunker.chunk(result.document))

for chunk in chunks:
    embed_text = chunker.contextualize(chunk)
    print(chunk.meta.headings)  # heading breadcrumb list
    print(chunk.meta.origin.page_no)  # source page number

OpenAI トークナイザー（OpenAI の埋め込みモデル用）：

import tiktoken
from docling_core.transforms.chunker.tokenizer.openai import OpenAITokenizer

tokenizer = OpenAITokenizer(
    tokenizer=tiktoken.encoding_for_model("text-embedding-3-small"),
    max_tokens=8192,
)
# Requires: uv add 'docling-core[chunking-openai]'

チャンク分割戦略とトークナイザーの詳細については、チャンク分割と HybridChunker に関する Docling のドキュメントを参照してください。

6. ドキュメントの構造を分析する

DoclingDocument オブジェクトを直接使用して、構造を調べます。

doc = result.document

for item, level in doc.iterate_items():
    if hasattr(item, "label") and item.label.name == "SECTION_HEADER":
        print(f"{'#' * level} {item.text}")

for table in doc.tables:
    print(table.export_to_dataframe())  # pandas DataFrame
    print(table.export_to_markdown())

for picture in doc.pictures:
    print(picture.caption_text(doc))  # caption if present

API の全容については、Docling の構造とテーブルのエクスポートに関するドキュメントを参照してください。

7. 出力を評価して反復する（「最善の努力」で変換する場合は必須）

忠実度を重視する（簡易プレビューではない）場合は、変換のたびに、JSON エクスポートにバンドルされている評価スクリプトを実行し、必要に応じてパイプラインを調整してください。これにより、エージェントは推測に頼らずに作業を確認し、実行結果を改善できます。

ステップ A — JSON と任意の Markdown を生成する

docling "<source>" --to json --output /tmp/
docling "<source>" --to md --output /tmp/

ステップ B — 評価する

uv run scripts/docling-evaluate.py /tmp/<filename>.json --markdown /tmp/<filename>.md

ユーザーがテーブル（請求書、PDF 内のスプレッドシートなど）を期待している場合は、--expect-tables を追加してください。CI 形式のチェックで条件を厳しくするには、--fail-on-warn を指定します。

スクリプトは JSON レポートを標準出力に出力します。レポートには status（pass | warn | fail）、metrics、issues、および次に試す具体的な docling CLI フラグを示す recommended_actions が含まれます。

ステップ C — 改善ループ（ユーザーから別の指示がない限り最大 3 回）

1. status が warn または fail の場合は、recommended_actions から主な変更を1 つ適用します（例：--pipeline vlm に切り替える、--ocr-engine を変更する、テーブルが有効になっていることを確認する）。
2. docling で再変換し、uv run scripts/docling-evaluate.py を再実行します。
3. status が pass になった時点、または 3 回反復した時点で停止し、効果があったことと残っている問題をユーザーに要約します。

ステップ D — 自己改善ログ（スキルの記憶）

評価に成功した後または最終反復の後に、このスキルのディレクトリにある improvement-log.md にエントリを 1 件追加します。

• ソースの種類（例：スキャン PDF、デジタル PDF、DOCX）
• 初回実行時の問題（issues から記載）
• 問題を解決または最も軽減したパイプラインとフラグ
• 最終的な status と品質に関する主観的な所感を 1 行

このログは任意で、ユーザーは git の対象から除外できます。今後、類似ドキュメントを処理する際に適切なパイプラインに近い状態から始められるようにするための、ローカルな学習用です。

8. エージェントの品質チェックリスト（スクリプトが利用できない場合は手動で確認）

scripts/docling-evaluate.py を実行できない場合も、次の項目を確認してください。

チェック項目	問題がある場合の対応
ページ数がおおむねソースと一致している	再実行する。レイアウトが複雑な場合は --pipeline vlm を試す
Markdown がほぼ空ではない	OCR / VLM を有効にする
見た目で明らかなテーブルが欠落していない	--no-tables を削除する。--pipeline vlm を試す
\ufffd の置換文字がある	別の --ocr-engine または --pipeline vlm を試す
同じ行が何度も繰り返されている	--pipeline vlm またはハイブリッドの force_backend_text（Python API）を試す

よくあるエッジケース

状況	対処方法
スキャン画像のみの PDF	OCR を使用した標準パイプライン、または最高品質を得るには --pipeline vlm を使用します
パスワードで保護された PDF	--pdf-password PASSWORD を指定します。パスワードが誤っている場合は ConversionError が発生します
非常に大きなドキュメント（500 ページ以上）	速度を優先するには、--no-tables を指定した標準パイプラインを使用します
複雑なレイアウト／複数列	--pipeline vlm を使用します。標準パイプラインでは読み取り順序が誤る場合があります
手書き文字や数式	--pipeline vlm のみ使用できます。標準 OCR では対応できません
認証が必要な URL	一時ファイルに事前ダウンロードして、ローカルパスを渡します
セルが結合された表	table.export_to_markdown() で結合範囲を処理できます。VLM のほうが正確な場合が多いです
UTF-8 以外のエンコーディング	Docling が内部で正規化するため、特別な処理は不要です
VLM がテキストを幻覚する	ハイブリッドモードでは、Python API で force_backend_text=True を指定します
VLM API 呼び出しがブロックされる	--enable-remote-services（CLI）または enable_remote_services=True（Python）を指定します
Apple Silicon	MLX バックエンドでは --vlm-model granite_docling を指定するか、GRANITEDOCLING_MLX プリセット（Python API）を使用します

パイプラインのリファレンス

すべての OCR エンジンオプション、VLM モデルプリセット、API サーバー設定を含む完全な判断マトリクスについては、pipelines.md を参照してください。

出力に関する規約

• ページ数と変換ステータスを必ず報告してください。
• 評価を行う場合は、評価器の status、主な issues、最終出力がどの改善試行で作成されたかを報告してください。
• Markdown 出力は、ユーザーがコピー＆ペーストする場合にのみフェンス付きコードブロックで囲んでください。それ以外の場合は、そのまま表示してください。
• JSON 出力は、ユーザーが別の形式を指定しない限り、indent=2 で整形してください。
• チャンクについては、チャンクの合計数と、トークン数の最小値／最大値／平均値を報告してください。
• 構造分析では、詳細に入る前に、見出しツリー、表の数、図の数を要約してください。

依存関係

# Install the docling CLI as a uv tool
uv tool install docling
# For OpenAI tokenizer support, add to your project:
uv add 'docling-core[chunking-openai]'

インストール済みのバージョンを確認します（docling には __version__ が設定されていない場合があるため、配布メタデータを優先してください）。

from importlib.metadata import version

print(version("docling"), version("docling-core"))

scripts/docling-evaluate.py は、インラインスクリプトメタデータ（PEP 723）で依存関係を宣言しています。インストール手順は不要で、uv run で直接実行できます。

uv run scripts/docling-evaluate.py /tmp/report.json --markdown /tmp/report.md

例

エンドツーエンドの手順例については、EXAMPLE.md を参照してください。