Skip to content

Docling to Qdrant: Chunking for RAG ​

The short answer: Docling gives you one of the best structure detectors in open source — a typed DoclingDocument tree with explicit heading levels and pre-isolated page furniture. Qdrant gives you excellent hybrid vector search. Wired together naively — export_to_markdown(), split, embed — they still produce mediocre RAG, because the flattening step throws away exactly what Docling worked to recover. The missing link is POMA: PrimeCut().ingest() consumes the export_to_dict() JSON (auto-detected), parses the tree natively into chunksets, and PomaQdrant.upsert_poma_points() writes them as hybrid dense+sparse points that carry the chunkset's lineage in the payload. Retrieval comes back as assembled, prompt-ready cheatsheets.

What each end of the pipeline actually provides ​

Docling (IBM's open-source converter, also served via docling-serve) returns the DoclingDocument: a typed texts/tables/pictures/groups tree in which section_header items carry an explicit numeric level, tables are cell grids rather than pipe approximations, and repeating page furniture is parked in the furniture group with page_header/page_footer labels. What it doesn't provide: retrieval units. Its HybridChunker packs items into token windows, which controls chunk length, not chunk meaning. Details: The Optimal Chunker for Docling.

Qdrant provides named dense + sparse vectors on one point, payload indexes for filtered ANN, and HNSW with quantization options. What it doesn't provide: any opinion about what a point should contain. It retrieves nearest neighbors of whatever you embedded — including orphaned fragments and page-number noise, if that's what you gave it. Details: The Optimal Chunks for the Best Retrieval in Qdrant.

The naive wiring, and where it breaks ​

The common recipe — doc.export_to_markdown() → RecursiveCharacterTextSplitter → embed → client.upsert(...) — breaks in a pair-specific way: the flattening step discards the two things Docling is best at, and Qdrant then indexes the loss.

  • Explicit heading levels become glyphs, then nothing. A section_header with level: 2 is reduced to ## in the markdown, and the character splitter cuts wherever the count lands. The passage under Early termination reaches Qdrant with no machine-readable link to Termination clauses or Master Services Agreement — the LLM reads an orphaned fragment and answers out of context.
  • Furniture gets re-injected, then embedded. Docling had already isolated running headers, footers, and page numbers in the furniture group. Flattening pours them back into the text stream, and every one becomes a vector — near-identical noise points, repeated once per page, that crowd top-k results.
  • Overlap inflates the collection. Splitter overlap embeds every boundary span twice, growing the HNSW graph and stacking near-duplicates behind hit 1.

POMA parses the tree natively instead: explicit section_header levels become real hierarchy depth, the furniture classification is honored (deterministic, and free — your precursor did the work), tables survive as HTML, and chunks group into overlap-free chunksets.

The pipeline, end to end ​

bash
pip install docling 'poma[qdrant]'
python
import json
import os
from docling.document_converter import DocumentConverter
from poma import PrimeCut
from poma.integrations.qdrant import PomaQdrant

# 1. Docling conversion — your existing call, unchanged.
converter = DocumentConverter()
doc = converter.convert("contract.pdf").document
with open("contract.docling.json", "w") as f:
    json.dump(doc.export_to_dict(), f)

# 2. The missing link — DoclingDocument tree in, chunks + chunksets out.
poma = PrimeCut()  # reads POMA_API_KEY
result = poma.ingest("contract.docling.json")  # DoclingDocument shape auto-detected

# 3. Qdrant — hybrid points with hierarchy payloads, one call.
qdrant = PomaQdrant(
    url=os.environ["QDRANT_URL"],
    api_key=os.environ["QDRANT_API_KEY"],
    cloud_inference=False,  # True needs Qdrant Cloud's inference service; False embeds locally via fastembed and works on OSS/local Qdrant too
    collection_name="contracts",
    dense_model="sentence-transformers/all-MiniLM-L6-v2",
    sparse_model="Qdrant/bm25",
    dense_size=384,
    auto_create_collection=True,
)
qdrant.upsert_poma_points(result)

# 4. Retrieve prompt-ready context.
cheatsheets = qdrant.get_cheatsheets(
    query="What are the early termination conditions?",
    limit=3,
)
print(cheatsheets[0]["content"])

POMA validates the payload shape up front — auto-detection fingerprints schema_name == "DoclingDocument", and a corrupted or mislabeled upload 422s immediately, never silently degrading the index. A docling-serve envelope carrying only md_content falls back to a markdown passthrough with the same downstream stages. To force or suppress detection, set external_ocr_source to "docling" or "none". Because Docling already ran the parsing, POMA charges only for the downstream structure and chunking value.

On our reference legal-document benchmark, this pipeline answers the same query with 337 tokens of retrieved context instead of 1,542 for a recursive character splitter, with zero information loss — methodology in Document Ingestion & Chunking for RAG.

Metadata mapping: POMA fields → Qdrant primitives ​

One point per chunkset. upsert_poma_points writes exactly this payload: {"chunkset_index", "chunks", "file_id", "text"} plus "chunk_details" (the chunkset's chunk records — chunk_index, content, depth, file_id, code) while store_chunk_details stays at its default True.

POMA fieldQdrant primitiveWhat it enables
to_embeddense vector + BM25 sparse vector (named vectors, one point)paraphrase + exact-term hybrid retrieval
text (a copy of to_embed)payload fieldread back what was embedded
file_idpayload field (no index is created for you — add one with create_payload_index)scope queries to one document
chunkset_indexpayload fieldidentifies the point: the id is a UUIDv5 of file_id + chunkset_index
chunks (chunk indices)payload fieldjoins the point back to its chunk records
chunk lineage (chunk_index, content, depth from the explicit section_header levels, code)payload (chunk_details)cheatsheet assembly without a second store
page (from Docling item provenance)not written by PomaQdrant — the SDK's PomaChunk drops it; it survives on the archive's chunk recordspage-cited answers, page-range filters — see below

get_cheatsheets reads only that payload back: it groups each hit's chunkset_index + chunks by file_id and assembles the text from the hit's chunk_details (or from a chunk_data you pass instead).

Page numbers are in the .poma archive, so keep it (poma.ingest(..., download_dir="store", filename="contract.poma")) and attach them to the same points:

python
from poma.utils import unpack_poma_archive
from poma.integrations.qdrant.qdrant_poma_utils import chunk_uuid_string

page_of = {c["chunk_index"]: c.get("page") for c in unpack_poma_archive(poma_archive_path="store/contract.poma")["chunks"]}
for cs in result.chunksets:
    leaf = cs.chunks[-1]  # chunk indices are in document order; the last one is the leaf
    qdrant.set_payload(collection_name="contracts", payload={"page": page_of[leaf]}, points=[chunk_uuid_string(cs.file_id, cs.chunkset_index)])

Frequently asked questions ​

How do I get Docling output into Qdrant for RAG? ​

Save export_to_dict() as JSON, run PrimeCut().ingest() on it (the DoclingDocument shape is auto-detected and the tree parsed natively), then PomaQdrant.upsert_poma_points(result) — hybrid points whose payload carries file_id, chunkset_index, the chunkset's chunk indices, the embedded text, and chunk_details (chunk_index, content, depth) for assembly. Retrieve with get_cheatsheets(query=...).

Should I export the DoclingDocument to markdown before embedding into Qdrant? ​

No. Flattening reduces explicit section_header levels to glyphs and re-injects the furniture group into the text stream, so Qdrant stores orphaned fragments plus page-noise vectors. Feed the tree; POMA keeps levels as depth and drops the furniture.

What Qdrant payload fields should Docling chunks carry? ​

PomaQdrant writes file_id, chunkset_index, chunks, text and chunk_details (the chunk records with chunk_index, content and depth from Docling's explicit heading levels) by default. It does not write page, and it creates no payload indexes: add a payload index on file_id yourself, and if you need page-cited answers or page-range filters, read page off the archive's chunk records with unpack_poma_archive and attach it with client.set_payload on the same point ids.

Do Docling's page headers and footers end up in my Qdrant collection? ​

Not when POMA gets the tree: the furniture group and page_header/page_footer labels are honored and dropped, with POMA's own running-header/footer strip on top. Flatten first and they become per-page noise points.

Can I use Docling's HybridChunker to prepare points for Qdrant? ​

It emits token windows without the ancestor heading path, and Qdrant returns them as-is. Chunksets keep every leaf attached to all its ancestors — no window size to tune — and PomaQdrant writes them as hybrid points directly.

Same parser, different store: Docling → Pinecone · Docling → Weaviate · Docling → pgvector

Same store, different parser: Mistral OCR → Qdrant · LlamaParse → Qdrant · Marker → Qdrant

Foundations: The Optimal Chunker for Docling · The Optimal Chunks for Qdrant · All pipeline recipes · RAG chunking guide