9565db5f94
* feat(config): add model alias field and self-validation Add ModelConfig.Alias (yaml: alias), IsAlias(), and an alias short-circuit at the top of Validate() that rejects self-reference and forbids setting backend/parameters.model on a pure-redirect alias. Assisted-by: Claude:claude-opus-4-8 [Claude Code] Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * feat(config): resolve and validate model alias targets in the loader Assisted-by: Claude:opus-4-8 [Claude Code] Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * feat(middleware): resolve model aliases and stamp requested/served identity Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * feat(modeladmin): reject alias configs with invalid targets on create/edit Validate alias targets at create/swap entry points (ImportModelEndpoint, EditYAML, PatchConfig) so a dangling, chained, or disabled alias target is rejected at save time rather than surfacing as a runtime error. Assisted-by: Claude:opus-4-8 [Claude Code] Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * feat(api): add GET /api/aliases to list model aliases Adds an admin-gated read-only endpoint that lists every model alias config as {name, target} pairs, backed by the loader's existing GetAllModelsConfigs(). Assisted-by: Claude:opus-4.8 [Claude Code] Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * feat(mcp): add set_alias and list_aliases tools Expose model-alias management over the LocalAI Assistant MCP surface: list_aliases (read-only, GET /api/aliases) and set_alias (mutating). SetAlias is swap-first: PATCH /api/models/config-json/:name swaps an existing alias's target (validated, non-destructive) and a 404 falls back to POST /models/import to create a fresh {name, alias} config. The inproc client mirrors this via ConfigService.PatchConfig + a create path modeled on ImportModelEndpoint. Deletion reuses delete_model. Assisted-by: Claude:claude-opus-4 [Claude Code] Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * style(mcp): replace em dashes in alias tool comments Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * feat(config-meta): expose alias as a model-select field Add an 'alias' section to DefaultSections() and an 'alias' field override in DefaultRegistry() so the schema-driven React editor renders the new top-level ModelConfig.Alias field as a model picker in its own section. Assisted-by: Claude:opus-4.8 [Claude Code] Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * feat(ui): add alias template card and Manage alias badge Add an 'Alias / Routing' template to the create-flow gallery that seeds a minimal name + alias config, and a read-only 'alias -> target' badge on the Manage Models tab. The capabilities row payload does not carry the alias field, so the badge resolves targets from GET /api/aliases looked up by name. Assisted-by: Claude:claude-opus-4 [Claude Code] Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs: document model aliases Assisted-by: Claude:claude-opus-4-8 [Claude Code] Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * docs(swagger): regenerate for GET /api/aliases Adds the /api/aliases path and AliasInfo schema generated from the ListAliasesEndpoint annotation. Assisted-by: Claude:claude-opus-4-8 [Claude Code] Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * test(localai): check os.RemoveAll error in aliases_test Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * fix: correct alias conversion docs and advertise /api/aliases in instructions Signed-off-by: Ettore Di Giacinto <mudler@localai.io> * fix(mcp): write alias config 0600 to satisfy gosec G306 The inproc createAlias path wrote the alias YAML with 0644, which gosec flags as a new G306 finding on the PR. The LocalAI process is the sole reader/writer of model configs, so 0600 is correct and keeps the scan clean. Assisted-by: Claude:claude-opus-4-8 [Claude Code] Signed-off-by: Ettore Di Giacinto <mudler@localai.io> --------- Signed-off-by: Ettore Di Giacinto <mudler@localai.io> Co-authored-by: Ettore Di Giacinto <mudler@localai.io>
3.1 KiB
+++ disableToc = false title = "Model Aliases" weight = 24 url = "/features/model-aliases/" +++
A model alias is a model name that redirects all traffic to another
configured model. Declare gpt-4 as an alias of my-llama-3 and every client
calling gpt-4 is served by my-llama-3 with no client reconfiguration: the
clients keep their existing model name while you control what answers them on
the server side.
Declaring an alias
Create a minimal config file in your models directory:
name: gpt-4
alias: my-llama-3
That is the whole config: a name (the alias clients call) and an alias key
(the target that actually serves the request).
Rules and behavior
- The target (
my-llama-3) must be an existing, non-alias, enabled model. You cannot point an alias at a missing model, a disabled model, or another alias (no chains). - Aliases are 1:1. One alias maps to exactly one target.
- The target can be swapped live by editing the config file, calling the API, using the UI, or asking the assistant. No restart is required.
- Both
gpt-4andmy-llama-3appear inGET /v1/models. - Responses echo the requested alias: a call to
gpt-4returnsgpt-4in the responsemodelfield, not the target name. - Usage accounting records both sides: requested
gpt-4, servedmy-llama-3. - Aliases work for every modality (chat, embeddings, audio, images, and so on).
Managing aliases
You can create, swap, and remove aliases from any of the management surfaces.
Web UI
Open Add Model and pick the Alias / Routing template, then set a name and a target. To re-point an existing alias, edit it and change the target.
REST API
- Create:
POST /models/import - Swap the target:
PATCH /api/models/config-json/:name - List all aliases:
GET /api/aliases - Delete:
POST /models/delete/:name
Assistant and MCP
The LocalAI Assistant (and the MCP server) expose the same operations as tools:
set_alias, list_aliases, and delete_model.
{{% notice note %}}
You cannot turn an existing real model into an alias. If you run set_alias
(or PATCH /api/models/config-json/:name) against a name that is already a real,
non-alias model, the request is rejected. An alias is a pure redirect, so it
must not carry a backend or parameters.model; a real model does, and merging
an alias onto it produces an invalid config that validation refuses with
alias config ... must not set backend or parameters.model. This is intentional:
it stops a stray set_alias call from clobbering a model that is serving.
To add an alias, point a new name at the target instead of reusing an existing model's name. Re-pointing an existing alias at a different target is fully supported and is the live-swap path: the alias config has no backend of its own, so swapping its target stays a valid pure redirect. {{% /notice %}}
Limits
Aliases are a static 1:1 redirect. For classifier-based or load-balanced selection across several downstream models, use the intelligent router in the [Middleware]({{%relref "features/middleware" %}}) feature instead.