Meta 的 Toolformer 论文让我对工具调用充满幻想，直到我用 Vercel AI SDK 3.0 在流式UI上连栽三个跟头

我是韩知行，在厂里搞 AI 研究，日常就是读论文、复现、再想办法把那些漂亮的数字变成能扛住真实流量的代码。上个月，我想给内部工具搭一个带实时流式输出的聊天助手，正好看到 Vercel AI SDK 3.0 发布了，文档里写着“useChat 一行搞定流式”，再翻到 Meta 之前那篇 Toolformer 论文——讲语言模型如何自己学会调用 API，工具使用这个方向一下子就通透了。我心想，这波应该能一个下午就把全栈搭完。结果，我踩了三个大坑，差点把演示的 demo 玩崩。所以这篇不是教程，是我的翻车笔记，我会把理论和实践的差距摊开讲，让你知道 AI SDK 到底在哪里帮你偷了懒，又在哪里你必须自己擦屁股。

项目搭好，但流式聊天没你想的那么简单

AI SDK 3.0 的脚手架：npx create-next-app 加一个依赖

我上来就直接用 Next.js 初始化了一个项目，因为 AI SDK 和 Next.js 13+ 的 App Router 配合最顺。一条命令：npx create-next-app@latest my-chat，然后安装 ai 和 @ai-sdk/openai。3.0 的 API 比 2.x 干净太多了，官方把模型适配器拆成了独立的 package，我选的是 OpenAI 的模型，就只装了这一个。路由文件里导出一个 POST handler，核心就这么几行：

// app/api/chat/route.ts
import { openai } from '@ai-sdk/openai';
import { streamText, tool } from 'ai';
import { z } from 'zod';

export const maxDuration = 30;

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = streamText({
    model: openai('gpt-4o-mini'),
    system: '你是一个有用的助手，可以调用工具获取信息。',
    messages,
    tools: {
      getWeather: tool({
        description: '获取指定城市的天气',
        parameters: z.object({ city: z.string() }),
        execute: async ({ city }) => {
          // 这里接真实的天气 API
          return `城市 ${city} 当前晴朗，25°C`;
        },
      }),
    },
  });

  return result.toDataStreamResponse();
}

看上去美如画，就一个 handler，streamText 自己处理了流式响应和工具调用的执行。我心想，这和 Toolformer 那篇论文里幻想的世界也太近了：模型能自行决定调用哪些 API，并且返回结果后继续生成文本。Toolformer 的方法是在训练时让模型学会生成特殊的 API 调用标记，但在推理时就是个简单的自回归过程，不涉及任何异步的外部系统。然而，论文里的实现环境是受控的——所有 API 调用都是模拟的、没有网络延迟、没有超时，更没有前端用户盯着屏幕等待一个天气结果。一旦搬进真实应用，事情就变味了。

useChat 背后的 SSE 协议，论文里可没说断连重试

前端我用的是 SDK 提供的 useChat hook，一行代码就能拿到 messages、input、handleSubmit 等，然后直接渲染成聊天界面。它默认走的是 Server-Sent Events，浏览器自动处理重连，后端持续推送 token。Toolformer 论文的附录里提到了推理时的流式解码，但他们对“流”的定义是逐 token 生成，完全没考虑连接中断。我在本地跑的时候，用 Chrome DevTools 把网络切成 Slow 3G，然后开始聊天。结果发现，SSE 连接一断，虽然 useChat 内部有 reconnection 逻辑，但它只是重新建立连接，并不会自动补发上次请求，所以用户那边就看到消息卡在一半，模型像死机了一样。论文里不会告诉你，现实里用户的网络差到让你怀疑人生。我得自己写一个 fetch wrapper，在请求失败时捕获错误并触发重新提交。这个 wrapper 后来在 Edge 部署时还引发了另一个问题，后面再说。

另外一点，SDK 文档里说 useChat 支持 onToolCall 回调，可以监听工具调用的状态。但实际上，当我同时使用工具调用和流式输出时，前端的消息顺序经常出问题——模型在回复里插入了多个 tool_use 事件，useChat 把这些事件解析后直接暴露给我，但它的内部状态更新并不是同步的，导致我在渲染工具调用的 loading 动画时，已经收到了工具结果，可界面还显示“正在查询天气”。这跟论文里假设的理想顺序完全不同，Toolformer 认为工具调用是原子性的——API 调用 → 返回结果 → 继续生成文本，但真实的流式环境中，工具调用、结果返回、文本生成可能是交织的，前端必须自己维护一个严格的事件队列。

工具调用是银弹？实际落地时，并发和超时差点要了我的命

工具定义与函数调用：从前端到后端的调用链

AI SDK 3.0 的工具调用机制设计得相当优雅。你在后端用 tool() 定义函数，然后用 Zod schema 约束参数，模型返回 tool_calls 时，SDK 会自动匹配并执行对应的 execute 函数，然后把结果塞回对话，继续生成。我很快就在聊天助手里加了两个工具：一个查天气，一个查股价。前端再用一个自定义的 ToolRenderer 组件，根据工具名称渲染不同的 UI。比如天气用一张卡片，股价用迷你 K 线图。代码长这样：

import { useChat } from '@ai-sdk/react';
import { WeatherCard, StockMiniChart } from './tool-components';

export default function Chat() {
  const { messages, input, handleInputChange, handleSubmit, addToolResult } = useChat({
    api: '/api/chat',
    onToolCall({ toolCall }) {
      // 可以在前端预先展示工具调用的意图
      console.log('Tool called:', toolCall);
    },
  });

  return (
    <div>
      {messages.map(m => (
        <div key={m.id}>
          {m.role === 'user' ? m.content : null}
          {m.role === 'assistant' && m.toolInvocations?.map(tool => {
            const { toolName, toolCallId, state, args, result } = tool;
            if (state === 'call') {
              return <div key={toolCallId}>正在调用 {toolName}...</div>;
            }
            if (state === 'result') {
              switch (toolName) {
                case 'getWeather': return <WeatherCard key={toolCallId} data={result} />;
                case 'getStock': return <StockMiniChart key={toolCallId} data={result} />;
                default: return <pre>{JSON.stringify(result, null, 2)}</pre>;
              }
            }
          })}
          {m.role === 'assistant' && m.content}
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input value={input} onChange={handleInputChange} />
      </form>
    </div>
  );
}

这个组件本身运行正常，但问题出在并发工具调用上。有一次我问“告诉我北京和上海的天气，还有苹果的股价”，模型直接并行触发了三次工具调用。SDK 的后端 streamText 是支持并行执行的，但我的天气 API 和股价 API 是两个不同的服务，其中一个股价 API 是第三方免费接口，平均延迟 1.3 秒，偶尔会飙到 10 秒。SDK 默认等所有工具调用都完成才继续生成文本。Toolformer 论文在 3.2 章节里提到，模型生成 API 标记后，环境会返回一个占位符继续解码，但那个模型是 Fine-tune 过的，知道如何等待结果。而真实场景下，用户看到聊天框空白了五秒，以为是 bug，直接刷新了页面。我必须自己实现一个超时机制，在后端的 execute 函数里用 Promise.race 套一层 3 秒超时，超过就返回一个降级结果。但这又带来了新问题：工具调用超时后，模型收到的是什么？SDK 默认会把错误信息直接传回模型，导致模型偶尔会道歉，偶尔会编造一个结果，完全不可控。

Toolformer 里的工具规划很完美，但我的天气 API 超时把 UI 卡死了

我后来读了 OpenAI 官方关于 Function Calling 的可靠性报告，以及一篇 2024 年 ACL 上关于 LLM 工具调用鲁棒性的 workshop 论文，里面统计了实际 API 的失败率在 2-7% 之间。Toolformer 在数据构建阶段是通过自动采样 API 调用并过滤无效结果来训练的，所以模型对错误是脱敏的。但在我的应用里，一旦第三方 API 挂了，整个生成流就中断，用户界面直接卡在“正在调用 getWeather”。我在 onToolCall 里加了一个全局的超时计时器，如果 4 秒内没有收到结果，就自动 addToolResult 插入一个“服务暂时不可用”的消息，让模型继续往下说。这个 Hack 虽然解决了卡死，但本质上是在和 SDK 的状态管理对着干，因为 SDK 并没有提供原生超时机制。

更头疼的是重试策略。Toolformer 论文假设工具调用是可重入的，然而，我的股价查询是计费的，每个 API Key 一天只有 100 次免费额度。当网络抖动导致工具调用被重复执行时，我一天之内就把额度刷爆了。SDK 目前对工具调用的重试没有任何约束，你必须自己在 execute 函数里做缓存和去重。我用了一个简单的 Redis 缓存，以调用参数哈希为 key，3 分钟内不重复请求。但如果你没有 Redis，那就得在前端用 addToolResult 手动插入缓存数据，防止后端触发实际请求。

把工具结果变成生成式 UI，才发现状态同步是个坑

React Server Components 与动态渲染的结合

AI SDK 3.0 宣传的一大卖点是生成式 UI，即根据模型输出的工具调用结果动态渲染复杂的 React 组件。我在上面的代码里实现了 WeatherCard，一个包含动态天气图标的组件。这个组件在客户端渲染没有任何问题，因为状态由 useChat 管理。但我想尝试把工具结果先通过 Server Component 预处理，比如把天气数据格式化成一段更友好的 HTML，然后再发送给客户端。于是我在 streamText 的 execute 里返回的不是纯文本，而是一个 React Server Component 的渲染结果，但这就踩了坑：AI SDK 当前版本对服务端组件的流式推送还不是开箱即用的，你必须自己用 renderToReadableStream 并注入到流中，而且客户端的 useChat 并不具备解析自定义内容类型的能力。我不得不放弃这个方案，老老实实把工具结果以 JSON 返回，让客户端组件自己渲染。这和论文里设想的“模型直接生成可交互界面”完全是两回事——Toolformer 只在文本层面操作，从来没有考虑前端富交互。

多轮工具调用下的组件状态混乱，不是论文里的理想序列

另一个坑是多轮对话中的上下文保持。当用户说“上周北京的天气怎么样”时，我需要另一个工具来查历史天气，这又引入了时间参数。模型调用 getWeatherHistory 后，结果返回了大量数据，但我之前的 WeatherCard 只适配了当前天气的格式，于是渲染崩了。我改成了根据工具名称和返回结构动态选择组件，但这让我的代码迅速膨胀。而且，当工具调用失败或超时，前端组件收到一个错误对象而不是预期格式，又得处理。我最后写了 200 多行的错误边界和 fallback 逻辑，才让生成式 UI 不至于白屏。Toolformer 论文没有涉及任何 UI 层面的交互，更不用提错误处理，而这些恰恰是工程中最耗费精力的部分。（延伸阅读：在Jetson Orin Nano上跑零样本导航的代价：生成式仿真省了300小时数据采集，但推理延迟从22ms涨到41ms）

部署到 Vercel Edge，延迟降了，但冷启动差点让我回滚

Edge Runtime 的优势与限制

SDK 3.0 从设计上就对 Edge Runtime 有很好的支持。我把 Next.js 项目部署到 Vercel，默认就是 Edge 环境，API 路由自动转为 edge function。部署完毕后，用 time 指令测试第一个 token 的到达时间，从原来的 1200ms 降到了 380ms，因为边缘节点就在东京，离我近。但第二天早上再次测试时，首次调用延迟又回到了 1.2 秒——那是 Edge 冷启动造成的。Vercel 的 edge function 在 5 分钟没有请求后会被回收，恢复时需要重新加载 OpenAI 的客户端和模型适配器。SDK 的初始化虽然快，但 OpenAI 客户端的 new OpenAI() 在 Edge 环境下会触发 DNS 解析和 TLS 握手，额外耗时。我后来通过 Next.js 的 route segment config 启用 keep-alive 预热，并在 Vercel 项目设置里添加了 cron job 每 4 分钟 ping 一次 API，勉强解决了冷启动。

性能优化：SSE 流缓冲和缓存策略

另一个优化点是流缓冲。默认情况下 streamText 每生成一个 token 就写一次流，但 Edge Worker 的 I/O 是有计费的，过于频繁的写入会消耗 CPU 时间。我参考 Cloudflare Workers 那篇《Streaming Large LLM Responses》博客，以及 Vercel 内部的 AI 基础设施论文（他们去年底在 arxiv 发了一篇关于 Edge AI 推理的预印本），调整了后端 API，在 execute 里使用了一个 16 个 token 的缓冲区，攒够一批再发送。这样既不影响用户的感知延迟，又减少了流写入次数约 60%。你可以在 streamText 里通过 experimental_streamOptions 控制，虽然文档说是 experimental，但我用下来很稳定。另外，对于重复的问题，我在前端用 swr 的缓存机制，把相同 messages 的请求缓存 2 分钟，避免重复调用模型的费用。

到这里，我的流式聊天助手终于在线上跑稳了。回顾这一路，最深的感触是：AI SDK 把“从想法到界面”的门槛压得非常低，让你在半小时内就能搭出一个看似完美的 demo，但你一旦把它当做真实产品对待，就会发现 SDK 替你隐藏的那些复杂度——流重连、工具超时、并发控制、冷启动——都会在某个凌晨的监控报警里冒出来。Toolformer 给了我一个美好的愿景，但现实世界的 API 会超时、网络会抖动、用户会同时发三条消息，这些都是论文里不会讨论的，却是你必须面对的。

实验笔记：我给 streamText 的工具调用加了一个基于队列的并发控制，防止突发请求打爆第三方 API。核心实现是维护一个 ConcurrencyLimiter，在 execute 前排队，确保同时只执行最多 2 个工具调用。代码片段如下：

const limiter = new ConcurrencyLimiter(2);
execute: async (args) => limiter.run(() => fetchWeather(args.city))

这让我能平稳应对模型并行调用三个查询的场景。但我最大疑问是：SDK 目前没有暴露工具调用的 abort 信号，当用户在前端点“停止生成”时，后端的 execute 不会被取消，仍然浪费资源。我下一步打算在 execute 里读取 request.signal 并传递给底层 fetch，看能否做到真正的取消。另外，Vercel 的 Edge 环境对 Node.js crypto 模块的支持有限，导致我原本想用 crypto.randomUUID 生成去重 key 的代码直接炸了，改用 headers 里的 x-vercel-id 来拼凑唯一 ID，算是 dirty 但有效。最让我兴奋的，倒不是 SDK 本身，而是这种把大模型能力接入现有 React 生态的方式，可能会倒逼框架层面更激进地支持流式状态管理——也许下一个版本的 React 会原生提供类似 useStream 的 hook？