将 Vercel AI SDK 接入 XiuRouter

使用 OpenAI-compatible provider 在服务端调用 XiuRouter，并验证文本、流式与用量。

Vercel AI SDK 使用 @ai-sdk/openai-compatible 连接 XiuRouter Chat Completions。Provider 和 API Key 只能放在服务端代码中，不能打进浏览器包。

配置方式

首次配置：安装 provider、保存服务端环境变量并创建 XiuRouter 实例。
替换已有：产品页当前只提供首次配置路径。需要切换时，保留原 provider 实例作为回滚点。
对话协助：不提供。密钥注入和生产环境变量必须由部署环境管理。

前置条件

项目使用 JavaScript 或 TypeScript，并能运行服务端代码。
已创建一把项目专用 XiuRouter API Key。
已从 XiuRouter 当前目录复制精确模型 ID。

安装依赖

npm install ai @ai-sdk/openai-compatible

必须使用 @ai-sdk/openai-compatible，不是 @ai-sdk/openai。

保存服务端 Key

Next.js 项目写入 .env.local，纯 Node 项目可写入未提交的 .env：

XIUROUTER_API_KEY=YOUR_XIUROUTER_API_KEY

确认环境文件已加入 .gitignore。不要使用 NEXT_PUBLIC_ 前缀；该前缀会把值暴露给浏览器。

创建 provider

新建只在服务端引用的文件，例如 lib/xiurouter.ts：

import { createOpenAICompatible } from "@ai-sdk/openai-compatible";

export const xiurouter = createOpenAICompatible({
  name: "xiurouter",
  apiKey: process.env.XIUROUTER_API_KEY,
  baseURL: "https://router-api.xiu.ai/v1",
});

生成文本

import { generateText } from "ai";
import { xiurouter } from "@/lib/xiurouter";

const { text, usage } = await generateText({
  model: xiurouter("YOUR_MODEL_ID"),
  prompt: "用两句话解释天为什么是蓝的。",
});

console.log(text);
console.log(usage);

脚本应打印完整回答和 Token 用量。

流式输出

import { streamText } from "ai";
import { xiurouter } from "@/lib/xiurouter";

const result = streamText({
  model: xiurouter("YOUR_MODEL_ID"),
  prompt: "写一首四行的短诗。",
});

for await (const textPart of result.textStream) {
  process.stdout.write(textPart);
}

验证

在服务端运行 generateText 示例。
确认输出包含回答和 usage。
在 XiuRouter 控制台“检查实际请求”核对 Key、模型、/v1/chat/completions 和成功状态。
再运行 streamText，确认流式输出完整结束。
工具调用和结构化输出按模型单独测试，不能从普通文本结果推断。

常见失败

现象	处理
`apiKey` 是 `undefined`	Next.js 重启开发服务器；纯 Node 用 `node --env-file=.env` 或在启动进程中设置变量
浏览器报 CORS 或能看到 Key	provider 被客户端代码引用；移到 Server Component、Route Handler 或后端服务
模型不存在	复制精确模型 ID，并检查这把 Key 的模型范围
请求走错接口	确认导入的是 `@ai-sdk/openai-compatible`，Base URL 以 `/v1` 结尾

回滚

把调用切回原 provider 实例，或删除 xiurouter 实例及对应环境变量。确认生产流量已恢复原路由后，再撤销项目专用 XiuRouter API Key。

来源与核对日期

本文以 XiuRouter 产品集成页当前 Vercel AI SDK 示例、服务端密钥边界和验证路径为准，核对日期为 2026-08-22。本轮未使用真实 Key 运行计费请求；工具调用与结构化输出需要按模型验证。