Principle:Ollama Ollama Model Alias API
| Knowledge Sources | |
|---|---|
| Domains | API Design, Name Resolution |
| Last Updated | 2025-02-15 00:00 GMT |
Overview
The Model Alias API provides HTTP endpoints for creating, listing, and managing alternative names (aliases) for existing models, enabling users to reference models by convenient short names or semantic labels without duplicating model data on disk.
Core Concepts
Alias as Symbolic Reference
A model alias is a symbolic name that points to an existing model manifest. Unlike a copy, an alias shares the same underlying blob data and manifest as the target model. This means creating an alias is instantaneous and consumes negligible additional storage. Aliases function similarly to symbolic links in a filesystem, providing an alternative path to the same underlying resource.
API Endpoints
The alias system exposes dedicated REST endpoints for alias management. A POST endpoint creates a new alias by associating a name with an existing model. A GET endpoint lists all defined aliases. A DELETE endpoint removes an alias without affecting the underlying model. These endpoints integrate with the existing model management API and follow the same authentication and authorization patterns.
Name Collision Handling
When a user creates an alias that conflicts with an existing model name or another alias, the system must resolve the conflict. The API enforces clear semantics: creating an alias with the same name as an existing alias overwrites the previous alias target, while attempting to alias over a real model name produces an error to prevent accidental shadowing of primary model references.
Implementation Notes
The alias API routes are defined in server/routes_aliases.go with supporting logic in server/aliases.go. Aliases are stored as lightweight manifest entries in the model store that reference the same blob digests as the target model. The alias resolution integrates with the broader model name resolution pipeline so that aliases are transparently resolved during inference requests.