12.Fine grained tool calling
此文档由 学习AI的1000天 翻译制作(抖音，B站，YouTube)
邮箱: szqshan@gmail.com | 微信: szqshan
网址: www.xueai.org
==================================================
当你将工具使用与 Claude 中的流式传输结合时，你可以在 AI 生成工具参数时获得实时更新。这创造了更具响应性的用户体验，但需要了解一些关于其幕后工作原理的重要细节。
基础工具流式传输
启用流式传输后，Claude 在处理你的请求时会发送不同类型的事件。你已经熟悉了像 ContentBlockDelta 这样用于常规文本生成的事件。对于工具使用，你还需要处理一个名为 InputJsonEvent 的新事件类型。
每个 InputJsonEvent 包含两个关键属性：
- partial_json - 表示工具参数一部分的 JSON 块
- snapshot - 从迄今为止接收到的所有块累积构建的 JSON
以下是在流式传输管道中处理这些事件的方法：
for chunk in stream:
if chunk.type == "input_json":
# 处理部分 JSON 块
print(chunk.partial_json)
# 或者使用到目前为止的完整快照
current_args = chunk.snapshot
JSON 验证工作原理
这里就是有趣的地方了。Anthropic API 不会立即发送 Claude 生成的每个数据块。相反，它会先缓冲数据块并进行验证。
API 会等待完整的顶级键值对后才发送任何内容。例如，如果你的工具期望这样的结构：
{
"abstract": "This paper presents a novel...",
"meta": {
"word_count": 847,
"review": "This paper introduces QuanNet..."
}
}
The API will:
- 等待整个 abstract 值完成
- 根据你的 schema 验证该键值对
- 一次性发送所有为 abstract 缓冲的块
- 对 meta 对象重复这个过程
这个验证过程解释了为什么即使启用了流式传输，你也会看到延迟后突然出现大量文本。这些块被保留直到一个完整、有效的顶级键值对准备就绪。
细粒度工具调用
如果你需要更快、更细粒度的流式传输——也许是为了向用户显示即时更新或快速开始处理部分结果——你可以启用细粒度工具调用。
细粒度工具调用主要做一件事：它在 API 端禁用 JSON 验证。这意味着：
- 你可以在 Claude 生成块的同时立即获得它们
- 顶级键之间没有缓冲延迟
- 更传统的流式处理行为
- 重要提示：JSON 验证已禁用 - 您的代码必须处理无效的 JSON
通过在 API 调用中添加 fine_grained=True 来启用它：
run_conversation(
messages,
tools=[save_article_schema],
fine_grained=True
)
使用细粒度工具调用时，您可能会在流中更早地收到 word_count 值，而无需等待整个 meta 对象完成。
处理无效 JSON
使用细粒度工具调用时，Claude 可能会生成无效的 JSON，如 "word_count": undefined 而不是正确的数字。您的应用程序需要优雅地处理这些情况：
try:
parsed_args = json.loads(chunk.snapshot)
except json.JSONDecodeError:
# 适当处理无效的JSON
print("接收到无效的JSON，继续执行...")
如果不使用细粒度工具调用，API的验证机制会捕获这个错误，并可能将有问题的值包装成字符串，这可能与你期望的模式不匹配。
何时使用细粒度工具调用
在以下情况下考虑启用细粒度工具调用：
- 你需要向用户实时显示工具参数生成的进度
- 你希望尽快开始处理部分工具结果
- 缓冲延迟对你的用户体验产生负面影响
- 你能够熟练实现健壮的JSON错误处理
对于大多数应用程序来说，带有验证的默认行为已经完全足够。但当你需要额外的响应速度时，细粒度工具调用为你提供了控制能力，让你能够以Claude生成的最快速度获取数据块。
==================================================
此文档由 学习AI的1000天 翻译制作(抖音，B站，YouTube)
邮箱: szqshan@gmail.com | 微信: szqshan
网址: www.xueai.org