引用 - Claude API Docs

This feature is eligible for Zero Data Retention (ZDR). When your organization has a ZDR arrangement, data sent through this feature is not stored after the API response is returned.

Claude 能够在回答有关文档的问题时提供详细的引用，帮助您追踪和验证响应中的信息来源。

所有活跃模型都支持引用，除了 Haiku 3。

请通过此表单分享您对引用功能的反馈和建议。

以下是如何在 Messages API 中使用引用的示例：

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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)

与基于提示的方法的比较

与基于提示的引用解决方案相比，引用功能具有以下优势：

成本节省： 如果您基于提示的方法要求 Claude 输出直接引用，您可能会看到成本节省，因为 cited_text 不计入您的输出令牌。
更好的引用可靠性： 由于引用被解析为上述各自的响应格式，并且 cited_text 被提取，引用保证包含对提供的文档的有效指针。
改进的引用质量： 在评估中，与纯粹基于提示的方法相比，引用功能被发现更可能引用文档中最相关的引用。

引用如何工作

通过以下步骤将引用与 Claude 集成：

提供文档并启用引用
- 包含任何支持格式的文档：PDF、纯文本或自定义内容文档
- 在每个文档上设置 citations.enabled=true。目前，引用必须在请求中的所有或没有文档上启用。
- 请注意，目前仅支持文本引用，图像引用尚不可用。
文档被处理
- 文档内容被"分块"以定义可能引用的最小粒度。例如，句子分块将允许 Claude 引用单个句子或链接多个连续句子以引用段落（或更长）！
  - 对于 PDF： 文本按照PDF 支持中的描述提取，内容被分块为句子。目前不支持从 PDF 中引用图像。
  - 对于纯文本文档： 内容被分块为可以引用的句子。
  - 对于自定义内容文档： 您提供的内容块按原样使用，不进行进一步分块。
Claude 提供引用的响应
- 响应现在可能包含多个文本块，其中每个文本块可以包含 Claude 正在做出的声明和支持该声明的引用列表。
- 引用引用源文档中的特定位置。这些引用的格式取决于被引用的文档类型。

自动分块与自定义内容

默认情况下，纯文本和 PDF 文档自动分块为句子。如果您需要更多地控制引用粒度（例如，对于项目符号或转录），请改用自定义内容文档。有关更多详情，请参阅文档类型。

例如，如果您希望 Claude 能够从您的 RAG 块中引用特定句子，您应该将每个 RAG 块放入纯文本文档中。否则，如果您不希望进行任何进一步的分块，或者如果您想自定义任何额外的分块，您可以将 RAG 块放入自定义内容文档中。

可引用与不可引用的内容

文档 source 内容中找到的文本可以被引用。
title 和 context 是可选字段，将传递给模型但不用于引用内容。
title 的长度有限制，因此您可能会发现 context 字段对于存储任何文档元数据作为文本或字符串化 json 很有用。

引用索引

文档索引从请求中所有文档内容块的列表进行 0 索引（跨越所有消息）。
字符索引是 0 索引的，具有排他性结束索引。
页码是 1 索引的，具有排他性结束页码。
内容块索引从自定义内容文档中提供的 content 列表进行 0 索引，具有排他性结束索引。

令牌成本

启用引用会因系统提示添加和文档分块而导致输入令牌略微增加。
但是，引用功能对输出令牌非常高效。在幕后，模型以标准化格式输出引用，然后解析为引用文本和文档位置索引。cited_text 字段为方便起见提供，不计入输出令牌。
当在后续对话轮次中传回时，cited_text 也不计入输入令牌。

功能兼容性

引用与其他 API 功能一起工作，包括提示缓存、令牌计数和批处理。

引用和结构化输出不兼容

引用不能与结构化输出一起使用。如果您在任何用户提供的文档（文档块或 RequestSearchResultBlock）上启用引用，并且还包含 output_config.format 参数（或已弃用的 output_format 参数），API 将返回 400 错误。

这是因为引用需要将引用块与文本输出交错，这与结构化输出的严格 JSON 模式约束不兼容。

将提示缓存与引用一起使用

引用和提示缓存可以有效地一起使用。

响应中生成的引用块不能直接缓存，但它们引用的源文档可以缓存。为了优化性能，将 cache_control 应用于您的顶级文档内容块。

在此示例中：

文档内容使用文档块上的 cache_control 进行缓存
在文档上启用引用
Claude 可以生成带有引用的响应，同时受益于缓存的文档内容
使用相同文档的后续请求将受益于缓存的内容

文档类型

选择文档类型

支持三种文档类型用于引用。文档可以直接在消息中提供（base64、文本或 URL），或通过文件 API上传并通过 file_id 引用：

类型	最适合	分块	引用格式
纯文本	简单文本文档、散文	句子	字符索引（0 索引）
PDF	包含文本内容的 PDF 文件	句子	页码（1 索引）
自定义内容	列表、转录、特殊格式、更细粒度的引用	无额外分块	块索引（0 索引）

不支持 .csv、.xlsx、.docx、.md 和 .txt 文件作为文档块。将这些转换为纯文本并直接包含在消息内容中。请参阅使用其他文件格式。

纯文本文档

纯文本文档自动分块为句子。您可以内联提供它们或通过其 file_id 引用：

PDF 文档

PDF 文档可以作为 base64 编码的数据或通过 file_id 提供。PDF 文本被提取并分块为句子。由于尚不支持图像引用，作为文档扫描且不包含可提取文本的 PDF 将无法引用。

自定义内容文档

自定义内容文档让您可以控制引用粒度。不进行额外分块，块根据提供的内容块提供给模型。

{
    "type": "document",
    "source": {
        "type": "content",
        "content": [
            {"type": "text", "text": "First chunk"},
            {"type": "text", "text": "Second chunk"},
        ],
    },
    "title": "Document Title",  # optional
    "context": "Context about the document that will not be cited from",  # optional
    "citations": {"enabled": True},
}

响应结构

启用引用后，响应包括多个带有引用的文本块：

{
    "content": [
        {"type": "text", "text": "According to the document, "},
        {
            "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,
                }
            ],
        },
        {"type": "text", "text": " and "},
        {
            "type": "text",
            "text": "the sky is blue",
            "citations": [
                {
                    "type": "char_location",
                    "cited_text": "The sky is blue.",
                    "document_index": 0,
                    "document_title": "Example Document",
                    "start_char_index": 20,
                    "end_char_index": 36,
                }
            ],
        },
        {
            "type": "text",
            "text": ". Information from page 5 states that ",
        },
        {
            "type": "text",
            "text": "water is essential",
            "citations": [
                {
                    "type": "page_location",
                    "cited_text": "Water is essential for life.",
                    "document_index": 1,
                    "document_title": "PDF Document",
                    "start_page_number": 5,
                    "end_page_number": 6,
                }
            ],
        },
        {
            "type": "text",
            "text": ". The custom document mentions ",
        },
        {
            "type": "text",
            "text": "important findings",
            "citations": [
                {
                    "type": "content_block_location",
                    "cited_text": "These are important findings.",
                    "document_index": 2,
                    "document_title": "Custom Content Document",
                    "start_block_index": 0,
                    "end_block_index": 1,
                }
            ],
        },
    ]
}

流式支持

对于流式响应，包含一个 citations_delta 类型，其中包含要添加到当前 text 内容块上的 citations 列表的单个引用。

client = anthropic.Anthropic()

# Long document content (e.g., technical documentation)
long_document = (
    "This is a very long document with thousands of words..." + " ... " * 1000
)  # Minimum cacheable length

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "text",
                        "media_type": "text/plain",
                        "data": long_document,
                    },
                    "citations": {"enabled": True},
                    "cache_control": {
                        "type": "ephemeral"
                    },  # Cache the document content
                },
                {
                    "type": "text",
                    "text": "What does this document say about API features?",
                },
            ],
        }
    ],
)
print(response)

引用如何工作

可引用与不可引用的内容

引用索引

令牌成本

功能兼容性

将提示缓存与引用一起使用

文档类型

选择文档类型

纯文本文档

纯文本引用示例

PDF 文档

PDF 引用示例

自定义内容文档

引用示例

响应结构

流式支持

流式事件示例