Skip to content

LlamaParse to Qdrant: Chunking for RAG ​

The short answer: LlamaParse gives you excellent per-page markdown; Qdrant gives you excellent hybrid vector search. Wired together the standard LlamaIndex way — MarkdownElementNodeParser into a VectorStoreIndex over Qdrant — they still produce mediocre RAG, because the nodes in between are isolated fragments. The missing link is POMA: PrimeCut().ingest() consumes the saved LlamaParse result JSON (auto-detected), rebuilds the cross-page heading hierarchy 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 ​

LlamaParse, LlamaIndex's markdown-native parser, returns a JSON result with pages[], each carrying a page number, an md string (headings marked, tables inline), a flattened text string, and an images list. The md field is where the value lives. What it doesn't provide: cross-page hierarchy (each page's md is independent — page 41's ## Termination clauses has no link to page 3's # Master Services Agreement), retrieval units, or inline image bytes (those stay server-side, one /result/image/{name} fetch each). Details: The Optimal Chunker for LlamaParse.

Qdrant provides named dense + sparse vectors on one point, payload indexes for filtered ANN, and HNSW with quantization options, in Qdrant Cloud or open source. What it doesn't provide: any opinion about what a point should contain. It retrieves nearest neighbors of whatever you embedded — including context-free fragments, 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 canonical LlamaIndex recipe — LlamaParse(result_type="markdown").load_data(...) → MarkdownElementNodeParser → VectorStoreIndex over a Qdrant vector store — is three lines of glue, which is exactly the problem. It breaks in a pair-specific way:

  • Nodes arrive in Qdrant as orphans. MarkdownElementNodeParser separates tables from prose, but the node under ### Early termination carries no machine-readable link to the chapter it lives in. Qdrant embeds and retrieves it faithfully — an out-of-context paragraph, at excellent latency.
  • LlamaParse's page numbers never reach the payload. Markdown mode hands the pipeline page-independent markdown; by the time nodes exist, pages[].page is gone, so no Qdrant payload can cite a page and page-range filters are off the table.
  • Dead image references become noise vectors. The saved result carries only ![](name) refs — the bytes live server-side at LlamaParse. Fed through a node parser, those dead links either pollute the embedded text or get regex-stripped with no record of what was lost.
  • Qdrant's sparse side goes unused. The default wiring embeds dense-only. Even when hybrid is enabled, fragments starve BM25 of section vocabulary — the terms worth matching live in the headings the node parser threw away.

Neither tool is at fault. LlamaParse parsed correctly; Qdrant retrieved correctly. The step between them discarded the structure one produced and the other could have filtered on.

The pipeline, end to end ​

bash
pip install llama-parse 'poma[qdrant]'
python
import json
import os

from llama_parse import LlamaParse
from poma import PrimeCut
from poma.integrations.qdrant import PomaQdrant

# 1. LlamaParse — your existing parse job, unchanged.
parser = LlamaParse(api_key=os.environ["LLAMA_CLOUD_API_KEY"])
json_result = parser.get_json_result("contract.pdf")
with open("contract.llamaparse.json", "w") as f:
    json.dump(json_result[0], f)

# 2. The missing link — raw result JSON in, chunks + chunksets out.
poma = PrimeCut()  # reads POMA_API_KEY
result = poma.ingest("contract.llamaparse.json")  # LlamaParse 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 fingerprints the payload up front (pages[] with md + page — a corrupted or mislabeled upload 422s immediately), reads md and ignores the flattened text, neutralizes the server-side image refs and counts them in content_metadata, strips running headers and footers, and rebuilds the cross-page heading tree before chunking. To force or suppress detection, set external_ocr_source to "llamaparse" or "none".

If you're building on LlamaIndex, POMA replaces the node-parser step, not your framework — from the retrieved cheatsheets onward, everything is your stack.

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, code)payload (chunk_details)cheatsheet assembly without a second store
page (from LlamaParse pages[].page)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

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)])

What retrieval looks like afterwards ​

get_cheatsheets runs the hybrid query (dense + BM25 sparse, fused), then deduplicates the heading lineage the retrieved chunksets share and merges them into one coherent context block. That assembly step is where the token savings land: on our reference legal-document benchmark, the same query answered with 337 tokens of context instead of 1,542 for a recursive character splitter, with zero information loss — methodology here. The point is not that Qdrant got faster; it's that every point in the collection was worth retrieving.

Frequently asked questions ​

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

Save the raw JSON result, run PrimeCut().ingest() on it (auto-detected, md preferred, hierarchy rebuilt), 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=...).

Do I still need MarkdownElementNodeParser and VectorStoreIndex to use LlamaParse with Qdrant? ​

No — that pairing is where the quality loss happens: isolated nodes, no ancestor context, page numbers gone. POMA replaces the node-parser step and writes chunksets to Qdrant directly; everything downstream of retrieval stays your LlamaIndex stack.

What Qdrant payload fields should LlamaParse chunks carry? ​

PomaQdrant writes file_id, chunkset_index, chunks, text and chunk_details (the chunk records with chunk_index, content and depth) by default. It does not write page, and it creates no payload indexes: add a payload index on file_id yourself for per-document scoping, and if you need page-cited answers or page-range filters, read page from the archive's chunk records with unpack_poma_archive and attach it with client.set_payload on the same point ids. Concatenate-then-split pipelines lose the page number entirely, before anything can be attached.

Do images in a LlamaParse result make it into Qdrant? ​

Not as content — the bytes live server-side at LlamaParse and the saved JSON has only ![](name) refs. POMA neutralizes those dead refs and counts each in content_metadata, so the loss is visible in the ingest result instead of embedded as broken links.

Should the Qdrant collection use hybrid search for LlamaParse content? ​

Yes: parsed documents are full of exact tokens that dense embeddings blur. PomaQdrant writes BM25 sparse vectors by default and fuses both at query time — and chunkset heading breadcrumbs give the sparse side section vocabulary that fragments lack.

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

Same store, different parser: Mistral OCR → Qdrant · Docling → Qdrant · Textract → Qdrant

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