更改 AI API Base URL 前的 7 项迁移测试

AI API 基础 URL 迁移测试应在环境变量更改之前进行，而不是在生产流量开始失败之后。更改单个 baseURL 或 base_url 可以同时将身份验证、模型选择、流式传输、工具调用、使用记录、配额行为和回滚控制转移到新路径上。

Flatkey 专为希望在模型提供商之间实现一个密钥、一个 OpenAI 兼容路由层以及更清晰的计费和使用情况审查的团队而设计。在 2026 年 7 月 7 日检查的 Flatkey 公共主页显示了示例路由 https://router.flatkey.ai/v1/chat/completions，而当前的模型和定价页面则公开了模型、端点、提供商和计费上下文以供审查。将这些页面视为迁移当日的证据，然后在转移流量之前运行您自己的账户冒烟测试。

使用本指南作为 AI API 基础 URL 迁移测试的实用顺序。目标不是证明每个应用程序路径。目标是证明通过新基础 URL 的最小安全路径，然后一次一层地添加功能。

7 项 AI API 基础 URL 迁移测试

按此顺序运行测试。每一项都应产生可以附加到部署工单的证据。

不要因为框架包装器已在预演环境中工作就跳过早期测试。大多数 AI API 基础 URL 迁移测试失败是因为 SDK 静默读取了不同的密钥，接收了错误的基础 URL 根目录，或将有效模型发送到了错误的端点系列。

测试 1：身份验证和基础 URL 构成

从应用程序外部开始。您需要证明密钥和基础 URL 可以访问最简单的端点形态。

常见的基础 URL 错误是将完整的端点传递给 SDK。对于 OpenAI 兼容的 SDK，基础 URL 通常是 API 根目录，例如 https://router.flatkey.ai/v1，然后 SDK 会附加 /chat/completions、/responses 或其他端点。将 https://router.flatkey.ai/v1/chat/completions 作为基础 URL 传递可能会创建重复的路径。

首先使用经过编辑的环境检查：

test -n "$FLATKEY_API_KEY" && echo "FLATKEY_API_KEY is set"
printf '%s' "$FLATKEY_API_KEY" | wc -c
printf '%s\n' "$FLATKEY_BASE_URL"

然后发出一个直接请求：

export FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
export FLATKEY_MODEL="your-current-flatkey-model-alias"

curl -sS "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'",
    "messages": [
      {"role": "user", "content": "Reply with exactly: base url ok"}
    ]
  }'

如果返回 401，请在更改模型之前修复密钥和身份验证标头。如果返回 404，请检查主机、/v1 根目录以及端点路径是否重复。如果返回 403，请检查账户、项目、模型、区域或 IP 策略。OpenAI 的错误代码文档将 401 视为身份验证，429 视为速率或配额，500 或 503 视为服务器或过载情况；网关可以添加更多详细信息，因此请保存响应正文。

测试 2：模型目录和端点系列

一个 OpenAI 兼容的基础 URL 并不意味着每个模型名称都是可移植的。OpenAI API 有一个列出模型的端点，其聊天补全和响应端点使用不同的请求形态。网关或提供商兼容的路由可以为一个端点系列公开一个模型，但不能为另一个端点系列公开。

在更改生产配置之前，创建一个小的模型映射：

通过条件不是“模型名称看起来正确”。通过条件是当前的 Flatkey 控制台、模型目录或提供商目录显示了您计划调用的确切端点族的确切别名。请通过 OpenAI 兼容模型名称指南将此工作与您更广泛的模型治理联系起来。

测试 3：普通聊天补全

第三项 AI API base URL 迁移测试是最小的真实生成请求。保持其非流式传输。不要包含工具、JSON 模式、文件、图像、重试或应用中间件。

保存：

如果普通请求失败，请不要立即调试流式传输。首先使用 OpenAI 兼容 API 故障排除指南来隔离密钥、路由、端点族和模型别名问题。

测试 4：SDK 对等性

在 curl 正常工作后，证明 SDK 构建了相同的路由。OpenAI 当前的官方文档将开发者指向官方的 JavaScript 和 Python SDK。OpenAI cookbook 也展示了自定义端点的用法，即使用令牌和自定义 base URL 创建客户端。对于迁移，请在代码中明确这一点，而不是依赖于遗留的 OPENAI_API_KEY 或 OPENAI_BASE_URL 值。

Python 模板：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["FLATKEY_API_KEY"],
    base_url=os.environ.get("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1"),
)

response = client.chat.completions.create(
    model=os.environ["FLATKEY_MODEL"],
    messages=[{"role": "user", "content": "Reply with exactly: sdk ok"}],
)

print(response.choices[0].message.content)
print(response.usage)

Node 模板：

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.FLATKEY_API_KEY,
  baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
});

const response = await client.chat.completions.create({
  model: process.env.FLATKEY_MODEL!,
  messages: [{ role: "user", content: "Reply with exactly: sdk ok" }],
});

console.log(response.choices[0]?.message?.content);
console.log(response.usage);

在进程启动时记录解析后的 base URL，但不要记录密钥。如果 curl 成功而 SDK 失败，请在更改模型之前检查环境变量优先级、SDK 版本、路径连接、组织/项目标头和代理行为。

测试 5：流式传输或 SSE

流式传输是许多迁移在 HTTP 层看起来正常但在应用程序中失败的地方。启用流式传输后，OpenAI 的聊天补全参考会返回一个 JSON 对象或流式聊天补全块。Responses API 也可以返回 text/event-stream，其事件名称与聊天补全块不同。

在非流式请求正常工作后运行此命令：

curl -N "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_MODEL"'"',
    "stream": true,
    "messages": [
      {"role": "user", "content": "Count from one to five slowly."}
    ]
  }'

通过条件：

要进行更深入的流解析，请与现有的 OpenAI 兼容流式 SSE 测试进行比较。

测试 6：工具或函数调用

工具调用增加了模式和能力风险。OpenAI 的函数调用指南描述了一个多步骤流程：发送工具、接收工具调用、执行应用代码、返回工具输出，然后接收最终的模型响应。即使纯文本工作正常，base URL 迁移也可能在这些边界中的任何一个失败。

不要一开始就使用完整的生产工具集。使用一个微小的函数：

{
  "model": "your-current-flatkey-model-alias",
  "messages": [
    {"role": "user", "content": "使用工具处理订单 A123。"}
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "lookup_order",
        "description": "返回测试订单状态。",
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": {"type": "string"}
          },
          "required": ["order_id"],
          "additionalProperties": false
        }
      }
    }
  ],
  "tool_choice": "auto"
}

如果此项测试失败而普通聊天功能正常，那么您就不再是调试基本 URL 了。您正在调试的是模型能力、端点系列、模式严格性、tool_choice 或所选路由的网关支持。已发布的工具调用兼容性指南涵盖了更广泛的提供商清单。

测试 7：用量、配额和回滚

最后的 AI API 基本 URL 迁移测试是操作性的。如果财务部门无法核对生成的响应，配额行为不符合预期，或者回滚需要紧急代码更改，那么仅有生成的响应是不够的。

在一次成功的冒烟测试后，请验证：

使用一个足够简单的回滚文件，以便在压力下执行：

# 活动
AI_API_BASE_URL=https://router.flatkey.ai/v1
AI_API_MODEL=your-current-flatkey-model-alias

# 回滚
AI_API_BASE_URL_ROLLBACK=https://previous-provider.example/v1
AI_API_MODEL_ROLLBACK=previous-production-model
AI_API_ROLLBACK_OWNER=platform-oncall

不要依赖记忆进行回滚。将先前的配置、功能标志、部署命令和验证命令与 AI API 基本 URL 迁移测试存储在同一个部署工单中。

需要保留的证据包

为每个环境保留一个能回答以下问题的证据包：

这是在切换前运行 AI API 基本 URL 迁移测试的实际优势。该产出物对于部署审查、事件响应、用量核对和采购证据都很有用。

Flatkey 的适用场景

Flatkey 可以通过将模型访问、路由、计费、用量分析和操作审查集中在一个密钥后面来减少迁移扩散。但这并不能免除测试的需要。它为团队提供了一个单一的控制点，工程、财务和运营部门可以在此检查相同的路由证据。

在迁移之前，请查看实时的 Flatkey 模型和定价页面，确认当前的控制台基本 URL，并从一个小的路由测试开始。如果您仍在计划更广泛的切换，请将本指南与 OpenAI 兼容 API 迁移指南结合使用。当您准备好运行自己的测试时，获取一个密钥，并保持第一个请求足够小，以便手动检查。

常见问题解答

什么是 AI API 基本 URL 迁移测试？

AI API 基本 URL 迁移测试是在切换前进行的检查，用于证明新的 API 根路径在身份验证、模型路由、普通聊天、SDK 使用、流式传输、工具、用量回读、配额行为和回滚方面都能正常工作。

我应该先测试 curl 还是 SDK？

先测试 curl。Curl 可以在没有框架行为的情况下证明密钥、URL、端点路径和模型别名的有效性。然后再使用相同的值测试 SDK。

基本 URL 是否应包含 /chat/completions？

通常不应该。将 API 根路径（例如 /v1）提供给 SDK，然后让 SDK 附加端点。仅在直接使用 curl 请求时才使用完整的端点。

为什么普通聊天正常而流式传输失败？

流式传输可能会失败，因为路由缓冲了响应、客户端解析器期望错误的事件形状、中间件消耗了流，或者所选的端点系列不支持您正在使用的流形状。

如果我还不能运行实时的 Flatkey 请求怎么办？

将代码片段保存为模板，验证公共文档和控制台配置，并且在真实密钥在您自己的环境中证明七项 AI API 基本 URL 迁移测试通过之前，不要迁移生产流量。

总结

更改 AI API base URL 是一次生产环境迁移，而不是简单的字符串编辑。请按顺序运行 AI API base URL 迁移测试：身份验证 (auth)、模型目录 (model catalog)、普通聊天 (plain chat)、SDK 对等性 (SDK parity)、流式传输 (streaming)、工具 (tools) 以及用量和回滚 (usage plus rollback)。当所有七项测试都通过时，base URL 的更改就成了一次受控的切换，而不是一次深夜的调试会议。