加载中
加载中

Anthropic API提供了两个配合使用效果极佳的强大功能:Files API和代码执行(Code Execution)。虽然乍看之下它们彼此独立,但将它们组合起来,为将复杂任务委托给Claude打开了一些非常有趣的可能性。

Files API

Files API提供了一种处理文件上传的替代方式。您不必将图像或PDF以base64数据的形式直接编码到消息中,而是可以提前上传文件,之后再引用它们。

我们的服务器向Claude发送原始图像数据和文字"你在这张图片里看到了什么?",Claude回答"我看到一棵高大的树"。

它的工作方式如下:

  • 通过单独的API调用将您的文件(图像、PDF、文本等)上传给Claude
  • 接收一个包含唯一文件ID的文件元数据对象
  • 在之后的消息中引用该文件ID,而不必再包含原始文件数据

我们的服务器在一个图像块中发送文件ID,并附上"你在这张图片里看到了什么?",Claude回答"我看到一棵高大的树"。

当您想多次引用同一个文件,或者处理那些在每次请求中都包含会显得繁琐的大文件时,这种方式尤其有用。

代码执行工具

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

我们的服务器向Claude请求圆周率到小数点后第50位;Claude返回代码、结果"3.1415926535"和文字回答。

代码执行环境的关键特性:

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

结合Files API与代码执行

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

下面列出的工作流程:一条带有容器上传块和文字的用户消息,随后是Claude回复的代码、结果和文字。

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

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

实践示例

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

streaming.csv文件,列包括UserID、SubscriptionTier和TotalViewingHoursLastMonth,行从USER_00001开始。

首先,使用一个辅助函数上传文件:

python
file_metadata = upload('streaming.csv')

然后创建一条消息,同时包含已上传的文件和分析请求:

python
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_20250825", "name": "code_execution"}]
)

理解响应内容

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

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

打印的响应:一个关于流失驱动因素的文本块,一个代码中导入了pandas的服务器工具使用块,然后是一个工具结果。

Claude在单次响应中可能会多次执行代码,迭代地构建其分析。每一轮执行周期都包括代码及其结果。

下载生成的文件

最强大的功能之一,是Claude能够生成文件(比如图表或报告),并将它们提供给您下载。当Claude创建一个可视化图表时,它会被存储在容器中,您可以使用Files API下载它。

在响应中查找type: "bash_code_execution_output"类型的块 —— 这些块中包含了生成内容的文件ID:

python
download_file("file_id_from_response")

下载的多面板流失分析图:500名用户,38.6%的流失率,最主要的流失驱动因素是客服互动。

最终得到的是一份全面的分析报告,配有专业的可视化图表,而这若靠手动编码完成将耗费大量精力。

不止于数据分析

虽然数据分析是一个天然契合的场景,但Files API与代码执行的结合还打开了许多其他可能性:

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

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