能力

引用

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

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

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

Claude Sonnet 3.7 的引用功能

与其他 Claude 模型相比，Claude Sonnet 3.7 在没有用户更明确指示的情况下可能不太倾向于生成引用。在使用 Claude Sonnet 3.7 的引用功能时，我们建议在 user 轮次中添加额外的指示，例如 "Use citations to back up your answer."。

我们还观察到，当要求模型以特定结构组织其响应时，除非明确告知在该格式中使用引用，否则模型不太可能使用引用。例如，如果要求模型在响应中使用 <result> 标签，您应该添加类似 "Always use citations in your answer, even within <result> tags." 的说明。

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

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

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "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?"
          }
        ]
      }
    ]
  }'

与基于提示词的方法对比

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

节省成本： 如果您基于提示词的方法要求 Claude 输出直接引用，您可能会看到成本节省，因为 cited_text 不计入输出 token。
更好的引用可靠性： 由于我们将引用解析为上述相应的响应格式并提取 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 开始索引，结束索引为排他性的。

Token 成本

启用引用会由于系统提示词的添加和文档分块而导致输入 token 略有增加。
然而，引用功能在输出 token 方面非常高效。在底层，模型以标准化格式输出引用，然后被解析为引用文本和文档位置索引。cited_text 字段是为了方便提供的，不计入输出 token。
在后续对话轮次中传回时，cited_text 也不计入输入 token。

功能兼容性

引用可与其他 API 功能配合使用，包括提示词缓存、token 计数和批处理。

引用与结构化输出不兼容

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

这是因为引用需要在文本输出中交错插入引用块，这与结构化输出的严格 JSON schema 约束不兼容。

将提示词缓存与引用配合使用

引用和提示词缓存可以有效地配合使用。

响应中生成的引用块不能直接缓存，但它们引用的源文档可以被缓存。为了优化性能，请在顶层文档内容块上应用 cache_control。

import anthropic

client = anthropic.Anthropic()

# 长文档内容（例如，技术文档）
long_document = "This is a very long document with thousands of words..." + " ... " * 1000  # 最小可缓存长度

response = client.messages.create(
    model="claude-opus-4-6",
    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"}  # 缓存文档内容
                },
                {
                    "type": "text",
                    "text": "What does this document say about API features?"
                }
            ]
        }
    ]
)

在此示例中：

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

文档类型

选择文档类型

我们支持三种用于引用的文档类型。文档可以直接在消息中提供（base64、文本或 URL），也可以通过 Files 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", # 可选
    "context": "Context about the document that will not be cited from", # 可选
    "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 的引用功能来追踪和验证响应中的信息来源。

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

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

Claude Sonnet 3.7 的引用功能

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

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

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-6",
    "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?"
          }
        ]
      }
    ]
  }'

与基于提示词的方法对比

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

节省成本： 如果您基于提示词的方法要求 Claude 输出直接引用，您可能会看到成本节省，因为 cited_text 不计入输出 token。
更好的引用可靠性： 由于我们将引用解析为上述相应的响应格式并提取 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 开始索引，结束索引为排他性的。

Token 成本

启用引用会由于系统提示词的添加和文档分块而导致输入 token 略有增加。
然而，引用功能在输出 token 方面非常高效。在底层，模型以标准化格式输出引用，然后被解析为引用文本和文档位置索引。cited_text 字段是为了方便提供的，不计入输出 token。
在后续对话轮次中传回时，cited_text 也不计入输入 token。

功能兼容性

引用可与其他 API 功能配合使用，包括提示词缓存、token 计数和批处理。

引用与结构化输出不兼容

这是因为引用需要在文本输出中交错插入引用块，这与结构化输出的严格 JSON schema 约束不兼容。

将提示词缓存与引用配合使用

引用和提示词缓存可以有效地配合使用。

响应中生成的引用块不能直接缓存，但它们引用的源文档可以被缓存。为了优化性能，请在顶层文档内容块上应用 cache_control。

import anthropic

client = anthropic.Anthropic()

# 长文档内容（例如，技术文档）
long_document = "This is a very long document with thousands of words..." + " ... " * 1000  # 最小可缓存长度

response = client.messages.create(
    model="claude-opus-4-6",
    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"}  # 缓存文档内容
                },
                {
                    "type": "text",
                    "text": "What does this document say about API features?"
                }
            ]
        }
    ]
)

在此示例中：

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

文档类型

选择文档类型

我们支持三种用于引用的文档类型。文档可以直接在消息中提供（base64、文本或 URL），也可以通过 Files 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", # 可选
    "context": "Context about the document that will not be cited from", # 可选
    "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?

引用的工作原理

可引用与不可引用的内容

引用索引

Token 成本

功能兼容性

将提示词缓存与引用配合使用

文档类型

选择文档类型

纯文本文档

纯文本引用示例

PDF 文档

PDF 引用示例

自定义内容文档

引用示例

响应结构

流式传输支持

流式事件示例

引用的工作原理

可引用与不可引用的内容

引用索引

Token 成本

功能兼容性

将提示词缓存与引用配合使用

文档类型

选择文档类型

纯文本文档

纯文本引用示例

PDF 文档

PDF 引用示例

自定义内容文档

引用示例

响应结构

流式传输支持

流式事件示例