本页目录10
要点速览
- 文档来源 source.type 分三种：text（纯文本）、base64（PDF）、content（自定义分块内容），对应不同的引用定位字段
- 响应中的引用对象按来源类型分别为 char_location、page_location、content_block_location，各自字段不同
- citations 必须对请求中所有文档统一启用或统一不启用，不能逐文档混用
- cited_text 字段不计入输出 token，但会因系统提示追加和文档分块使输入 token 略有增加
- 引用功能不能与结构化输出（output_config.format）同时使用；图片引用（含 PDF 中的图片）暂不支持
本文是对 Claude 官方参考页的中文整理，完整与最新内容以原文为准：https://platform.claude.com/docs/en/build-with-claude/citations
概览
Citations（引用）功能让 Claude 在回答关于文档的问题时，返回支撑每条论断的确切原文段落，便于追踪与核实回答来源。
| 项目 | 内容 |
|---|---|
| ZDR（零数据保留） | 符合条件（不含「受管控模型」，详见官方 ZDR 文档） |
| 支持平台 | Claude API、Claude Platform on AWS、Amazon Bedrock、Google Cloud、Microsoft Foundry |
| 支持模型 | 所有 active models（当前在售模型）均支持引用功能 |
基本用法示例
在 Messages API 请求中，给 document 内容块加上 citations: {enabled: true} 即可开启引用：
{
"model": "claude-opus-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?"}
]
}
]
}
文档块（document block）顶层字段
| 字段 | 是否必需 | 说明 |
|---|---|---|
type | 必需 | 固定为 document |
source | 必需 | 文档来源对象，结构因 source.type 而异，见下表 |
title | 可选 | 传给模型但不计入被引用内容；长度有限制（原文未给出具体数值） |
context | 可选 | 传给模型但不计入被引用内容；适合存放文档元数据（文本或字符串化 JSON），当 title 长度不够用时可用它补充信息 |
citations | 启用引用时必需 | 例如 {"enabled": true}；同一请求内所有文档必须统一启用或统一不启用引用，不支持逐文档混用 |
文档来源类型（source.type）
source.type | media_type / 关键字段 | data / content 格式 | 说明 |
|---|---|---|---|
text | text/plain | data：原始文本字符串 | 纯文本文档，按句子分块 |
base64 | application/pdf | data:PDF 的 base64 编码字符串 | PDF 文档，按句子分块并附带页码；仅支持可提取文字的 PDF，扫描版（无可提取文本层）PDF 无法被引用 |
content | 无 media_type | content：内容块数组，如 [{"type": "text", "text": "First chunk"}, {"type": "text", "text": "Second chunk"}] | 自定义分块内容，不做额外切分，按你提供的块直接作为引用单元 |
另有
search_result（搜索结果）类型的文档来源在导航与「下一步」中被提及，但本页正文未给出其 JSON 示例，具体结构请参考官方「Search results」相关页面。
响应中的引用对象类型
响应里，带引用的文本块结构为：
{
"type": "text",
"text": "string",
"citations": [
{"type": "char_location|page_location|content_block_location", "...": "..."}
]
}
每种来源类型对应的引用对象类型与字段如下：
| 引用类型 | 对应来源 | 字段 |
|---|---|---|
char_location | text（纯文本） | type、cited_text、document_index、document_title、start_char_index、end_char_index |
page_location | base64(PDF) | type、cited_text、document_index、document_title、start_page_number、end_page_number |
content_block_location | content（自定义内容） | type、cited_text、document_index、document_title、start_block_index、end_block_index |
search_result_location | 搜索结果文档 | 原文本页未详述其字段，仅在搜索结果功能相关内容中被提及 |
公共字段说明：
| 字段 | 含义 |
|---|---|
cited_text | 被引用的原文片段；为方便阅读而提供，不计入输出 token |
document_index | 该引用对应的文档在请求 content 数组中的索引 |
document_title | 对应文档的 title 字段值 |
流式事件（Streaming）
| 事件 | 说明 |
|---|---|
citations_delta（出现在 content_block_delta 事件内） | 每个 delta 携带一条待追加到当前 text 内容块 citations 列表的引用记录，该记录放在 citation 字段里（原文流式示例："delta": {"type": "citations_delta", "citation": {"type": "char_location", ...}}） |
限制与不支持的组合
| 限制 | 说明 |
|---|---|
| 与结构化输出（structured outputs）不兼容 | 当设置了 output_config.format 时不能同时启用引用，因为引用需要在文本输出中穿插引用块，与严格 JSON schema 输出冲突 |
| 图片引用暂不支持 | 「Image citations are not yet possible」，包括无法引用 PDF 中的图片内容 |
| 扫描版 PDF 不可引用 | 缺少可提取文字层的 PDF 无法生成引用 |
| 启用方式为「全有或全无」 | 同一请求内的所有文档必须统一启用或统一不启用 citations |
Token 与计费说明
| 项目 | 说明 |
|---|---|
| 输入 token | 会因系统提示追加内容和文档分块处理而略有增加 |
| 输出 token | cited_text 字段不计入输出 token 成本（模型内部以标准化格式输出引用，再解析为 cited_text 与文档位置索引，前者只是便于阅读的附加字段） |
| 后续轮次复用 | 若后续消息中重新引用了先前的 cited_text，该部分不重复计入输入 token |
与其他功能的交互
| 功能 | 交互说明 |
|---|---|
| Prompt caching（提示缓存） | 可与引用功能配合使用：响应中生成的引用块本身不能被直接缓存，但引用所依据的源文档可以被缓存 |
| 结构化输出 | 不兼容，见上文限制表 |
反馈渠道
官方提供了一个引用功能反馈表单，供开发者提交使用中的建议与问题（具体链接见原文页面的 Tip 提示框）。