Chunking policy

When you upload a document knowledge source, you choose a chunking policy that controls how extracted text is split before embedding. The choice is stored on the source and applied during background processing: extract text (Docling) → chunk → embed → index.

Policies at a glance

PolicyBest forBehavior
ParagraphGeneral policies, manuals, reports, mixed proseMerge paragraphs (blank-line splits) up to ~1000 characters per chunk
FAQSupport Q&A lists, FAQ pagesOne chunk per detected question/answer pair; falls back to paragraph if nothing matches
CustomTuned corporaYou set chunk size (100–8000 chars) and overlap (up to half of chunk size); uses the same paragraph-merging logic as Paragraph

Re-upload or re-process a source to apply a new policy. Changing policy does not automatically re-index files already processed.

Paragraph

  • Splits on blank lines, then greedily merges paragraphs until the size target is reached.
  • Default overlap is 0.
  • Oversized single paragraphs may produce chunks larger than the target.

Custom

You specify:

  • Chunk size - target maximum characters per chunk (100–8000).
  • Overlap - characters copied from the end of one chunk into the start of the next, which can help retrieval across boundaries.

Custom does not change the splitting algorithm-only the numbers.

FAQ

  • Scans line by line for question markers, then treats following lines as the answer until the next marker.
  • One searchable chunk per pair when possible; very long answers may split into multiple chunks with the question repeated on each part.
  • If no FAQ patterns are found, processing falls back to paragraph chunking.

How questions are detected

A new FAQ item starts when a line begins with one of these patterns (case-insensitive):

  • Q: Q. Q) Q-
  • Question: Question. (and similar punctuation)
  • FAQ: …
  • Markdown-style headings such as ## Q: …
  • Numbered lines such as 1. 2. at the start of the line
Text before the first question is ignored (except 
Comment:
lines-see below). Each pair must have a non-empty answer or it is skipped.

Comment lines (structure and author notes)

Lines that start with 
Comment:
 (also 
Comment.
/ 
Comment)
/ 
Comment-
, case-insensitive) are not treated as questions or answers. They are omitted as standalone chunks.
The text after the marker sets context for following Q/A pairs until the next 
Comment:
line. That context is prepended to each affected chunk as:
[Comment: your text here]

Q: …
…
Use 
Comment:
for section titles, group labels, or internal editor notes you do not want as their own indexed chunk. A 
Comment:
between two questions does not get appended to the previous answer.
Comment: Orders & shipping

Q: How long does delivery take?
Standard shipping is 5–7 business days.

Comment: Returns

Q: What is your return policy?
You may return unworn items within 30 days.

Formatting FAQ documents (Word / PDF)

Author in plain paragraphs when possible-avoid tables, text boxes, and multi-column layouts.

Recommended pattern - one question per paragraph, then answer paragraph(s):

Q: What is your return policy?

You may return unworn items within 30 days with receipt.

Q: Do you ship internationally?

Yes. We ship to most countries. Import duties may apply.

Question: and numbered questions (1. What are your opening hours?) work the same way.

Do

  • Put the full question on one paragraph.
  • Use a consistent prefix (Q` or Question:) for every item.
  • Use normal paragraph breaks between question and answer.
  • Use a dedicated FAQ document for FAQ content; use Paragraph for mixed prose.

Avoid

PitfallWhy
Questions without Q: / Question: / numberingNot detected; content before the first marker is skipped.
Question and answer in the same paragraphThe whole line is the “question”; answer may be empty.
Shift+Enter inside a questionThe next line may be treated as answer text.
Lines starting with 
1.
inside an answer		Starts a new FAQ item-use bullets in answers instead.
Intro you need indexedPreamble is ignored-use 
Comment:
+ Q/A or use Paragraph.
Comment:
inside an answer		Starts a new context for the next question only; it is not added to the current answer.

After upload, confirm processing is completed and test chat with wording similar to your questions.

What is stored

Upload metadata includes a chunking object, for example:

{ "chunking": { "strategy": "faq" } }

or

{
  "chunking": {
    "strategy": "manual",
    "chunk_size": 1200,
    "chunk_overlap": 100
  }
}

After processing, resolved settings are recorded on the source for support and debugging.

Ingest trace (debug observability)

Opt in with 
chunking.debug_trace: true
on upload (checkbox Record ingest trace in Agent Studio), or set server env 
INGEST_DEBUG_TRACE=true
.
When enabled, PrimePilot creates a private ingest trace chat (
deployment_type: ingest_trace
) owned by the tenant system user. The chat has no squad handler. Messages use log roles:
  • Summary - policy, namespace, index, total chunk count
  • Up to 20 chunk payloads (full text)
  • Truncation notice if more than 20 chunks were produced (all chunks are still indexed)
  • Upsert result after Pinecone upload
The chat id is stored on the knowledge source as 
ingest_log_chat_id
in 
source_metadata
. Open it from Conversation history like other observability chats.

Related