Pick the cleanest way to log citation linkage between answer and chunks
Have the model emit citation markers that map to stable chunk ids, then store the resolved mapping as a structured citations attribute on the span so groundedness checks and user-facing UIs both have what they need.
Imagine a research essay where every paragraph ends with a tiny footnote number. The numbers connect back to a bibliography at the end, and the bibliography lines up with actual books on a shelf. A reader can pick any footnote and walk to the exact book to verify the claim. If the essay had no footnote numbers, the reader has to trust the writer. If the footnotes referenced 'book 3' but the bibliography did not exist, the reader is stuck. RAG citation linkage builds the same chain inside an answer: the model emits the footnote numbers, the trace stores the bibliography, and a verifier can walk every claim back to a real retrieved chunk.
Concept explanation~2 min read
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Concept explanation~2 min read
Everything you need to truly understand this topic: intuition, mechanics, step by step explanation, code, formulas, and worked example. Click to expand.
Citation linkage in RAG observability is one of those problems that looks easy until you actually need to verify a claim three weeks after the fact and the trace tells you 'here is the answer, here are some chunks that were retrieved'. The link between specific claims and specific chunks has to be a structured object on the span; everything else is fuzzy matching and regret.
This card walks through the three components (stable ids, markers in the answer, structured attribute on the span), the schema choices that make downstream consumers happy, and the failure modes that the observability layer has to detect.
Three components and why each is non-negotiable
A citation linkage system is the composition of three small pieces.
Stable chunk ids
Every retrieved chunk needs a deterministic id that survives across the lifecycle of the trace. Content-addressed hashing (SHA-256 over normalized text plus document and version) is the standard. Database row ids work in steady state but break when the index re-builds and ids shift. Free text snippets are unworkable because the model paraphrases.
The id has to travel from the retriever through the reranker into the LLM context and back out as part of the generated answer's citation markers.
Marker in the answer
The model emits a citation marker after each factual claim. The system prompt instructs the format. Modern frontier models follow the instruction reliably once a few-shot example is provided. The marker is the bridge: it lives inside the freeform answer text but maps deterministically to a chunk id.
Structured citations attribute on the span
The generation span carries a typed list of citation objects. Minimum shape: {marker, chunk_id}. The producer parses the answer once at emission, resolves each marker to a chunk id, validates that every marker resolves, and writes the list as a typed attribute.
What you lose without any one of them
- No stable ids: you have markers and an unsearchable answer text; reconstruction requires storing chunk text on the span (expensive) or re-running retrieval (lossy).
- No markers: you have ids and an answer with no link; you have to guess which chunk grounded which claim.
- No structured attribute: you have markers in text; every consumer re-parses, format drift breaks everyone.
Situations where this technique stops working.
2–4 min · Everything important, quickly.
Real products, models, and research that use this idea.
- Perplexity renders inline numbered citations that map to indexed sources; the same shape stored as span attributes powers their internal quality dashboards.
- Anthropic's Claude with the 'citations' API parameter emits structured citation objects natively; pass them through to the span and you have linkage for free.
What an interviewer would ask next. Try answering before peeking at the approach.
QHow do you detect when the model invents a citation marker for a chunk that was not retrieved?
Parse markers from the answer, attempt to resolve each against the retrieval set; emit a 'hallucinated citation' counter on the span and alarm on its rate.
Red flags & common mistakes
The phrases that signal junior thinking. Click to expand.
Red flags & common mistakes
The phrases that signal junior thinking. Click to expand.
Logging just the answer text and the chunks separately with no marker to id mapping; you can see both lists but cannot tell which chunk grounded which claim.
60 second bullets to scan on the way to the call.
Three components: stable id, marker in answer, structured attribute
Content-addressed hashing for chunk ids
Primary sources. Browse if you want the original framing.
Same topic, related formats. Practice these next.