Vercel AI SDK怎么用？从模型接入到流式文本与工具调用的入门指南

Vercel AI SDK是一组用于构建AI应用的开发工具，适合网页聊天、内容生成、结构化输出和工具调用等场景。它通常把模型请求放在服务端，把消息状态和流式文本展示放在前端。这样既能减少前端重复处理不同模型接口的工作，也能避免把模型密钥直接暴露给浏览器。

一、准备模型提供商和环境变量

先在项目中安装核心SDK、目标模型提供商适配包，以及用于参数校验的工具库。以某个支持的提供商为例，项目需要配置对应的API密钥，例如在本地环境文件中写入PROVIDER_API_KEY=你的密钥。环境文件不应提交到代码仓库，生产环境则应使用部署平台的服务端环境变量。

模型选择通常写在服务端代码中，例如使用提供商适配包创建一个模型对象，再传给SDK的文本生成方法。不同提供商的初始化方式和模型名称可能不同，应该以所使用提供商的文档为准。不要把密钥写在以公开前端变量为用途的环境变量中，也不要在客户端代码中直接调用需要密钥的模型接口。

二、创建基础聊天接口

在服务端路由中接收前端传来的消息，调用SDK的文本生成能力。基本结构可以概括为：读取请求体中的messages，调用streamText传入model和messages，然后将结果转换为适合前端消费的流式响应。示意代码中的方法名称应与项目安装的SDK版本保持一致。

服务端流程：接收请求 → 校验消息格式 → 调用模型 → 返回流式响应。请求体不要无条件信任，至少应限制消息数量、文本长度和允许的角色，避免异常输入造成不必要的模型调用。

如果暂时不需要实时输出，也可以使用非流式文本生成方法，等待模型完整返回后再响应。流式方式更适合聊天界面，因为用户能先看到已经生成的内容，不必等待整段回答结束。

三、把流式文本传到前端

前端可以使用SDK提供的React聊天能力，或自行读取Fetch返回的ReadableStream。使用官方前端钩子时，通常需要指定聊天接口地址，并把输入框内容加入消息列表；服务端返回的增量内容会持续更新当前回答。自行处理时，则要读取响应流、解码每一段数据，并将文本追加到正在显示的消息中。

聊天界面应至少包含输入框、发送按钮、生成中状态和错误提示。发送请求期间可以禁用重复提交；用户中止生成时，要让前端取消请求，并在服务端妥善处理连接关闭。流式数据格式由所用SDK的响应方法决定，不能简单假设所有返回都是普通纯文本。

四、加入工具调用

工具调用不是让模型直接访问数据库，而是由开发者声明工具名称、用途和参数结构。模型根据对话决定是否请求工具，服务端收到请求后校验参数，执行实际函数，再把执行结果交回模型，由模型生成最终答复。

例如天气工具可以定义city参数，数据库查询工具可以定义关键词、分页和筛选条件。使用SDK的工具定义函数时，通常会提供description和基于Schema的参数规则，并配置execute函数。参数校验通过后，execute才可以调用天气服务或数据库；查询结果应只返回完成任务所需的数据，避免泄露内部字段。

完整流程是：模型提出工具调用 → 服务端校验并执行 → 返回工具结果 → 模型继续生成文本。要设置工具白名单、超时和权限边界。涉及写入数据、发送邮件或支付等副作用时，最好增加用户确认，而不是让模型自动执行。

五、错误处理与安全检查

• 模型请求失败时返回明确的HTTP错误和用户可读提示，同时在服务端记录必要的诊断信息。
• 对工具参数、查询条件和返回结果做Schema校验，避免把未经检查的数据继续传给模型或页面。
• 限制请求频率、上下文长度和工具执行时间，并为外部天气服务或数据库调用设置超时。
• 过滤日志中的密钥、授权头和敏感用户内容，避免调试日志变成数据泄露渠道。
• API密钥只放在服务端，前端只能访问自己的聊天接口，不能直接读取密钥。

六、最小实现思路

可以先完成一个只有文本输入和流式回答的聊天框，确认服务端模型调用、前端增量显示和异常提示都正常，再增加一个只读天气工具。工具稳定后，再接入数据库查询，并为查询条件添加权限校验。这样分阶段调试，比一次加入多个模型、多个工具和复杂UI更容易定位问题。实际项目中，应根据已安装SDK的接口文档调整导入名称、消息转换方法和流式响应方法。