routing
Model Aliases & Hot-Reload
Hot-swap models without code changes
Define semantic aliases like 'fast', 'smart', or 'cheap' and map them to concrete models in config. The gateway watches the config file and reloads on change, so you can migrate models at runtime — your application keeps calling the same alias while the target changes underneath it.
What you get
Everything in the box
- Friendly semantic model names
- Hot-swap models in production
- Zero code changes in the app layer
- Config file watch & live reload
- Pairs with conditional and cost routing
# config.yaml — changed at runtime, no restart
aliases:
fast: groq/llama-3-8b-8192
smart: openai/gpt-4o
cheap: google/gemini-flash-1.5
vision: anthropic/claude-3-5-sonnet
# Application code never changes:
resp, _ := gw.Route(ctx, providers.Request{
Model: "smart", // resolves at the gateway
Messages: messages,
})
When to use it
When to reach for this
Rename models for clarity
Replace opaque model strings in your code with intent-revealing names like fast or smart, so call sites read clearly and never need to change.
Swap out a deprecated model
When a model is retired, repoint its alias to a successor in config — every application that uses the alias migrates at once, with no code change.
Tune the cost/quality tradeoff centrally
Point cheap or smart at whichever model currently offers the right balance, and adjust it from one place as pricing and quality shift.
Migrate with zero downtime
Because config is watched and reloaded at runtime, you can move traffic to a new model without restarting the gateway or redeploying clients.
FAQ
Frequently asked questions
What is a model alias?
A semantic name (like fast, smart, or cheap) mapped in config to a concrete provider/model identifier. Applications call the alias, and the gateway resolves it to the real model at request time.
Do I need to redeploy my application to change which model an alias uses?
No. You edit the alias mapping in config.yaml. Since your application only ever referenced the alias, no application change or redeploy is needed.
How does hot-reload work?
The gateway watches the config file and picks up changes at runtime, so editing an alias takes effect without restarting the gateway.
Can aliases work together with routing rules?
Yes. An alias resolves at the gateway, so it composes with routing — for example, conditional routing can match on a model prefix while the alias keeps your client code stable.
Why use aliases instead of hard-coding model names?
Hard-coded model IDs couple your code to a specific model and force a deploy to change it. Aliases decouple intent from implementation, so model choices become a config decision rather than a code change.
Related features
Feature deep dives
8 Routing Strategies
Choose from eight production-hardened routing strategies shipped out of the box. Switch between them with a single config key — no code changes required.
A/B Testing & Conditional Routing
A/B test routing splits traffic across weighted variants and tags every request with a variant label for downstream analysis, so you can compare quality, latency, and cost between providers on live traffic. Conditional routing complements it with exact-model and model-prefix rules — no client-side changes, no deploys.
Smart Fallbacks & Retries
Fallback routing tries your providers in priority order: on an error or a retryable status code, the gateway moves to the next target with exponential backoff. Pair it with per-target circuit breakers and a single failing provider never takes your AI features down.