Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
Loading
关于"zero data retention"（零数据保留），即 ZDR 如何适用于此功能，请参阅 API 与数据保留。
Claude 在回答有关文档的问题时可以提供详细的引用，帮助您追踪和验证每个回答背后的来源。
所有活跃模型都支持引用。
请使用引用反馈表单分享您对引用功能的反馈和建议。
以下示例展示了如何通过 Messages API 在纯文本文档上启用引用：
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-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 引用来源相比，引用功能具有以下优势：
cited_text 不计入您的输出令牌。cited_text，因此可以保证引用包含指向所提供文档的有效指针。按照以下步骤将引用与 Claude 集成：
提供文档并启用引用
文档被处理
Claude 提供带引用的回答
自动分块与自定义内容
默认情况下，纯文本和 PDF 文档会自动分块为句子。如果您需要对引用粒度进行更多控制（例如，对于项目符号列表或转录文本），请改用自定义内容文档。有关更多详细信息，请参阅文档类型。
例如，如果您希望 Claude 能够引用您的 RAG 块中的特定句子，您应该将每个 RAG 块放入一个纯文本文档中。否则，如果您不希望进行任何进一步的分块，或者希望自定义任何额外的分块，您可以将 RAG 块放入自定义内容文档中。
source 内容中的文本可以被引用。title 和 context 是可选字段，它们会传递给模型，但不会用于被引用的内容。title 的长度有限，因此 context 字段可用于以文本或字符串化 JSON 的形式存储文档元数据。content 列表从 0 开始索引，结束索引为排他性的。cited_text 字段是为了方便而提供的，不计入输出令牌。cited_text 也不计入输入令牌。引用可与其他 API 功能配合使用，包括提示缓存、令牌计数和批处理。
引用与结构化输出不兼容
引用不能与结构化输出一起使用。如果您在任何用户提供的文档（document 块或 search_result 块）上启用引用，同时还包含 output_config.format 参数（或已弃用的 output_format 参数），API 将返回 400 错误。
这是因为引用需要将引用块与文本输出交错排列，这与结构化输出的严格 JSON 模式约束不兼容。
引用和提示缓存可以有效地结合使用。
响应中生成的引用块不能直接缓存，但它们所引用的源文档可以被缓存。为了优化性能，请将 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",
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 来缓存文档内容。引用支持三种文档类型。文档可以直接在消息中提供（base64、文本或 URL），也可以通过 Files API 上传并通过 file_id 引用：
| 类型 | 最适合 | 分块方式 | 引用格式 |
|---|---|---|---|
| 纯文本 | 简单文本文档、散文 | 句子 | 字符索引（从 0 开始索引） |
| 包含文本内容的 PDF 文件 | 句子 | 页码（从 1 开始索引） | |
| 自定义内容 | 列表、转录文本、特殊格式、更细粒度的引用 | 不进行额外分块 | 块索引（从 0 开始索引） |
对于 document 块不支持的文件类型（例如 .docx 和 .xlsx），请将文件转换为纯文本并将内容直接包含在消息内容中。已经是纯文本的文件（如 .csv 和 .md 文件）也可以使用显式的 text/plain 内容类型上传。请参阅处理其他文件格式。
纯文本文档会自动分块为句子。您可以内联提供它们，也可以通过其 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 文档可以作为 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",
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",
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,
}
],
},
]
}对于流式传输响应，引用会作为 citations_delta 增量类型出现在 content_block_delta 事件中。每个增量包含一个要添加到当前 text 内容块的 citations 列表中的单个引用。
在处理文本增量的同时处理 citations_delta 增量类型，以便在流式传输时渲染带引用的响应。
将来自您的 RAG 管道的搜索结果作为具有内置引用支持的一等内容块传递。
了解 Claude 如何从 PDF 中提取文本，以及基于页面的引用如何映射回您的源文件。
只需上传一次文档，即可在多个引用请求中通过 file_id 引用它们。
Was this page helpful?