模型别名

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

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

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

选择模型形态

AISIX 支持以下分发形态。向量嵌入模型是带有额外向量元数据的直接模型，并非单独的虚拟分发形态。

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

一个模型资源必须只包含一种分发形态：直接模型字段（provider、model_name 和 provider_key_id）、routing 块、semantic 块或 ensemble 块。Admin API 会拒绝混用这些形态的请求体。

准备工作

请先准备以下内容：

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

创建直接模型

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

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

# 请替换为实际值
export AISIX_ADMIN_KEY="YOUR_ADMIN_KEY"
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" \
  --data-binary @- <<EOF
  {
    "display_name": "gpt-4o-prod",
    "provider": "openai",
    "model_name": "gpt-4o",
    "provider_key_id": "${PROVIDER_KEY_ID}"
  }
EOF

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

{
  "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 或部署名称。两者可以相同，也可以不同。

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

为语义路由创建向量嵌入模型

/v1/embeddings 端点可以使用由任何受支持向量嵌入服务提供方支持的直接模型，不要求存在 embedding 块。当语义路由器要使用该直接模型比较请求文本和路由示例时，请添加此块。

使用上游向量嵌入端点返回的向量维度创建模型：

curl -sS -X POST "http://127.0.0.1:3001/admin/v1/models" \
  -H "Authorization: Bearer ${AISIX_ADMIN_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @- <<EOF
  {
    "display_name": "embedding-prod",
    "provider": "openai",
    "model_name": "text-embedding-3-small",
    "provider_key_id": "${PROVIDER_KEY_ID}",
    "embedding": {
      "dimensions": 1536,
      "normalize": true
    }
  }
EOF

❶ dimensions 必须与每个上游向量返回的值数量一致。

❷ normalize 表示端点是否已经返回单位长度向量，默认值为 true。如果应由 AISIX 在语义相似度比较前对向量进行归一化，请将其设为 false。

有关服务提供方支持情况和调用方请求结构，请参阅向量嵌入。

创建路由模型

当一个面向调用方的别名需要从多个目标模型中选择时，路由模型会很有用。它使用 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
    }
  }'

❶ strategy 控制 AISIX 如何排列符合条件的目标。默认策略是 failover，按声明顺序尝试目标。

❷ retries 允许在同一目标上重试一次，默认值为 0。

❸ max_fallbacks 允许尝试后续的一个目标。对于两个目标，默认值同样为 1。

❹ retry_on_429 将上游 429 响应纳入重试和故障转移行为，默认值为 false。

有关负载均衡与基于信号的策略、符合条件的失败条件和尝试次数限制，请参阅路由与故障转移。

创建语义路由器

语义路由器使用一个向量嵌入模型，将最新用户消息与路由示例进行比较。它把请求发送到匹配度最高的直接目标；如果没有路由达到阈值，则发送到默认直接模型。

请先创建向量嵌入模型、默认模型和路由目标，再在 semantic 块中引用它们的 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": "topic-router",
    "semantic": {
      "embedding_model": "embedding-prod",
      "default": "gpt-4o-primary",
      "match": {
        "distance_metric": "cosine",
        "aggregation": "max",
        "threshold": 0.75
      },
      "routes": [
        {
          "name": "legal",
          "target": "claude-sonnet-primary",
          "examples": [
            "Review this contract for liability risk",
            "Explain the indemnity clause in this agreement"
          ],
          "threshold": 0.8
        }
      ]
    }
  }'

每条路由都需要名称、直接目标和至少一个示例。路由级 threshold 会覆盖该路由的共享阈值。向量嵌入模型、默认模型和每个路由目标都必须已经存在。

有关匹配行为、失败处理和阈值调优，请参阅语义路由。

创建合议模型

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

请先创建作为合议成员和评审模型的直接模型，然后创建合议模型，并通过 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 条目通过 display_name 引用直接模型别名。可选的 temperature 和 seed 会覆盖该合议成员调用中的调用方请求值。judge.model 也通过 display_name 引用直接模型别名；当默认综合提示词不合适时，可以包含 synthesis_prompt。

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

配置可选模型行为

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

常见可选字段包括：

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

路由模型使用所选目标的服务提供方设置、超时、健康状态和冷却行为。语义路由器使用所选目标和向量嵌入模型的设置。合议模型使用合议成员和评审模型的设置。服务提供方设置、健康检查和冷却行为应配置在被引用的直接模型上，而不是虚拟模型别名上。

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 允许该别名时，调用方仍可直接指定它。

下一步

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

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

选择模型形态​

准备工作​

创建直接模型​

为语义路由创建向量嵌入模型​

创建路由模型​

创建语义路由器​

创建合议模型​

配置可选模型行为​

成本元数据​

验证调用方可见性​

下一步​