企业官网建设流程全解析

我先把结论放前面：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 能力表

这套工具链的价值不在于封装了多少花哨界面，而在于它把“输入提示词 -> 拿到流式回复 -> 渲染到界面”这条链路标准化了。比较典型的收益是：你换模型厂商时，业务层不需要大改。

1.2 Vercel AI Gateway 能力表

所以，这里的基本结论是：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 Key

AI 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-app@latest vercel-ai-demo

执行过程中会问是否启用 TypeScript、ESLint、Tailwind CSS、App Router 等选项。建议：

• TypeScript 选 Yes，AI 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' }}> <h1>Vercel 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支持通过工厂函数创建 Provider：

import { createOpenAI } from '@ai-sdk/openai'; const gatewayOpenAI = createOpenAI({ apiKey: process.env.GATEWAY_API_KEY, baseURL: process.env.GATEWAY_BASE_URL, });

然后在需要调用模型的地方把模型替换成网关 Provider：

const 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, start=1): response = client.chat.completions.create( model="你的网关模型标识", messages=[ {"role": "user", "content": prompt} ], temperature=0.7, ) content = response.choices[0].message.content print(f"第 {i} 条:", content)

代码不能直接复制运行。需要把网关地址、Key、模型标识替换成你在 Vercel 控制面板里实际拿到的值。如果运行时提示不了 OpenAI SDK，先执行：

pip install openai

6.3 批量任务的重试策略

即使有网关兜底，批量任务最好仍然自己处理失败重试。建议在循环里捕获异常：

for i, prompt in enumerate(prompts, start=1): 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 应用测试不能只测“能不能返回”，还建议测试流式、多轮、错误处理、缓存命中这几个维度。

7.2 缓存效果验证

AI Gateway 的缓存不是所有请求都默认命中。执行下面步骤验证：

• 确认网关请求日志里能看到第一次请求。
• 修改请求内容里的 temperature 等参数，看看是否会绕过缓存。
• 对同一条 prompt 连续发送第二次请求。
• 在网关日志中观察是否出现“cache hit”字样。

普通文本生成如果命中缓存，响应速度一般会明显低于完整模型调用。如果你测出来两条请求耗时差不多，可能是缓存 key 里带了随机参数、多温度参数，或网关配置里没有开启缓存。

7.3 失败场景验证

最好人工制造几个失败场景，确认自己的错误处理真的有效：