Model Aliases

Model aliases give callers stable names while AISIX controls how their requests reach upstream models.

Each AISIX model resource defines a caller-facing alias in display_name and the dispatch path behind it. A direct model maps the alias to one upstream model through one provider key. Routing, semantic, and ensemble models are virtual model aliases that resolve to one or more direct models at request time.

Start with direct models for the upstreams AISIX can call. Add a virtual model only when the caller-facing alias needs target selection or response synthesis.

Choose a Model Shape

AISIX supports the following dispatch shapes. An embedding model is a direct model with additional vector metadata, not a separate virtual dispatch shape.

Model shape	How AISIX handles a request	Use when
Direct	Calls one upstream model through one provider key.	The alias has one upstream destination.
Direct with `embedding`	Calls an embedding-capable upstream and records vector metadata for semantic comparisons.	A semantic router needs an embedding model.
Routing	Selects one direct target by failover, round robin, weights, cost, latency, or load.	One stable alias should distribute traffic or survive target failure.
Semantic	Embeds the latest user message and selects one direct target by meaning.	Different topics should reach different models without caller-side routing.
Ensemble	Calls several direct panel models and asks a direct judge model to synthesize one response.	One answer should incorporate multiple model responses.

A model resource must contain exactly one dispatch shape: the direct fields (provider, model_name, and provider_key_id), a routing block, a semantic block, or an ensemble block. The Admin API rejects payloads that mix these shapes.

Prerequisites

Before starting, prepare the following:

A self-hosted gateway with the admin listener available.
The admin key from the gateway config.yaml.
A provider key ID for each direct upstream. If you do not have one yet, configure Provider Credentials first.

Create a Direct Model

A direct model maps one caller-facing alias to one upstream model.

Create a direct model with the provider key ID you prepared:

# Replace with your values
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

Every successful model creation request returns the created resource in the same response envelope. The following example shows the response for the direct model:

{
  "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
}

Save the highlighted id to update, inspect, or delete the model later. The examples for the other model shapes omit this common response.

The display_name is the name callers send in model. The model_name is the upstream model ID or deployment name AISIX sends to the provider. These values can be the same, but they do not have to be.

On the Dashboard, the Upstream model id field suggests the models that the provider behind the selected provider key publishes in the model catalog, so you do not have to recall an ID by hand. Open the suggestions with the arrow in the field, or type to filter them. The field still accepts any value: enter the ID verbatim for a preview model, a private deployment, or any other model the catalog does not list. A Bring Your Own Endpoint provider key has no catalog entry, so the field stays a plain text input for it.

Create an Embedding Model for Semantic Routing

The /v1/embeddings endpoint can use a direct model backed by any supported embeddings provider; it does not require an embedding block. Add this block when a semantic router will use the direct model to compare request text with route examples.

Create the model with the vector dimensions returned by the upstream embedding endpoint:

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 must match the number of values returned in each upstream vector.

❷ normalize indicates whether the endpoint already returns unit-length vectors and defaults to true. Set it to false when AISIX should normalize the vectors before semantic similarity comparisons.

For provider support and the caller request shape, see Embeddings.

Create a Routing Model

A routing model is useful when one caller-facing alias should select from multiple target models. It uses a routing block instead of storing its own provider key or upstream model name.

Create the direct target models first. Then create the routing model and reference those target aliases by 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 controls how AISIX orders eligible targets. failover is the default and attempts targets in declaration order.

❷ retries allows one retry on the same target. The default is 0.

❸ max_fallbacks allows one later target to be attempted. With two targets, 1 is also the default.

❹ retry_on_429 includes upstream 429 responses in retry and fallback behavior. The default is false.

See Routing and Failover for load-balancing and signal-based strategies, eligible failure conditions, and attempt limits.

Create a Semantic Router

A semantic router uses one embedding model to compare the latest user message with route examples. It sends the request to the best-matching direct target, or to a default direct model when no route reaches its threshold.

Create the embedding model, default model, and route targets first. Then reference their display_name values in the semantic block:

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
        }
      ]
    }
  }'

Each route needs a name, a direct target, and at least one example. A route-level threshold overrides the shared threshold for that route. The embedding model, default model, and every route target must already exist.

For matching behavior, failure handling, and threshold tuning, see Semantic Routing.

Create an Ensemble Model

An ensemble model uses other direct model aliases as panel members and a judge. Unlike a routing model, it does not choose one target for the request. It calls the panel members, keeps enough successful responses to satisfy min_responses, and calls the judge model to synthesize the final answer.

Create the direct panel and judge models first. Then create the ensemble model and reference those aliases by 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
    }
  }'

The panel entries reference direct model aliases by display_name. Optional temperature and seed values override the caller's request for that panel call. The judge.model also references a direct model alias by display_name and can include synthesis_prompt when the default synthesis prompt is not appropriate.

When min_responses is omitted, AISIX requires up to two successful panel responses, capped by the panel size. timeout_ms applies to each panel call and the judge call. Ensemble models are supported on chat-completions requests, including streaming requests.

Configure Optional Model Behavior

A direct model requires a caller-facing display_name alias, provider label, upstream model name, and provider key ID. Add optional fields only when the behavior is part of your traffic plan.

Common optional fields include:

timeout, when a provider request should have a stricter per-request timeout.
stream_timeout, when a streaming request should have a separate per-chunk read timeout.
allowed_cidrs, when only callers from specific client IP ranges should use the model alias.
background_model_check, when AISIX should probe a direct model outside the request path and mark it unhealthy after failed probes.
cooldown, when real request failures should temporarily exclude a direct model from routing.
rate_limit, when the limit should apply to one model alias. For details, see Rate Limits.

Routing models use the selected target's provider settings, timeout, health, and cooldown behavior. Semantic routers use the settings on the selected target and their embedding model. Ensemble models use the settings on their panel and judge models. Configure provider settings, health, and cooldown behavior on the referenced direct models, not on the virtual model alias.

allowed_cidrs applies wherever the model is used, including when it serves as a target of a routing model. A caller outside the ranges cannot reach the model directly or through the routing model. AISIX resolves the client IP from the immediate peer unless proxy.real_ip is configured to trust forwarded headers from your load balancer or ingress.

Cost Metadata

Use cost when usage reporting or budget checks need pricing metadata for the model alias. The field records input and output cost in USD per 1,000 tokens; it does not affect provider routing or access control.

Add the cost object when you create or update the model alias that represents the priced upstream model:

{
  "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
  }
}

Verify Caller Visibility

After creating or changing a model, verify both the admin resource and the caller-visible proxy behavior.

List models through the proxy with a caller API key that is allowed to use the alias:

# Replace with your values
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 lists direct models, including embedding-capable direct models, plus ensemble and semantic-router aliases that the caller API key is authorized to access. Routing model aliases are intentionally hidden from this discovery response, even though callers can target them directly when the alias is allowed on their caller API key.

Next Steps

You have now configured a caller-facing model alias. Continue with Caller API Keys to allow callers to use the alias.

For complete model request fields, response shapes, and status routes, see the Admin API Reference.

Choose a Model Shape​

Prerequisites​

Create a Direct Model​

Create an Embedding Model for Semantic Routing​

Create a Routing Model​

Create a Semantic Router​

Create an Ensemble Model​

Configure Optional Model Behavior​

Cost Metadata​

Verify Caller Visibility​

Next Steps​