Skip to main content

​
Inspect a knowledge document’s chunks

When an AI agent answers from your knowledge base, it never reads the document — it reads the chunks the document was split into at ingestion. When an agent retrieves the wrong text, the fix is almost always at the chunk level: a split that landed mid-thought, or a chunk so large the match scores cannot tell it apart from its neighbors. The Document Inspector is the page where you see that structure and prove a hypothesis before you change anything.

​
Where the inspector lives

Open Agents → your agent → Knowledge base, pick a document, and the Document Inspector opens at:
The page loads the document’s chunk list, the document header (name, version badge, ingest status), and four working surfaces:
  • a test query bar across the top,
  • the rendered document with each chunk as a hover-highlightable region (left),
  • a per-chunk inspector for whatever chunk is selected (right),
  • the chunking configuration panel with the re-chunk action (bottom).
Documents still ingesting show a Processing badge; chunk-level actions wait for ingest to finish. Access follows the same role gate as the rest of the agent workspace — owner, admin, and developer roles can inspect and re-chunk.

​
Reading the document render

The left pane renders the document as a vertical stack of chunk regions, in chunk order. Each region is labeled with its chunk number, token count, and retrieval count, and the regions are colour-coded by how often real conversations have retrieved them — cold chunks the agent never reached stand out immediately next to the hot ones doing all the work. Hover a region to see exactly where the ingestion boundaries fell: where one chunk ends, where the overlap re-reads the tail of the previous chunk, and where the next one picks up. These boundaries are what the embedder saw — this is the actual text the retrieval index scored, not a re-rendered preview of the source file. Long documents paginate. The inspector loads 200 chunks at a time with a Load more chunks control, so a multi-thousand-chunk document remains fully inspectable.

​
Test-query bar: run a similarity query

The bar at the top runs a real similarity search against this document’s vectors — the same retrieval path the agent takes at runtime, scoped to one document.
  1. Type a question the way a customer would phrase it — “What would a user ask about this doc?” is the prompt, and it is the right shape.
  2. Press Enter or Run query.
  3. Read the match list: the matched chunk regions light up inline in the document render, each matched region shows its score in its header, and the result count appears under the bar. When the run produces a synthesized answer, it appears beneath the matches with the model that generated it.
Two diagnostics to read honestly:
  • No matching chunks — the query ran and nothing scored. That is the empty-result empty state, not a silent failure. Try the phrasing a customer would actually use, and confirm the document finished indexing.
  • KB collection missing in vector store — the document’s embeddings are absent from the vector store entirely. Re-ingest the document before studying chunk boundaries; nothing else will match until the collection exists.

​
Per-chunk inspector: preview what the agent retrieves

Select any chunk region and the right pane shows exactly what the agent receives when retrieval returns that chunk: This is the ground truth for a wrong-answer investigation: the agent does not see the document, it sees this box.

​
Diagnose “the agent answered the wrong text”

Work the diagnosis with the test query as your probe, not with re-ingestion guesses:
  1. Enter the customer’s phrasing in the test bar. If nothing matches, the problem is missing content — a gap, not a chunking defect. The knowledge gap miner catalogues these misses across all conversations.
  2. If the right chunk matched but scored weakly, open it in the inspector. A chunk that mixes three topics dilutes its embedding: the query matches, but barely. Chunk too large.
  3. If the wrong chunk matched, check where the right chunk’s boundary fell — a heading plus the first half of an answer with the second half pushed into the next chunk splits retrieval across two regions, and neither scores well on its own. Split boundary.
  4. Check retrieval counts. A correct chunk that is cold (zero retrievals) with a low overlap value can be structurally unreachable; a small overlap increase often recovers it.
Both defects resolve the same way: adjust the chunking configuration and re-chunk, then re-run the same test query to confirm the fix.

​
Chunking configuration and the re-chunk action

The bottom panel exposes the two fields ingestion used, with the document’s current values shown under each input:
  • Chunk size (chars) — how much text goes into one chunk, 100–8000 in steps of 50. Smaller chunks isolate topics; larger chunks carry more context per retrieval.
  • Chunk overlap (chars) — how much of the previous chunk’s tail repeats in the next chunk, 0–2000 in steps of 50. Overlap preserves sentences that a boundary would otherwise amputate, at the cost of duplicated vectors.
Click Re-chunk this doc to re-run ingestion with the new values. The action re-chunks and re-embeds every chunk of the document and bumps the document version — the version badge in the header advances, and every prior version’s test-query results are discarded rather than mislabeled as current. Re-chunking is safe to run on a live agent: retrieval reads only the current version, and the version move is atomic — either the agent continues on the old chunks or it reads the new ones; there is no partial state. The button is disabled while the document is processing, so a re-chunk cannot race an in-flight ingest.

​
Propagation: re-chunk → re-embed → re-test

A re-chunk does not finish at the click. The sequence to expect:
  1. The document re-chunks with the new size and overlap values.
  2. Every new chunk is re-embedded with the workspace’s embedding model.
  3. The version badge bumps; prior-version test results are invalidated.
  4. Re-run your test query against the new chunks — the page flags a result as stale (“from an earlier doc version — re-run the query”) if you try to read matches the version move has outrun.
Only step 4 tells you the change worked, so keep the original test query text around until you have re-run it.

​
Audit trail and version lineage (KB-VIZ-1)

The inspector is a built compliance surface (audit reference KB-VIZ-1): it exists so an operator can answer, on the record, “what text did the agent retrieve, and why” without touching production data. Two properties keep it auditable:
  • Role-gated access. Inspection and re-chunking are limited to owner, admin, and developer roles — the same roles that hold agent write access.
  • Version lineage. When the document sits in a legacy knowledge base, a Version history panel lists every retained version: pick any two for a line-level diff with added/removed counts, and Restore a retained version non-destructively — restoring re-uploads that content as a new head version, so a mistaken re-upload remains reversible. Restoration routes you to the new version’s inspector.
Verify a change in the inspector first, and keep the test-query evidence with your change notes — that pair is what makes “the agent answers wrong text” a closed case instead of a recurring ticket.

​
See also