Model alias

[akshaydeo]

Date	Notes
27th Nov 2025	Spec published
In progress	Feature implementation in progress

Model aliases

We have been receiving a lot of requests to add model aliases similar to LiteLLM. Model aliases are an important abstraction that make it easy to switch underlying models without making a lot of changes in the code that interacts with the gateway.

Based on our experience while building Maxim AI, most real-world use cases quickly outgrow simple 1:1 mappings. To address this, we are extending the concept of aliases to support rule-based alias mappings in addition to static mappings.

The idea is that model aliases will be top-level entities in provider configuration. Users will be able to create and manage aliases directly from the dashboard (and via config.json). Dynamic aliases will be evaluated at runtime based on the incoming request, with nanosecond-level overhead compared to static 1:1 mappings.

Please let us know if you have any suggestions about this approach.

Goals

• Allow applications to decouple their code from concrete model names.
• Support both simple 1:1 alias mappings and advanced, rule-based routing behind an alias.
• Keep alias resolution in-memory and extremely fast, adding negligible overhead.
• Make alias configuration declarative, versionable, and UI-driven (via dashboard).

Core concepts

Static alias

A static alias maps one alias name to a single underlying provider model.

• Example: gpt-4-prod → openai/gpt-4.1-mini
• Behavior is deterministic and does not depend on request context.

Example config:

{
  "aliases": {
    "gpt-4-prod": {
      "type": "static",
      "target": {
        "provider": "openai",
        "model": "gpt-4.1-mini"
      }
    }
  }
}

Dynamic alias

A dynamic alias maps an alias name to a set of rules. At runtime, the first matching rule (or a configured strategy) selects the concrete model.

• Example: chat-default resolves differently based on tenant, use case, or request metadata.
• Useful for gradual rollouts, A/B testing, cost-based routing, or per-tenant overrides.

Example config (illustrative):

{
  "aliases": {
    "chat-default": {
      "type": "dynamic",
      "rules": [
        {
          "name": "Enterprise tenant – premium model",
          "match": "tenant_id == 'acme-enterprise'",
          "target": {
            "provider": "openai",
            "model": "gpt-4.1"
          }
        },
        {
          "name": "Cost-optimized default",
          "match": "fallback == true",
          "target": {
            "provider": "openai",
            "model": "gpt-4.1-mini"
          }
        }
      ]
    }
  }
}

Configuration & precedence

• Aliases are top-level and provider-agnostic; each alias resolves to a (provider, model) pair.
• Name uniqueness: alias names must be unique within a given environment/config.
• Static vs dynamic precedence:
  • If both a static and a dynamic alias are defined with the same name, the behavior will be:
    • Default (recommended): configuration validation fails at startup (no ambiguity).
    • Optionally, this could be made configurable via a flag (static_precedence / dynamic_precedence).
• Multiple rule matches (dynamic):
  • Rules are evaluated in order by default (first match wins).
  • Optionally, a priority field can be added to each rule; if present, rules are sorted by descending priority, then by order.

Rule language & capabilities

Dynamic alias (CEL expressions) rules are evaluated against a request context object. At minimum, the rule engine will support:

Context fields (examples):

• Header values
• Virtual key
• Customer
• Team

Operators (CEL-based):

Rules are expressed using CEL (Common Expression Language), which provides:

• Equality / inequality (==, !=)
• Membership (in, not in)
• Boolean conjunctions (&&, ||, !)
• Comparison operators (<, >, <=, >=)
• String operations (.startsWith(), .endsWith(), .contains(), .matches())
• Ternary conditionals (condition ? true_value : false_value)
• Field access and nested property navigation

Runtime resolution failures

• No matching rule for a dynamic alias:
  • Option 1 (recommended): return a clear ALIAS_RESOLUTION_FAILED error with the alias name.
  • Option 2: allow a default_target inside the alias config that is used as a fallback.
• Alias not found:
  • Return a clear ALIAS_NOT_FOUND error, including the alias name.

All errors should be:

• Logged with enough context (tenant, request id).
• Exposed in traces for debugging.

Observability

Alias resolution should be visible in both logs and traces.

Tracing (OTel / similar):

Add span attributes such as:

• bifrost.alias.name
• bifrost.alias.type (static | dynamic)
• bifrost.alias.rule (for dynamic; rule name/id)
• bifrost.model.provider
• bifrost.model.name

Logging:

Log alias resolution decisions at debug level, including:

• Alias name
• Resolved model
• Rule matched (for dynamic)

Metrics (optional but recommended):

Counters such as:

• alias_resolution_total{alias=...,type=...,status=...}

These help track alias usage and failure patterns.

Performance characteristics

• Alias resolution happens in-process and in-memory.
• Configuration is pre-parsed and compiled where necessary (e.g., rule expressions) at startup or reload time.
• Dynamic aliases use Google's CEL (Common Expression Language) library, which provides the fastest CEL expression execution available.
• Per-request work is limited to:
  • A small number of field lookups on the request context.
  • A small number of boolean evaluations.

Expected overhead:

• Static alias: effectively zero extra work beyond a single table lookup.
• Dynamic alias: nanosecond-level overhead relative to static mapping (no additional network hops or I/O), thanks to Google's highly optimized CEL implementation.

Dashboard UX (high-level)

• A dedicated “Model aliases” section in the provider/gateway configuration:

  • List view of aliases: name, type (static / dynamic), target(s), and basic usage indicators.
  • Create/edit alias flows:
    • Static aliases: select provider and model from dropdowns.
    • Dynamic aliases: add ordered rules, with fields for match conditions and target models.

• Hot reload:

  Alias changes should be applied without restarting nodes (where supported by the config engine).

[larrykoo711]

So, any progress? It's the blocker to replace litellm.

[akshaydeo]

@larrykoo711 yes - we actually changed the scope to cover a bit of routing as well. Should go live by 3rd week of Jan 2026

[kierr]

In the age of Opus 4.6, Codex 5.3, GLM-5, Kimi-2.5 and MiniMax-M2.5, this can't be hard to implement...

For anyone using LiteLLM, it's a must have...

[rmarku]

Any news about this?

[Vincentdu-cn]

Waiting so hard!Make it happen!
Please

[Pratham-Mishra04]

Hello, we are finally picking it up next week first thing🙇🏼‍♂️

[DFP-]

Glad to hear you're looking into this, there's a lot of buzz over litellm alternatives with the recent vulnerability, the main thing I use that for is model aliasing.

[akshaydeo]

This is released already with v1.5.0-prerelease2

[Pratham-Mishra04]

https://docs.getbifrost.ai/providers/aliasing-models