跳转至

Citationware RAG（引文优先 RAG）

本页系统化 Eagle-RAG 的「引文优先 RAG」概念：每条生成 claim 必须可溯源到检索证据，引文是一等公民而非可选装饰。引文的物质基础来自 证据聚合 收敛后的证据集，可观测性与质量校验可经 Agent 可观测性 的 Langfuse score 接入。

当前成熟度

Eagle-RAG 已落地 answer-level [n] inline citation + hovercard，属「prompt 引导的软引文」。claim 级 span grounding、faithfulness 校验等是 §5 Roadmap。

1. 概念定义

Citationware RAG（引文优先 RAG）指一类 RAG 系统：生成的每条陈述（claim）都必须由检索到的证据支撑，并附带可验证的溯源（provenance）—— 引文是回答结构的一部分，而非事后附加的可有可无的来源列表。

成熟度可分两层：

层级 形态 Eagle-RAG 现状
L1 answer-level 答案文本中用 [n] 索引引用 sources 列表，前端 hovercard 展示 已实现
L2 claim-level 每条 claim → source span 级 grounding 映射 + faithfulness 校验 + abstain 未实现（roadmap）

2. 现有引文链路（已实现）

2.1 后端：引文坐标 schema

eagle_rag/api/schemas/query.py 中，TextSource 与 ImageSource 携带完整引文坐标：

# eagle_rag/api/schemas/query.py
class TextSource(BaseModel):       # L71
    # 引文坐标：path / document_id / score / content / page_nums / keywords / source_chunk_id
    ...

class ImageSource(BaseModel):      # L98
    # 四锚点：image_id / chunk_type / parent_section / content_summary / source_chunk_id
    ...

class QueryResponse(BaseModel):    # L148
    answer: str
    sources: QuerySources          # L152 = {text: list[TextSource], image: list[ImageSource]}
    route: RouteInfo
    steps: list[QueryStep]

ImageSource 的四锚点（image_id / chunk_type / parent_section / content_summary / source_chunk_id）让视觉证据可被章节归属与跨集合链接（见 多模态融合 锚定字段）。

2.2 后端：source 构造

eagle_rag/generation/multimodal_engine.py 把重排后的 NodeWithScore 映射为 sources：

函数 作用
text_sources_from_nodes（L857） 文本节点 → TextSource 列表，附 registry 回填的 file_name
_text_source（L780） 单节点 → source dict（path / level / score / content）
_enrich_text_sources（L821） 用文件名 registry 富化 source
_image_source（L863） 视觉节点 → ImageSource（含四锚点）

2.3 Prompt：[n] 索引引导

VLM prompt 要求模型用 [n] 索引引用参考文本、描述图片不捏造 URL（见 生成 §1.4 grounding 与引用）。这是「软引文」—— 由 prompt 引导，非结构化保证。

2.4 前端：inline citation hovercard

frontend/components/qa/sources-utils.ts 已实现 inline citation 的对齐与展示：

函数 行 作用
flattenSources L11 把 {text, image} 扁平为 1-based 索引列表，对齐 answer 中 [n]
findImageSourceIndex L27 按 image_id 查视觉 source 的 1-based 索引
sourceCitationExcerpt L122 hovercard 的证据摘录正文
sourceCitationTitle L135 hovercard 的标题行
resolveAnswerImageSrc L199 把 VLM 捏造的外部图片 URL 重映射到真实 /images/{image_id}

3. 引文流水线

flowchart LR
    R["retrieve"] --> RR["rerank"]
    RR --> TN["top_n 证据"]
    TN --> SRC["text_sources_from_nodes / _image_source<br/>构造 sources 列表"]
    TN --> PROMPT["VLM prompt<br/>引导 [n] 索引"]
    SRC --> RESP["QueryResponse.sources"]
    PROMPT --> RESP2["QueryResponse.answer (含 [n])"]
    RESP & RESP2 --> FE["前端 flattenSources<br/>1-based 索引对齐 [n]"]
    FE --> HC["hovercard<br/>sourceCitationExcerpt/Title"]
    FE --> IMG["resolveAnswerImageSrc<br/>图片 URL 重映射"]

关键耦合：sources 列表的顺序与 answer 中 [n] 的顺序必须一致 —— 前端 flattenSources 产 1-based 索引，[1] 对应 sources.text[0]。证据的排序（来自 证据聚合）直接决定引文编号。

4. 当前成熟度定位

已落地的是 L1 answer-level 软引文：

  • sources 列表携带完整引文坐标（path / document_id / page_nums / source_chunk_id）；
  • VLM prompt 引导 [n] 索引；
  • 前端 hovercard + 图片 URL 重映射；
  • [n] 是 prompt 引导，非结构化保证 —— 模型可能漏标、错标或捏造索引；
  • 无 claim → source span 级映射，无生成后校验。

5. Roadmap（未实现）

以下均为未实现的设计缺口，非当前能力

  • claim → source span 级 grounding 映射：当前 [n] 是答案级引用。理想是结构化 citations: list[ClaimCitation]，每条含 claim_text / source_index / source_span（source 内的字符范围）。潜在扩展点：QueryResponse 增 citations 字段；VLM 输出结构化 citation JSON 或后处理解析 [n] → span。
  • faithfulness / groundedness 校验：生成后校验每条 claim 是否真被 cited source 支撑。潜在扩展点：RERANK_MERGED 后或生成后增 GROUNDING_CHECK hook；接 Langfuse score（faithfulness / citation 覆盖率）做评测。
  • abstain / uncitable 检测：当证据不足以支撑时，系统应显式 abstain（「证据不足」）而非强行生成。潜在扩展点：结合 证据聚合 的聚合置信度阈值。
  • citation 覆盖率检查：统计答案中无引文 claim 的比例，作为质量指标暴露到 Agent 可观测性。
  • 冲突证据标注：当多 source 对同一 claim 矛盾时，在引文中标注冲突（与 证据聚合 冲突消解 roadmap 衔接）。

6. 与可观测性的衔接

引文质量可作为观测指标接入 Agent 可观测性：

  • Langfuse score（未实现）：faithfulness / citation 覆盖率 / abstain 率，作为 generation observation 的 score 上报；
  • structlog AI JSONL（已实现）：generate 事件已记录 prompt/completion（截断），可扩展记录 citation_count / uncited_claim_count；
  • Prometheus（已实现）：可新增 eagle_citation_coverage 之类的指标（roadmap）。

7. 参考