chunking

Chunking

Use this when feeding documents into an LLM context window or a vector

store. Kreuzberg chunks two ways: inline during extraction (chunks land on

result.chunks), or standalone via the chunk command for text you

already have. Sizing is character-based by default, or token-based when a

tokenizer model is supplied.

Inline during extraction

Turn on chunking with --chunk and the chunks appear on the structured

result under chunks:

# 1000-char chunks, 200-char overlap (defaults when --chunk is on)
kreuzberg extract report.pdf --chunk --format json | jq '.chunks | length'

# Explicit size + overlap
kreuzberg extract report.pdf --chunk --chunk-size 1500 --chunk-overlap 300 --format json

Overlap must be smaller than chunk size — the CLI rejects

--chunk-overlap >= --chunk-size. When you set only --chunk-overlap

against an existing config, an overlap that exceeds the size is clamped to

chunk_size / 4.

Standalone chunk command

Chunk text you already have, from --text or stdin. Output defaults to

JSON:

# From a flag
kreuzberg chunk --text "long document text ..." --chunk-size 800 --chunk-overlap 100

# From stdin (pipe extracted content straight in)
kreuzberg extract notes.md | kreuzberg chunk --chunk-size 500 --format json

JSON output carries chunks (array of strings), chunk_count, the

resolved config (max_characters, overlap, chunker_type), and

input_size_bytes. Use --format text for a human-readable dump with

--- chunk N --- separators.

> Note: in the JSON output, chunker_type is rendered capitalized ("Text",

> "Markdown", "Yaml", "Semantic") because it is emitted via Rust's Debug

> formatting, whereas the --chunker-type input flag is lowercase

> (text, markdown, yaml, semantic). Lowercase the value before

> comparing if you parse it back.

Chunker types

--chunker-type selects the splitting strategy (standalone chunk

command):

| Type | Behavior |

| ---------- | ------------------------------------------------------------------- |

| text | Default. Plain character-window splitting with overlap. |

| markdown | Markdown-aware — splits on structure (headings, blocks) where possible. |

| yaml | YAML-aware splitting for structured config/data documents. |

| semantic | Topic-boundary splitting driven by --topic-threshold (0.0–1.0, default 0.75). |

# Markdown-aware chunking keeps headings and blocks intact
kreuzberg chunk --text "$(cat README.md)" --chunker-type markdown

# Semantic chunking — lower threshold = more, smaller topic chunks
kreuzberg chunk --text "$(cat transcript.txt)" --chunker-type semantic --topic-threshold 0.6

Token-based sizing

By default --chunk-size counts characters. To size chunks by tokens for

a specific model, pass --chunking-tokenizer with a HuggingFace tokenizer

id. On the extract command this implicitly enables chunking. Requires the

chunking-tokenizers feature (present in the default CLI build).

# Size chunks by GPT-4o tokens during extraction
kreuzberg extract report.pdf --chunking-tokenizer Xenova/gpt-4o --format json

# Or on the standalone command
kreuzberg chunk --text "$(cat doc.txt)" --chunking-tokenizer Xenova/gpt-4o --chunk-size 512

With a tokenizer set, --chunk-size is interpreted in tokens, not

characters.

Config file alternative

Field names in config files are snake_case under [chunking]:

[chunking]
max_characters = 1000
overlap = 200
chunker_type = "markdown"

kreuzberg extract report.pdf --config kreuzberg.toml --format json

> CLI flags map to config fields as --chunk-size → max_characters and

> --chunk-overlap → overlap. In config files use the snake_case names.

Programmatic access

From Python, enable chunking on the config and read result.chunks:

from kreuzberg import extract_file_sync, ExtractionConfig, ChunkingConfig

config = ExtractionConfig(
    chunking=ChunkingConfig(max_chars=1000, max_overlap=200),
)
result = extract_file_sync("report.pdf", config=config)
for chunk in result.chunks:
    print(len(chunk))

> Python ChunkingConfig uses max_chars / max_overlap. Rust uses

> max_characters / overlap. See references/python-api.md and

> references/rust-api.md in the sibling kreuzberg skill.

Picking parameters

• RAG / vector store — 500–1000 chars (or 256–512 tokens) with

10–20% overlap. Use markdown chunking for docs to keep sections whole.

• LLM summarization — larger chunks (1500–4000 chars) with small

overlap; size by tokens to stay under the model window.

• Topic segmentation — semantic chunker; tune --topic-threshold

down for finer splits, up for coarser ones.

Common pitfalls

• Overlap ≥ size — rejected on extract; clamped to size / 4 when

only overlap is changed against an existing config.

• Tokenizer without the feature — --chunking-tokenizer errors if the

CLI was built without chunking-tokenizers. The default build includes it.

• Empty input — the standalone chunk command bails on empty text;

provide --text or pipe non-empty stdin.

See references/configuration.md for the full [chunking] schema and

references/cli-reference.md for every chunk flag.