Model aliases: names of your own
A model alias is a name of your own that stands for a model string, so code asks for fast and one dictionary decides which provider and model answer.
Last updated: 12 Oct, 2026 · LiteLLM 1.105
Providers and keys: the model string ended with a name LiteLLM could not place. An alias is how you teach it a name. The decision about which model a name means then leaves the calling code, so swapping a model never touches the code that asks.
Calling a name LiteLLM does not know
Before the alias exists, "fast" fails in the way the last lesson showed.
import litellm
litellm.suppress_debug_info = True
try:
litellm.completion(model="fast", messages=[{"role": "user", "content": "hi"}], max_tokens=400)
except litellm.BadRequestError as error:
print(str(error).splitlines()[0])litellm.BadRequestError: LLM Provider NOT provided. Pass in the LLM provider you are trying to call. You passed model=fast
Defining aliases with model_alias_map
litellm.model_alias_map is a dictionary from the name you chose to a real model string. Set it once, near the top of the program.
litellm.model_alias_map = {
"fast": "groq/openai/gpt-oss-20b", # small and quick
"careful": "groq/openai/gpt-oss-120b", # larger
}Calling a model by its alias
The loop below asks for each alias and prints which model the provider reports. The calls say fast and careful, and the real model names appear only in the dictionary.
import litellm
litellm.model_alias_map = {
"fast": "groq/openai/gpt-oss-20b",
"careful": "groq/openai/gpt-oss-120b",
}
for alias in ["fast", "careful"]:
response = litellm.completion(
model=alias,
messages=[{"role": "user", "content": "Name one colour."}],
max_tokens=400,
)
print(alias, "->", response.model, "->", response.choices[0].message.content)
litellm.model_alias_map = {} # clear the aliases againfast -> openai/gpt-oss-20b -> Blue. careful -> openai/gpt-oss-120b -> Blue.
- The reply's
modelfield is the real model. Logs and costs stay truthful while the code keeps sayingfast. - Each alias reached a different model, the 20b for
fastand the 120b forcareful. - Nothing in the calls changed to move between them. Pointing
fastat a different string in the dictionary moves every call that uses it.
Aliases vs the Router and the gateway
| model_alias_map | Router model group | Gateway model name | |
|---|---|---|---|
| Where it lives | A dictionary in one program | A model_list in one program | A configuration file on a server |
| One name can stand for | One model string | Several deployments | Several deployments |
| Shared by many applications | No | No | Yes |
| Taught in | This lesson | Router: model groups and deployments | The LiteLLM proxy |
Where you use aliases
- A cheap and a strong model named
fastandcareful, chosen by the caller by purpose and not by vendor. - A model upgrade done by editing one dictionary entry instead of every call.
- Tests that point an alias at a small model and production at a large one.
Related
- Previous: Providers and keys: the model string
- Next: Streaming: the answer a piece at a time
- Reference: Input params in the LiteLLM docs
- Add a third alias,
"cheap", that points at"gemini/gemini-2.5-flash-lite", and call it. - Point
fastat the 120b model and run the loop again. The code is unchanged and the model is not. - Call
"fast"after the last line clears the map and read the error.
You understood something today that you didn't yesterday.