Overview
Model aliasing lets you decouple the model name your application sends from the identifier Bifrost actually uses when calling a provider. You can:- Send
"best-model"and have Bifrost resolve it to whatever model you’ve decided is best - without touching your application code - Map a single logical name like
"gpt-4o"to a provider-specific deployment name, inference profile ARN, or fine-tuned model ID - Give different teams different underlying models behind the same name
Static Aliasing
Static aliasing is available in Bifrost v1.5.0-prerelease2 and above.
How it works
- Your application sends a request with
model: "best-model" - Bifrost selects a key that supports
"best-model"(alias names are treated as model identifiers for key selection and allowlists) - Before calling the provider, Bifrost resolves
"best-model"→"gpt-4o-2024-11-20"using that key’saliasesmap - The provider receives
"gpt-4o-2024-11-20"- your application never needs to know
Configuration
Add analiases object to any key in config.json:
Provider-specific overrides (only set on aliases whose owning key matches the provider; validation rejects mismatches):
Validation rules
Bifrost rejects an aliases map that violates any of these:- No empty strings - both the alias name and
model_idmust be non-empty - No leading or trailing whitespace on either side
- No duplicate alias names (checked case-insensitively) -
"GPT-4o"and"gpt-4o"cannot both be keys in the same map - Valid patterns - a
regex:alias name must compile as RE2, and itsmodel_idandmodel_namemay only reference capture groups the pattern defines (see Pattern aliases) - No provider mismatch on sub-configs - an Azure-specific override (
api_version,endpoint, …) can only appear on an alias whose owning key is an Azure key, and likewise for Vertex / Bedrock / Replicate
Case-insensitive matching
Alias lookup is case-insensitive. If your map has"GPT-4O": "gpt-4o-2024-11-20" and a request comes in with model: "gpt-4o", it resolves correctly. Aliases are stored as-is but matched without regard to case.
Pattern aliases
An alias name that starts withregex: is a pattern. One row then covers every model name that matches, so you do not add a row for each model. The common case is a Bedrock key where every Claude model goes through a global. inference profile:
claude-opus-5 goes to Bedrock as global.anthropic.claude-opus-5. The log row records global.anthropic.claude-opus-5 as the model and claude-opus-5 as the alias. Cost comes from the global.anthropic.claude-opus-5 pricing row.
The pattern is RE2, case-insensitive, and has to match the whole requested model name. That is the same rule regex: entries follow in models and blacklisted_models. In model_id and model_name, $1 or ${1} inserts the first capture group and ${name} inserts a named group (?P<name>...). Write $$ for a literal dollar sign.
To pin one model to a different target, add an exact row next to the pattern. With
"claude-opus-4-8": "us.anthropic.claude-opus-4-8" in the same map, that one name uses the us. profile and every other Claude model still follows the pattern.
Bifrost rejects a pattern that does not compile, an empty pattern, regex:*, and a template that references a capture group the pattern does not define. Watch for $1x. Go reads it as a group named 1x, so write ${1}x.
Pattern aliases and model listing
/v1/models lists what the provider returns, filtered by the key’s models list. Bifrost cannot enumerate the names a pattern could match, so a pattern alias adds nothing to the list and does not rename the entries the provider returns.
For the Bedrock key above, that has a side effect. Bedrock returns anthropic.claude-opus-5, and regex:claude-.* has to match the whole name, so the key lists no Claude models even though a request for claude-opus-5 works. What you see depends on the models list:
If clients pick model names from
/v1/models, make the vendor prefix optional in both the allow list and the pattern:
anthropic.claude-opus-5. Both claude-opus-5 and anthropic.claude-opus-5 go to Bedrock as global.anthropic.claude-opus-5.
Tracking in responses
Every response includes arouting_info block in extra_fields describing the routing decisions Bifrost made:
Each field is also sent as a response header, so SDK routes whose body has no
extra_fields can read it: x-bifrost-routing-info-provider, x-bifrost-routing-info-model, x-bifrost-routing-info-requested-model, and so on; see Response Headers.
When no alias matches, resolved_key_alias is omitted and model carries the wire identifier directly.
extra_fields.provider, extra_fields.original_model_requested, and extra_fields.resolved_model_used are deprecated but still populated for backward compatibility. New consumers should read from routing_info. Despite its name, original_model_requested is the model after routing rules ran; the model the caller sent is routing_info.requested_model.Dynamic Aliasing
Dynamic aliasing uses Routing Rules to rewrite the model at request time based on a CEL expression. Unlike static aliases (which are fixed to a key), dynamic aliases fire conditionally and are scoped - so the same model name can resolve differently depending on who is making the request.How scopes make it dynamic
Routing rules are organized into four scopes, evaluated in priority order:- Global scope aliases
"best-model"→"gpt-4o-mini"(cost-effective default for everyone) - Team scope for the AI team overrides
"best-model"→"claude-3-5-sonnet-20241022"(more capable) - Virtual Key scope for a specific VK overrides
"best-model"→"o1"(highest capability, specific use case)
Example: alias based on request type
model: "embedder" that is an embedding request gets routed to "text-embedding-3-small".
Example: alias with provider switch
Multi-step rewrites with chaining
Settingchain_rule: true on a rule causes Bifrost to re-evaluate the full scope chain with the new provider/model as the new context. This lets you build layered alias resolution where a global rule establishes provider intent and a VK-scoped rule applies the final key selection.
Scenario: All clients send model: "best-model". Premium VKs should get gpt-5 via a high-tier key; standard VKs should get gpt-4.1 via a lower-tier key.
Rule 1 - Global scope (chain_rule: true):
best-model resolves to OpenAI and re-evaluates the scope chain with provider="openai", model="best-model".
Rule 2a - VK scope on premium-vk (chain_rule: false):
standard-vk (chain_rule: false):
premium-vk request:
standard-vk request:
Advanced: Combining Both Layers
Static and dynamic aliasing compose naturally - routing rules fire first (at the HTTP layer), then key-level aliases resolve second (inside the inference worker, after key selection). This lets you separate concerns across two distinct layers:- Routing rules decide which provider and which key tier to use, based on who is making the request
- Key aliases handle the final model identifier forwarded to the provider
Example
Setup: Two OpenAI keys with different tiers, each with their ownbest-model alias:
extra_fields.routing_info for tech-team + premium-vk:
routing_info.model is the model after any routing rule rewrites, and routing_info.requested_model is what the client sent before them. routing_info.resolved_key_alias.model_id is the final identifier that reached the provider API - after both routing and key-level alias resolution. When no key-level alias matches, resolved_key_alias is omitted and the wire model equals routing_info.model.
