Claude API 引用（citations）怎么用：citations.enabled、三种文档类型、引用位置字段和与结构化输出的冲突

本文根据 Claude 开发者平台官方文档《Citations》整理，资料核对于 2026-11-05。配图为本站整理的示意图，不是界面截图。本站（bigolab.com）不是 Anthropic 官方网站。

适用于谁

• 做文档问答、合同 / 报告核对、知识库问答，需要让用户看到「这句话出自哪里」的开发者；
• 不想自己用字符串匹配去反查依据的人。

基础调用见 /guides/claude-api-python-quickstart。联网搜索自带的引用是另一套机制，见 /guides/claude-api-web-search-tool；本文讲的是基于你自己提供的文档的引用。

结论先说

1. 官方定义： 引用让 Claude 在回答关于文档的问题时，给出支持每个论断的原文段落，方便核对来源。官方写明所有活跃模型都支持。
2. 打开方式： 在每个 document 块里加 "citations": {"enabled": true}。官方限制：一次请求里要么所有文档都开，要么都不开。
3. 三种文档： 纯文本（按句分块，引用是字符位置）、PDF（按句分块，引用是页码）、自定义内容（不再分块，引用是内容块编号）。
4. 目前只支持文本引用，不支持图片引用。 所以扫描件 PDF（没有可提取文字）无法被引用。
5. 与结构化输出冲突： 开了引用又带 output_config.format（或已弃用的 output_format），API 返回 400。

图：本站根据 Claude 官方文档：Citations 整理的示意图

一、最小请求

官方示例是一个纯文本文档。下面是把它转写成 Python 的版本（模型 ID 沿用官方示例中的 claude-opus-5-5）：

python
import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "text",
                        "media_type": "text/plain",
                        "data": "The grass is green. The sky is blue.",
                    },
                    "title": "My Document",
                    "context": "This is a trustworthy document.",
                    "citations": {"enabled": True},
                },
                {"type": "text", "text": "What color is the grass and sky?"},
            ],
        }
    ],
)
print(response)

字段说明（官方）：

• source 里的文字是可以被引用的内容；
• title 和 context 是可选字段，会传给模型，但不会被当作引用来源；title 长度有限制，要放文档元数据（比如编号、来源）可以用 context，写成文本或序列化后的 JSON。

二、官方说的处理过程

1. 你提供文档并设置 citations.enabled；
2. 文档内容被「分块」，分块决定了引用的最小粒度。比如按句分块，Claude 可以引用单句，也可以把连续几句串起来引用一整段；
3. Claude 返回带引用的回答：回答可能由多个文本块组成，每个文本块可以带一个支持该论断的引用列表。

引用的位置格式取决于文档类型：

文档编号（document_index）从 0 开始，按整个请求中所有文档块的顺序算（跨所有消息）。

官方的建议：想让 Claude 引用 RAG 检索片段里的具体句子，就把每个片段放进一个纯文本文档；如果不想再被分块，或想自己定义粒度，就把片段放进自定义内容文档。

三、返回里的字段

启用后，响应的 content 是一串文本块，带引用的块长这样（官方示例，省略部分字段）：

json
{
  "type": "text",
  "text": "the grass is green",
  "citations": [
    {
      "type": "char_location",
      "cited_text": "The grass is green. ",
      "document_index": 0,
      "document_title": "Example Document",
      "start_char_index": 0,
      "end_char_index": 20
    }
  ]
}

三种引用类型：

• 纯文本：char_location，字段 start_char_index、end_char_index；
• PDF：page_location，字段 start_page_number、end_page_number；
• 自定义内容：content_block_location，字段 start_block_index、end_block_index。

它们都带 cited_text、document_index、document_title。

怎么用在页面上： 按顺序遍历文本块，把有 citations 的块渲染成可点击的角标，点击时用 document_index 找到文档、用位置字段高亮原文。官方示例里的 cited_text 是为方便而提供的。

四、自定义内容文档

想控制引用粒度，用 source.type: "content"，把每一块自己切好放进去（官方示例的结构）：

json
{
  "type": "document",
  "source": {
    "type": "content",
    "content": [
      {"type": "text", "text": "First chunk"},
      {"type": "text", "text": "Second chunk"}
    ]
  },
  "title": "Document Title",
  "citations": {"enabled": true}
}

官方说明：不做额外分块，提供的块原样交给模型；引用的是块编号范围。

PDF 可以用 base64、URL 或 file_id 提供；官方说明扫描件没有可提取文本时不可引用。官方还指出 .docx、.xlsx 等 document 块不支持的格式，要先转成纯文本再放进消息；.csv、.md 这类纯文本文件可以用明确的 text/plain 类型上传。文件上传见官方 Files API 页面。

五、费用、缓存、流式

• Token： 官方说启用引用会让输入 token 略有增加（系统提示词增加和文档分块导致），但对输出 token 很高效；cited_text 不计入输出 token，在后续对话轮中回传时也不计入输入 token。
• 提示词缓存： 可以配合使用。官方说回复里生成的引用块不能直接被缓存，但它们引用的源文档可以；做法是在顶层的文档内容块上加 cache_control。缓存基础见 /guides/claude-prompt-caching。
• 其他兼容： 官方说引用可以与提示词缓存、token 计数、批量处理配合。
• 流式： 引用以 content_block_delta 事件里的 citations_delta 类型到达，每个增量带一条引用，要追加到当前文本块的 citations 列表里。

六、想要结构化数据又要引用怎么办

图：本站根据官方文档整理的示意图

官方明确：引用和结构化输出不兼容，因为引用需要在文本输出里穿插引用块，而结构化输出要求严格的 JSON 模式。同时用会返回 400。

官方给的替代办法：让 Claude 每个字段一行回答，例如 field: value，并要求每行都引用文档；然后在你的代码里把行解析成结构化数据。官方提示词示例：

text
Extract these fields from the document: grass_color, sky_color.
Answer with one line per field in the form "field: value", and cite the document for each line. After the colon, write only the value, with no explanation or quotation.

官方还提醒两点：

• 避免只要 JSON 的提示词，例如「只返回一个 JSON 对象，不要其他文字」。这样的请求能成功，但回答里可能很少甚至没有引用；
• 解析后要检查：每个字段要有值且至少有一条引用，API 不保证这两点。

常见问题

Q：有些文档开了引用、有些没开可以吗？

不可以。官方写的是「目前引用必须在一次请求的所有文档上都启用或都不启用」。

Q：图片能引用吗？

不能，官方说目前不支持图片引用，PDF 里的图片同理。

Q：和联网搜索的引用有什么区别？

联网搜索的引用总是开启，字段是 web_search_result_location；文档引用需要你在每个文档块里显式打开。

Q：我碰到 429 或 400 怎么处理？

429 见 /guides/claude-api-error-429-rate-limit；400 先对照本文第六节检查是不是引用和结构化输出同时开了。

相关教程

• /guides/claude-api-python-quickstart：Python 快速上手
• /guides/claude-prompt-caching：提示词缓存
• /guides/claude-api-web-search-tool：联网搜索工具

参考资料

• Claude 开发者平台文档：Citations — https://platform.claude.com/docs/en/build-with-claude/citations