代码执行与 Files API

Anthropic API 提供了两个配合使用效果极佳的强大功能：Files API 和代码执行（Code Execution）。虽然它们乍看起来是独立的功能，但将它们结合起来，为将复杂任务委托给 Claude 开辟了一些非常有趣的可能性。

Files API

Files API 提供了一种处理文件上传的替代方式。您无需在消息中将图像或 PDF 直接编码为 base64 数据，而是可以提前上传文件，并在之后引用它们。



其工作原理如下：

• 使用单独的 API 调用将您的文件（图像、PDF、文本等）上传到 Claude
• 接收一个包含唯一文件 ID 的文件元数据对象
• 在未来的消息中引用该文件 ID，而不是包含原始文件数据



当您想要多次引用同一文件，或处理在每次请求中都包含会很繁琐的大文件时，这种方法特别有用。

代码执行工具

代码执行是一种基于服务器的工具，不需要您提供实现。您只需在请求中包含一个预定义的工具模式（schema），Claude 就可以选择在隔离的 Docker 容器中执行 Python 代码。



代码执行环境的主要特征：

• 在隔离的 Docker 容器中运行
• 无网络访问权限（无法进行外部 API 调用）
• Claude 可以在单次对话中多次执行代码
• 结果由 Claude 捕获并解读，用于生成最终响应

结合使用 Files API 和代码执行

真正的强大之处在于将这些功能结合使用。由于 Docker 容器没有网络访问权限，Files API 成为在执行环境中传入和传出数据的主要方式。



以下是一个典型的工作流程：

1. 使用 Files API 上传您的数据文件（如 CSV）
2. 在消息中包含一个带有文件 ID 的容器上传块
3. 要求 Claude 分析数据
4. Claude 编写并执行代码来处理您的文件
5. Claude 可以生成您可以下载的输出（如图表）

实际示例

让我们来看一个使用流媒体服务数据的真实示例。该 CSV 文件包含用户信息，包括订阅等级、观看习惯，以及他们是否已流失（取消了订阅）。



首先，使用一个辅助函数上传文件：

file_metadata = upload('streaming.csv')

然后创建一条消息，其中同时包含已上传的文件和分析请求：

messages = []
add_user_message(
    messages,
    [
        {
            "type": "text",
            "text": """Run a detailed analysis to determine major drivers of churn.
            Your final output should include at least one detailed plot summarizing your findings."""
        },
        {"type": "container_upload", "file_id": file_metadata.id},
    ],
)

chat(
    messages,
    tools=[{"type": "code_execution_20250522", "name": "code_execution"}]
)

理解响应

当 Claude 使用代码执行时，响应中会包含多种类型的块：

• 文本块 - Claude 的分析和解释
• 服务器工具使用块 - Claude 决定运行的实际代码
• 代码执行工具结果块 - 运行代码后的输出



Claude 可能在单次响应中多次执行代码，逐步构建其分析。每个执行周期都包括代码及其结果。

下载生成的文件

最强大的功能之一是 Claude 能够生成文件（如图表或报告）并使其可供下载。当 Claude 创建可视化内容时，它会存储在容器中，您可以使用 Files API 下载它。

在响应中查找 type: "code_execution_output" 的块——这些块包含生成内容的文件 ID：

download_file("file_id_from_response")



最终结果是一份包含专业可视化内容的综合分析，若手动编码完成将需要大量工作。

超越数据分析

虽然数据分析是一个天然的应用场景，但 Files API 与代码执行的结合开启了许多可能性：

• 图像处理与操作
• 文档解析与转换
• 数学计算与建模
• 带自定义格式的报告生成

关键在于，您可以将复杂的计算任务委托给 Claude，同时通过 Files API 保持对输入和输出的控制。这创造了一种强大的工作流程，使 Claude 成为您的编码助手，能够真正执行并迭代解决方案。