PDF to RAG chunks: preserve headings, pages, and retrieval context
RAG quality starts before embeddings. A PDF must become chunks that remain understandable outside the full document, retain their heading path, and carry enough page evidence to audit an answer later.
Short answer: Split on meaningful document blocks and headings, not arbitrary byte positions. Keep a stable chunk ID, heading path, source pages, and block-level provenance beside the text; then evaluate retrieval on questions from your own corpus before choosing a final size or overlap.
A chunk needs context as well as text
A paragraph such as “revenue increased by 3%” is weak retrieval material when the company, reporting period, and section title were left in another chunk. Heading paths and concise document context make the passage interpretable after it leaves the source PDF. Anthropic describes the same failure mode in its Contextual Retrieval work: isolated chunks can lose the information needed to retrieve and use them correctly.
| Chunk field | Purpose | Review question |
|---|---|---|
| text | Content sent to search or embedding | Does it make sense by itself? |
| heading_path | Document context | Does the path name the right section? |
| pages | Source location | Can a reviewer reopen the evidence? |
| sources | Block-level method and offsets | Are unavailable fields null rather than guessed? |
What the pdfmd RAG profile actually exports
The current pdfmd.rag-chunk.v1 profile writes JSONL: one JSON object per chunk. It starts a new chunk at heading boundaries and around 1,600 characters, carries one previous non-heading block as overlap, and reports an estimated token count. These are transparent defaults, not a claim that one setting is optimal for every model or corpus.
{"schema_version":"pdfmd.rag-chunk.v1",
"id":"report-chunk-3",
"heading_path":["Risk factors","Supply chain"],
"pages":[8,9],"estimated_tokens":312,
"text":"...","sources":[{"block_id":"p8b4","page":8}]}Evaluate retrieval before indexing the full corpus
- Create answerable questions whose evidence lives on known pages, plus unanswerable controls.
- Inspect whether the correct chunk appears before judging the generated answer.
- Test exact identifiers with keyword search as well as semantic retrieval.
- Compare at least two chunk sizes and overlaps on the same question set.
- Store the source-map export beside the chunks when citations or audits matter.
OpenAI vector stores expose both automatic and static chunking strategies, which is a useful reminder that chunk size is an ingestion decision rather than a universal constant. Production changes should be versioned and evaluated; a larger overlap can improve recall while also increasing storage, duplicate hits, and prompt cost.
Official sources and evidence boundary
These links support format and platform behavior. pdfmd processing and point costs are governed by this site's pricing and privacy pages.
Keep the review checklist
Download the Markdown checklist and reuse it next time. Export-format changes are recorded in the public changelog.
Frequently asked questions
What chunk size should I use for PDF RAG?
There is no universal size. Start with the exported defaults, then compare retrieval results on questions from your own documents before indexing the full corpus.
Why keep heading paths in every chunk?
They restore section context that can disappear when a paragraph is separated from the surrounding PDF.
Is JSONL ready to upload to every vector database?
No. It is a portable line-oriented intermediate file. Map its fields to the schema required by your retrieval system.
Does pdfmd create embeddings or host a vector database?
No. It exports chunks and provenance. Embedding, indexing, retrieval evaluation, and storage remain in your chosen stack.
Export evidence-aware chunks, then run your own eval
Convert the PDF once and choose the RAG chunks profile. Cloud conversion requires Google sign-in and page points; download the JSONL before leaving because results are not stored automatically.