Implementation:Ollama Ollama Server Aliases

Knowledge Sources	Ollama
Domains	Model Management, Server Configuration
Last Updated	2025-02-15 00:00 GMT

Overview

Implements the persistent alias store for model name aliasing, supporting both exact-match and prefix-based model name resolution with cycle detection and atomic file persistence.

Description

The store struct holds two alias collections: entries (a map for exact model name matches) and prefixEntries (a sorted slice for longest-prefix-first matching). Aliases are persisted to a server.json file in the Ollama config directory, with atomic file writes (write to temp file, then rename) for crash safety. ResolveName resolves a model name through aliases with cycle detection (max 10 hops), checking exact matches first then prefix matches. Set creates or updates an alias with cycle detection. Delete/DeleteByString remove aliases. List returns all aliases. The save logic preserves unknown fields in the JSON config to avoid clobbering settings managed by other components.

Usage

Used by the alias route handlers (routes_aliases.go) and by the model resolution logic throughout the server to translate user-specified model names to their actual targets.

Code Reference

Source Location

• Repository: Ollama
• File: server/aliases.go
• Lines: 1-438

Signature

type aliasEntry struct {
    Alias          string `json:"alias"`
    Target         string `json:"target"`
    PrefixMatching bool   `json:"prefix_matching,omitempty"`
}

type store struct {
    entries       map[string]aliasEntry
    prefixEntries []aliasEntry
    configPath    string
}

func createStore(configPath string) (*store, error)
func (s *store) ResolveName(name model.Name) model.Name
func (s *store) Set(alias, target model.Name, prefix bool) error
func (s *store) Delete(alias model.Name) (bool, error)
func (s *store) DeleteByString(alias string) (bool, error)
func (s *store) List() []aliasEntry

Import

import "github.com/ollama/ollama/server"

I/O Contract

Inputs

Name	Type	Required	Description
configPath	string	Yes	Path to the server.json configuration file
alias	model.Name	Yes	The alias name to create, resolve, or delete
target	model.Name	Yes	The target model name that the alias points to
prefix	bool	No	Whether this is a prefix-matching alias

Outputs

Name	Type	Description
resolved	model.Name	Resolved model name after following alias chain
[]aliasEntry	slice	List of all configured aliases
deleted	bool	Whether the delete operation found and removed the alias
error	error	errAliasCycle if a cycle is detected, or I/O errors

Usage Examples

// Create an alias store
store, err := createStore("/path/to/server.json")

// Set an alias
err = store.Set(
    model.ParseName("my-model"),
    model.ParseName("llama3:latest"),
    false,
)

// Resolve a model name through aliases
resolved := store.ResolveName(model.ParseName("my-model"))
// resolved = "llama3:latest"

// List all aliases
aliases := store.List()

Related Pages

• Principle:Ollama_Ollama_Model_Alias_Resolution