Cloudflare AI Gateway 模型别名：用一个名称管理模型池

一个名称指向一组候选模型

Cloudflare 于 2026 年 11 月 4 日为 AI Gateway 发布模型别名。你可以把一组模型放入一个别名，让应用始终请求同一个名称；需要换模型或调整路由时，可在网关里更新配置，不必因此改写应用中的模型名称。

别名属于单个网关。两个网关可以各自创建同名别名，但它们的模型池和路由配置互不相同，所以推理请求必须指向创建别名的网关。别名提供候选选择与回退机制，不保证任一模型、提供方或请求一定成功。

准备认证与计费

先创建 AI Gateway 并开启认证，再为别名中的模型配置可用的提供方密钥，或设置 Unified Billing。通过 REST API 发起推理时，Cloudflare API token 需要 Account > Workers AI > Read 权限；通过 API 管理别名则需要 AI Gateway 权限。这两类权限用途不同。

AI Gateway 面向所有方案开放，定价页列出的核心功能（分析、缓存和速率限制）免费，但这不代表模型推理免费。Unified Billing 购买 credits 会加收 5% 费用，例如购买 100 美元额度会收取 105 美元；提供方推理价格按原价转付、不加价。日志、Guardrails 或 Logpush 等功能可能另行计费，需按账户当前价格确认。

上述定价页没有单独列出模型别名的额外价格，也没有提供逐地区开放清单；这些细节仍需按当前账户条件核对。Enterprise 客户应向账户团队确认合同价格。

在控制台创建别名

在 Cloudflare 控制台打开 AI > AI Gateway，选择目标网关，再进入 Routing 并选择 Create alias。在 Alias name 中填写不带 custom/ 前缀的名称，例如 support-fast；控制台会在列表和实际调用名称中自动显示 custom/。

在 Models 中选择一个模型；如需回退，再添加其他模型并拖动排序。然后选择 Routing algorithm 并创建别名。默认的 preferred 顺序会从上到下尝试目标；smart 会为每次请求选择模型，如果无法为候选模型排序，网关会回到默认顺序。单次请求的 options.routing 可以覆盖别名保存的算法。

选择目标时要确认模型支持请求使用的协议和输入格式；别名不会把不同模型的格式变成通用格式。更改模型或路由后，配置传播可能需要时间，部分请求在刷新期间仍可能使用缓存配置。重命名会改变应用必须提交的别名名称。

从 REST API 调用别名

推理请求发送到 Cloudflare REST API 的 /client/v4/accounts/{account_id}/ai/run。请求体的 model 填 custom/support-fast，并提供该模型接受的 input；同时设置 cf-aig-gateway-id 标头，值为创建别名的网关 ID。少了正确的网关标识，请求就无法按预期查找该网关下的别名。 使用标准 Authorization 标头，以 Bearer 方式传入 Cloudflare API token，并将 Content-Type 设为 application/json。

网关只会在符合请求协议并通过网关检查的模型与提供方中选择；某次尝试失败时，可能继续尝试其他合格目标。路由不会绕过认证、计费或网关策略。先用实际请求格式核对候选模型；不要把“已配置回退”理解成服务成功承诺。

用 API 管理完整配置

别名管理接口位于 /client/v4/accounts/{account_id}/ai-gateway/gateways/{gateway_id}/model_aliases：可用 GET 列表或读取单项，用 POST 创建、PUT 替换、DELETE 删除。POST 和 PUT 中的 name 不带 custom/ 前缀；配置包含模型列表，也可以为每个模型指定 providers。 读取、替换或删除单个别名时，在该路径后加 /{alias_id}；列表与创建使用集合路径。

providers 列表会限制该模型可用的提供方，并按所列顺序设置优先级；省略 providers 时，网关可使用该模型已登记的提供方。提供方限制通过 API 配置，控制台编辑器只选择模型。PUT 会替换整份配置，需一并提交要保留的所有模型和提供方限制；省略 routing、或把它设为 null 或空对象，会清除已保存的路由偏好。

检查名称、数量与错误响应

每个网关最多可有 100 个别名，每个别名包含 1 到 50 个模型条目。名称在所属网关内唯一，长度为 1 到 64 个字符，只能使用小写字母、数字，以及单个点号、下划线或连字符作为分隔；例如 support-fast 有效，Support Fast、support--fast 和 support- 无效。

收到 404 且提示 Model not found，表示所选网关没有该名称的别名；核对网关 ID、别名拼写和 custom/ 前缀。

收到 400 且提示 has no available models，表示没有目标解析为可用且协议兼容的模型；检查模型 ID 和提供方限制。

收到 503 且提示 Model aliases are temporarily unavailable，表示网关暂时无法读取配置，可以重试请求；来源未给出重试必成功或恢复时限保证。