模型

本指南将介绍如何创建调用方发送给 AISIX 的模型别名，并说明单目标模型、多目标模型和集成模型如何进入请求链路。

模型会把面向调用方的模型别名连接到 AISIX 应调用的上游目标。单目标模型通过一个服务提供方密钥指向一个上游模型；多目标模型指向多个目标模型别名，并让 AISIX 在请求时选择其中一个；集成模型会把聊天请求扇出到多个 panel 模型，再让 judge 模型综合生成最终答案。

建议先从单目标模型开始。当调用方需要用一个稳定名称承载故障转移、轮询或加权目标选择时，再创建多目标模型。当调用方需要基于多个模型响应获得一个综合答案时，再创建集成模型。

准备工作

请先准备以下内容：

一个 Admin 监听器可用的自托管网关。
网关 config.yaml 中的 Admin Key。
上游凭证对应的服务提供方密钥 ID。如果还没有，请先配置服务提供方凭证。

创建单目标模型

单目标模型会把一个 AISIX 模型别名映射到一个上游模型。

使用准备好的服务提供方密钥 ID 创建单目标模型：

export AISIX_ADMIN_KEY="admin-local-only-change-me"
export PROVIDER_KEY_ID="YOUR_PROVIDER_KEY_ID"

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/models" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "gpt-4o-prod",
    "provider": "openai",
    "model_name": "gpt-4o",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }'

你应该会看到类似下面的响应：

{
  "id": "677c847f-d92d-4f0e-b445-8b449764f06a",
  "value": {
    "display_name": "gpt-4o-prod",
    "provider": "openai",
    "model_name": "gpt-4o",
    "provider_key_id": "YOUR_PROVIDER_KEY_ID"
  },
  "revision": 1
}

如果后续需要更新、查看或删除该模型，请复制高亮的 id。

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

创建多目标模型

当一个面向调用方的别名需要从多个目标模型中选择时，多目标模型会很有用。它使用 routing 配置块，而不是直接保存自己的服务提供方密钥或上游模型名称。

请先创建目标模型，然后创建多目标模型，并通过 display_name 引用这些目标别名：

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/models" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "chat-prod",
    "routing": {
      "strategy": "failover",
      "targets": [
        {"model": "gpt-4o-primary"},
        {"model": "gpt-4o-secondary"}
      ],
      "retries": 1,
      "max_fallbacks": 1,
      "retry_on_429": true
    }
  }'

你应该会看到类似下面的响应：

{
  "id": "134c4b01-09e6-41b7-97c7-f4e9a608f4c2",
  "value": {
    "display_name": "chat-prod",
    "routing": {
      "strategy": "failover",
      "targets": [
        {
          "model": "gpt-4o-primary"
        },
        {
          "model": "gpt-4o-secondary"
        }
      ],
      "retries": 1,
      "max_fallbacks": 1,
      "retry_on_429": true
    }
  },
  "revision": 1
}

如果后续需要更新、查看或删除该多目标模型，请复制高亮的 id。

根据网关选择第一个目标的方式来选择策略：

策略	适用场景
`failover`	一个目标是主目标，后续目标作为备用。
`round_robin`	多个相似目标需要简单分发请求。
`weighted`	不同目标需要接收不同比例的流量。

第一个目标选定后，后续故障转移仍会按目标顺序进行。详细路由行为请参见路由与故障转移。

创建集成模型

集成模型会使用其它直接模型别名作为 panel 成员和 judge。它不同于多目标模型，不会为请求只选择一个目标，而是调用多个 panel 成员，在成功响应数量满足 min_responses 后，再调用 judge 模型综合生成最终答案。

请先创建直接的 panel 和 judge 模型，然后创建集成模型，并通过 display_name 引用这些别名：

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/models" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "research-ensemble",
    "ensemble": {
      "panel": [
        {"model": "gpt-4o-primary", "temperature": 0.2},
        {"model": "claude-sonnet-primary", "temperature": 0.4}
      ],
      "judge": {
        "model": "gpt-4o-judge"
      },
      "min_responses": 2,
      "timeout_ms": 45000
    }
  }'

panel 条目引用直接模型别名。可选的 temperature 和 seed 会覆盖该 panel 调用中的调用方请求值。judge.model 也引用直接模型别名；当默认综合提示词不合适时，可以包含 synthesis_prompt。

省略 min_responses 时，AISIX 最多要求两个成功的 panel 响应，并受 panel 数量限制。timeout_ms 会作用于每个 panel 调用和 judge 调用。集成模型支持 Chat Completions 请求，包括流式请求。

配置可选模型行为

大多数模型只需要面向调用方的别名、服务提供方标签、上游模型名称和服务提供方密钥 ID。只有当某个行为属于你的流量计划时，才需要添加可选字段。

常见可选字段包括：

timeout：当服务提供方请求需要更严格的单请求超时时使用。
stream_timeout：当流式请求需要单独的分块读取超时时使用。
allowed_cidrs：当只有特定客户端 IP 网段的调用方可以使用该模型别名时使用。
background_model_check：当 AISIX 需要在请求链路外探测单目标模型，并在探测失败后标记为不健康时使用。
cooldown：当真实请求失败后，需要临时将单目标模型从路由中排除时使用。
rate_limit：当限流需要跟随某个模型别名时使用。详情参见限流。

多目标模型会使用所选目标模型的服务提供方设置、超时、健康状态和冷却行为。集成模型在调用直接模型时，会使用 panel 和 judge 模型自身的设置。服务提供方设置、健康检查和冷却行为应配置在被引用的直接模型上，而不是多目标或集成别名上。

allowed_cidrs 作用于调用方指定的模型别名。除非配置了 proxy.real_ip 以信任来自负载均衡器或入口网关的转发头，否则 AISIX 会从直接连接的对端解析客户端 IP。

成本元数据

当用量报告或预算检查需要模型别名的价格元数据时，可以使用 cost。该字段记录每 1,000 个 token 的输入和输出成本，单位为美元；它不会影响服务提供方路由或访问控制。

创建或更新代表计费上游模型的模型别名时，可以添加 cost 对象：

{
  "display_name": "gpt-4o-prod",
  "provider": "openai",
  "model_name": "gpt-4o",
  "provider_key_id": "PROVIDER_KEY_ID",
  "cost": {
    "input_per_1k": 0.0025,
    "output_per_1k": 0.01
  }
}

验证调用方可见性

创建或修改模型后，请同时验证 Admin 资源和调用方可见的代理行为。

使用允许访问该别名的调用方 API Key，通过代理列出模型：

export AISIX_API_KEY="YOUR_CALLER_API_KEY"

curl -sS "http://127.0.0.1:3000/v1/models" \
  -H "Authorization: Bearer ${AISIX_API_KEY}"

GET /v1/models 会列出该调用方 API Key 有权访问的单目标和集成模型别名。多目标别名会刻意从这个发现响应中隐藏，即使调用方知道别名后仍然可以直接指定它们。

下一步

你已经配置了面向调用方的模型别名。继续阅读调用方 API Key，允许调用方使用该别名。

完整的模型请求字段、响应结构和状态路由，请参见 Admin API 参考。

准备工作​

创建单目标模型​

创建多目标模型​

创建集成模型​

配置可选模型行为​

成本元数据​

验证调用方可见性​

下一步​