Conversion

The convert/ package turns raw checkpoints (safetensors, sentencepiece, pickle/torch) into the GGUF format Ollama stores and serves.

Purpose

Let users ollama create a model from a Hugging Face download or a fine-tuning artifact without first running an external converter. The package supports a long list of architectures and is one of the busiest areas of the repo to update.

Directory layout

convert/
├── convert.go                # entry point: detect architecture and dispatch
├── reader.go                 # generic checkpoint reader interface
├── reader_safetensors.go     # safetensors loader
├── reader_torch.go           # pickle/torch loader
├── tensor.go                 # tensor metadata + manipulation
├── tokenizer.go              # tokenizer extraction
├── tokenizer_spm.go          # sentencepiece-specific tokenizer code
├── sentencepiece/            # generated sentencepiece protobuf
├── sentencepiece_model.proto # source schema
├── json_compat.go            # tolerant JSON parsing for HF configs
├── convert_<arch>.go         # one per architecture: gemma, gemma2, gemma3,
│                              gemma3n, gemma4, llama, llama4, mistral,
│                              mixtral, qwen2, qwen3, qwen3vl, qwen3next,
│                              qwen25vl, deepseek2, deepseekocr, glm4moelite,
│                              glmocr, gptoss, lfm2, lfm2_vl, mllama,
│                              mistral_causal, nemotron_h, nomicbert, olmo,
│                              phi3, commandr, bert, llama_adapter,
│                              gemma2_adapter, laguna
└── testdata/                 # golden inputs and expected outputs

Key abstractions

Symbol	Location	Purpose
Convert	convert/convert.go	Top-level conversion entry. Reads the source config, picks a per-arch implementation, invokes it, writes GGUF.
ModelArch interface	convert/convert.go	What every convert_<arch>.go implements: tensor mapping, GGUF metadata, vocabulary handling.
Reader	convert/reader.go	Generic checkpoint reader.
tokenizer package	convert/tokenizer.go, convert/tokenizer_spm.go	Extracts tokenizer from tokenizer.json / tokenizer.model / sentencepiece protobufs into the Ollama vocabulary.

How it works

graph TD
    Source[safetensors / torch / sentencepiece] --> Reader
    Reader --> Detect[detect architecture from config.json]
    Detect --> ArchImpl[convert_<arch>.ModelArch]
    ArchImpl --> TensorMap[map tensor names + dtypes]
    TensorMap --> Tokenizer[tokenizer extraction]
    Tokenizer --> Metadata[GGUF metadata]
    Metadata --> Writer[GGUF writer in fs/gguf]
    Writer --> Output[gemma3.gguf]

Convert reads config.json, switches on architectures[0], and constructs the matching ModelArch. The arch implementation knows how to:

• Map source tensor names to GGUF tensor names.
• Reshape or split tensors (e.g., GLM models split QKV; Llama3 swaps RoPE bases).
• Set the GGUF metadata fields (head count, layer count, RoPE base, vocab size, BOS/EOS tokens).
• Re-quantize when the user requested a non-source quantization level — see server/quantization.go for the server-side companion.

Adding an architecture

1. Implement convert_<name>.go mirroring an existing one (convert_gemma.go is a clean template). Add a unit test under convert_<name>_test.go with a tiny golden checkpoint in testdata/.
2. Register the architecture in convert.go's switch.
3. If the prompt format isn't standard, also add a renderer / parser under model/renderers/ / model/parsers/.
4. Add the architecture to model/models/<name>/ if you want it to run on ollamarunner.

Integration points

• Called by ollama create and by x/create/ for the experimental safetensors path.
• Writes through fs/gguf/.
• Outputs feed storage and registry.

Entry points for modification

• New tensor name remap or quantization tweak → the per-arch file.
• New tokenizer source → extend tokenizer.go and tokenizer_spm.go.
• New checkpoint format → extend reader.go with a sibling reader.

Key source files

File	Purpose
convert/convert.go	Entry point, architecture dispatch.
convert/reader_safetensors.go	Safetensors loader.
convert/reader_torch.go	Pickle / torch loader.
convert/tokenizer.go	Tokenizer extraction.
convert/convert_gemma.go, convert/convert_llama.go, …	Per-arch implementations.
convert/testdata/	Golden fixtures used by convert_*_test.go.