引用

Note

此功能支持零数据保留 (ZDR)。当您的组织有 ZDR 协议时，通过此功能发送的数据在 API 响应返回后不会被存储。

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

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

Tip

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

以下是使用 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-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?"
          }
        ]
      }
    ]
  }'

ant messages create <<'YAML'
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?
YAML

import anthropic

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)

import com.anthropic.client.AnthropicClient;
import com.anthropic.client.okhttp.AnthropicOkHttpClient;
import com.anthropic.models.messages.*;
import java.util.List;

public class DocumentExample {

  public static void main(String[] args) {
    AnthropicClient client = AnthropicOkHttpClient.fromEnv();

    PlainTextSource source = PlainTextSource.builder()
      .data("The grass is green. The sky is blue.")
      .build();

    DocumentBlockParam documentParam = DocumentBlockParam.builder()
      .source(source)
      .title("My Document")
      .context("This is a trustworthy document.")
      .citations(CitationsConfigParam.builder().enabled(true).build())
      .build();

    TextBlockParam textBlockParam = TextBlockParam.builder()
      .text("What color is the grass and sky?")
      .build();

    MessageCreateParams params = MessageCreateParams.builder()
      .model(Model.CLAUDE_OPUS_4_7)
      .maxTokens(1024)
      .addUserMessageOfBlockParams(
        List.of(
          ContentBlockParam.ofDocument(documentParam),
          ContentBlockParam.ofText(textBlockParam)
        )
      )
      .build();

    Message message = client.messages().create(params);
    System.out.println(message);
  }
}

Tip

与基于提示的方法的比较

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

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

引用的工作原理

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

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

Tip

自动分块与自定义内容

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

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

可引用与不可引用内容

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

引用索引

文档索引根据请求中所有文档内容块列表（跨所有消息）从 0 开始索引。
字符索引从 0 开始索引，结束索引为独占索引。
页码从 1 开始索引，结束页码为独占页码。
内容块索引从 0 开始索引，结束索引为独占索引，来自自定义内容文档中提供的 content 列表。

Token 成本

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

功能兼容性

引用可与其他 API 功能一起使用，包括 prompt caching、token counting 和 batch processing。

Warning

引用与结构化输出不兼容

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

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

将 Prompt Caching 与引用结合使用

引用和 prompt caching 可以有效地一起使用。

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

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data '{
    "model": "claude-opus-4-7",
    "max_tokens": 1024,
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "text",
                        "media_type": "text/plain",
                        "data": "This is a very long document with thousands of words..."
                    },
                    "citations": {"enabled": true},
                    "cache_control": {"type": "ephemeral"}
                },
                {
                    "type": "text",
                    "text": "What does this document say about API features?"
                }
            ]
        }
    ]
}'

ant messages create \
  --model claude-opus-4-7 \
  --max-tokens 1024 <<'YAML'
messages:
  - role: user
    content:
      - type: document
        source:
          type: text
          media_type: text/plain
          data: This is a very long document with thousands of words...
        citations:
          enabled: true
        cache_control:
          type: ephemeral
      - type: text
        text: What does this document say about API features?
YAML

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-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"
                    },  # 缓存文档内容
                },
                {
                    "type": "text",
                    "text": "What does this document say about API features?",
                },
            ],
        }
    ],
)
print(response)

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

// 长文档内容（例如技术文档）
const longDocument =
  "This is a very long document with thousands of words..." + " ... ".repeat(1000); // 最小可缓存长度

const response = await 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: longDocument
          },
          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 开始）

Note

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

纯文本文档

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

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

{
    "type": "document",
    "source": {"type": "file", "file_id": "file_011CNvxoj286tYUAZFiZMf1U"},
    "title": "Document Title",  # 可选
    "context": "Context about the document that will not be cited from",  # 可选
    "citations": {"enabled": True},
}

纯文本引用示例

{
    "type": "char_location",
    "cited_text": "The exact text being cited",  # 不计入输出 token
    "document_index": 0,
    "document_title": "Document Title",
    "start_char_index": 0,  # 从 0 开始索引
    "end_char_index": 50,  # 独占
}

PDF 文档

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

{
    "type": "document",
    "source": {
        "type": "base64",
        "media_type": "application/pdf",
        "data": base64_encoded_pdf_data,
    },
    "title": "Document Title",  # 可选
    "context": "Context about the document that will not be cited from",  # 可选
    "citations": {"enabled": True},
}

{
    "type": "document",
    "source": {"type": "file", "file_id": "file_011CNvxoj286tYUAZFiZMf1U"},
    "title": "Document Title",  # 可选
    "context": "Context about the document that will not be cited from",  # 可选
    "citations": {"enabled": True},
}

PDF 引用示例

{
    "type": "page_location",
    "cited_text": "The exact text being cited",  # 不计入输出 token
    "document_index": 0,
    "document_title": "Document Title",
    "start_page_number": 1,  # 从 1 开始索引
    "end_page_number": 2,  # 独占
}

自定义内容文档

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

{
    "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": "content_block_location",
    "cited_text": "The exact text being cited",  # 不计入输出 token
    "document_index": 0,
    "document_title": "Document Title",
    "start_block_index": 0,  # 从 0 开始索引
    "end_block_index": 1,  # 独占
}

响应结构

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

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

流式事件示例

event: message_start
data: {"type": "message_start", ...}

event: content_block_start
data: {"type": "content_block_start", "index": 0, ...}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0,
       "delta": {"type": "text_delta", "text": "According to..."}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0,
       "delta": {"type": "citations_delta",
                 "citation": {
                     "type": "char_location",
                     "cited_text": "...",
                     "document_index": 0,
                     ...
                 }}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: message_stop
data: {"type": "message_stop"}

引用

引用的工作原理

提供文档并启用引用

文档被处理

Claude 提供带引用的响应

可引用与不可引用内容

引用索引

Token 成本

功能兼容性

将 Prompt Caching 与引用结合使用

文档类型

选择文档类型

纯文本文档

PDF 文档

自定义内容文档

响应结构

流式支持