8.Code execution and the Files API
此文档由 学习AI的1000天 翻译制作(抖音，B站，YouTube)
邮箱: szqshan@gmail.com | 微信: szqshan
网址: www.xueai.org
==================================================
Anthropic API 提供了两个强大的功能，它们结合使用效果非常出色：Files API 和代码执行。虽然乍看之下它们似乎是独立的功能，但将它们结合起来为委托 Claude 处理复杂任务开辟了一些非常有趣的可能性。
Files API
Files API 提供了处理文件上传的另一种方式。您无需在消息中直接将图像或 PDF 编码为 base64 数据，而是可以提前上传文件并在后续引用它们。
工作原理如下：
- 通过单独的 API 调用将您的文件（图像、PDF、文本等）上传到 Claude
- 接收包含唯一文件 ID 的文件元数据对象
- 在后续消息中引用该文件 ID，而不是包含原始文件数据
当您想要多次引用同一个文件，或者处理较大的文件（在每个请求中包含这些文件会很麻烦）时，这种方法特别有用。
Code Execution Tool
代码执行是一个基于服务器的工具，不需要您提供实现。您只需在请求中包含预定义的工具模式，Claude 就可以选择性地在隔离的 Docker 容器中执行 Python 代码。
代码执行环境的关键特征：
- 在隔离的 Docker 容器中运行
- 无网络访问权限（无法进行外部 API 调用）
- Claude 可以在单次对话中多次执行代码
- 执行结果会被 Claude 捕获并解释，用于生成最终响应
结合 Files API 和代码执行功能
真正的威力来自于将这些功能结合使用。由于 Docker 容器没有网络访问权限，Files API 成为了向执行环境传入和传出数据的主要方式。
以下是典型的工作流程：
- 使用 Files API 上传您的数据文件（如 CSV 文件）
- 在消息中包含一个容器上传块，并提供文件 ID
- 要求 Claude 分析数据
- Claude 编写并执行代码来处理您的文件
- Claude 可以生成输出（如图表），您可以下载这些输出
Practical Example
让我们看一个使用流媒体服务数据的真实示例。CSV 文件包含用户信息，包括订阅层级、观看习惯，以及他们是否已经流失（取消订阅）。
首先，使用辅助函数上传文件：
file_metadata = upload('streaming.csv')
然后创建一条消息，既包含上传的文件，也包含分析请求：
messages = []
add_user_message(
messages,
[
{
"type": "text",
"text": """运行详细分析以确定客户流失的主要驱动因素。
你的最终输出应该包含至少一个详细的图表来总结你的发现。"""
},
{"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 下载这些文件。
在响应中查找类型为 "code_execution_output" 的块 - 这些块包含生成内容的文件 ID：
download_file("file_id_from_response")
最终结果是一个包含专业可视化图表的综合分析，如果手动编码实现这些功能将需要大量工作。
超越数据分析
虽然数据分析是自然的应用场景，但 Files API 与代码执行的结合开启了许多可能性：
- 图像处理和操作
- 文档解析和转换
- 数学计算和建模
- 自定义格式的报告生成
关键在于，你可以将复杂的计算任务委托给Claude，同时通过Files API保持对输入和输出的控制。这创造了一个强大的工作流程，Claude成为你的编程助手，能够实际执行和迭代解决方案。
==================================================
此文档由 学习AI的1000天 翻译制作(抖音，B站，YouTube)
邮箱: szqshan@gmail.com | 微信: szqshan
网址: www.xueai.org