OpenAI 兼容模型名称：避免别名、提供商和版本错误

OpenAI 兼容模型名称是那些原本顺利的迁移悄然出问题的地方。SDK 接受一个 model 字符串，请求形状看起来很熟悉，base URL 也指向一个 OpenAI 兼容路由。然后生产环境就会看到 model_not_found、无声地回退到错误能力，或者把图像模型发送到聊天端点。

解决办法不是把每家提供商的目录都背下来。应将 OpenAI 兼容模型名称视为受控配置：每个字符串都隶属于一个提供商目录、一个端点家族、一条路由、一项版本策略和一份计费记录。在移动真实流量之前，先验证这五项。

Flatkey 在这里很有用，因为团队可以通过一个网关集中管理模型访问、路由、计费、使用分析和运维审核。但网关并不会让松散的模型字符串变得安全。本指南会在你更改 base URL、SDK 设置或生产别名前，给你一套验证 OpenAI 兼容模型名称的工作流。

为什么 OpenAI 兼容模型名称会漂移

“OpenAI-compatible” 描述的是一种 API 形态，而不是通用命名标准。兼容端点可能接受 OpenAI 风格的 JSON 和 SDK，同时仍然要求它自己的模型 ID。

这意味着这些字符串并不能互换：

安全规则很简单：不要凭记忆批准 OpenAI 兼容模型名称。要根据当前目录、当前端点家族以及一次冒烟测试来批准。

模型名称验证工作流

在更改 OPENAI_BASE_URL、baseURL、model、Flatkey 别名或生产路由策略之前，请使用此工作流。

这就是模型名称检查清单的核心价值：它把 OpenAI 兼容模型名称从临时字符串变成经过审查的部署输入。

可供借鉴的当前提供商示例

先用官方文档理解模式，然后在发布前验证你自己的账号或网关目录。

这些示例说明，OpenAI 兼容模型名称应被视为特定于提供商的字符串。兼容性减少了客户端改动；它不会抹平目录差异。

构建一个已批准的模型映射

不要把原始模型字符串散落在应用代码、笔记本、自动化工具和支持脚本中。把已批准的 OpenAI 兼容模型名称放在一个小型映射里，并让每个服务都通过它路由。

type EndpointFamily = "chat" | "responses" | "embeddings" | "images" | "video";

type ApprovedModelRoute = {
  alias: string;
  providerModel: string;
  endpointFamily: EndpointFamily;
  baseURL: string;
  owner: string;
  reviewedAt: string;
  rollbackAlias: string;
};

export const models: Record<string, ApprovedModelRoute> = {
  support_chat: {
    alias: "support_chat",
    providerModel: process.env.FLATKEY_SUPPORT_CHAT_MODEL!,
    endpointFamily: "chat",
    baseURL: process.env.FLATKEY_BASE_URL ?? "https://router.flatkey.ai/v1",
    owner: "support-platform",
    reviewedAt: "2026-07-07",
    rollbackAlias: "support_chat_previous",
  },
};

这个映射将你应用中使用的名称与提供商或网关的模型字符串分开。这为采购、财务和事件响应人员提供了一个稳定的位置来询问：是谁批准了这个模型，它用于哪个端点，以及我们如何回滚它？

如需更广泛的目录治理，请结合使用AI 模型目录指南。如需进行基础 URL 迁移，请使用OpenAI 兼容 API 迁移指南。

在迁移 SDK 之前对精确名称做冒烟测试

模型名称的冒烟测试应该小到可以人工检查。不要一开始就使用工具、流式传输、JSON schema 或框架封装器。先从你计划上线的路由、密钥和模型字符串开始。

export FLATKEY_API_KEY="sk-fk-..."
export FLATKEY_BASE_URL="https://router.flatkey.ai/v1"
export FLATKEY_MODEL="the-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: model route ok"}
    ]
  }'

如果这一步失败，不要先调试 SDK。先检查模型字符串、端点家族、密钥作用域、路由和目录。如果成功，则保存响应正文、状态码、请求 ID（如果有）、时间戳、usage 对象，以及 Flatkey usage 回读信息。

然后通过 SDK 测试相同的 OpenAI 兼容模型名称：

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 route ok" }],
});

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

SDK 测试应使用相同的 base URL 根路径、相同的模型别名，以及相同的端点家族。如果 curl 能正常工作但 SDK 失败，请先检查环境变量，再修改模型名称。

将别名与提供商 ID 分开

别名不等同于提供商 ID。提供商 ID 是上游提供商或兼容提供商路由接受的字符串。网关别名则是你的网关映射到某个提供商模型、回退策略、价格组或账号的字符串。

两者都可能有效。问题出现在团队不再标注自己到底在用哪一个时。

请使用以下命名纪律：

这使 OpenAI 兼容模型名称可审计。如果路由失败，你就能判断问题出在应用别名、Flatkey 别名、提供商模型 ID，还是端点家族。

避免端点家族不匹配

model_not_found 并不总是意味着字符串拼写错误。它也可能意味着该字符串在另一个路由上才有效。

聊天模型可能无法在 Responses 路由上使用。图像模型可能需要图像生成端点。视频模型可能要求不同的载荷家族。提供商兼容层可能会静默忽略不受支持的字段，或者只暴露提供商目录的一部分。

在添加可选参数之前，请回答这些问题：

1. 我调用的这个路由是否已批准使用该模型？
2. 这个端点期望的是 messages、input、prompt、图片、文件，还是其他请求结构？
3. 所选 SDK 是否会在 base URL 后追加端点路径？
4. 提供商是否要求特定于区域或工作区的 base URL？
5. Flatkey 是否会在预发和生产环境中将这个别名路由到同一端点系列？

OpenAI 兼容 API 排错指南涵盖了更广泛的调试路径。对于模型名称问题，请尽量把故障范围缩小：一个路由、一个模型字符串、一个简短请求。

为版本和弃用变更制定计划

OpenAI 兼容的模型名称会随着时间变化。有些名称是稳定的系列，有些是带日期的快照，有些是预览模型，还有一些是由你们团队自己控制的网关别名。

为每一条生产模型路由建立评审节奏：

不要仅仅把这些决策埋在环境变量里。保留一份可供审阅的证据包，这样工程、运维和采购都能看清楚为什么这个模型被允许使用。

切换前在 Flatkey 中需要检查什么

把 Flatkey 当作运行控制点，而不是跳过验证的理由。

在将生产流量迁移之前，请确认：

1. 你在控制台或入门笔记中看到的当前 Flatkey base URL。
2. 应用程序将要发送的确切模型别名。
3. 别名背后的提供商模型或路由。
4. 端点系列，例如 Chat Completions 或 Responses。
5. 该密钥或工作区的配额和支出限制。
6. 在成功冒烟测试后的使用情况回读。
7. 主路由失败时的回退行为。
8. 上一条提供商路由或上一条 Flatkey 别名的回滚配置。

然后将运行侧情况与Flatkey 定价进行比较，并获取一个密钥用于测试路径。只有在迁移当天检查过之后，才应将定价和模型目录页面视为最新证据。

常见问题

OpenAI 兼容的模型名称是通用的吗？

不是。OpenAI 兼容的模型名称仍然是特定于提供商或网关的字符串。请求结构可以兼容，但模型目录仍然可能不同。

为什么我的 OpenAI 兼容路由会返回 model_not_found？

模型字符串可能拼写错误、账户不可用、在网关中被禁用、发送到了错误的端点系列、限定于另一个区域，或者已被弃用。请在当前目录中验证确切字符串，并运行一个最小化路由测试。

我应该使用直接的提供商模型 ID，还是 Flatkey 别名？

当你需要集中路由、计费、使用情况审查、回退控制或团队级治理时，请使用 Flatkey 别名。让该别名映射到一个已验证的提供商模型 ID，并记录负责人。

我可以从旧的提供商指南里复制模型名称吗？

只能作为起点。旧指南可能包含已退役、预览或仅作示例的字符串。请重新检查当前的提供商文档、当前的 Flatkey 目录，以及一次真实的冒烟测试。

模型名称变更评审中应该包含什么？

应包含旧字符串、新字符串、端点系列、base URL、提供商或 Flatkey 别名、负责人、来源文档、冒烟测试响应、使用情况回读、预期成本影响、回退行为和回滚计划。

结论

OpenAI 兼容的模型名称是迁移输入，不是无关细节。在更改生产流量之前，请验证目录、端点系列、别名负责人、版本策略和运行时证据。如果你把这些检查集中在 Flatkey 中，同一份模型名称证据就可以支持工程切换、事故复盘、使用量对账和采购审批。

当你准备好测试时，从一个密钥、一个 base URL、一个端点系列和一个已批准的模型别名开始。这是让 OpenAI 兼容模型名称在生产中变得“无聊”的最快方式。