Vercel AI SDK 自定义提供商基础 URL：Flatkey 设置笔记

Vercel AI SDK 自定义提供商基础 URL 的设置不仅仅是字符串替换。有用的部分是将 AI SDK 提供商指向 Flatkey，但安全的生产工作是在用户流量转移之前验证模型别名、端点族、流式行为、工具调用、使用证据、配额控制和回滚。

本指南适用于在 Next.js 路由、服务器操作、工作程序、队列或代理循环中使用 AI SDK 的开发人员、AI 产品团队、平台工程师、自动化构建者、财务运营商和采购审查员。本文根据当前的 AI SDK 文档、对当前 AI SDK 包的类型检查以及 Flatkey 的实时公共页面于 2026 年 6 月 29 日更新。代码片段是模板。此任务中没有可用的实时 Flatkey API 密钥，因此请使用您自己的密钥、当前的 Flatkey 控制台基础 URL 以及为您的帐户启用的模型别名来运行冒烟测试。

快速解答：Vercel AI SDK 自定义提供商基础 URL

对于使用 Flatkey 的 Vercel AI SDK 自定义提供商基础 URL 设置，请从官方的 OpenAI 兼容提供商包开始。使用 createOpenAICompatible 创建一个提供商，将 baseURL 设置为从您的控制台获取的当前 Flatkey 基础 URL，将 apiKey 设置为您的 Flatkey 密钥，并在 generateText 或 streamText 中使用 Flatkey 模型别名。

npm install ai @ai-sdk/openai-compatible zod

export FLATKEY_API_KEY="fk_your_key"
export FLATKEY_BASE_URL="https://console.flatkey.ai/v1" # Copy the current value from Flatkey
export FLATKEY_MODEL="your-flatkey-model-alias"

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

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Missing ${name}`);
  }
  return value;
}

const flatkey = createOpenAICompatible({
  name: 'flatkey',
  apiKey: requiredEnv('FLATKEY_API_KEY'),
  baseURL: requiredEnv('FLATKEY_BASE_URL'),
  includeUsage: true,
});

const result = await generateText({
  model: flatkey.chatModel(requiredEnv('FLATKEY_MODEL')),
  prompt: 'Reply with one short Flatkey AI SDK routing check.',
});

console.log(result.text);
console.log(result.finishReason);
console.log(result.usage);
console.log(result.warnings);

这是 Vercel AI SDK 自定义提供商基础 URL 迁移的最小可行形式。不要止步于此。一个通过的文本响应仅证明一个请求形式到达了一个模型别名。它并不能证明流式使用、工具、结构化输出、成本可见性、配额行为或回滚。

当前 AI SDK 文档支持什么

当前的 AI SDK 文档有两条相关路径。OpenAI 兼容提供商包是为实现 OpenAI API 的提供商构建的。它公开了 createOpenAICompatible，其选项包括 name、apiKey、baseURL、headers、queryParams、自定义 fetch、includeUsage、supportsStructuredOutputs、请求体转换和元数据提取。

OpenAI 提供商包还支持 createOpenAI({ baseURL }) 用于自定义设置，包括代理服务器。对于 Vercel AI SDK 自定义提供商基础 URL 来说，OpenAI 兼容提供商是更清晰的默认选项，因为它的提供商名称、自定义元数据提取、提供商特定选项和模型工厂名称都是为非 OpenAI 的 OpenAI 兼容路由设计的。

需谨慎使用的最新 Flatkey 证据

在 2026 年 6 月 29 日检查的 Flatkey 主页标题为 One API gateway for production AI teams，其 meta 描述称 Flatkey 统一了模型访问、路由、计费、使用分析和操作控制。实时定价 API 返回了 633 个模型行、23 个供应商以及用于 /v1/chat/completions、/v1/responses、/v1/messages、/v1beta/models/{model}:generateContent、/v1/images/generations 和 /v1/video/generations 的端点族。

将这些事实用作定位和目录形状的过时公共证据，而不是作为每个帐户都可以调用每个路由、每个模型别名都可用或每个功能都已启用的证明。在投入生产流量之前，您的 Vercel AI SDK 自定义提供商基础 URL 检查应使用您的应用程序将发送的确切密钥、基础 URL、模型别名、端点族和功能路径。

基础 URL 和环境设置

将基础 URL、密钥和模型别名保存在环境变量中。这样一来，Vercel AI SDK 自定义提供商基础 URL 的部署就可以在部署配置中进行审查，而不是深埋在路由处理程序、提示文件和 worker 中。

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Missing ${name}`);
  }
  return value;
}

const flatkey = createOpenAICompatible({
  name: 'flatkey',
  apiKey: requiredEnv('FLATKEY_API_KEY'),
  baseURL: requiredEnv('FLATKEY_BASE_URL'),
  includeUsage: true,
});

然后，将工作负载路由与传输设置分开。基础 URL 告诉 SDK 将请求发送到哪里。模型别名决定了您请求的是哪个 Flatkey 路由和上游模型。

const MODEL_ROUTES = {
  supportTriage: 'FLATKEY_SUPPORT_MODEL',
  workflowPlanning: 'FLATKEY_PLANNING_MODEL',
  codeReview: 'FLATKEY_CODE_MODEL',
  fallback: 'FLATKEY_FALLBACK_MODEL',
} as const;

function modelFor(routeName: keyof typeof MODEL_ROUTES) {
  return flatkey.chatModel(requiredEnv(MODEL_ROUTES[routeName]));
}

这种模式可以防止团队在代码库中分散提供商名称、模型别名和基础 URL。它还为财务和运营团队提供了一组稳定的工作负载名称，以便与使用量记录进行匹配。

首先对非流式文本进行冒烟测试

从 generateText 开始。它会给你一个直接的结果对象，其中包含文本、完成原因、使用情况、警告、步骤和响应元数据。在测试流式传输或工具之前，用它来验证身份验证、基础 URL 格式、模型别名和使用情况的可见性。

import { generateText } from 'ai';

const result = await generateText({
  model: modelFor('supportTriage'),
  prompt: 'Reply with one short migration readiness check.',
});

console.log({
  text: result.text,
  finishReason: result.finishReason,
  usage: result.usage,
  warnings: result.warnings,
});

只有当生成的文本、模型别名、完成原因和使用情况字段足以满足应用程序的日志记录和审查需求时，才批准这第一次 Vercel AI SDK 自定义提供商基础 URL 检查。如果调用返回了文本，但在 Flatkey 记录中找不到使用情况，则说明迁移尚未准备好用于生产环境。

单独测试流式传输

流式传输有不同的故障面。它涉及响应流、无服务器超时、UI 取消、错误处理和使用情况核算。AI SDK 文档展示了 streamText、result.textStream、一个 onError 回调以及诸如 result.usage 之类的结果 promise。当提供商支持时，OpenAI 兼容提供商还具有 includeUsage 用于流式传输响应元数据。

import { streamText } from 'ai';

const stream = streamText({
  model: flatkey.chatModel(requiredEnv('FLATKEY_MODEL')),
  prompt: 'Stream three short setup checks.',
  onError({ error }) {
    console.error(error);
  },
});

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

const usage = await stream.usage;
console.log({ usage });

只有在所选的 Flatkey 模型别名在您的真实请求形态下证明稳定后，才保持流式传输启用。如果流式文本正常工作但使用情况不完整，请在用户流量转移之前，决定您的团队是否可以从 Flatkey 记录而不是流式响应中收集使用情况。

使用相同的别名验证工具调用

AI SDK 工具 API 使用一个 tools 对象、tool 辅助函数、一个 inputSchema 和一个可选的 execute 函数。一次普通的聊天传递并不能批准工具调用。首先测试一个小的 schema，然后扩展到您的代理实际使用的工具集。

import { generateText, isStepCount, tool } from 'ai';
import { z } from 'zod';

const result = await generateText({
  model: flatkey.chatModel(requiredEnv('FLATKEY_TOOL_MODEL')),
  tools: {
    routeReadiness: tool({
      description: 'Return the readiness state for a Flatkey route.',
      inputSchema: z.object({
        routeName: z.string().describe('Internal route name to inspect'),
      }),
      execute: async ({ routeName }) => ({
        routeName,
        checked: true,
      }),
    }),
  },
  stopWhen: isStepCount(2),
  prompt: 'Use the tool for route supportTriage.',
});

console.log(result.toolCalls);
console.log(result.toolResults);
console.log(result.usage);

对于代理流量，记录模型是否调用了预期的工具，输入是否通过验证，工具结果是否干净地返回，以及 Flatkey 使用情况记录是否可以追溯到同一路由。如果严格的 schema、审批流程或并行工具调用很重要，请使用确切的模型别名测试这些功能。

何时改用 createOpenAI

如果您的应用程序已经到处使用 @ai-sdk/openai，那么 OpenAI 提供商的 baseURL 选项可能是一条差异较小的迁移路径。这仍然是一个 Vercel AI SDK 自定义提供商基础 URL 设置，但您应该更明确地选择模型 API。

import { createOpenAI } from '@ai-sdk/openai';
import { generateText } from 'ai';

const flatkeyViaOpenAIProvider = createOpenAI({
  name: 'flatkey',
  apiKey: requiredEnv('FLATKEY_API_KEY'),
  baseURL: requiredEnv('FLATKEY_BASE_URL'),
});

const result = await generateText({
  model: flatkeyViaOpenAIProvider.chat(requiredEnv('FLATKEY_MODEL')),
  prompt: 'Reply with one short OpenAI-provider base URL check.',
});

当前的 OpenAI 提供商文档指出，自 AI SDK 5 起，除非您指定像 .chat(...) 这样的路由，否则 Responses 是 OpenAI 提供商的默认 API。这就是为什么上面的示例明确使用 .chat(...)。如果您打算测试 Flatkey 的 /v1/responses 端点系列，请将其视为一个单独的路由检查，并使用单独的模型别名和回滚路径。

设置清单

常见故障模式

本文与其他 Flatkey 指南的关系

如果您需要更广泛的迁移路径，请从 OpenAI 兼容 API 迁移指南开始。对于相关的工具设置模式，请查阅 Cherry Studio API 设置指南以及 cc-switch Claude Code Flatkey 指南。使用 Flatkey 定价来查看当前的模型目录，然后在您准备好在自己的账户中运行冒烟测试时获取密钥。

常见问题解答

如何为 Flatkey 设置 Vercel AI SDK 自定义提供商基础 URL？

使用 createOpenAICompatible 创建一个 OpenAI 兼容的提供商，将 baseURL 设置为当前的 Flatkey 基础 URL，将 apiKey 设置为您的 Flatkey 密钥，并将一个 Flatkey 模型别名传递给 generateText 或 streamText。

我应该使用 @ai-sdk/openai-compatible 还是 @ai-sdk/openai？

对于新的 Flatkey 设置，请使用 @ai-sdk/openai-compatible，因为它专为 OpenAI 兼容的提供商设计。当您的应用程序已经标准化使用 OpenAI 提供商，并且您希望代码差异更小时，请使用带有 createOpenAI({ baseURL }) 的 @ai-sdk/openai。

基础 URL 是否需要包含 /v1？

请使用您当前 Flatkey 控制台中显示的值。在大多数 OpenAI 兼容的 SDK 模式中，基础 URL 包含版本前缀，以便 SDK 调用可以正确地附加诸如 /chat/completions 之类的路径。

一个 Flatkey 基础 URL 可以路由多个模型吗？

Flatkey 的公开定位是作为模型访问、路由、计费、用量分析和运营控制的统一网关。在您的应用程序中，仍然需要将每个工作负载映射到一个明确的 Flatkey 模型别名，并在流量转移之前测试实际的别名。

这些 AI SDK 代码片段经过测试了吗？

这些代码片段于 2026 年 6 月 29 日针对 ai@7.0.4、@ai-sdk/openai-compatible@3.0.1、@ai-sdk/openai@4.0.2、TypeScript 和 Zod 进行了类型检查。它们没有针对 Flatkey 执行，因为在此运行时中没有可用的实时 Flatkey API 密钥。

总结

Vercel AI SDK 自定义提供商基础 URL 的迁移应该是一个小的提供商变更，并附带一份严格的验证清单。为 Flatkey 提供商使用 createOpenAICompatible，将基础 URL 和模型别名保留在配置中，首先测试非流式文本，分别测试流式传输和工具调用，在 Flatkey 中确认使用证据，并在生产流量稳定之前准备好回滚方案。当检查准备就绪时，获取一个密钥并使用您自己的模型别名运行冒烟测试。