LlamaIndex CitationQueryEngine 怎样返回引用节点

LlamaIndex 的 CitationQueryEngine 查询结果要保留为响应对象，再读取 response.source_nodes。列表中的元素是 NodeWithScore，实际节点在 item.node，可读取正文与元数据。只保存 str(response) 会留下回答文字，无法从这段字符串直接取回来源节点。

官方地址：https://developers.llamaindex.ai/

最小写法：返回回答和来源列表

以下函数接收已经建好的 index。调用前应完成文档索引、嵌入模型和 LLM 的配置；它不是从零安装环境的脚本。使用当前模块化导入路径，显式关闭流式输出，先处理普通文本响应。

from llama_index.core.query_engine import CitationQueryEngine
from llama_index.core.schema import MetadataMode

def query_with_sources(index, question):
    # index 及其嵌入模型、LLM 已由项目配置；不在函数中写入凭据。
    engine = CitationQueryEngine.from_args(
        index,
        similarity_top_k=3,
        citation_chunk_size=384,
        citation_chunk_overlap=32,
        streaming=False,
    )
    response = engine.query(question)

    # 必须保留对象；转成字符串只用于取得回答文本。
    sources = []
    for number, item in enumerate(response.source_nodes, start=1):
        node = item.node
        sources.append({
            "citation_number": number,
            "node_id": node.node_id,
            "score": item.score,
            "text": node.get_content(metadata_mode=MetadataMode.NONE),
        })
    return {"answer": str(response), "sources": sources}

# 示例调用需传入项目现有的 index，不预设模型返回内容。
# result = query_with_sources(index, "资料中对设备维护周期有什么说明？")

这里的 3、384 和 32 是示例配置，不是推荐给所有知识库的最优参数。函数返回的 sources 是自己整理的应用字段，框架原字段仍叫 source_nodes。正常返回时，应用可以展示回答，同时用来源列表填充展开区域；模型服务或检索出错时应由上层处理异常，不要统一转成空来源列表。

source_nodes 中的对象包含什么

普通非流式响应包含回答文本与来源节点。NodeWithScore 将节点和分数放在一起；分数不应被显示成“事实正确率”，没有分数时也不要补成 100%。节点正文通过 get_content() 取得，文档标题、页码或公开地址则需要从入库时保留的 metadata 中读取。

这个功能由 Python 后端组织，不是浏览器原生引用 API。前端需要的通常是普通 JSON 数据，而不是整个 Python 响应对象。不要把内部索引对象直接交给浏览器，也不要期望前端只拿到回答字符串就能访问服务端节点。

引用编号对应引用分块，不一定对应原始文档

默认文本路径会把检索节点再次切成适合引用的片段，并为片段加入 Source 1: 这样的标识。因而一次检索得到的节点数与最终引用节点数可以不同；同一文档也可以出现多个引用片段。

在未自定义相关处理的标准文本路径下，来源顺序对应给生成器提供的 Source 编号。整理列表时先用 enumerate(..., start=1) 记录编号，再做展示。不要先按分数重新排序后重编编号，也不要按文档标题去重后让回答里的 [2] 指向另一段内容。

来源列表表示参与回答合成的来源上下文，不等于模型逐句实际引用了其中每一项。回答可能只出现部分编号，也可能产生不正确的标记；引用提示词不会自动证明每个结论都由对应片段支持。自定义合成器或上层包装还可能改变返回形式，需以所用接口为准。

展示标题与页码时，只提取允许公开的字段

来源节点不会凭空生成可信的网页 URL 或页码。下面约定项目在入库时提供可公开的 title 和 page_label，如果未提供就显示缺省文案。它们是应用约定，不是每个加载器都必然存在的固定字段。

from llama_index.core.schema import MetadataMode

def build_source_cards(response):
    cards = []
    for number, item in enumerate(response.source_nodes, start=1):
        node = item.node
        metadata = node.metadata or {}

        # 只输出允许公开的字段，不透传路径、凭据或内部文档信息。
        cards.append({
            "citation_number": number,
            "title": str(metadata.get("title") or "未提供标题"),
            "page_label": str(metadata.get("page_label") or ""),
            "excerpt": node.get_content(
                metadata_mode=MetadataMode.NONE
            )[:600],
        })
    return cards

示例将片段截成 600 个字符，适合预览卡片。完整片段可保留在受权限控制的后端，避免一口气把全部上下文塞进首屏。字符截断只改变预览文本，不应改变编号映射。若需要公开链接，应从受信任的元数据字段提取，并按应用规则处理链接；不要用任意文件路径拼接网页地址。

前端渲染回答、片段和标题时，应采用文本转义或受控 Markdown 渲染，避免把检索文本直接当作 HTML 插入。可点击来源也应遵循文档权限，不能因为它被检索到就默认对所有用户公开。

空来源与字段丢失怎么区分

若旧版本或包装层缺少预期属性，不建议用 getattr(response, "source_nodes", []) 把所有不兼容都静默变为空列表。应明确区分“不支持该响应结构”和“正常查询没有来源”，再决定降级为只展示回答还是提示来源暂不可用。

citation_chunk_size 越小越好吗？

不一定。更细的片段会改变来源粒度与数量，也可能拆散理解所需的上下文；应以能阅读和定位原文为目标，不能仅追求更多引用编号。

节点 ID 能当引用编号吗？

不宜。节点 ID 是对象标识，回答中的数字标记属于本次引用上下文。应用应单独保存 citation_number，不把两者混用。

有来源节点是否就保证回答正确？

不保证。来源便于追溯与对照，分数和标记都不等于结论正确性。展示时保留这种区别，比把所有来源贴上“已证实”更准确。

对已有查询代码，最关键的改动是在字符串转换之前保留响应对象，读取 source_nodes，并把稳定的本次引用编号与片段一起返回。标题、页码和公开链接则依赖入库元数据，不能由引用引擎自动补齐。

参考：CitationQueryEngine API；引用节点构造实现；响应对象定义。