我先把结论放前面Vercel AI SDK 和 Vercel AI Gateway 并不是“二选一”的关系而是一条很典型的 AI 应用链路里的两层。AI SDK 负责让你在 Next.js 等前端技术栈里快速写出流式聊天、文本生成、工具调用这类功能AI Gateway 则像一个统一的模型接入收口把不同大模型厂商的 API 收拢到一个可控的入口上顺带把缓存、限流、重试、日志这些工程问题从业务代码里剥出去。这次我们用一个最小可运行项目来演示先通过 AI SDK 写一个 Chat API 和小型聊天界面再把请求改到 AI Gateway 上最后用接口测试、批量文本生成、日志观测和异常排查把这些能力串起来。如果你是做前端、全栈或者正在规划“把好几个大模型 API 接入统一平台”的中小型团队这篇文章会比较对口。先说清楚一个边界AI SDK 和 AI Gateway 属于“云端模型调用型”基础能力不是本地推理工具。它们本身不加载模型权重也基本不涉及 GPU 显存。真正吃算力的是你配置的后端大模型服务。所以这篇文章不讨论显卡要求重点是启动方式、接口能力、批量任务、日志观测和排查成本。1. Vercel AI SDK 与 AI Gateway 核心能力速览1.1 Vercel AI SDK 能力表能力项说明项目类型面向 TypeScript / JavaScript 的 AI 应用开发工具包Vercel 团队开源维护支持运行环境Node.js 服务端、Next.js App Router/Pages Router、其他适配框架主要功能流式文本生成、多轮对话、工具调用、结构化输出、Agent 工作流等模型接入方式通过 Provider 适配层统一接入 OpenAI、Anthropic、Google、Mistral 等模型服务商是否支持流式响应支持streamText配合toDataStreamResponse()可直接返回流是否有前端配套有useChat等 Hooks 可快速实现聊天 UI 状态管理是否本地推理否实际推理发生在你配置的云端模型服务上需要 GPU / 显存不需要本地显存占用可忽略API 服务由你控制。你写的路由就是 API前端、脚本、第三方系统都可以调用批量任务不内置任务队列但可以自己循环调用也可以接到队列里异步执行适合场景快速搭建 AI 功能原型、流式对话、多模型切换、内部工具界面这套工具链的价值不在于封装了多少花哨界面而在于它把“输入提示词 - 拿到流式回复 - 渲染到界面”这条链路标准化了。比较典型的收益是你换模型厂商时业务层不需要大改。1.2 Vercel AI Gateway 能力表能力项说明项目类型Vercel 提供的托管模型网关服务位于应用与大模型服务商之间主要功能统一 API 接入点、请求缓存、速率限制、失败重试、日志与用量观测兼容接口对外多为 OpenAI Chat Completions 风格接口可用 base_url 方式切换支持的模型通常覆盖 OpenAI、Anthropic、Google、Mistral 等主流服务商以 Vercel 控制面板实时列表为准启动方式无需本地安装在 Vercel 面板创建网关项目并获取网关地址和网关 Key是否支持缓存支持命中缓存后可以减少一次昂贵的模型调用是否支持批量任务本身不提供任务队列但适合作为批量调用时统一限流和统计的入口数据位置请求会经过网关再转发到模型服务商涉及数据合规时需要单独确认适合场景多项目共用模型 Key、需要观测成本、需要限流/缓存/日志的线上环境所以这里的基本结论是AI SDK 负责写应用逻辑AI Gateway 负责把整个模型访问收口进“一层可观测、可限流、可缓存”的基础设施。2. 适用场景与使用边界2.1 它适合谁这个组合最适合下面几类情况你在 Next.js、Vue、Svelte 这类现代前端项目里写 AI 功能不想单独维护一套后端聊天服务。你想在一个应用里同时支持多个大模型厂商并且不想给每个模型都写一套适配代码。团队内部有多个项目都要调用 GPT/Claude/国产模型等接口希望统一管理 Key、限制访问频次、记录日志。你希望模型响应能“边生成边显示”而不是等几秒后一次性返回提升用户体感。你准备做批量文本标注、批量摘要、批量文案生成需要一个稳定的调用入口。对以上场景来说AI SDK 解决“怎么写代码”AI Gateway 解决“怎么接入、怎么治理、怎么观测”。2.2 不适合什么如果满足下面条件你可能不需要这套组合你只想在 Python 脚本里调一次 API 做数据处理。这种情况直接拿 OpenAI SDK 或 requests 写更轻。你必须私有化部署模型数据完全不能离开内部网络。Vercel AI Gateway 是托管服务不适合你你可以考虑开源网关或自建模型网关。你只是做一个本地量最大的 demo且不关心多模型 Key 管理和日志。那 AI SDK 可以留着AI Gateway 可以后置。2.3 使用边界和合规提醒这里要特别提示几个点通过 AI Gateway 发请求时请求内容和模型返回内容默认会经过网关是否留存、留存多久要以 Vercel 产品文档和你的数据协议为准。不要把涉及商业秘密、个人隐私、医疗健康信息、未成年人信息等敏感数据随意传给第三方大模型接口。即使有网关也无法改变“数据进入模型服务商”的事实。AI SDK 是基础开发工具用它生成的内容版权风险由业务方自行判断。如果做商用内容建议加上人工核验。Vercel 是云端服务可能有计费额度和频率限制。生产使用前必须去官方定价和配额页面确认不要只参考第三方教程里的数字。3. 环境准备与前置条件3.1 本机开发环境从技术栈看AI SDK 主要面向 Node.js/TypeScript 生态。建议准备Node.js 18 或更高版本。npm、pnpm 或 yarn任选一个。一个能跑 Next.js 的基本开发环境。能访问对应的大模型 API 服务并且有一个可用的模型 API Key。这部分不限制操作系统。Windows、macOS、Linux 都可以。关键是要确认 Node.js 版本够新避免安装依赖时出现引擎版本报错。如果你已经装过 Node.js可以先跑node -v npm -v只要能正常输出版本号就可以继续。3.2 获取大模型 API KeyAI SDK 是模型无关的 SDK。你至少需要一种模型服务商的 Key。这里以 OpenAI 风格的接口为例因为大多数 AI Gateway 和 AI SDK 示例都会默认对接它。获取 Key 之后建议放到环境变量里不要直接写死在 Git 仓库。在 Next.js 项目根目录创建.env.local# .env.local OPENAI_API_KEY你的OpenAI密钥 # 如果你配置了网关再增加网关相关变量 GATEWAY_API_KEY你的网关密钥 GATEWAY_BASE_URL网关控制面板展示的完整地址注意.env.local会被 Next.js 在开发环境中读取。修改环境变量后通常需要重启开发服务器才能生效。3.3 Vercel 平台账号AI Gateway 不是本地安装包而是 Vercel 平台上的一种服务。如果你想完整走通“AI SDK 调用 AI Gateway”的链路需要去 Vercel 注册或登录一个账号。注册流程直接看官网。免费账号通常可以用于体验和原型验证但不同版本的免费额度和计费策略变化较快所以建议以登陆后 Dashboard 里看到的额度为准不要照搬任何教程里的“免费多少万 token”之类的数字。如果你只想先试用 AI SDK不接 AI Gateway那也可以不注册 Vercel 账号直接在本地运行。4. 快速启动用 AI SDK 搭建一个可运行的最小项目4.1 初始化 Next.js 项目创建项目的命令比较简单npx create-next-applatest vercel-ai-demo执行过程中会问是否启用 TypeScript、ESLint、Tailwind CSS、App Router 等选项。建议TypeScript 选 YesAI SDK 类型提示很关键。App Router 选 Yes因为后面要用到app/api/chat/route.ts。Tailwind 可以选 No示例不需要复杂样式。进入目录cd vercel-ai-demo然后安装 AI SDK 相关依赖npm install ai ai-sdk/openai如果你打算用前端 Hook 的聊天 UI则 AI SDK 新版本里会用到 React 配套包可以一并安装npm install ai-sdk/react说明AI SDK 的 Hook 导入路径在不同大版本之间有差异。较新版本建议从ai-sdk/react导入useChat如果你的项目使用的是比较旧的 v4 分支则可能是ai/react。安装后以你实际安装包的类型定义和官方文档为准不要在项目里混用两套导入路径。4.2 创建 Chat API 路由在app/api/chat/route.ts中写入下面的代码import { openai } from ai-sdk/openai; import { streamText } from ai; // 允许服务器执行更长的时间避免流式生成中途超时 export const maxDuration 60; export async function POST(req: Request) { // 读取客户端发来的 messages const { messages } await req.json(); // 调用模型并流式生成 const result streamText({ model: openai(process.env.OPENAI_MODEL_ID || gpt-4o-mini), messages, }); // 转成 AI SDK 约定的数据流格式返回 return result.toDataStreamResponse(); }这段代码的意思是前端提交一个messages数组里面包含系统角色、用户角色、助手角色等历史消息。streamText发起一次模型生成请求。toDataStreamResponse()把生成结果包装成 HTTP 流响应浏览器端可以逐段接收。4.3 创建聊天页面在app/page.tsx中写入use client; import { useChat } from ai-sdk/react; export default function ChatPage() { const { messages, input, handleInputChange, handleSubmit } useChat(); return ( div style{{ maxWidth: 700, margin: 40px auto, padding: 0 16px }} h1Vercel AI SDK Demo/h1 div style{{ minHeight: 200, whiteSpace: pre-wrap }} {messages.map((m) ( div key{m.id} strong{m.role user ? 用户: : AI: }/strong {m.content} /div ))} /div form onSubmit{handleSubmit} input value{input} onChange{handleInputChange} placeholder输入你的问题... style{{ width: 100%, padding: 12, marginTop: 16 }} / /form /div ); }如果你安装的 AI SDK 版本较旧可能需要把ai-sdk/react改成ai/react。这里并不准备把代码写死成某个版本而是让你在跑通后留意控制台有没有导入错误。4.4 启动开发服务器执行npm run dev浏览器打开http://localhost:3000。输入“用一句话介绍 Vercel AI SDK”如果页面能像 ChatGPT 那样逐字显示回复说明链路已经通了。4.5 直接用 curl 测试 Chat API除了浏览器还可以直接用 curl 验证接口curl -N http://localhost:3000/api/chat \ -H Content-Type: application/json \ -d {messages:[{role:user,content:用一句话介绍 Vercel AI Gateway}]}加上-N是为了关闭 curl 的缓冲尽快看到流式内容。返回内容不是普通 JSON而是一段 AI SDK 自定义数据流格式浏览器端useChat能正确解析所以看到不算“标准 JSON”其实正常。5. 配置 AI Gateway 并接入统一接口5.1 在 Vercel 控制台创建网关项目登录 Vercel 后到 AI Gateway 相关页面点击创建网关项目或添加 Provider。大致流程是选择要接入的模型服务商例如 OpenAI。填写该服务商的 API Key。这个 Key 会保存在 Vercel 侧不用下发到你的业务服务器。获取网关地址Vercel 通常会分配一个专属网关域名形如https://xxxx.ai-gateway.vercel.app之类具体以控制面板展示为准。生成一个网关 Key用于业务侧请求。这里需要强调界面文案和入口位置变化很频繁。不要死记某个按钮名称而是理解概念创建 Provider、添加模型、生成网关 Key、拿到网关 Base URL。按控制面板实际路径做即可。5.2 用 curl 走一遍 AI Gateway 请求网关对外一般提供 OpenAI Chat Completions 兼容接口。接入方式通常是把 base_url 指向网关地址。下面是一个通用模板curl https://你的网关地址/v1/chat/completions \ -H Authorization: Bearer 你的网关Key \ -H Content-Type: application/json \ -d { model: 你配置好的模型标识, messages: [ {role: user, content: Vercel AI Gateway 能做什么} ], stream: false }需要注意两个容易踩坑的点地址末尾是否需要加/v1以网关控制面板或官方示例为准。有的网关地址本身已经带路径再拼一次/v1就会 404。model字段不是填模型昵称而是要和控制面板里显示/配置的模型 ID 保持一致。常见格式类似于openai/gpt-4o-mini。如果能正常返回choices数组说明网关已经打通。5.3 让 AI SDK 也走 AI Gateway如果你的 AI SDK 依然直接连 OpenAI Provider那 AI Gateway 的缓存、限流、日志能力就没有覆盖到业务请求。一个比较务实的接入方式是在调用 AI SDK 时使用自定义 base URL 的 OpenAI Provider。ai-sdk/openai支持通过工厂函数创建 Providerimport { createOpenAI } from ai-sdk/openai; const gatewayOpenAI createOpenAI({ apiKey: process.env.GATEWAY_API_KEY, baseURL: process.env.GATEWAY_BASE_URL, });然后在需要调用模型的地方把模型替换成网关 Providerconst result streamText({ model: gatewayOpenAI(process.env.OPENAI_MODEL_ID || gpt-4o-mini), messages, });这里不需要改streamText的业务逻辑只换模型 Provider 即可。这样你的 Next.js 服务就不再直接持有模型服务商 Key而是统一持有一个网关 Key。网关会帮你记录请求量、token 用量和错误状态。6. 接口 API 与批量文本生成任务6.1 在 AI SDK 中实现批量生成AI SDK 并不内置“任务队列”但批量生成本质上就是循环调用。如果你需要批量生成摘要、批改文案、生成标签可以写一个类似下面的函数import { openai } from ai-sdk/openai; import { generateText } from ai; const prompts [ 用一句话介绍 HTTP 缓存, 用一句话介绍 API Gateway, 用一句话介绍速率限制, ]; export async function generateBatch(modelId: string) { const outputs: string[] []; for (const prompt of prompts) { const { text } await generateText({ model: openai(modelId), prompt, }); outputs.push(text); } return outputs; }这里有几个工程化建议首次批量任务先跑 1~3 条确认模型稳定后再扩大。循环里建议增加错误捕获某一条失败时不要中断整个批次。大批量任务不要直接放在浏览器请求里最好由后台任务或队列消费。6.2 Python 脚本通过 AI Gateway 做批量调用AI Gateway 另一个很大的用途是给 Python、Java、运维脚本也提供统一入口。这种方式不需要在非 Node 项目里安装 AI SDK。用 Python 示例如下from openai import OpenAI client OpenAI( base_url你的网关地址必要时以/v1结尾, api_key你的网关Key, ) prompts [ 用一句话解释 Vercel AI SDK, 用一句话解释 AI 流式输出, 给这篇文章生成一个 SEO 标题, ] for i, prompt in enumerate(prompts, start1): response client.chat.completions.create( model你的网关模型标识, messages[ {role: user, content: prompt} ], temperature0.7, ) content response.choices[0].message.content print(f第 {i} 条:, content)代码不能直接复制运行。需要把网关地址、Key、模型标识替换成你在 Vercel 控制面板里实际拿到的值。如果运行时提示不了 OpenAI SDK先执行pip install openai6.3 批量任务的重试策略即使有网关兜底批量任务最好仍然自己处理失败重试。建议在循环里捕获异常for i, prompt in enumerate(prompts, start1): for attempt in range(3): try: response client.chat.completions.create(...) print(...) break except Exception as e: print(f第 {i} 条失败第 {attempt 1} 次重试:, e) time.sleep(1)你还可以在网关控制台配置限流阈值和重试次数。网关层面的重试主要解决瞬时错误业务代码里的重试解决任务级失败。两层配合会更稳。7. 功能测试与效果验证7.1 测试用例设计AI 应用测试不能只测“能不能返回”还建议测试流式、多轮、错误处理、缓存命中这几个维度。测试项输入示例预期结果验证方法基础对话“你好”返回一段正常文本页面显示或 curl 输出流式生成让模型写一篇长文页面逐字出现不是一次性打印浏览器观察多轮对话先问“11 等于几”再问“上面我提了什么”模型能引用上一轮上下文页面连续对话历史消息格式发送错误 message 结构接口返回 400 参数错误curl 查看状态码网关请求记录走 AI Gateway 发一次请求网关日志能看到请求和 token 用量Vercel 面板日志7.2 缓存效果验证AI Gateway 的缓存不是所有请求都默认命中。执行下面步骤验证确认网关请求日志里能看到第一次请求。修改请求内容里的 temperature 等参数看看是否会绕过缓存。对同一条 prompt 连续发送第二次请求。在网关日志中观察是否出现“cache hit”字样。普通文本生成如果命中缓存响应速度一般会明显低于完整模型调用。如果你测出来两条请求耗时差不多可能是缓存 key 里带了随机参数、多温度参数或网关配置里没有开启缓存。7.3 失败场景验证最好人工制造几个失败场景确认自己的错误处理真的有效失败场景测试方式预期处理API Key 无效把网关 Key 改成错误值返回 401需透出明确提示模型 ID 不存在把 model 改成不存在的值返回 400/404应用应显示错误请求体过大塞入超长文本
Vercel AI SDK与AI Gateway：AI应用开发中的模型接入与网关治理
我先把结论放前面Vercel AI SDK 和 Vercel AI Gateway 并不是“二选一”的关系而是一条很典型的 AI 应用链路里的两层。AI SDK 负责让你在 Next.js 等前端技术栈里快速写出流式聊天、文本生成、工具调用这类功能AI Gateway 则像一个统一的模型接入收口把不同大模型厂商的 API 收拢到一个可控的入口上顺带把缓存、限流、重试、日志这些工程问题从业务代码里剥出去。这次我们用一个最小可运行项目来演示先通过 AI SDK 写一个 Chat API 和小型聊天界面再把请求改到 AI Gateway 上最后用接口测试、批量文本生成、日志观测和异常排查把这些能力串起来。如果你是做前端、全栈或者正在规划“把好几个大模型 API 接入统一平台”的中小型团队这篇文章会比较对口。先说清楚一个边界AI SDK 和 AI Gateway 属于“云端模型调用型”基础能力不是本地推理工具。它们本身不加载模型权重也基本不涉及 GPU 显存。真正吃算力的是你配置的后端大模型服务。所以这篇文章不讨论显卡要求重点是启动方式、接口能力、批量任务、日志观测和排查成本。1. Vercel AI SDK 与 AI Gateway 核心能力速览1.1 Vercel AI SDK 能力表能力项说明项目类型面向 TypeScript / JavaScript 的 AI 应用开发工具包Vercel 团队开源维护支持运行环境Node.js 服务端、Next.js App Router/Pages Router、其他适配框架主要功能流式文本生成、多轮对话、工具调用、结构化输出、Agent 工作流等模型接入方式通过 Provider 适配层统一接入 OpenAI、Anthropic、Google、Mistral 等模型服务商是否支持流式响应支持streamText配合toDataStreamResponse()可直接返回流是否有前端配套有useChat等 Hooks 可快速实现聊天 UI 状态管理是否本地推理否实际推理发生在你配置的云端模型服务上需要 GPU / 显存不需要本地显存占用可忽略API 服务由你控制。你写的路由就是 API前端、脚本、第三方系统都可以调用批量任务不内置任务队列但可以自己循环调用也可以接到队列里异步执行适合场景快速搭建 AI 功能原型、流式对话、多模型切换、内部工具界面这套工具链的价值不在于封装了多少花哨界面而在于它把“输入提示词 - 拿到流式回复 - 渲染到界面”这条链路标准化了。比较典型的收益是你换模型厂商时业务层不需要大改。1.2 Vercel AI Gateway 能力表能力项说明项目类型Vercel 提供的托管模型网关服务位于应用与大模型服务商之间主要功能统一 API 接入点、请求缓存、速率限制、失败重试、日志与用量观测兼容接口对外多为 OpenAI Chat Completions 风格接口可用 base_url 方式切换支持的模型通常覆盖 OpenAI、Anthropic、Google、Mistral 等主流服务商以 Vercel 控制面板实时列表为准启动方式无需本地安装在 Vercel 面板创建网关项目并获取网关地址和网关 Key是否支持缓存支持命中缓存后可以减少一次昂贵的模型调用是否支持批量任务本身不提供任务队列但适合作为批量调用时统一限流和统计的入口数据位置请求会经过网关再转发到模型服务商涉及数据合规时需要单独确认适合场景多项目共用模型 Key、需要观测成本、需要限流/缓存/日志的线上环境所以这里的基本结论是AI SDK 负责写应用逻辑AI Gateway 负责把整个模型访问收口进“一层可观测、可限流、可缓存”的基础设施。2. 适用场景与使用边界2.1 它适合谁这个组合最适合下面几类情况你在 Next.js、Vue、Svelte 这类现代前端项目里写 AI 功能不想单独维护一套后端聊天服务。你想在一个应用里同时支持多个大模型厂商并且不想给每个模型都写一套适配代码。团队内部有多个项目都要调用 GPT/Claude/国产模型等接口希望统一管理 Key、限制访问频次、记录日志。你希望模型响应能“边生成边显示”而不是等几秒后一次性返回提升用户体感。你准备做批量文本标注、批量摘要、批量文案生成需要一个稳定的调用入口。对以上场景来说AI SDK 解决“怎么写代码”AI Gateway 解决“怎么接入、怎么治理、怎么观测”。2.2 不适合什么如果满足下面条件你可能不需要这套组合你只想在 Python 脚本里调一次 API 做数据处理。这种情况直接拿 OpenAI SDK 或 requests 写更轻。你必须私有化部署模型数据完全不能离开内部网络。Vercel AI Gateway 是托管服务不适合你你可以考虑开源网关或自建模型网关。你只是做一个本地量最大的 demo且不关心多模型 Key 管理和日志。那 AI SDK 可以留着AI Gateway 可以后置。2.3 使用边界和合规提醒这里要特别提示几个点通过 AI Gateway 发请求时请求内容和模型返回内容默认会经过网关是否留存、留存多久要以 Vercel 产品文档和你的数据协议为准。不要把涉及商业秘密、个人隐私、医疗健康信息、未成年人信息等敏感数据随意传给第三方大模型接口。即使有网关也无法改变“数据进入模型服务商”的事实。AI SDK 是基础开发工具用它生成的内容版权风险由业务方自行判断。如果做商用内容建议加上人工核验。Vercel 是云端服务可能有计费额度和频率限制。生产使用前必须去官方定价和配额页面确认不要只参考第三方教程里的数字。3. 环境准备与前置条件3.1 本机开发环境从技术栈看AI SDK 主要面向 Node.js/TypeScript 生态。建议准备Node.js 18 或更高版本。npm、pnpm 或 yarn任选一个。一个能跑 Next.js 的基本开发环境。能访问对应的大模型 API 服务并且有一个可用的模型 API Key。这部分不限制操作系统。Windows、macOS、Linux 都可以。关键是要确认 Node.js 版本够新避免安装依赖时出现引擎版本报错。如果你已经装过 Node.js可以先跑node -v npm -v只要能正常输出版本号就可以继续。3.2 获取大模型 API KeyAI SDK 是模型无关的 SDK。你至少需要一种模型服务商的 Key。这里以 OpenAI 风格的接口为例因为大多数 AI Gateway 和 AI SDK 示例都会默认对接它。获取 Key 之后建议放到环境变量里不要直接写死在 Git 仓库。在 Next.js 项目根目录创建.env.local# .env.local OPENAI_API_KEY你的OpenAI密钥 # 如果你配置了网关再增加网关相关变量 GATEWAY_API_KEY你的网关密钥 GATEWAY_BASE_URL网关控制面板展示的完整地址注意.env.local会被 Next.js 在开发环境中读取。修改环境变量后通常需要重启开发服务器才能生效。3.3 Vercel 平台账号AI Gateway 不是本地安装包而是 Vercel 平台上的一种服务。如果你想完整走通“AI SDK 调用 AI Gateway”的链路需要去 Vercel 注册或登录一个账号。注册流程直接看官网。免费账号通常可以用于体验和原型验证但不同版本的免费额度和计费策略变化较快所以建议以登陆后 Dashboard 里看到的额度为准不要照搬任何教程里的“免费多少万 token”之类的数字。如果你只想先试用 AI SDK不接 AI Gateway那也可以不注册 Vercel 账号直接在本地运行。4. 快速启动用 AI SDK 搭建一个可运行的最小项目4.1 初始化 Next.js 项目创建项目的命令比较简单npx create-next-applatest vercel-ai-demo执行过程中会问是否启用 TypeScript、ESLint、Tailwind CSS、App Router 等选项。建议TypeScript 选 YesAI SDK 类型提示很关键。App Router 选 Yes因为后面要用到app/api/chat/route.ts。Tailwind 可以选 No示例不需要复杂样式。进入目录cd vercel-ai-demo然后安装 AI SDK 相关依赖npm install ai ai-sdk/openai如果你打算用前端 Hook 的聊天 UI则 AI SDK 新版本里会用到 React 配套包可以一并安装npm install ai-sdk/react说明AI SDK 的 Hook 导入路径在不同大版本之间有差异。较新版本建议从ai-sdk/react导入useChat如果你的项目使用的是比较旧的 v4 分支则可能是ai/react。安装后以你实际安装包的类型定义和官方文档为准不要在项目里混用两套导入路径。4.2 创建 Chat API 路由在app/api/chat/route.ts中写入下面的代码import { openai } from ai-sdk/openai; import { streamText } from ai; // 允许服务器执行更长的时间避免流式生成中途超时 export const maxDuration 60; export async function POST(req: Request) { // 读取客户端发来的 messages const { messages } await req.json(); // 调用模型并流式生成 const result streamText({ model: openai(process.env.OPENAI_MODEL_ID || gpt-4o-mini), messages, }); // 转成 AI SDK 约定的数据流格式返回 return result.toDataStreamResponse(); }这段代码的意思是前端提交一个messages数组里面包含系统角色、用户角色、助手角色等历史消息。streamText发起一次模型生成请求。toDataStreamResponse()把生成结果包装成 HTTP 流响应浏览器端可以逐段接收。4.3 创建聊天页面在app/page.tsx中写入use client; import { useChat } from ai-sdk/react; export default function ChatPage() { const { messages, input, handleInputChange, handleSubmit } useChat(); return ( div style{{ maxWidth: 700, margin: 40px auto, padding: 0 16px }} h1Vercel AI SDK Demo/h1 div style{{ minHeight: 200, whiteSpace: pre-wrap }} {messages.map((m) ( div key{m.id} strong{m.role user ? 用户: : AI: }/strong {m.content} /div ))} /div form onSubmit{handleSubmit} input value{input} onChange{handleInputChange} placeholder输入你的问题... style{{ width: 100%, padding: 12, marginTop: 16 }} / /form /div ); }如果你安装的 AI SDK 版本较旧可能需要把ai-sdk/react改成ai/react。这里并不准备把代码写死成某个版本而是让你在跑通后留意控制台有没有导入错误。4.4 启动开发服务器执行npm run dev浏览器打开http://localhost:3000。输入“用一句话介绍 Vercel AI SDK”如果页面能像 ChatGPT 那样逐字显示回复说明链路已经通了。4.5 直接用 curl 测试 Chat API除了浏览器还可以直接用 curl 验证接口curl -N http://localhost:3000/api/chat \ -H Content-Type: application/json \ -d {messages:[{role:user,content:用一句话介绍 Vercel AI Gateway}]}加上-N是为了关闭 curl 的缓冲尽快看到流式内容。返回内容不是普通 JSON而是一段 AI SDK 自定义数据流格式浏览器端useChat能正确解析所以看到不算“标准 JSON”其实正常。5. 配置 AI Gateway 并接入统一接口5.1 在 Vercel 控制台创建网关项目登录 Vercel 后到 AI Gateway 相关页面点击创建网关项目或添加 Provider。大致流程是选择要接入的模型服务商例如 OpenAI。填写该服务商的 API Key。这个 Key 会保存在 Vercel 侧不用下发到你的业务服务器。获取网关地址Vercel 通常会分配一个专属网关域名形如https://xxxx.ai-gateway.vercel.app之类具体以控制面板展示为准。生成一个网关 Key用于业务侧请求。这里需要强调界面文案和入口位置变化很频繁。不要死记某个按钮名称而是理解概念创建 Provider、添加模型、生成网关 Key、拿到网关 Base URL。按控制面板实际路径做即可。5.2 用 curl 走一遍 AI Gateway 请求网关对外一般提供 OpenAI Chat Completions 兼容接口。接入方式通常是把 base_url 指向网关地址。下面是一个通用模板curl https://你的网关地址/v1/chat/completions \ -H Authorization: Bearer 你的网关Key \ -H Content-Type: application/json \ -d { model: 你配置好的模型标识, messages: [ {role: user, content: Vercel AI Gateway 能做什么} ], stream: false }需要注意两个容易踩坑的点地址末尾是否需要加/v1以网关控制面板或官方示例为准。有的网关地址本身已经带路径再拼一次/v1就会 404。model字段不是填模型昵称而是要和控制面板里显示/配置的模型 ID 保持一致。常见格式类似于openai/gpt-4o-mini。如果能正常返回choices数组说明网关已经打通。5.3 让 AI SDK 也走 AI Gateway如果你的 AI SDK 依然直接连 OpenAI Provider那 AI Gateway 的缓存、限流、日志能力就没有覆盖到业务请求。一个比较务实的接入方式是在调用 AI SDK 时使用自定义 base URL 的 OpenAI Provider。ai-sdk/openai支持通过工厂函数创建 Providerimport { createOpenAI } from ai-sdk/openai; const gatewayOpenAI createOpenAI({ apiKey: process.env.GATEWAY_API_KEY, baseURL: process.env.GATEWAY_BASE_URL, });然后在需要调用模型的地方把模型替换成网关 Providerconst result streamText({ model: gatewayOpenAI(process.env.OPENAI_MODEL_ID || gpt-4o-mini), messages, });这里不需要改streamText的业务逻辑只换模型 Provider 即可。这样你的 Next.js 服务就不再直接持有模型服务商 Key而是统一持有一个网关 Key。网关会帮你记录请求量、token 用量和错误状态。6. 接口 API 与批量文本生成任务6.1 在 AI SDK 中实现批量生成AI SDK 并不内置“任务队列”但批量生成本质上就是循环调用。如果你需要批量生成摘要、批改文案、生成标签可以写一个类似下面的函数import { openai } from ai-sdk/openai; import { generateText } from ai; const prompts [ 用一句话介绍 HTTP 缓存, 用一句话介绍 API Gateway, 用一句话介绍速率限制, ]; export async function generateBatch(modelId: string) { const outputs: string[] []; for (const prompt of prompts) { const { text } await generateText({ model: openai(modelId), prompt, }); outputs.push(text); } return outputs; }这里有几个工程化建议首次批量任务先跑 1~3 条确认模型稳定后再扩大。循环里建议增加错误捕获某一条失败时不要中断整个批次。大批量任务不要直接放在浏览器请求里最好由后台任务或队列消费。6.2 Python 脚本通过 AI Gateway 做批量调用AI Gateway 另一个很大的用途是给 Python、Java、运维脚本也提供统一入口。这种方式不需要在非 Node 项目里安装 AI SDK。用 Python 示例如下from openai import OpenAI client OpenAI( base_url你的网关地址必要时以/v1结尾, api_key你的网关Key, ) prompts [ 用一句话解释 Vercel AI SDK, 用一句话解释 AI 流式输出, 给这篇文章生成一个 SEO 标题, ] for i, prompt in enumerate(prompts, start1): response client.chat.completions.create( model你的网关模型标识, messages[ {role: user, content: prompt} ], temperature0.7, ) content response.choices[0].message.content print(f第 {i} 条:, content)代码不能直接复制运行。需要把网关地址、Key、模型标识替换成你在 Vercel 控制面板里实际拿到的值。如果运行时提示不了 OpenAI SDK先执行pip install openai6.3 批量任务的重试策略即使有网关兜底批量任务最好仍然自己处理失败重试。建议在循环里捕获异常for i, prompt in enumerate(prompts, start1): for attempt in range(3): try: response client.chat.completions.create(...) print(...) break except Exception as e: print(f第 {i} 条失败第 {attempt 1} 次重试:, e) time.sleep(1)你还可以在网关控制台配置限流阈值和重试次数。网关层面的重试主要解决瞬时错误业务代码里的重试解决任务级失败。两层配合会更稳。7. 功能测试与效果验证7.1 测试用例设计AI 应用测试不能只测“能不能返回”还建议测试流式、多轮、错误处理、缓存命中这几个维度。测试项输入示例预期结果验证方法基础对话“你好”返回一段正常文本页面显示或 curl 输出流式生成让模型写一篇长文页面逐字出现不是一次性打印浏览器观察多轮对话先问“11 等于几”再问“上面我提了什么”模型能引用上一轮上下文页面连续对话历史消息格式发送错误 message 结构接口返回 400 参数错误curl 查看状态码网关请求记录走 AI Gateway 发一次请求网关日志能看到请求和 token 用量Vercel 面板日志7.2 缓存效果验证AI Gateway 的缓存不是所有请求都默认命中。执行下面步骤验证确认网关请求日志里能看到第一次请求。修改请求内容里的 temperature 等参数看看是否会绕过缓存。对同一条 prompt 连续发送第二次请求。在网关日志中观察是否出现“cache hit”字样。普通文本生成如果命中缓存响应速度一般会明显低于完整模型调用。如果你测出来两条请求耗时差不多可能是缓存 key 里带了随机参数、多温度参数或网关配置里没有开启缓存。7.3 失败场景验证最好人工制造几个失败场景确认自己的错误处理真的有效失败场景测试方式预期处理API Key 无效把网关 Key 改成错误值返回 401需透出明确提示模型 ID 不存在把 model 改成不存在的值返回 400/404应用应显示错误请求体过大塞入超长文本
