convert Command

Overview

The convert command transforms documents into knowledge graphs using configurable extraction pipelines.

Key Features:

Multiple backend support (LLM/VLM)
Flexible processing modes
Configurable chunking
Multiple export formats
Batch processing support

Basic Usage

uv run docling-graph convert SOURCE --template TEMPLATE [OPTIONS]

Required Arguments

Argument	Description
`SOURCE`	Path to document (PDF, JPG, PNG, TXT, MD), URL, or DoclingDocument JSON
`--template`, `-t`	Dotted path to Pydantic template

Examples

# PDF document
uv run docling-graph convert invoice.pdf \
    --template "templates.BillingDocument"

# Text file
uv run docling-graph convert notes.txt \
    --template "templates.Report" \
    --backend llm

# URL
uv run docling-graph convert https://example.com/doc.pdf \
    --template "templates.BillingDocument"

# Markdown file
uv run docling-graph convert README.md \
    --template "templates.Documentation" \
    --backend llm

Core Options

Debug Mode

--debug

Enable debug mode to save all intermediate extraction artifacts for debugging and analysis.

When to use:

Debugging extraction issues
Analyzing extraction quality
Performance profiling
Development and testing

Output: All debug artifacts saved to outputs/{document}_{timestamp}/debug/

Example:

# Enable debug mode
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --debug

# Debug artifacts will be in:
# outputs/document_pdf_20260206_094500/debug/

See Debug Mode Documentation for details on debug artifacts.

Backend Selection

--backend {llm|vlm}

LLM (Language Model):

Best for text-heavy documents
Supports chunking and consolidation
Works with local and remote providers

VLM (Vision-Language Model):

Best for forms and structured layouts
Processes images directly
Local inference only

Example:

# Use LLM backend
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --backend llm

# Use VLM backend
uv run docling-graph convert form.jpg \
    --template "templates.IDCard" \
    --backend vlm

Inference Mode

--inference {local|remote}

Local:

Run models on your machine
Requires GPU for best performance
No API costs

Remote:

Use cloud API providers
Requires API key
Pay per request

Example:

# Local inference
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --inference local

# Remote inference
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --inference remote

Processing Mode

--processing-mode {one-to-one|many-to-one}

many-to-one (recommended):

Merge all pages into single graph
Better for multi-page documents
Enables consolidation

one-to-one:

Create separate graph per page
Better for independent pages
Faster processing

Example:

# Merge all pages
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --processing-mode many-to-one

# Process pages separately
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --processing-mode one-to-one

Model Configuration

Provider Override

--provider PROVIDER

Available providers:

Local: vllm, ollama, lmstudio
Remote: mistral, openai, gemini, watsonx

Model Override

--model MODEL

Example:

# Use specific model
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --provider mistral \
    --model mistral-large-latest

LLM connection overrides

Use --llm-base-url to point to a custom endpoint (e.g. on-prem OpenAI-compatible server). API keys are set via environment variables or config.yaml (llm_overrides.connection), not CLI. See LLM Model Configuration for the full list of overrides and on-prem setup.

For LM Studio (--provider lmstudio): override the base URL with LM_STUDIO_API_BASE or --llm-base-url; when the server requires auth, set LM_STUDIO_API_KEY or llm_overrides.connection.api_key in config.

For the on-prem flow (openai-compatible), use fixed env vars:

export CUSTOM_LLM_BASE_URL="https://your-llm.example.com/v1"
export CUSTOM_LLM_API_KEY="your-api-key"

Extraction Options

Chunking

--use-chunking / --no-use-chunking

Enable chunking for:

Large documents (>5 pages)
Documents exceeding context limits
Better extraction accuracy

Disable chunking for:

Small documents
When full context is needed
Faster processing

Example:

# Enable chunking (default)
uv run docling-graph convert large_doc.pdf \
    --template "templates.ScholarlyRheologyPaper" \
    --use-chunking

# Disable chunking
uv run docling-graph convert small_doc.pdf \
    --template "templates.BillingDocument" \
    --no-use-chunking

Staged Extraction Tuning

These flags apply when --extraction-contract staged is used in many-to-one mode.

--staged-tuning {standard|advanced}
--staged-retries INT
--parallel-workers INT
--staged-nodes-fill-cap INT
--staged-id-shard-size INT

--staged-tuning: preset defaults (standard or advanced).
--staged-retries: retries per staged pass for invalid JSON responses.
--parallel-workers: parallel workers for extraction (staged fill pass and delta batch calls).
--staged-nodes-fill-cap: max node instances per fill-pass call.
--staged-id-shard-size: max catalog paths per ID-pass call (0 disables sharding).

ID pass always runs sequentially across shards for stable skeleton assembly.

Delta Extraction Tuning

These flags apply when --extraction-contract delta is used in many-to-one mode (chunking must be enabled). To configure delta resolvers and quality gates interactively, run docling-graph init and choose delta as the extraction contract; the wizard will prompt for resolver enable/mode and optional quality tweaks (see init Command).

--llm-batch-token-size INT
--parallel-workers INT
--delta-normalizer-validate-paths / --no-delta-normalizer-validate-paths
--delta-normalizer-canonicalize-ids / --no-delta-normalizer-canonicalize-ids
--delta-normalizer-strip-nested-properties / --no-delta-normalizer-strip-nested-properties
--delta-resolvers-enabled / --no-delta-resolvers-enabled
--delta-resolvers-mode {off|fuzzy|semantic|chain}
--delta-resolver-fuzzy-threshold FLOAT
--delta-resolver-semantic-threshold FLOAT

--llm-batch-token-size: max input tokens per delta batch (default: 1024).
--parallel-workers: parallel workers for delta batch LLM calls.
Delta normalizer flags control path validation, ID canonicalization, and nested property stripping.
Resolvers optionally merge near-duplicate entities after merge (fuzzy, semantic, or chain).

Quality gate options (e.g. delta_quality_max_parent_lookup_miss, delta_quality_require_relationships) are not CLI flags; set them in config.yaml under defaults or use the init wizard when selecting delta.

See Delta Extraction for full options and quality gate settings.

Gleaning (direct and delta)

Optional second-pass extraction ("what did you miss?") to improve recall. Applies to direct and delta contracts only (not staged). Enabled by default.

--gleaning-enabled / --no-gleaning-enabled
--gleaning-max-passes INT

--gleaning-enabled: run one extra extraction pass and merge additional entities/relations (default: enabled).
--gleaning-max-passes: max number of gleaning passes when enabled (default: 1).

Example (delta with gleaning):

uv run docling-graph convert document.pdf \
    --template "templates.ScholarlyRheologyPaper" \
    --processing-mode many-to-one \
    --extraction-contract delta \
    --gleaning-enabled \
    --gleaning-max-passes 1 \
    --parallel-workers 2

Example (basic delta):

uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --processing-mode many-to-one \
    --extraction-contract delta \
    --use-chunking \
    --llm-batch-token-size 2048 \
    --parallel-workers 2

Example (delta with resolvers):

uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --processing-mode many-to-one \
    --extraction-contract delta \
    --use-chunking \
    --delta-resolvers-enabled \
    --delta-resolvers-mode fuzzy \
    --delta-resolver-fuzzy-threshold 0.9 \
    --parallel-workers 2

Structured Output Mode

Structured output is enabled by default for LLM extraction and enforces schema through LiteLLM response_format=json_schema.

--schema-enforced-llm / --no-schema-enforced-llm
--structured-sparse-check / --no-structured-sparse-check

Use --schema-enforced-llm (default) for strict schema-constrained output.
Use --no-schema-enforced-llm to fall back to legacy prompt-embedded schema mode.
Use --no-structured-sparse-check to disable the sparse structured-result quality guard.
When schema mode fails at runtime (unsupported backend/model or malformed request), Docling Graph logs the error and automatically retries once using legacy prompt-schema mode.
Even when schema mode succeeds technically, Docling Graph can trigger the same fallback once if the structured payload is detected as obviously sparse for the target schema.

Example:

uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --processing-mode many-to-one \
    --extraction-contract staged \
    --parallel-workers 4 \
    --staged-nodes-fill-cap 12 \
    --staged-id-shard-size 2

Docling Configuration

Pipeline Selection

--docling-pipeline {ocr|vision}

OCR Pipeline:

Traditional OCR approach
Most accurate for standard documents
Faster processing

Vision Pipeline:

Uses Granite-Docling VLM
Better for complex layouts
Handles tables and figures better

Example:

# Use OCR pipeline (default)
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --docling-pipeline ocr

# Use vision pipeline
uv run docling-graph convert complex_doc.pdf \
    --template "templates.ScholarlyRheologyPaper" \
    --docling-pipeline vision

Export Options

Export Format

--export-format {csv|cypher}

CSV:

For Neo4j import
Separate nodes.csv and edges.csv
Easy to analyze

Cypher:

Direct Neo4j execution
Single .cypher file
Ready to import

Example:

# Export as CSV
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --export-format csv

# Export as Cypher
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --export-format cypher

Docling Exports

--export-docling-json / --no-docling-json
--export-markdown / --no-markdown
--export-per-page / --no-per-page

Example:

# Export all Docling outputs
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --export-docling-json \
    --export-markdown \
    --export-per-page

# Minimal exports
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --no-docling-json \
    --no-markdown \
    --no-per-page

Graph Options

Reverse Edges

--reverse-edges

Creates bidirectional relationships in the graph.

Example:

uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --reverse-edges

Output Options

Output Directory

--output-dir PATH

Default: outputs/

Example:

# Custom output directory
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --output-dir "results/invoice_001"

# Organize by date
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --output-dir "outputs/$(date +%Y-%m-%d)"

Complete Examples

📍 Simple Invoice (VLM)

uv run docling-graph convert invoice.jpg \
    --template "templates.BillingDocument" \
    --backend vlm \
    --processing-mode one-to-one \
    --output-dir "outputs/invoice"

📍 Rheology Research (Remote LLM)

export MISTRAL_API_KEY="your-key"

uv run docling-graph convert research.pdf \
    --template "templates.ScholarlyRheologyPaper" \
    --backend llm \
    --inference remote \
    --provider mistral \
    --model mistral-large-latest \
    --processing-mode many-to-one \
    --use-chunking \
    --output-dir "outputs/research"

📍 Debug Mode Enabled

# Enable debug mode for troubleshooting
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --backend llm \
    --debug \
    --output-dir "outputs/debug_run"

# Debug artifacts will be saved to:
# outputs/debug_run/document_pdf_20260206_094500/debug/

📍 Local Processing (Ollama)

# Start Ollama server first
ollama serve

uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --backend llm \
    --inference local \
    --provider ollama \
    --model llama3:8b \
    --processing-mode many-to-one \
    --use-chunking \
    --output-dir "outputs/local"

📍 Cypher Export for Neo4j

uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --backend llm \
    --inference remote \
    --export-format cypher \
    --output-dir "outputs/neo4j"

# Import to Neo4j
cat outputs/neo4j/graph.cypher | cypher-shell

📍 Minimal Processing

uv run docling-graph convert small_doc.pdf \
    --template "templates.BillingDocument" \
    --backend llm \
    --inference local \
    --no-use-chunking \
    --no-docling-json \
    --no-markdown \
    --output-dir "outputs/minimal"

Batch Processing

Process Multiple Files

# Bash loop
for pdf in documents/*.pdf; do
    uv run docling-graph convert "$pdf" \
        --template "templates.BillingDocument" \
        --output-dir "outputs/$(basename $pdf .pdf)"
done

Parallel Processing

# Using GNU parallel
ls documents/*.pdf | parallel -j 4 \
    uv run docling-graph convert {} \
        --template "templates.BillingDocument" \
        --output-dir "outputs/{/.}"

Batch Script

#!/bin/bash
# batch_convert.sh

TEMPLATE="templates.BillingDocument"
INPUT_DIR="documents"
OUTPUT_BASE="outputs"

for file in "$INPUT_DIR"/*.pdf; do
    filename=$(basename "$file" .pdf)
    echo "Processing: $filename"
    
    uv run docling-graph convert "$file" \
        --template "$TEMPLATE" \
        --output-dir "$OUTPUT_BASE/$filename" \
        --backend llm \
        --inference remote
    
    echo "Completed: $filename"
done

Configuration Priority

Options are resolved in this order (highest to lowest):

Command-line arguments
config.yaml (from init)
Built-in defaults

Example

# config.yaml
defaults:
  backend: llm
  inference: local
  processing_mode: many-to-one

# This uses remote inference (CLI overrides config)
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --inference remote

Output Structure

outputs/
├── metadata.json                # Pipeline metadata
├── docling/                     # Docling conversion output
│   ├── document.json            # Docling format
│   └── document.md              # Markdown export
└── docling_graph/               # Graph outputs
    ├── graph.json               # Complete graph
    ├── nodes.csv                # Node data
    ├── edges.csv                # Edge data
    ├── graph.html               # Interactive visualization
    └── report.md                # Summary report
    └── ...

Error Handling

Configuration Errors

[red]Configuration Error:[/red] Invalid backend type: 'invalid'

Solution: Use llm or vlm

Extraction Errors

[red]Extraction Error:[/red] Template not found: 'templates.Missing'

Solution: Check template path and ensure it's importable

API Errors

[red]Pipeline Error:[/red] API key not found for provider: mistral

Solution:

export MISTRAL_API_KEY="your-key"

Troubleshooting

🐛 Template Not Found

Error:

ModuleNotFoundError: No module named 'templates'

Solution:

# Ensure template is in Python path
export PYTHONPATH="${PYTHONPATH}:$(pwd)"

# Or use absolute path
uv run docling-graph convert document.pdf \
    --template "my_project.templates.BillingDocument"

🐛 Out of Memory

Error:

CUDA out of memory

Solution:

# Enable chunking
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --use-chunking

# Or use smaller model
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --model "ibm-granite/granite-4.0-1b"

🐛 Slow Processing

Solution:

# Disable chunking for small documents to speed up
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --no-use-chunking

Best Practices

👍 Use Configuration Files

# ✅ Good - Reusable configuration
uv run docling-graph init
uv run docling-graph convert document.pdf -t "templates.BillingDocument"

# ❌ Avoid - Repeating options
uv run docling-graph convert document.pdf \
    --template "templates.BillingDocument" \
    --backend llm --inference remote --provider mistral

👍 Organize Outputs

# ✅ Good - Organized by document
uv run docling-graph convert invoice_001.pdf \
    --template "templates.BillingDocument" \
    --output-dir "outputs/invoice_001"

# ❌ Avoid - Overwriting outputs
uv run docling-graph convert invoice_001.pdf \
    --template "templates.BillingDocument"

👍 Use Appropriate Backend

# ✅ Good - VLM for forms
uv run docling-graph convert id_card.jpg \
    --template "templates.IDCard" \
    --backend vlm

# ✅ Good - LLM for documents
uv run docling-graph convert research.pdf \
    --template "templates.ScholarlyRheologyPaper" \
    --backend llm

Next Steps

inspect Command → - Visualize results
CLI Recipes → - Common patterns
Examples → - Real-world examples

FilesExpand file tree

convert-command.md

Latest commit

History

convert-command.md

File metadata and controls

convert Command

Overview

Basic Usage

Required Arguments

Examples

Core Options

Debug Mode

Backend Selection

Inference Mode

Processing Mode

Model Configuration

Provider Override

Model Override

LLM connection overrides

Extraction Options

Chunking

Staged Extraction Tuning

Delta Extraction Tuning

Gleaning (direct and delta)

Structured Output Mode

Docling Configuration

Pipeline Selection

Export Options

Export Format

Docling Exports

Graph Options

Reverse Edges

Output Options

Output Directory

Complete Examples

📍 Simple Invoice (VLM)

📍 Rheology Research (Remote LLM)

📍 Debug Mode Enabled

📍 Local Processing (Ollama)

📍 Cypher Export for Neo4j

📍 Minimal Processing

Batch Processing

Process Multiple Files

Parallel Processing

Batch Script

Configuration Priority

Example

Output Structure

Error Handling

Configuration Errors

Extraction Errors

API Errors

Troubleshooting

🐛 Template Not Found

🐛 Out of Memory

🐛 Slow Processing

Best Practices

👍 Use Configuration Files

👍 Organize Outputs

👍 Use Appropriate Backend

Next Steps