LiteLLMLiteLLM 1.105 · Python 3.10+
Dashboard
0%

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.

ExampleAn alias that is not defined yet
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])

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.

python
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.

ExampleAPI keyTwo aliases, two models
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 again
  • The reply's model field is the real model. Logs and costs stay truthful while the code keeps saying fast.
  • Each alias reached a different model, the 20b for fast and the 120b for careful.
  • Nothing in the calls changed to move between them. Pointing fast at a different string in the dictionary moves every call that uses it.

Aliases vs the Router and the gateway

model_alias_mapRouter model groupGateway model name
Where it livesA dictionary in one programA model_list in one programA configuration file on a server
One name can stand forOne model stringSeveral deploymentsSeveral deployments
Shared by many applicationsNoNoYes
Taught inThis lessonRouter: model groups and deploymentsThe LiteLLM proxy

Where you use aliases

  • A cheap and a strong model named fast and careful, 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.
Watch out. The map is a setting of the running program, held in memory. Two processes, or two applications, each need their own copy, and nothing keeps them in step. Sharing one set of names between applications is what the Router and the gateway add.
Try it yourself
  • Add a third alias, "cheap", that points at "gemini/gemini-2.5-flash-lite", and call it.
  • Point fast at 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.