引用

构建模型能力

引用

了解如何在 Claude 中使用引用功能来追踪和验证信息来源。

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： 引用包括页码范围（1 索引）。
  - 对于纯文本文档： 引用包括字符索引范围（0 索引）。
  - 对于自定义内容文档： 引用包括内容块索引范围（0 索引），对应于您提供的原始内容列表。
- 文档索引用于指示参考源，并根据您原始请求中的所有文档列表进行 0 索引。

自动分块与自定义内容

默认情况下，纯文本和 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 应用于您的顶级文档内容块。

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)

在此示例中：

文档内容使用文档块上的 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 列表的单个引用。

Was this page helpful?

构建模型能力

引用

了解如何在 Claude 中使用引用功能来追踪和验证信息来源。

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： 引用包括页码范围（1 索引）。
  - 对于纯文本文档： 引用包括字符索引范围（0 索引）。
  - 对于自定义内容文档： 引用包括内容块索引范围（0 索引），对应于您提供的原始内容列表。
- 文档索引用于指示参考源，并根据您原始请求中的所有文档列表进行 0 索引。

自动分块与自定义内容

可引用与不可引用的内容

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

引用索引

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

令牌成本

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

功能兼容性

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

引用和结构化输出不兼容

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

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

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

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

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)

在此示例中：

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

文档类型

选择文档类型

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

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

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

纯文本文档

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

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 列表的单个引用。

Was this page helpful?

引用如何工作

可引用与不可引用的内容

引用索引

令牌成本

功能兼容性

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

文档类型

选择文档类型

纯文本文档

纯文本引用示例

PDF 文档

PDF 引用示例

自定义内容文档

引用示例

响应结构

流式支持

流式事件示例

引用如何工作

可引用与不可引用的内容

引用索引

令牌成本

功能兼容性

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

文档类型

选择文档类型

纯文本文档

纯文本引用示例

PDF 文档

PDF 引用示例

自定义内容文档

引用示例

响应结构

流式支持

流式事件示例