> ## Documentation Index
> Fetch the complete documentation index at: https://docs.inputapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Vercel AI SDK 接入

> 使用 OpenAI Compatible Provider，通过服务端 Chat Completions 接入。

## 使用条件

本页使用通用 `@ai-sdk/openai-compatible` 适配器，把 AI SDK 的 `generateText` 接到本项目的 Chat Completions。需要 Node.js 22.18+ 或 24 LTS、API Key，以及已验证支持 Chat 的模型。密钥与脚本只运行在服务端或终端。

文档目录已锁定 `ai@7.0.141`、`@ai-sdk/openai-compatible@3.0.69`，执行 `npm ci` 即可安装。在自己的 Node 项目中安装：

```sh theme={null}
npm install --save-exact ai@7.0.141 @ai-sdk/openai-compatible@3.0.69
```

SDK 升级可能改变请求与响应归一化行为，请重新检查发送路径并运行契约测试。这个示例显式使用 `provider.chatModel()`；不会自动改用 Responses。

## 完整可运行示例

保存为 `examples/ai-sdk.mts`，然后执行：

```sh theme={null}
export API_BASE_URL='https://gateway.example.com/v1'
export API_KEY='YOUR_API_KEY'
export API_MODEL='YOUR_CHAT_MODEL_ID'
node examples/ai-sdk.mts
```

保留部署路径前缀，Base URL 包含 `/v1`，不包含 `/chat/completions`。下面的文本示例只接受一个完整的纯文本回答；拒绝、工具调用、截断或空文本均以非零状态结束，不把部分内容打印为成功结果。

```typescript theme={null}
import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText } from 'ai';

try {
  const { API_BASE_URL, API_KEY, API_MODEL } = process.env;
  const base = new URL(API_BASE_URL || 'invalid:');
  if (!['http:', 'https:'].includes(base.protocol) || base.username || base.password
    || base.search || base.hash || !API_KEY?.trim() || !API_MODEL?.trim()) {
    throw new Error('Invalid configuration.');
  }
  const provider = createOpenAICompatible({
    name: 'api-gateway', baseURL: base.href.replace(/\/+$/, ''), apiKey: API_KEY,
    fetch: (input, init) => fetch(input, { ...init, redirect: 'error' }),
  });
  const result = await generateText({
    model: provider.chatModel(API_MODEL),
    prompt: 'Say hello in one short sentence.',
    maxRetries: 0,
    abortSignal: AbortSignal.timeout(60_000),
    include: { responseBody: true },
  });
  // Check the raw Chat response as well: adapters can normalize away refusal fields.
  const raw = result.response.body as {
    error?: unknown;
    choices?: Array<{ index?: number; finish_reason?: string; message?: {
      role?: string; content?: unknown; refusal?: unknown; tool_calls?: unknown;
      function_call?: unknown;
    } }>;
  } | undefined;
  const choice = raw?.choices?.[0];
  const message = choice?.message;
  if (raw?.error || raw?.choices?.length !== 1 || choice?.index !== 0
    || choice.finish_reason !== 'stop' || message?.role !== 'assistant'
    || message.refusal != null || message.tool_calls != null || message.function_call != null
    || typeof message.content !== 'string' || !message.content.trim()
    || result.finishReason !== 'stop' || result.toolCalls.length !== 0
    || result.text !== message.content) {
    throw new Error('Expected one completed text response.');
  }
  console.log(result.text);
} catch {
  console.error('AI SDK request failed or returned incomplete text. Check configuration and request logs. No automatic retry.');
  process.exitCode = 1;
}
```

## 关键设置

| 设置 | 原因 |
| - | - |
| `chatModel(API_MODEL)` | 固定使用 `/chat/completions`；模型来自目标部署 |
| `maxRetries: 0` | 禁用 AI SDK 自动重试，避免和网关内部策略叠加 |
| `AbortSignal.timeout(60_000)` | 限定本次调用总等待时间；取消不能证明上游没有执行 |
| `redirect: 'error'` | 地址错误或重定向直接失败，修正实际 API 地址 |
| `include.responseBody` | 为完成状态校验保留原始回执，仅在内存使用，不写入日志 |
| 完成状态及原始响应校验 | 适配器归一化后可能隐藏拒绝等字段；示例同时核对原始 Chat 回执 |

## 扩展能力逐项启用

这个脚本只验证非流式文本。流式、工具、结构化输出、视觉和向量需要单独配置及模型验证。`includeUsage`、`supportsStructuredOutputs` 等适配器选项不能让上游凭空支持对应能力；确认渠道支持后再设置。浏览器 `useChat`、框架路由处理器和 SDK 数据流协议也需要独立的服务端实现，不能把 API Key 直接交给浏览器。

需要原始协议细节时，查看 [Chat API](/zh/api-reference/chat-completions)、[流式输出](/zh/guides/streaming)、[工具调用](/zh/guides/tool-calling)与[结构化输出](/zh/guides/structured-output)。

本地校验包含所有 `.mts` 示例的严格类型检查，以及该脚本的真实 SDK + 本机 HTTP fixture 请求检查；没有验证真实模型。参考：[官方适配器文档](https://ai-sdk.dev/providers/openai-compatible-providers)与 [generateText 参数](https://ai-sdk.dev/docs/reference/ai-sdk-core/generate-text)。

[Read in English](/en/guides/ai-sdk)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.