Visible model aliases for discoverability

[moschroe]

Config aliases should be visible, so that they can be discovered by downstream API users.

With overlapping APIs unifying, a simple alias like "Quality Medium" could be served by vllm, ollama and any other compatible backend, without users having to change their config and or having to hard-code the model.

I am running an implementation of this locally (done by claude code), could offer a PR if interested. But this is invasive and touches tens of files.

[thushan]

Hey, thanks for raising this and for the offer to PR it, much appreciated.

Wanted to map out the current state first so we're on the same page, because there are actually two alias systems in play and I want to make sure we're solving the right gap:

1. User-configured model_aliases (in config.yaml that came in implementation(PR-98): model aliases #99 ) - maps a virtual name to specific backend model names. These resolve at request time in the proxy handler, but they're invisible everywhere else. A downstream client has no way to discover them. This sounds like the core of what you're after.
2. Auto-discovered unification aliases (UnifiedModel.Aliases) - the native names the unifier merges when the same model shows up across backends. These are exposed on /olla/models, but they're raw backend names, not the human-friendly virtual name
   you're describing.

So the premise is spot on - config aliases exist for routing but aren't discoverable. Before we get into implementation though, a few things I'd love to clarify since the answers change the shape of this quite a bit:

• Which concept are you after? Your "Quality Medium" example reads like a semantic tier that fans out across backends, which is a bigger abstraction than the existing name-to-name model_aliases. Are we making the existing aliases visible, or introducing a new tier/capability-style alias?
• First-class model, or metadata? Should an alias show up as its own entry in the model list (so GET /v1/models returns an id: "Quality Medium" that's directly routable), or just as an aliases: [...] field decorating the real models? The former is what actually saves clients from hard-coding, the latter is cheaper but they still have to pick a real model.
• Which endpoints? Happy to surface these on the Olla-native /olla/models, but the OpenAI-compat (/olla/proxy/v1/models) and Anthropic (/olla/anthropic/v1/models) listings have rigid schemas. Exposing aliases there means either non-standard fields or
  synthetic model entries, so I'd want to know whether spec-compliance or discoverability wins for those.

One thing that'll come up regardless: collision/precedence when an alias name clashes with a real backend model name, and what happens if the alias resolves to a backend that's currently down. Worth thinking about early.

On the PR - given you mentioned it's invasive and touches tens of files, let's land on the answers above first so we don't burn effort in the wrong direction. Keen to see what you've got either way.

On a side note, I'm considering redoing a proper olla API in #155.

[moschroe]

The design I chose is that "User-configured model_aliases" are the same and just become visible as virtual models. This is the adapted docs/content/concepts/model-aliases.md from my experiment:

Listing Visibility

By default, configured aliases are surfaced as first-class entries in the model listings so OpenAI-shape clients (e.g. Open-WebUI) can populate their model dropdowns with the virtual names:

• GET /olla/proxy/v1/models — alias name appears as a data[].id entry.
• GET /olla/ollama/api/tags — alias name appears as a models[].name entry with representative metadata copied from the chosen target.
• GET /olla/models/<alias> — returns an alias-aware response shape with kind: "alias", the canonical selected_target_id, and an alias_targets array enumerating every underlying model.

The representative target for tags metadata is chosen deterministically: highest endpoint priority wins, with the least capable model breaking ties (fewer parameters → more compressed quantisation → fewer capabilities → lexicographic ID). The displayed metadata is therefore the lower bound a client can rely on across the alias's routing pool.

Aliases whose targets are not currently discovered (orphans) are hidden — they only appear when at least one target is reachable.

Disabling alias visibility

Visibility is governed by model_registry.expose_config_aliases. The default is true. Set to false to keep aliases invisible in listings while routing continues to work transparently:

model_registry:
  expose_config_aliases: false

This is useful when you only want aliases as a routing convenience and not as discoverable model names.

Alias chains are rejected at startup

Aliases must be flat. Each target must be either:

• a real model name (not another alias key), or
• the alias's own name (self-target — extends the alias's routing pool to include a model that also goes by the alias name on at least one backend).

Cycles (A: [B]; B: [A]), alias-of-alias chains (A: [B]; B: [real]), and other indirect references are rejected at config load with a descriptive error naming both keys.

The key is that the resolution for the virtual model is done the same way dispatch resolution works, so there is no logic drift and the output is deterministic.

To be honest, I never tested anything but openai/ollama APIs as others are not in use for the foreseeable time.

Regarding level of abstraction, this is highly individual, but it makes sense to not spread backend models too widely. For example, "medium" could be gemma4-26B 16bit on vllm and gemma4-26B Q8 on ollama, but an 8B model should be a "simple" or "small".

[bongiozzo]

Hi

We use Olla for cluster of 4 omlxs on Apple silicon hardware - https://github.com/shared-goals/thunder-forge
Another idea is to manage cluster via agent (kinda Hermes)

Models on nodes are configured in tfconfig.yaml and managed through fast fabric Thunderbolt 5 interface.

Compromise and KISS solution with visible aliases (before implementing API) is to generate configs for Opencode or Hermes with comments )

make target with arg of user/apikey outputs and copies it to clipboard )
For opencode and custom sticky headers we need such cli config option anyway.

make opencode shag
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "thunder-forge": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Thunder Forge",
      "options": {
        "baseURL": "http://thunder-forge:40116/v1",
        // TF_USER_SHAG: check .env
        "apiKey": ""
      },
      "models": {
        // mlx-community/Qwen3.6-35B-A3B-4bit; disk_gb: 20.5
        "agent": {
          "name": "agent",
          "limit": {
            "context": 262144,
            "output": 8192
          },
          "headers": {
            "X-Olla-Session-ID": "agent-shag"
          }
        },
        // mlx-community/Qwen3.6-35B-A3B-mxfp8; disk_gb: 36.6
        "agent-better": {
          "name": "agent-better",
          "limit": {
            "context": 262144,
            "output": 8192
          },
          "headers": {
            "X-Olla-Session-ID": "agent-better-shag"
          }
        },
        // mlx-community/Qwen3-Coder-Next-4bit; disk_gb: 44.8
        "coder": {
          "name": "coder",
          "limit": {
            "context": 262144,
            "output": 8192
          },
          "headers": {
            "X-Olla-Session-ID": "coder-shag"
          }
        },
        // mlx-community/Qwen3-Coder-Next-mxfp8; disk_gb: 82.2
        "coder-better": {
          "name": "coder-better",
          "limit": {
            "context": 262144,
            "output": 8192
          },
          "headers": {
            "X-Olla-Session-ID": "coder-better-shag"
          }
        },
        // mlx-community/gpt-oss-20b-mxfp4-bf16; disk_gb: 13.0
        "memory": {
          "name": "memory",
          "limit": {
            "context": 131072,
            "output": 8192
          },
          "headers": {
            "X-Olla-Session-ID": "memory-shag"
          }
        }
      }
    }
  }
}

[ccsmart]

I too was just about to request showing configuration file user defined aliases like normal models alongside backend models. I'd even go as far as adding another configuration item that allows to hide any backend name that is provided by any alias and not an alias itself and / or a manual list of model names to hide.

Some clients, eg openwebui, kind of even require this as they populate their model selection that way. So currently i wouldnt be able to use such an alias if it doesnt happen to be the same as a real backend name.

[thushan]

Good feedback, I'm going to wrap up v0.0.28 soon in the next day or so and will focus on this and the API next for v0.0.29.

[moschroe]

I'd even go as far as adding another configuration item that allows to hide any backend name that is provided by any alias and not an alias itself and / or a manual list of model names to hide.

This essentially ties configuration aliases into the planned "Global Model Filtering".

In my mind, filters should be available upstream as well as downstream, so that each back-end can be filtered, but the front-end as well. Then, including only configured aliases would take care of hiding everything else.

That leads to a more fundamental aspect of this, for which I created a separate issue, due to scope: #177

[ccsmart]

the filtering might have themed toggles then, such as "filter any aliased model" or "filter all backend models".
it might be very reasonable to basically never just forward backend model names automatically.