Claude Platform Docs
Messages模型能力

引用

让 Claude 的回答以您的源文档为依据。引用功能会返回支持每项论断的确切段落，以便您验证答案并向用户展示来源。

Claude 在回答有关文档的问题时可以提供详细的 "citations"（引用），帮助您追踪和验证每个回答背后的来源。

所有活跃模型均支持引用功能。

以下示例展示了如何通过 Messages API 在纯文本文档上启用引用：

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)

引用的工作原理

按以下步骤将引用功能与 Claude 集成：

  1. 提供文档并启用引用

    • 以任一受支持的格式包含文档：PDF、纯文本或自定义内容文档。
    • 在每个文档上设置 citations.enabled=true。目前，在一个请求中必须对所有文档全部启用或全部不启用引用。
    • 目前仅支持文本引用。尚不支持图像引用。

  2. 文档被处理

    • 文档内容会被 "chunked"（分块），以定义可能引用的最小粒度。例如，句子分块允许 Claude 引用单个句子，或将多个连续句子串联起来以引用一个段落或更长的篇幅。
      • 对于 PDF： 按照 PDF 支持中所述提取文本，并将内容分块为句子。目前不支持引用 PDF 中的图像。
      • 对于纯文本文档： 内容被分块为可供引用的句子。
      • 对于自定义内容文档： 您提供的内容块按原样使用，不做进一步分块。

  3. Claude 提供带引用的回答

    • 响应现在可能包含多个文本块，其中每个文本块可以包含 Claude 提出的一项论断以及支持该论断的引用列表。
    • 引用指向源文档中的特定位置。这些引用的格式取决于被引用文档的类型。
      • 对于 PDF： 引用包含页码范围（从 1 开始索引）。
      • 对于纯文本文档： 引用包含字符索引范围（从 0 开始索引）。
      • 对于自定义内容文档： 引用包含与所提供的原始内容列表相对应的内容块索引范围（从 0 开始索引）。
    • 提供文档索引以指示引用来源，该索引根据您原始请求中所有文档的列表从 0 开始编号。

可引用与不可引用的内容

  • 文档 source 内容中的文本可以被引用。
  • title 和 context 是可选字段，会传递给模型，但不用于被引用的内容。
  • title 有长度限制，因此 context 字段可用于以文本或字符串化 JSON 的形式存储文档元数据。

引用索引

  • 文档索引根据请求中所有文档内容块的列表（跨越所有消息）从 0 开始编号。
  • 字符索引从 0 开始，结束索引为不包含（exclusive）。
  • 页码从 1 开始，结束页码为不包含。
  • 内容块索引根据自定义内容文档中提供的 content 列表从 0 开始编号，结束索引为不包含。

令牌成本

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

功能兼容性

引用功能可与其他 API 功能配合使用，包括 "prompt caching"（提示缓存）、令牌计数和批处理。有关提示缓存的详细信息，请参阅提示缓存。

将提示缓存与引用结合使用

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

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

client = anthropic.Anthropic()

# 长文档内容（例如技术文档）
long_document = (
    "This is a very long document with thousands of words..." + " ... " * 1000
)  # Minimum cacheable length

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": 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），也可以通过 Files API 上传并通过 file_id 引用：

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

纯文本文档

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

本页顶部的入门示例展示了每种 SDK 中完整的纯文本请求。文档块使用 text 源：

{
  "type": "document",
  "source": {
    "type": "text",
    "media_type": "text/plain",
    "data": "Plain text content..."
  },
  "title": "Document Title",
  "context": "Context about the document that will not be cited from",
  "citations": { "enabled": true }
}

PDF 文档

PDF 文档可以以 base64 编码数据、URL 或 file_id 的形式提供。PDF 文本会被提取并分块为句子。由于尚不支持图像引用，因此属于文档扫描件且不包含可提取文本的 PDF 无法被引用。

client = anthropic.Anthropic()

pdf_base64 = base64.standard_b64encode(
    pathlib.Path("/path/to/document.pdf").read_bytes()
).decode()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_base64,
                    },
                    "title": "Document Title",
                    "context": "Context about the document that will not be cited from",
                    "citations": {"enabled": True},
                },
                {"type": "text", "text": "Summarize this document."},
            ],
        }
    ],
)
print(response)

自定义内容文档

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "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},
                },
                {"type": "text", "text": "Summarize this document."},
            ],
        }
    ],
)
print(response)

响应结构

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

{
  "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
        }
      ]
    }
  ]
}

流式传输支持

对于 "streaming"（流式传输）响应，引用以 content_block_delta 事件中的 citations_delta 增量类型到达。每个增量包含一条引用，用于添加到当前 text 内容块的 citations 列表中。

后续步骤

流式传输消息

在处理文本增量的同时处理 citations_delta 增量类型，以便在流式传输过程中渲染带引用的响应。

搜索结果

将 RAG 管道中的搜索结果作为具有内置引用支持的一等内容块传入。

PDF 支持

了解 Claude 如何从 PDF 中提取文本，以及基于页码的引用如何映射回您的源文件。

Files API

一次上传文档，即可在多个引用请求中通过 file_id 引用它们。

Compatibility

Supported platforms
  • Claude API
  • Claude Platform on AWS
  • Amazon Bedrock
  • Google Cloud
  • Microsoft Foundry

Was this page helpful?