mirror of
https://github.com/mudler/LocalAI.git
synced 2026-06-22 15:49:12 -04:00
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>
82 lines
3.1 KiB
Markdown
82 lines
3.1 KiB
Markdown
|
|
+++
|
|
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:
|
|
|
|
```yaml
|
|
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-4` and `my-llama-3` appear in `GET /v1/models`.
|
|
- Responses echo the requested alias: a call to `gpt-4` returns `gpt-4` in the
|
|
response `model` field, not the target name.
|
|
- Usage accounting records both sides: requested `gpt-4`, served `my-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.
|