Principle:Ollama Ollama Model Alias Resolution
| Knowledge Sources | |
|---|---|
| Domains | Name Resolution, Registry |
| Last Updated | 2025-02-15 00:00 GMT |
Overview
Model Alias Resolution is the process of translating a user-provided model name string into a concrete model manifest, handling default tags, registry prefixes, local aliases, and fallback strategies to locate the correct model definition.
Core Concepts
Name Parsing
Model names in Ollama follow a structured format: [registry/][namespace/]model[:tag]. The resolution system parses this string into its constituent components, applying defaults where components are omitted. If no tag is specified, the system defaults to "latest". If no registry is specified, the system defaults to the Ollama registry. This hierarchical naming enables both concise local references and fully qualified remote references.
Manifest Lookup
Once parsed, the name is used to locate a manifest on the local filesystem. The manifest directory structure mirrors the name hierarchy, with directories for registry, namespace, model, and tag. The resolution process walks this directory structure to find the manifest file, which contains the list of blob digests (layers) that comprise the model.
Alias Chain Resolution
A model name may resolve to an alias rather than a direct manifest. The resolution system follows alias chains to find the terminal manifest. To prevent infinite loops, the system imposes a maximum chain depth and raises an error if the limit is exceeded.
Fallback and Error Handling
When a model name cannot be resolved locally, the system can fall back to pulling the model from the remote registry. The resolution pipeline distinguishes between "not found locally" (triggerable auto-pull) and "invalid name" (immediate error) to provide appropriate user feedback and behavior.
Implementation Notes
Name parsing is implemented in the manifest/ package with structured types for model name components. The manifest lookup logic in server/ maps parsed names to filesystem paths under the Ollama model store directory. Alias entries stored alongside regular manifests are resolved transparently during the lookup process, ensuring callers receive the final resolved manifest regardless of whether aliases were traversed.