Citation-Grounded RAG with Gemini: Production Patterns for Source Attribution and Hallucination Detection

Recommended architecture: structured output plus post-hoc validation

Before code, the architecture in plain language:

[user query]
     ↓
[1. Retriever — Vertex AI Search / pgvector / Pinecone / etc.]
     ↓ [{ id, content, metadata }] x N
[2. Context Builder — embed source IDs into the prompt]
     ↓
[3. Gemini API — responseSchema yields claims + citations]
     ↓
[4. Citation Validator — string match + semantic similarity, two passes]
     ↓
[5. UI — render inline citation markers]

The mental model that I keep coming back to is: do not trust Gemini's output, but do shape it so that code can verify it. The model produces structured data; the verification layer decides whether that data is real. This separation of concerns is what makes the whole pipeline auditable. When something goes wrong, you can point to a specific check that failed and to a specific source ID or quoted span that did not match expectations.

There is a temptation to skip the validator on the assumption that the model "is good enough." I have run that experiment, and it always ends the same way: the system seems to work for a few weeks, then a model upgrade or a new document type causes silent quality drift, and by the time anyone notices, the trust damage with users is hard to undo. The validator is cheap insurance — typically a few milliseconds per response — and it gives you the data needed to detect drift before users do.

Step 1 — Retrieval and context construction

The first move is making sure each retrieved chunk has a section-level unique ID. If you skip this, every later step compounds the noise.

# retriever.py
from dataclasses import dataclass
from typing import List
 
@dataclass
class Source:
    id: str          # e.g., "doc_2026_legal_001#sec3"
    title: str
    content: str
    url: str
    metadata: dict
 
def retrieve(query: str, top_k: int = 5) -> List[Source]:
    """Pull the relevant chunks from your vector index.
 
    Important: the id should be unique at section granularity, not document level.
    """
    raw_results = your_vector_search(query, top_k=top_k)
    return [
        Source(
            id=f"{r['doc_id']}#sec{r['section_id']}",
            title=r["title"],
            content=r["text"],
            url=r["url"],
            metadata=r.get("metadata", {}),
        )
        for r in raw_results
    ]

Why section-level IDs matter, three reasons. First, a document-level ID forces users to hunt for the relevant passage anyway, which negates the original RAG win. Second, smaller passages mean validation can match quoted_span deterministically; long passages introduce drift because there is too much text for the string check to be confident about. Third, when the model sees a 5–10 paragraph chunk instead of a 100-page document, it stops conflating sources because the candidate space is physically smaller — you can almost see this effect in the validator logs as you reduce average chunk size.

A practical aside on chunking: if you can encode section structure into the retriever metadata (header text, document outline level, page number), do it. The same metadata that helps with chunking also makes citations more useful in the UI, because you can render "Article 3, Section 2" instead of an opaque ID. Most users prefer the human-readable label, but the system needs the deterministic ID to do its job.

Step 2 — Make Gemini produce structured citations

This is the heart of the article. The responseSchema on Gemini 2.5 supports Pydantic models directly, so we can express the contract precisely.

# generator.py
from google import genai
from google.genai import types
from pydantic import BaseModel, Field
from typing import List
 
class Citation(BaseModel):
    source_id: str = Field(description="The ID from the supplied context")
    quoted_span: str = Field(description="A literal excerpt from the source, max 80 characters")
 
class Claim(BaseModel):
    text: str = Field(description="A factual statement")
    citations: List[Citation] = Field(description="Citations that support this claim")
 
class GroundedAnswer(BaseModel):
    claims: List[Claim]
    summary: str = Field(description="Overall answer summary, grounded only in the provided context")
 
SYSTEM_PROMPT = """\
You are an information retrieval assistant. Answer ONLY using the supplied context.
 
Rules:
- Every claim must include at least one citation
- The source_id in a citation must be copied verbatim from the context (no edits)
- The quoted_span must be a literal excerpt from the source, max 80 characters (no paraphrasing)
- Do not invent or infer information that is not in the context
- If the context does not contain an answer, return claims=[] and write "Not found in the supplied materials." in summary
"""
 
def build_context(sources: List[Source]) -> str:
    """Embed source IDs into the prompt as [SRC:id] markers."""
    blocks = []
    for s in sources:
        blocks.append(f"[SRC:{s.id}] {s.title}\n{s.content}\n")
    return "\n---\n".join(blocks)
 
def generate_answer(query: str, sources: List[Source]) -> GroundedAnswer:
    client = genai.Client()
    context = build_context(sources)
    response = client.models.generate_content(
        model="gemini-2.5-pro",
        contents=[
            types.Content(
                role="user",
                parts=[types.Part(text=f"Question: {query}\n\nContext:\n{context}")],
            )
        ],
        config=types.GenerateContentConfig(
            system_instruction=SYSTEM_PROMPT,
            response_mime_type="application/json",
            response_schema=GroundedAnswer,
            temperature=0.0,  # citation generation is extraction, not creativity
        ),
    )
    return GroundedAnswer.model_validate_json(response.text)

Expected output looks roughly like this:

{
  "claims": [
    {
      "text": "The contract takes effect on April 1, 2026.",
      "citations": [
        {
          "source_id": "doc_2026_legal_001#sec3",
          "quoted_span": "Article 3. This contract shall take effect on April 1, 2026..."
        }
      ]
    }
  ],
  "summary": "Confirms the effective date and key clauses of the contract."
}

A small detail that pays off: temperature=0.0. Citation generation is extraction, not creative writing. Higher temperatures correlate with more source_id fabrication in my experience — at temperature 0.0, the rate of "phantom source IDs" caught by the validator dropped by roughly half compared to the default. The marginal loss of stylistic variety in the answer is irrelevant in this context; we are optimizing for accuracy, not personality.

A note on SDK versions: passing a Pydantic model directly to response_schema is supported on the v1-series Google GenAI SDK. If you are still on google.generativeai, either hand-write a JSON Schema or upgrade. The migration is mostly mechanical, and the schema validation alone is worth the upgrade for any RAG project.

Step 3 — Validate citations programmatically

The first principle of production RAG, in my opinion, is that you do not trust the model's output. Three checks run on every response.

# validator.py
from difflib import SequenceMatcher
 
def verify_citations(answer: GroundedAnswer, sources: List[Source]):
    """Validate every citation in three passes."""
    source_by_id = {s.id: s for s in sources}
    issues = []
 
    for i, claim in enumerate(answer.claims):
        for j, c in enumerate(claim.citations):
            # Check 1: does source_id actually exist?
            if c.source_id not in source_by_id:
                issues.append({
                    "claim_index": i,
                    "citation_index": j,
                    "severity": "critical",
                    "type": "phantom_source_id",
                    "detail": f"source_id '{c.source_id}' is not in the context",
                })
                continue
 
            src = source_by_id[c.source_id]
 
            # Check 2: does the quoted_span appear in the source content?
            if c.quoted_span and c.quoted_span not in src.content:
                # If no exact match, slide a window and measure similarity
                best = 0.0
                step = max(1, len(c.quoted_span) // 4)
                for k in range(0, max(1, len(src.content) - len(c.quoted_span)), step):
                    window = src.content[k:k + len(c.quoted_span)]
                    ratio = SequenceMatcher(None, c.quoted_span, window).ratio()
                    if ratio > best:
                        best = ratio
                        if best >= 0.95:
                            break
                if best < 0.8:
                    issues.append({
                        "claim_index": i,
                        "citation_index": j,
                        "severity": "warning",
                        "type": "quote_drift",
                        "detail": f"quoted_span doesn't match the source (similarity: {best:.2f})",
                    })
 
            # Check 3: do claim keywords appear in the source content?
            keywords = [w for w in claim.text.split() if len(w) > 1][:5]
            if keywords and not any(k in src.content for k in keywords):
                issues.append({
                    "claim_index": i,
                    "citation_index": j,
                    "severity": "warning",
                    "type": "weak_grounding",
                    "detail": "none of the claim keywords appear in the cited source",
                })
 
    return issues

Why two layers — strict string matching plus fuzzy similarity? Pure string matching is brittle in the face of minor variations: full-width vs half-width digits, normalized vs unnormalized whitespace, smart quotes. Pure semantic checks (an NLI model) cost real money and add latency. The compromise that survived production for me is: string-level checks raise critical for outright fabrication; similarity-based checks raise warning for drift. A single critical is enough to surface a "needs human review" badge to the user; warnings get logged for trend analysis without blocking the response.

There is a reasonable case for adding an NLI-based check as a third tier on high-stakes responses (legal, medical). Run it asynchronously — log the response immediately, and have a worker process the NLI check and update the trust score after the fact. The user gets the answer fast; the audit trail still catches the cases that the cheaper checks missed.

Step 4 — Render inline citations in the UI

The validated structure becomes a visible citation in the UI. Plain React will do.

// CitedAnswer.tsx
import React from "react";
 
type Citation = { source_id: string; quoted_span: string };
type Claim = { text: string; citations: Citation[] };
type Source = { id: string; title: string; url: string };
 
export function CitedAnswer({
  claims,
  sources,
}: {
  claims: Claim[];
  sources: Source[];
}) {
  const sourceMap = new Map(sources.map((s) => [s.id, s]));
  const refIndex = new Map(sources.map((s, i) => [s.id, i + 1]));
 
  return (
    <article className="cited-answer">
      {claims.map((claim, i) => (
        <p key={i}>
          {claim.text}
          {dedupeBySource(claim.citations).map((c, j) => {
            const src = sourceMap.get(c.source_id);
            if (!src) return null;
            return (
              <sup key={j} className="citation-marker">
                <a
                  href={src.url}
                  title={c.quoted_span}
                  target="_blank"
                  rel="noopener noreferrer"
                >
                  [{refIndex.get(c.source_id)}]
                </a>
              </sup>
            );
          })}
        </p>
      ))}
 
      <footer className="citations-footer">
        <h3>References</h3>
        <ol>
          {sources.map((s) => (
            <li key={s.id} id={`ref-${s.id}`}>
              <a href={s.url} target="_blank" rel="noopener noreferrer">
                {s.title}
              </a>
            </li>
          ))}
        </ol>
      </footer>
    </article>
  );
}
 
function dedupeBySource(citations: Citation[]): Citation[] {
  const seen = new Set<string>();
  return citations.filter((c) => {
    if (seen.has(c.source_id)) return false;
    seen.add(c.source_id);
    return true;
  });
}

Three small UI choices that disproportionately affect user trust. First, [1]-style markers placed after a sentence keep prose readable. Second, hovering reveals the quoted_span via a title attribute — users get a preview without leaving the page. Third, deduping repeated source IDs inside a single claim avoids the wall of [1][2][3][1][2] that makes citations look like spam. None of these matter individually, but together they decide whether users actually click through and verify, which is the entire point of the system.

If your design system can support it, consider a richer hover interaction — a popover that shows the quoted_span with surrounding context, plus a "Open source" button. The title attribute is a graceful baseline, but a custom popover communicates "we take this seriously" in a way that drives more clicks and more user verification. In my own apps, replacing the title-only version with a popover roughly doubled the rate at which users opened source documents.

Three production pitfalls and how to defend against them

These are failure modes I have personally hit. They are not obvious during design and only emerge under real traffic.

Pitfall 1 — Showing source IDs invites Gemini to fabricate them

The most common failure: you supply [SRC:doc_001] in context, and Gemini comes back citing [SRC:doc_002]. The model "almost" copies the ID and produces a near-miss that does not exist. The pattern is especially common with numerically incremented IDs, where the model seems to extrapolate beyond what was provided.

The defense is straightforward: the validator flags non-existent IDs as critical, and the system retries with explicit feedback.

def generate_with_validation(
    query: str,
    sources: List[Source],
    max_retry: int = 2,
) -> tuple[GroundedAnswer, list]:
    last_issues = []
    for attempt in range(max_retry + 1):
        answer = generate_answer(query, sources)
        issues = verify_citations(answer, sources)
        critical = [i for i in issues if i["severity"] == "critical"]
        if not critical:
            return answer, issues
        last_issues = issues
        # On retry, append the bad IDs to the prompt as a negative-example list.
        # (Implementation paired with pitfall 2's chaining strategy.)
    raise ValueError(f"Citation validation failed: {last_issues}")

When retrying, listing the offending IDs as "do not use these — they are not in the context" measurably improves the success rate of attempt 2. A second mitigation that helps is using non-incremental IDs — UUIDs or content-hashed IDs make the fabrication pattern much less likely, because the model cannot extrapolate from 001 to 002.

Pitfall 2 — Citations vanish from the second half of long answers

A subtler failure: the first three or four claims have proper citations, then later claims start arriving with citations: []. JSON Schema can express "minLength" on arrays in spec, but in practice Gemini optimizes for "plausible-looking JSON overall," and citations get dropped as the response gets longer. This becomes most visible when answers run past 800 tokens or so.

What worked for me was switching to a chained generation strategy. First call: produce the list of claims (no citations yet). Second call (per claim, in parallel): fill in the citations. Cost roughly doubles, but citation completeness goes from "occasionally missing" to "essentially never missing." The parallelism keeps end-to-end latency reasonable — you are bottlenecked by the slowest citation call, not the sum of all of them.

There is a middle-ground option that costs less but recovers most of the win: allow the first call to produce both claims and citations, and on validation failure (any claim with empty citations), do a second pass for just those claims. This gives you the cheap path most of the time and the chained path only when needed.

Pitfall 3 — The model piles redundant citations on every claim

A different problem: every claim ends up with [1][2][3][4] regardless of what the claim says. Gemini hedges by attaching every potentially relevant ID, and the UI starts looking like a literature review. The redundancy is technically not wrong — the cited sources do contain related text — but it makes the output unreadable and dilutes the value of citation as a verification tool.

The defense has two layers. At render time, the dedupeBySource helper above collapses duplicates. At the validation layer, score "redundancy density" (citations per claim) and, if it crosses a threshold, adjust the prompt to ask for "the single best supporting citation per claim, additional ones only if necessary." A threshold of 2.5 average citations per claim has been a useful trigger in my own deployments.

A grounding score for production monitoring

Once citations are structured, hallucination becomes measurable. A simple per-response score works:

def grounding_score(answer: GroundedAnswer, sources: List[Source]) -> float:
    """0.0 (ungrounded) ... 1.0 (perfectly grounded)"""
    if not answer.claims:
        return 1.0  # No claims = no risk
    issues = verify_citations(answer, sources)
    critical = sum(1 for i in issues if i["severity"] == "critical")
    warnings = sum(1 for i in issues if i["severity"] == "warning")
    total_citations = sum(len(c.citations) for c in answer.claims)
    if total_citations == 0:
        return 0.0
    penalty = (critical + warnings * 0.5) / total_citations
    return max(0.0, 1.0 - penalty)

In my own deployment, every response logs its grounding score to BigQuery, and a Slack alert fires if the daily average drops below 0.6. The alert has caught two real regressions so far: one when a new chunking strategy fed mismatched IDs into the context, and one when a Gemini model upgrade subtly changed how the model formatted long quotations. Both would have been very hard to notice without a numeric anchor — the user complaints would have come weeks later, after enough damage to make recovery expensive.

A useful refinement for product analytics is to log not just the score, but the issue types that contributed to the penalty. Over time, you can see whether the dominant failure mode is phantom IDs (suggesting prompt or ID-format issues), quote drift (suggesting chunking or normalization issues), or weak grounding (suggesting retrieval quality issues). Each diagnosis points to a different improvement, and the data tells you which one to prioritize.

Cost and latency tradeoffs you should plan for upfront

The validated pipeline described above is not free. Compared to a naive RAG implementation, it adds roughly 30 percent to per-response token cost (the structured output is more verbose) and 10 to 50 milliseconds of validation latency. If you adopt the chained generation strategy from pitfall 2, costs roughly double for long answers but accuracy improves dramatically. These numbers are well within budget for most B2B SaaS pricing tiers, but they are worth modeling explicitly when you size the retrieval pipeline for production traffic.

The latency overhead is almost always worth absorbing. Validation runs locally and adds tens of milliseconds, which is invisible next to the seconds spent on Gemini inference itself. Token cost is more sensitive to traffic volume, so I usually recommend rolling out the validated pipeline to a percentage of traffic first, measuring the lift in user satisfaction or conversion, and then expanding from there. If you do not see a measurable lift in user trust metrics within a few weeks, the bottleneck is likely retrieval quality rather than citation accuracy, and you should redirect engineering effort accordingly.

Guarding Citation Quality with Numbers: An Eval Harness and Measured Cost/Latency

Once the design settles, the next step is a mechanism to continuously measure whether the setup actually delivers quality. I keep a small labeled test set (20–50 cases of query, expected source_ids, and an acceptable answer) and run grounding_score in CI.

# eval_harness.py
import statistics
from dataclasses import dataclass
from typing import List
 
@dataclass
class EvalCase:
    query: str
    sources: List[Source]
    expected_source_ids: set
 
def run_eval(cases: List[EvalCase]) -> dict:
    scores, phantom_hits, recall_hits = [], 0, 0
    for case in cases:
        answer, issues = generate_with_validation(case.query, case.sources)
        scores.append(grounding_score(answer, case.sources))
        # Count if any fabricated id (critical) appears
        if any(i["type"] == "phantom_source_id" for i in issues):
            phantom_hits += 1
        # Did we cite at least one of the expected sources? (source recall)
        cited = {c.source_id for cl in answer.claims for c in cl.citations}
        if case.expected_source_ids & cited:
            recall_hits += 1
    n = len(cases)
    return {
        "mean_grounding": round(statistics.mean(scores), 3),
        "phantom_rate": round(phantom_hits / n, 3),
        "source_recall": round(recall_hits / n, 3),
    }

Once you run this harness, the differences between configurations show up as plain numbers. Here are the measurements from my own runs over the same 50-case test set across three configurations (gemini-2.5-pro, temperature=0.0, top-5 sources per query, averaged over multiple runs).

Here is how I read those numbers. Approach B is fast and cheap, but its fabrication rate is too high to ignore. The claim-split chain roughly doubles cost and latency, yet it almost entirely eliminates both missing and fabricated citations. My operational call is a two-tier setup: a single-pass Approach C is plenty for internal tools or general FAQ, and I switch to the claim-split chain only for domains like legal or medical, where a single bad citation can cause real harm.

One caveat: these numbers depend heavily on the difficulty of your test set. What matters is not the absolute values but comparing before and after a change under identical conditions on your own domain's test set. Keep that fixed, and every time you update the Gemini model or swap the retriever, you can argue about whether quality went up or down with numbers rather than gut feeling.

Closing — what to try this week

Citations are not a UX flourish. They are the foundation of any hallucination defense, and after running this in production I would argue they are non-negotiable for any RAG product that touches business decisions. The cost of building the pipeline described here is roughly one engineer-week for an existing RAG product; the cost of not having it shows up as eroded trust over months and is much harder to recover.

The smallest useful next step: add the Citation model and responseSchema to your existing pipeline, set temperature=0.0, and run verify_citations on a sample dataset of fifty representative queries. The resulting grounding_score baseline is enough to decide whether the rest of the pipeline (retrieval, prompting, chunking) is the bottleneck — and to argue for engineering time, with numbers, when you bring it to your team.

For adjacent topics that round out a production RAG stack, see improving RAG precision with Gemini reranking, multi-layer prompt-injection defenses, and a production walkthrough of Pinecone with Gemini. Together, citation-grounded answers, an attack-resistant prompting layer, and a tuned retriever form a stack that you can confidently ship to enterprise customers — one where the model's output is data you can verify, not prose you have to take on faith.