你写前端，想把大模型接进页面：流式输出、多轮对话、切模型、调工具，结果发现每家接口字段都不一样，光 fetch 就写了一堆胶水代码。这时候会有人跟你提 Vercel AI SDK。这篇不堆概念，就讲它是干什么的、能省掉哪些活、什么情况下反而不该用，以及上手前先确认哪几件事。
你写前端，想把大模型接进页面：流式输出、多轮对话、切模型、调工具，结果发现每家接口字段都不一样，光 fetch 就写了一堆胶水代码。这时候有人跟你提 Vercel AI SDK。先给一句话定位：它不是模型，也不是中转站，而是一层跑在你前端或 Node 项目里的调用封装，把「请求模型—接流式返回—渲染到界面」这条链路标准化。
这篇不堆概念，讲它替你省掉哪些活、几个核心模块分别管什么、什么情况下反而不该用，以及动手前先确认哪几件事。读完你至少能判断：自己这个项目现在该不该引入它。
它到底替你省了哪几步活
没用它的时候，这些活全是你自己干：拼请求体、处理 SSE 分片、把增量字符串攒起来、维护多轮消息数组、给不同厂商改字段名。这些活单看都不难，但换一次模型就要重来一遍，是典型的消耗型工作量。SDK 用统一接口加适配层把这些兜住，你的页面代码只跟统一的那套打交道。
- 统一调用接口
- 同一种写法调用不同厂商的模型，换模型时改的是配置，不是页面逻辑
- 流式适配
- 服务端逐块吐回来的内容接到前端，边收边渲染，不用自己切分片
- 消息编排
- 多轮对话的消息数组、系统提示的拼接位置由它管，你只管往界面塞
- 结构化输出
- 让模型按你定义的字段结构返回，方便直接喂给下游代码
- 工具调用
- 模型说「我要调某个函数」，你这边执行完把结果塞回去，形成闭环
重点在于「换模型时前端代码基本不动」：模型名和 key 从配置走，页面里那套对话渲染逻辑不用重写。反过来说，如果你的项目根本不用 JS 或 TS 生态，或者你要的是纯后端批处理、跑离线任务，这层封装帮不上你。
几个核心模块分别管什么
| 模块 | 管的事 | 典型场景 |
|---|---|---|
| 对话编排 | 消息列表、系统提示、多轮上下文 | 聊天界面、客服问答 |
| 流式输出 | 把服务端逐块返回的内容边收边渲染 | 打字机效果、边生成边展示 |
| 结构化输出 | 按你定的字段结构返回结果 | 表单填充、分类打标 |
| 工具调用 | 模型发起函数调用，你执行并回填 | 查数据库、调内部接口 |
这张表不是让你全上，而是让你按需求挑。做聊天界面，第一、二个模块是主力；做后台数据加工，第三个模块更关键；要接内部系统，第四个模块才是重点。都想要也可以，但要注意一个前提。
这些模块只在支持对应能力的模型上才有效。比如工具调用和结构化输出，不是每个模型都支持。选模型前先到 AI 模型库（/models） 核对目标模型的能力项，别等写完才发现模型不返回你要的结构。
- 先明确主场景：聊天、内容生成、后台加工，还是函数调用
- 按主场景挑一到两个模块，不要一次全上
- 到模型库核对能力支持情况，尤其是工具调用和结构化输出
- 能力不支持时，要么换模型，要么把这块逻辑放到你自己后端兜
动手前先确认这几件事
- 定接口来源直连官方、走中转站还是本地模型，三种的 base URL 和鉴权字段都不一样，这步没定后面全是返工。比对入口可以看 换模型前先比一比率和额度（/ai-nav/category/ai-api），具体数字以页面当时显示的为准。
- 把 key 放环境变量别写进前端代码，浏览器里能看到的 key 等于公开。正确做法是前端只调你自己的后端路由，由后端带 key 去请求模型。
- 先跑通最短链路第一步发一次非流式请求拿到完整回复，第二步改成流式，第三步再加多轮。一次全上，出错时分不清是哪一层的问题。
- 检查运行环境这套东西大量依赖流式响应和较长连接。部署在短超时的函数环境里，要单独调超时和缓冲设置，否则会出现半截断流。
- 量一遍延迟基线别等上线才发现首字慢。可以用 接口测速：先量出你的延迟基线（/tools/speed-test），后面换模型或换线路时才有对比参照。
这五步里最容易跳过的是最后一步。没有基线，你后面所有「变快了还是变慢了」的判断都是靠感觉，换模型中转之后也没法验证。
什么时候该用，什么时候绕开
适合用的场景比较集中：做聊天界面、做需要边生成边展示的交互、需要在同一套前端里给用户切换不同模型。这三类的共同点是「界面逻辑和模型解耦」对你有真实价值，不是理论上的好处。
- 适合用：聊天界面、流式生成展示、前端统一切换多家模型
- 可以不用：一次性后台调用、只跑脚本的离线任务
- 可以不用：团队已有成熟内部封装，再叠一层等于多一个要跟的依赖
- 要谨慎：生产系统需要精细控制重试、超时和缓存的场合
选型时按三条排：你要不要流式、要不要换模型、团队写不写 TS。三条里有两条是「要」，引入的收益就比较明显；只有一条，先评估自己写胶水的成本。
判断标准会随场景变，这点要说清楚。同一套 SDK，做 Demo 很省事；但到了需要精细控制重试、超时和缓存的生产系统，你可能要绕开部分封装自己接管。这不代表它不好用，而是封装替你做的决定，未必每个都符合你的业务要求。
不适用的情况也要摆明：你的接口不走 HTTP 流式、团队不用 JS 生态、或者模型能力本身不支持你要的模块，这时候引入它只是多一层需要维护的东西。
下一步先想清楚你的主场景属于哪一类，再去站内核对模型能力和接口来源。同一套判断标准，配合当时的真实数字才有意义。→常见问题
Vercel AI SDK 是模型吗？用了它是不是就有免费额度？
不是模型，它本身不提供任何推理能力，也不送额度。它只是一层代码封装，真正干活的是你背后接的那家模型接口——官方、中转站还是本地都行。所以费用、限速、可用模型这些，取决于你在配置里指向了谁，跟这个 SDK 无关。
我只写前端，不会后端，能用它吗？
部分能用，但要小心。它的流式调用需要服务端路由配合，纯浏览器里直接放 key 等于把密钥公开。稳妥做法是让后端同事提供一条自己的接口，你在前端只管消息和渲染。如果实在只有前端，至少把 key 放在服务端环境变量里。
用了它之后换模型还要改很多代码吗？
通常不用大改。模型名、key、接口地址都是配置项，页面里的对话渲染逻辑和它解耦。但要注意不同模型对工具调用、结构化输出的支持程度不一样，换之前先到站内模型库核对该模型的能力清单，否则会出现代码没错但功能不生效的情况。
