模型别名

模型别名为调用方提供稳定的名称，同时由 AISIX 控制请求如何到达上游模型。

每个 AISIX 模型资源都通过 display_name 定义面向调用方的别名，并定义该别名背后的分发路径。直接模型通过一个服务提供方密钥将别名映射到一个上游模型。路由模型、语义模型和合议模型则是虚拟模型别名，会在请求时解析为一个或多个直接模型。

请先为 AISIX 可以调用的上游创建直接模型。仅当面向调用方的别名需要选择目标或合成响应时，才添加虚拟模型。

选择模型形态

AISIX 支持以下分发形态。选择一种形态即可打开相应的配置说明。向量嵌入模型与直接模型采用相同的分发方式，只是额外包含向量元数据；它不属于虚拟分发形态。

模型形态	AISIX 如何处理请求	适用场景
直接模型	通过一个服务提供方密钥调用一个上游模型。	别名仅有一个上游目标。
向量嵌入模型	调用支持向量嵌入的上游，并记录用于语义比较的向量元数据。	语义路由器需要向量嵌入模型。
路由模型	通过故障转移、轮询、权重、成本、延迟或负载选择一个直接模型目标。	一个稳定别名需要分发流量，或在目标故障时继续服务。
语义模型	对最新的用户消息进行向量嵌入，并根据语义选择一个直接模型目标。	不同主题需要到达不同模型，且调用方不应自行路由。
合议模型	调用多个直接模型作为合议成员，再由一个直接评审模型合成单一响应。	一个回答需要综合多个模型的响应。

一个模型资源只能包含一种分发形态：直接上游字段、routing 块、semantic 块或 ensemble 块。AISIX Cloud 通过资源 ID 引用服务提供方密钥和其他模型；开源 AISIX 网关则通过 display_name 在 resources.yaml 中引用这些资源。两种管理方式都会拒绝混用多种形态的资源。

直接模型将上游模型记录在 model_name 中。即使没有向量嵌入元数据，它也可以处理 /v1/embeddings。只有当模型用于支持语义路由时，才添加 embedding 块；相关配置流程请参阅语义路由。有关受支持的服务提供方和调用方请求格式，请参阅向量嵌入。

准备工作

开始前，请准备以下资源：

• 为模型将使用的每个上游凭据创建一个服务提供方密钥。
• 对于 AISIX Cloud，需要有权访问一个环境、一台已接入的网关，以及具有写权限范围的 Admin Token。服务提供方密钥必须允许目标环境，并且你需要取得其资源 ID。对于本地部署，请按照 AISIX Cloud 快速入门操作。如需申请混合云访问权限，请联系 API7。
• 对于开源 AISIX 网关，需要一台加载了声明式资源文件的网关，且该文件中已包含服务提供方密钥。模型通过该密钥的 display_name 引用它。

创建直接模型

直接模型将一个面向调用方的别名映射到一个上游模型。

AISIX Cloud

导出 AISIX Cloud 连接信息和服务提供方密钥 ID：

# AISIX_CP 是 Admin API 基础 URL；应包含 /api，且末尾不要带斜杠。
# 本地部署快速入门使用 http://localhost:8080/api。
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"
export PROVIDER_KEY_ID="YOUR_PROVIDER_KEY_ID"

使用准备好的服务提供方密钥 ID 创建直接模型：

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "gpt-4o-prod",
    "model_name": "gpt-4o",
    "provider_key_id": "'"$PROVIDER_KEY_ID"'"
  }'

每个成功的模型创建请求都会在同一个响应信封中返回已创建的资源。以下示例展示直接模型的响应：

{
  "model": {
    "id": "677c847f-d92d-4f0e-b445-8b449764f06a",
    "env_id": "YOUR_ENVIRONMENT_ID",
    "kind": "direct",
    "display_name": "gpt-4o-prod",
    "model_name": "gpt-4o",
    "provider_key_id": "YOUR_PROVIDER_KEY_ID",
    "created_at": "2026-06-24T12:18:39Z",
    "updated_at": "2026-06-24T12:18:39Z"
  }
}

复制高亮显示的 id。路由模型、语义模型和合议模型会通过这个 ID 引用其他模型；之后更新、查看或删除模型时也需要使用它。其他模型形态的示例会省略这个通用响应。

display_name 是调用方在 model 中发送的名称。model_name 是 AISIX 发送给服务提供方的上游模型 ID 或部署名称。两者可以相同，也可以不同。上游服务提供方由被引用的服务提供方密钥决定。

在控制台中，上游模型 ID 字段会根据所选服务提供方密钥，建议目录中发布的模型。点击字段中的箭头打开建议列表，或输入内容进行筛选。该字段仍可接受任意值。对于预览模型、私有部署或其他未在目录中列出的模型，请原样输入 ID。自定义模型服务的服务提供方密钥没有目录条目，因此该字段会保持为纯文本输入框。

开源 AISIX 网关

将模型添加到 models 集合，并按名称引用服务提供方密钥：

resources.yaml

models:
  - display_name: gpt-4o-prod
    provider: openai
    model_name: gpt-4o
    provider_key: openai-prod

display_name 仍是调用方在 model 中发送的别名，model_name 则是上游模型 ID。模型条目需要显式声明 provider，并按名称引用服务提供方密钥。验证并重新加载完整资源文件以应用该模型。

使用通配符匹配模型名称

如果模型别名的 display_name 包含一个 *，它就会匹配所有符合该模式的请求模型名称。因此，一个别名便可代理多个上游模型，无需为每个名称分别创建资源。

通配符别名属于直接模型。将 model_name 设置为 * 可把匹配部分转发给上游；也可以使用固定值，将所有匹配请求发送到同一个上游模型。

对于 AISIX Cloud，使用先前准备的服务提供方密钥创建通配符模型：

curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
  -H "Authorization: Bearer $AISIX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "openai/*",
    "provider_key_id": "'"$PROVIDER_KEY_ID"'",
    "model_name": "*"
  }'

使用此别名时，请求 openai/gpt-4o 会使用上游模型 gpt-4o，请求 openai/o3-mini 则使用 o3-mini。精确别名始终优先于通配符别名；如果有多个通配符匹配，则最具体的通配符优先。

把返回的模型 ID 添加到调用方 API Key 的 allowed_models 列表。通配符别名是模式而不是具体模型名称，因此不会出现在 GET /v1/models 中。

对于开源网关，将通配符声明为直接模型，并允许调用方密钥使用其名称：

resources.yaml

models:
  - display_name: openai/*
    provider: openai
    provider_key: openai-prod
    model_name: "*"

api_keys:
  - display_name: wildcard-caller
    key_env: CALLER_API_KEY
    allowed_models:
      - openai/*

配置可选模型行为

大多数直接模型只需要面向调用方的别名、上游模型名称和服务提供方密钥引用。只有当某项行为属于流量方案的一部分时，才添加相应的可选字段。

常用可选字段包括：

• timeout：服务提供方请求需要更严格的单次请求超时时使用。
• stream_timeout：流式请求需要单独的分块读取超时时使用。
• retries：模型在遇到可重试的上游失败后需要重试特定次数时使用。请参阅重试预算。
• allowed_cidrs：只有来自特定客户端 IP 范围的调用方可以使用模型别名时使用。
• background_model_check：AISIX 需要在请求路径之外探测直接模型，并在探测失败后将其标记为不健康时使用。
• cooldown：实际请求失败后需要暂时将直接模型排除在路由之外时使用。
• rate_limit：限流需要应用于单个模型别名时使用。详情请参阅 API Key 与模型限流。

路由模型使用所选目标的服务提供方设置、超时、健康状态和冷却行为。语义路由器使用所选目标及其向量嵌入模型上的设置，并在选路时同样执行目标自身的门禁：调用方 IP 无法访问的路由目标会回落到默认目标，同时清除 x-aisix-route 响应头；路由目标与默认目标都被排除时，返回与直接调用模型相同的 403；处于冷却中或被后台健康检查标记为不健康的目标，会被可用的默认目标顶替。向量嵌入子调用的截止时间依次取路由器的 embedding_timeout_ms、向量嵌入模型自身的 timeout、部署级默认值。语义路由器自身的 retries 也是重试链中的组级槽位，请参阅重试预算。合议模型使用合议成员模型和评审模型上的设置。请在被引用的直接模型上配置服务提供方设置、健康状态和冷却行为，而不要在虚拟模型别名上配置。

无论模型以何种方式被使用，allowed_cidrs 都会生效，包括它作为路由模型目标时。范围之外的调用方既不能直接访问该模型，也不能通过路由模型访问。除非通过 proxy.real_ip 配置信任负载均衡器或 Ingress 转发的请求头，否则 AISIX 会从直接对端解析客户端 IP。

重试预算

retries 表示 AISIX 在遇到可重试的上游失败（例如 5xx 响应或传输错误）后，对一个模型发起的额外尝试次数。它适用于每个代理端点，包括向量嵌入、重排序、音频、图像和透传；无论模型单独使用还是作为路由目标使用，都会生效。

AISIX 按以下优先级为每次尝试确定预算：

来源	适用条件
模型上的 retries	模型设置了该字段。即使该模型作为路由模型的目标，且路由模型也设置了 retries，此处仍优先。
路由模型上的 routing.retries	目标没有设置 retries。它作为组级默认值应用于每个目标。
语义路由器上的 retries	分发的路由目标没有设置 retries，且请求经由语义路由器。路由器顶层的值填充的组级槽位与模型组上的 routing.retries 相同。
网关配置文件中的 upstream.retries	以上均未设置。默认值为 2。请参阅启动配置参考。

将 retries: 0 设为模型的值可关闭重试。无论在哪一层，0 都是显式设置，绝不表示该字段未设置。

以下两条规则仅适用于部署级默认值。无论在模型层还是路由层显式配置的预算，都会始终按所写值应用。

• 存在其他目标。 当路由模型仍有其他目标可尝试且未配置 retries 时，AISIX 会转到下一个目标，而不会重复尝试当前目标。重复请求一个失败的目标只会延迟故障转移，无法改善结果。列表中的最后一个目标无处可转，因此会应用默认值。
• 请求超时。 未显式配置的预算不会消耗在 timeout 上。timeout 是对等待模型时间的主动限制，重复尝试会成倍增加等待时间，通常仍得到相同结果。如果需要在超时后重试，请在模型上配置 retries。无论是否配置重试，超时都会触发到另一个目标的故障转移。

每次重试都会重新发送完整请求体，且 AISIX 的重试发生在服务提供方边缘自身可能进行的重试之外。在高流量模型上提高预算前，请计算合计的上游尝试次数。

在原始透传端点和视频提交调用中，如果服务提供方已经返回响应状态，则非幂等请求绝不会重试。此时响应体丢失或无效意味着操作已在上游提交，重放会造成重复写入。连接或发送阶段的失败仍可在所有端点重试。

成本元数据

成本会影响用量报告、预算检查和 least_cost 路由；不会影响服务提供方路由或访问控制。

在 AISIX Cloud 部署中，控制面会从定价目录和组织级覆盖项中解析单次请求成本。如需为目录尚未覆盖的模型设置价格，请参阅模型定价。

对于开源 AISIX 网关，请通过模型上的 cost 字段在 resources.yaml 中记录成本元数据。该字段以每 1,000 个 Token 的美元价格记录输入和输出成本：

models:
  - display_name: gpt-4o-prod
    provider: openai
    model_name: gpt-4o
    provider_key: openai-prod
    cost:
      input_per_1k: 0.0025
      output_per_1k: 0.01

有关从 resources.yaml 文件运行网关的方法，请参阅开源 AISIX 网关快速入门。

下一步

至此，你已经配置了面向调用方的模型别名。接下来，请参阅调用方 API Key，允许应用使用该别名并通过代理进行验证。