加载中
加载中

当您在 Claude 中将工具使用与流式传输结合起来时,您可以在 AI 生成工具参数时获得实时更新。这创造了更具响应性的用户体验,但关于其背后的工作原理,有一些重要细节需要理解。

基本工具流式传输

启用流式传输后,Claude 在处理您的请求时会发送不同类型的事件。您已经熟悉了用于常规文本生成的事件,比如 ContentBlockDelta。对于工具使用,您还需要处理一种名为 InputJsonEvent 的新事件类型。

按顺序排列的 Claude 流式事件,从 MessageStart 到 MessageStop,其中 ContentBlockDelta 事件承载文本。

每个 InputJsonEvent 包含两个关键属性:

  • partial_json - 表示工具参数一部分的 JSON 块
  • snapshot - 从目前为止收到的所有块累积构建的 JSON

以下是您在流式传输管道中处理这些事件的方式:

python
for chunk in stream:
    if chunk.type == "input_json":
        # 处理部分 JSON 数据块
        print(chunk.partial_json)
        # 或使用目前为止完整的快照
        current_args = chunk.snapshot

启用流式传输后,三个 InputJsonEvent 回复的 partial_json 块构建出快照标题 "Vector Storage"。

JSON 验证的工作原理

这正是有趣的地方。Anthropic API 不会在 Claude 生成每个块时立即将其发送给您。相反,它会先缓冲这些块并对其进行验证。

我们的服务器发送 save_article_schema 和一条用户消息;Anthropic API 显示了 "abstract"、"This paper" 和 "pre" 这几个块。

API 会等待完整的顶层键值对后才发送任何内容。例如,如果您的工具期望如下结构:

json
{
  "abstract": "This paper presents a novel...",
  "meta": {
    "word_count": 847,
    "review": "This paper introduces QuanNet..."
  }
}

API 将会:

  1. 等待整个 abstract 值完成
  2. 对照您的 schema 验证该键值对
  3. 一次性发送 abstract 的所有缓冲块
  4. 对 meta 对象重复此过程

四个缓冲的块合并为一个 "abstract" 键和值,Anthropic API 会根据 save_article_schema 对其进行检查。

这个验证过程解释了为什么即使启用了流式传输,您看到的仍是延迟之后的一阵文本爆发。这些块会被一直保留,直到一个完整、有效的顶层键值对准备就绪。

API 缓冲四个块,直到顶层 "abstract" 键值对有效,然后一次性将全部四个块发送给我们的服务器。

细粒度工具调用

如果您需要更快、更细粒度的流式传输——也许是为了向用户展示即时更新或尽快开始处理部分结果——您可以启用细粒度工具调用。

Anthropic API 向服务器发送多组部分 JSON 块的示意图,每组都在值的中途结束,而不是在键的位置结束。

细粒度工具调用主要做一件事:它禁用了 API 端的 JSON 验证。这意味着:

  • 您会在 Claude 生成块后立即收到它们
  • 顶层键之间没有缓冲延迟
  • 更传统的流式传输行为
  • 关键点: JSON 验证被禁用——您的代码必须处理无效的 JSON

通过在工具上将 eager_input_streaming 设置为 True 来启用它:

python
run_conversation(
    messages, 
    tools=[{**save_article_schema, "eager_input_streaming": True}]
)

启用细粒度工具调用后,您可能会在流中更早地收到 word_count 值,而无需等待整个 meta 对象完成。

处理无效的 JSON

在使用细粒度工具调用时,Claude 可能会生成无效的 JSON,例如 "word_count": undefined 而不是一个正确的数字。您的应用程序需要优雅地处理这些情况:

python
try:
    parsed_args = json.loads(chunk.snapshot)
except json.JSONDecodeError:
    # 适当处理无效的 JSON
    print("Received invalid JSON, continuing...")

如果不使用细粒度工具调用,API 的验证会捕获此错误,并可能将有问题的值包装在字符串中,这可能与您预期的 schema 不匹配。

何时使用细粒度工具调用

在以下情况下,请考虑启用细粒度工具调用:

  • 您需要向用户展示工具参数生成的实时进度
  • 您希望尽快开始处理部分工具结果
  • 缓冲延迟对您的用户体验产生了负面影响
  • 您愿意实现健壮的 JSON 错误处理

对于大多数应用程序而言,带有验证的默认行为已经完全够用。但当您需要那种额外的响应性时,细粒度工具调用能让您以 Claude 生成内容的最快速度获取数据块的控制权。