---
title: "将 Vercel AI SDK 接入 XiuRouter"
description: "使用 OpenAI-compatible provider 在服务端调用 XiuRouter，并验证文本、流式与用量。"
image: "https://docs.xiu.ai/og.png"
---

> XiuAI 文档索引
> 完整文档索引：https://docs.xiu.ai/llms.txt
> 阅读前先通过索引确认当前可用页面。

# 将 Vercel AI SDK 接入 XiuRouter

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

## 配置方式

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

## 前置条件

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

## 安装依赖

```bash
npm install ai @ai-sdk/openai-compatible
```

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

## 保存服务端 Key

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

```dotenv
XIUROUTER_API_KEY=YOUR_XIUROUTER_API_KEY
```

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

## 创建 provider

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

```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",
});
```

## 生成文本

```ts
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 用量。

## 流式输出

```ts
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);
}
```

## 验证

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

## 常见失败

| 现象 | 处理 |
| --- | --- |
| `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 运行计费请求；工具调用与结构化输出需要按模型验证。

源文件：https://docs.xiu.ai/router/integrations/vercel-ai-sdk/index.mdx