Messages处理文件

PDF 支持

使用 Claude 处理 PDF：从您的文档中提取文本、分析图表并理解视觉内容。

此功能符合零数据保留（ZDR）的条件。当您的组织签订了 ZDR 协议时，通过此功能发送的数据在 API 响应返回后不会被存储。

您可以向 Claude 询问您提供的 PDF 中的任何文本、图片、图表和表格。一些示例用例：

分析财务报告并理解图表/表格
从法律文件中提取关键信息
文档翻译辅助
将文档信息转换为结构化格式

开始之前

检查 PDF 要求

Claude 可以处理任何标准 PDF。请确保您的请求大小满足以下要求：

要求	限制
最大请求大小	32 MB（因平台而异）
每个请求的最大页数	600（当请求的上下文窗口低于 1M 令牌时为 100）
格式	标准 PDF（无密码/加密）

这两个限制都针对整个请求负载，包括与 PDF 一起发送的任何其他内容。对于大型 PDF，请考虑使用 Files API 上传并通过 file_id 引用，以保持请求负载较小。

内容密集的 PDF（许多小字体页面、复杂表格或大量图形）可能在达到页数限制之前就填满上下文窗口。包含大型 PDF 的请求也可能在达到页数限制之前失败，即使使用 Files API 也是如此。请尝试将文档拆分为多个部分；对于大文件，由于每一页都作为图像处理，对嵌入的图像进行降采样也会有所帮助。

由于 PDF 支持依赖于 Claude 的视觉能力，因此它与其他视觉任务受到相同的限制和注意事项的约束。

支持的平台和模型

PDF 支持可在 Claude API、Claude Platform on AWS、Amazon Bedrock（参见 Amazon Bedrock PDF 支持）、Google Cloud 和 Microsoft Foundry 上使用。所有活跃模型都支持 PDF 处理。

Amazon Bedrock PDF 支持

当通过 Converse API（Claude on Amazon Bedrock（旧版）的一部分）使用 PDF 支持时，有两种不同的文档处理模式：

重要提示： 要在 Converse API 中访问 Claude 完整的视觉 PDF 理解能力，您必须启用引用（citations）。如果未启用引用，API 将回退到仅进行基本文本提取。了解更多关于使用引用的信息。

文档处理模式

Converse Document Chat（原始模式 - 仅文本提取）
- 提供 PDF 的基本文本提取
- 无法分析 PDF 中的图像、图表或视觉布局
- 处理 3 页 PDF 大约使用 1,000 个令牌
- 在未启用引用时自动使用
Claude PDF Chat（新模式 - 完整视觉理解）
- 提供 PDF 的完整视觉分析
- 可以理解和分析图表、图形、图像和视觉布局
- 将每一页同时作为文本和图像处理，以实现全面理解
- 处理 3 页 PDF 大约使用 7,000 个令牌
- 需要在 Converse API 中启用引用

主要限制

Converse API：视觉 PDF 分析需要启用引用。目前没有在不使用引用的情况下使用视觉分析的选项（与 InvokeModel API 不同）。
InvokeModel API：提供对 PDF 处理的完全控制，无需强制使用引用。

常见问题

如果在使用 Converse API 时 Claude 无法看到 PDF 中的图像或图表，您可能需要启用引用标志。如果没有它，Converse 将回退到仅进行基本文本提取。

这是 Converse API 的已知限制。对于需要在不使用引用的情况下进行视觉 PDF 分析的应用程序，请考虑改用 InvokeModel API。

纯文本文件（如 .txt、.csv 或 .md）可以直接在文档块中使用：使用 MIME 类型 text/plain 将它们上传到 Files API，并通过 file_id 引用它们。二进制格式（如 .xlsx 或 .docx）在文档块中不受支持，必须先转换为文本或 PDF。请参阅处理其他文件格式。

使用 Claude 处理 PDF

发送您的第一个 PDF 请求

让我们从使用 Messages API 的简单示例开始。您可以通过三种方式向 Claude 提供 PDF：

作为托管在线的 PDF 的 URL 引用
作为 document 内容块中的 base64 编码 PDF
通过来自 Files API 的 file_id

在 Amazon Bedrock 和 Google Cloud 上，目前仅提供 base64 编码的来源。在 Microsoft Foundry 上，托管在 Azure 上的部署不支持 Files API。

选项 1：基于 URL 的 PDF 文档

最简单的方法是直接从 URL 引用 PDF：

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "url",
                        "url": "https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf",
                    },
                },
                {"type": "text", "text": "What are the key findings in this document?"},
            ],
        }
    ],
)

print(message.content)

响应会在 content 中以文本块的形式返回 Claude 的分析结果，并在 usage 中返回令牌消耗情况：

Output

{
  "id": "msg_01Hfp8YuFjQ55VgWbpdHDehB",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-4-8",
  "content": [
    {
      "type": "text",
      "text": "This document is an addendum to the Claude 3 model card, reporting updated evaluation results. The key findings include..."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 45000,
    "output_tokens": 300
  }
}

选项 2：Base64 编码的 PDF 文档

如果您需要从本地系统发送 PDF，或者在没有 URL 可用时：

import base64
import httpx

# 首先，加载并编码 PDF
pdf_url = "https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf"
pdf_data = base64.standard_b64encode(
    httpx.get(pdf_url, follow_redirects=True).content
).decode("utf-8")

# 替代方案：从本地文件加载
# with open("document.pdf", "rb") as f:
#     pdf_data = base64.standard_b64encode(f.read()).decode("utf-8")

# 使用 base64 编码发送给 Claude
client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_data,
                    },
                },
                {"type": "text", "text": "What are the key findings in this document?"},
            ],
        }
    ],
)

print(message.content)

选项 3：Files API

对于您将重复使用的 PDF，或者当您希望避免编码开销时，请使用 Files API（测试版）：

client = anthropic.Anthropic()

# 上传 PDF 文件
with open("/path/to/document.pdf", "rb") as f:
    file_upload = client.beta.files.upload(file=("document.pdf", f, "application/pdf"))

# 在消息中使用已上传的文件
message = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    betas=["files-api-2025-04-14"],
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {"type": "file", "file_id": file_upload.id},
                },
                {"type": "text", "text": "What are the key findings in this document?"},
            ],
        }
    ],
)

print(message.content)

PDF 支持的工作原理

当您向 Claude 发送 PDF 时，会发生以下步骤：

系统提取文档的内容。
- 系统将文档的每一页转换为图像。
- 从每一页提取文本，并与每一页的图像一起提供。
Claude 分析文本和图像，以更好地理解文档。
- 文档以文本和图像的组合形式提供以供分析。
- 这使用户能够询问有关 PDF 视觉元素的见解，例如图表、示意图和其他非文本内容。
Claude 做出响应，并在相关时引用 PDF 的内容。
Claude 在响应时可以引用文本和视觉内容。您可以通过将 PDF 支持与以下功能集成来进一步提高性能：
- 提示缓存：提高重复分析的性能。
- 批处理：用于大批量文档处理。
- 工具使用：从文档中提取特定信息以用作工具输入。

估算您的成本

PDF 文件的令牌数量取决于从文档中提取的总文本量以及页数：

文本令牌成本：每页通常使用 1,500-3,000 个令牌，具体取决于内容密度。适用标准 API 定价，无额外 PDF 费用。
图像令牌成本：由于每一页都被转换为图像，因此适用相同的基于图像的成本计算。

您可以使用令牌计数来估算特定 PDF 的成本。

优化 PDF 处理

提高性能

遵循以下最佳实践以获得最佳结果：

在请求中将 PDF 放在文本之前
使用标准字体
确保文本清晰易读
将页面旋转到正确的直立方向
在提示中使用逻辑页码（来自 PDF 查看器）
必要时将大型 PDF 拆分为多个块
为重复分析启用提示缓存

扩展您的实现

对于大批量处理，请考虑以下方法：

使用提示缓存

使用提示缓存缓存 PDF，以提高重复查询的性能：

import base64
import httpx

# 首先，加载并编码 PDF
pdf_url = "https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf"
pdf_data = base64.standard_b64encode(
    httpx.get(pdf_url, follow_redirects=True).content
).decode("utf-8")

# 使用已缓存的文档创建消息
client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_data,
                    },
                    "cache_control": {"type": "ephemeral"},
                },
                {
                    "type": "text",
                    "text": "Which model has the highest human preference win rates across each use-case?",
                },
            ],
        }
    ],
)

print(message.content)

批量处理文档

使用 Message Batches API 在一个请求中处理多个 PDF：

import base64
import httpx

# 首先，加载并编码 PDF
pdf_url = "https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf"
pdf_data = base64.standard_b64encode(
    httpx.get(pdf_url, follow_redirects=True).content
).decode("utf-8")

# 创建一批使用该文档的请求
client = anthropic.Anthropic()
message_batch = client.messages.batches.create(
    requests=[
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-4-8",
                "max_tokens": 1024,
                "messages": [
                    {
                        "role": "user",
                        "content": [
                            {
                                "type": "document",
                                "source": {
                                    "type": "base64",
                                    "media_type": "application/pdf",
                                    "data": pdf_data,
                                },
                            },
                            {
                                "type": "text",
                                "text": "Which model has the highest human preference win rates across each use-case?",
                            },
                        ],
                    }
                ],
            },
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-8",
                "max_tokens": 1024,
                "messages": [
                    {
                        "role": "user",
                        "content": [
                            {
                                "type": "document",
                                "source": {
                                    "type": "base64",
                                    "media_type": "application/pdf",
                                    "data": pdf_data,
                                },
                            },
                            {
                                "type": "text",
                                "text": "Extract 5 key insights from this document.",
                            },
                        ],
                    }
                ],
            },
        },
    ]
)

print(message_batch)

批处理是异步进行的。要检查进度并在处理结束后检索结果，请参阅批处理。

后续步骤

视觉

Claude 的视觉能力使其能够理解和分析图像，为多模态交互开辟了令人兴奋的可能性。

尝试 PDF 示例

在 cookbook 示例中探索 PDF 处理的实际示例。

查看 API 参考

查看 PDF 支持的完整 API 文档。

Was this page helpful?

Messages处理文件

PDF 支持

使用 Claude 处理 PDF：从您的文档中提取文本、分析图表并理解视觉内容。

此功能符合零数据保留（ZDR）的条件。当您的组织签订了 ZDR 协议时，通过此功能发送的数据在 API 响应返回后不会被存储。

您可以向 Claude 询问您提供的 PDF 中的任何文本、图片、图表和表格。一些示例用例：

分析财务报告并理解图表/表格
从法律文件中提取关键信息
文档翻译辅助
将文档信息转换为结构化格式

开始之前

检查 PDF 要求

Claude 可以处理任何标准 PDF。请确保您的请求大小满足以下要求：

要求	限制
最大请求大小	32 MB（因平台而异）
每个请求的最大页数	600（当请求的上下文窗口低于 1M 令牌时为 100）
格式	标准 PDF（无密码/加密）

由于 PDF 支持依赖于 Claude 的视觉能力，因此它与其他视觉任务受到相同的限制和注意事项的约束。

支持的平台和模型

PDF 支持可在 Claude API、Claude Platform on AWS、Amazon Bedrock（参见 Amazon Bedrock PDF 支持）、Google Cloud 和 Microsoft Foundry 上使用。所有活跃模型都支持 PDF 处理。

Amazon Bedrock PDF 支持

当通过 Converse API（Claude on Amazon Bedrock（旧版）的一部分）使用 PDF 支持时，有两种不同的文档处理模式：

文档处理模式

Converse Document Chat（原始模式 - 仅文本提取）
- 提供 PDF 的基本文本提取
- 无法分析 PDF 中的图像、图表或视觉布局
- 处理 3 页 PDF 大约使用 1,000 个令牌
- 在未启用引用时自动使用
Claude PDF Chat（新模式 - 完整视觉理解）
- 提供 PDF 的完整视觉分析
- 可以理解和分析图表、图形、图像和视觉布局
- 将每一页同时作为文本和图像处理，以实现全面理解
- 处理 3 页 PDF 大约使用 7,000 个令牌
- 需要在 Converse API 中启用引用

主要限制

Converse API：视觉 PDF 分析需要启用引用。目前没有在不使用引用的情况下使用视觉分析的选项（与 InvokeModel API 不同）。
InvokeModel API：提供对 PDF 处理的完全控制，无需强制使用引用。

常见问题

如果在使用 Converse API 时 Claude 无法看到 PDF 中的图像或图表，您可能需要启用引用标志。如果没有它，Converse 将回退到仅进行基本文本提取。

这是 Converse API 的已知限制。对于需要在不使用引用的情况下进行视觉 PDF 分析的应用程序，请考虑改用 InvokeModel API。

使用 Claude 处理 PDF

发送您的第一个 PDF 请求

让我们从使用 Messages API 的简单示例开始。您可以通过三种方式向 Claude 提供 PDF：

作为托管在线的 PDF 的 URL 引用
作为 document 内容块中的 base64 编码 PDF
通过来自 Files API 的 file_id

在 Amazon Bedrock 和 Google Cloud 上，目前仅提供 base64 编码的来源。在 Microsoft Foundry 上，托管在 Azure 上的部署不支持 Files API。

选项 1：基于 URL 的 PDF 文档

最简单的方法是直接从 URL 引用 PDF：

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "url",
                        "url": "https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf",
                    },
                },
                {"type": "text", "text": "What are the key findings in this document?"},
            ],
        }
    ],
)

print(message.content)

响应会在 content 中以文本块的形式返回 Claude 的分析结果，并在 usage 中返回令牌消耗情况：

Output

{
  "id": "msg_01Hfp8YuFjQ55VgWbpdHDehB",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-4-8",
  "content": [
    {
      "type": "text",
      "text": "This document is an addendum to the Claude 3 model card, reporting updated evaluation results. The key findings include..."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 45000,
    "output_tokens": 300
  }
}

选项 2：Base64 编码的 PDF 文档

如果您需要从本地系统发送 PDF，或者在没有 URL 可用时：

import base64
import httpx

# 首先，加载并编码 PDF
pdf_url = "https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf"
pdf_data = base64.standard_b64encode(
    httpx.get(pdf_url, follow_redirects=True).content
).decode("utf-8")

# 替代方案：从本地文件加载
# with open("document.pdf", "rb") as f:
#     pdf_data = base64.standard_b64encode(f.read()).decode("utf-8")

# 使用 base64 编码发送给 Claude
client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_data,
                    },
                },
                {"type": "text", "text": "What are the key findings in this document?"},
            ],
        }
    ],
)

print(message.content)

选项 3：Files API

对于您将重复使用的 PDF，或者当您希望避免编码开销时，请使用 Files API（测试版）：

client = anthropic.Anthropic()

# 上传 PDF 文件
with open("/path/to/document.pdf", "rb") as f:
    file_upload = client.beta.files.upload(file=("document.pdf", f, "application/pdf"))

# 在消息中使用已上传的文件
message = client.beta.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    betas=["files-api-2025-04-14"],
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {"type": "file", "file_id": file_upload.id},
                },
                {"type": "text", "text": "What are the key findings in this document?"},
            ],
        }
    ],
)

print(message.content)

PDF 支持的工作原理

当您向 Claude 发送 PDF 时，会发生以下步骤：

系统提取文档的内容。
- 系统将文档的每一页转换为图像。
- 从每一页提取文本，并与每一页的图像一起提供。
Claude 分析文本和图像，以更好地理解文档。
- 文档以文本和图像的组合形式提供以供分析。
- 这使用户能够询问有关 PDF 视觉元素的见解，例如图表、示意图和其他非文本内容。
Claude 做出响应，并在相关时引用 PDF 的内容。
Claude 在响应时可以引用文本和视觉内容。您可以通过将 PDF 支持与以下功能集成来进一步提高性能：
- 提示缓存：提高重复分析的性能。
- 批处理：用于大批量文档处理。
- 工具使用：从文档中提取特定信息以用作工具输入。

估算您的成本

PDF 文件的令牌数量取决于从文档中提取的总文本量以及页数：

文本令牌成本：每页通常使用 1,500-3,000 个令牌，具体取决于内容密度。适用标准 API 定价，无额外 PDF 费用。
图像令牌成本：由于每一页都被转换为图像，因此适用相同的基于图像的成本计算。

您可以使用令牌计数来估算特定 PDF 的成本。

优化 PDF 处理

提高性能

遵循以下最佳实践以获得最佳结果：

在请求中将 PDF 放在文本之前
使用标准字体
确保文本清晰易读
将页面旋转到正确的直立方向
在提示中使用逻辑页码（来自 PDF 查看器）
必要时将大型 PDF 拆分为多个块
为重复分析启用提示缓存

扩展您的实现

对于大批量处理，请考虑以下方法：

使用提示缓存

使用提示缓存缓存 PDF，以提高重复查询的性能：

import base64
import httpx

# 首先，加载并编码 PDF
pdf_url = "https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf"
pdf_data = base64.standard_b64encode(
    httpx.get(pdf_url, follow_redirects=True).content
).decode("utf-8")

# 使用已缓存的文档创建消息
client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-opus-4-8",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": [
                {
                    "type": "document",
                    "source": {
                        "type": "base64",
                        "media_type": "application/pdf",
                        "data": pdf_data,
                    },
                    "cache_control": {"type": "ephemeral"},
                },
                {
                    "type": "text",
                    "text": "Which model has the highest human preference win rates across each use-case?",
                },
            ],
        }
    ],
)

print(message.content)

批量处理文档

使用 Message Batches API 在一个请求中处理多个 PDF：

import base64
import httpx

# 首先，加载并编码 PDF
pdf_url = "https://assets.anthropic.com/m/1cd9d098ac3e6467/original/Claude-3-Model-Card-October-Addendum.pdf"
pdf_data = base64.standard_b64encode(
    httpx.get(pdf_url, follow_redirects=True).content
).decode("utf-8")

# 创建一批使用该文档的请求
client = anthropic.Anthropic()
message_batch = client.messages.batches.create(
    requests=[
        {
            "custom_id": "my-first-request",
            "params": {
                "model": "claude-opus-4-8",
                "max_tokens": 1024,
                "messages": [
                    {
                        "role": "user",
                        "content": [
                            {
                                "type": "document",
                                "source": {
                                    "type": "base64",
                                    "media_type": "application/pdf",
                                    "data": pdf_data,
                                },
                            },
                            {
                                "type": "text",
                                "text": "Which model has the highest human preference win rates across each use-case?",
                            },
                        ],
                    }
                ],
            },
        },
        {
            "custom_id": "my-second-request",
            "params": {
                "model": "claude-opus-4-8",
                "max_tokens": 1024,
                "messages": [
                    {
                        "role": "user",
                        "content": [
                            {
                                "type": "document",
                                "source": {
                                    "type": "base64",
                                    "media_type": "application/pdf",
                                    "data": pdf_data,
                                },
                            },
                            {
                                "type": "text",
                                "text": "Extract 5 key insights from this document.",
                            },
                        ],
                    }
                ],
            },
        },
    ]
)

print(message_batch)

批处理是异步进行的。要检查进度并在处理结束后检索结果，请参阅批处理。

后续步骤

视觉

Claude 的视觉能力使其能够理解和分析图像，为多模态交互开辟了令人兴奋的可能性。

尝试 PDF 示例

在 cookbook 示例中探索 PDF 处理的实际示例。

查看 API 参考

查看 PDF 支持的完整 API 文档。

Was this page helpful?

开始之前

检查 PDF 要求

支持的平台和模型

Amazon Bedrock PDF 支持

文档处理模式

主要限制

常见问题

使用 Claude 处理 PDF

发送您的第一个 PDF 请求

选项 1：基于 URL 的 PDF 文档

选项 2：Base64 编码的 PDF 文档

选项 3：Files API

PDF 支持的工作原理

估算您的成本

优化 PDF 处理

提高性能

扩展您的实现

使用提示缓存

批量处理文档

后续步骤

开始之前

检查 PDF 要求

支持的平台和模型

Amazon Bedrock PDF 支持

文档处理模式

主要限制

常见问题

使用 Claude 处理 PDF

发送您的第一个 PDF 请求

选项 1：基于 URL 的 PDF 文档

选项 2：Base64 编码的 PDF 文档

选项 3：Files API

PDF 支持的工作原理

估算您的成本

优化 PDF 处理

提高性能

扩展您的实现

使用提示缓存

批量处理文档

后续步骤

开始之前

检查 PDF 要求

支持的平台和模型

Amazon Bedrock PDF 支持

文档处理模式

主要限制

常见问题

使用 Claude 处理 PDF

发送您的第一个 PDF 请求

选项 1：基于 URL 的 PDF 文档

选项 2：Base64 编码的 PDF 文档

选项 3：Files API

PDF 支持的工作原理

估算您的成本

优化 PDF 处理

提高性能

扩展您的实现

使用提示缓存

批量处理文档

后续步骤

开始之前

检查 PDF 要求

支持的平台和模型

Amazon Bedrock PDF 支持

文档处理模式

主要限制

常见问题

使用 Claude 处理 PDF

发送您的第一个 PDF 请求

选项 1：基于 URL 的 PDF 文档

选项 2：Base64 编码的 PDF 文档

选项 3：Files API

PDF 支持的工作原理

估算您的成本

优化 PDF 处理

提高性能

扩展您的实现

使用提示缓存

批量处理文档

后续步骤