Kenhuang Academy
  • English

      • Modelfile

      A Modelfile is Ollama’s model blueprint: pin a system prompt, sampling parameters, and context length on top of existing weights, then ollama create a new local name. The CLI, native API, and OpenAI-compatible layer all use that name—you do not paste a long system string in every client.

      Instructions are case-insensitive; docs use uppercase for readability. Order does not matter; put FROM first by convention.

      Minimal example

      FROM gemma4
PARAMETER temperature 0.7
PARAMETER num_ctx 8192
SYSTEM """You are a teaching assistant. Be concise. If you are unsure, say you do not know."""

      Save as Modelfile (extension optional) and, in that directory:

      ollama create kenhuang-tutor -f Modelfile
ollama run kenhuang-tutor

      The official CLI also accepts ollama create -f Modelfile without a name (see current --help). Inspect the expanded file for an existing model:

      ollama show --modelfile gemma4

      The dumped FROM often points at a blob hash, plus the stock TEMPLATE and stop tokens. When you customize, set FROM to a human tag (FROM gemma4:latest) instead of copying the blob path unless you intend to pin that exact blob.

      FROM (required)

      FROM gemma4
FROM gemma4:latest
FROM ./my-model.gguf
FROM /abs/path/to/weights-dir
      SourceNotes
      Library nameMost common; references a model you already pulled
      .ggufPath relative to the Modelfile or absolute
      Safetensors directorySome architectures only (Llama / Mistral / Gemma / Phi3, …—see the official table)

      For GGUF from Hugging Face, check license and chat template first. Background: Hugging Face tutorial.

      SYSTEM

      This becomes the template’s system message—persona and hard rules:

      SYSTEM """You are a senior Python reviewer. Comment on correctness and readability only. Do not rewrite the whole file."""

      A later API system field or messages[role=system] may override or stack depending on the template. Put stable rules in the Modelfile; keep the request for the actual task.

      PARAMETER

      PARAMETER <name> <value>. Common ones:

      ParameterRoleExample
      temperatureHigher is more random (default ~0.8)temperature 0.3
      num_ctxContext window in tokensnum_ctx 8192
      num_predictMax new tokens (-1 unbounded)num_predict 512
      top_p / top_k / min_pNucleus and candidate cutoffstop_p 0.9
      seedReproducibilityseed 42
      stopStop string; repeat the instruction for severalstop "User:"
      repeat_penaltyDampen loopsrepeat_penalty 1.1

      The OpenAI layer has no num_ctx field—bake it into a created model. Larger context uses more VRAM (Models).

      MESSAGE, TEMPLATE, and the rest

      MESSAGE user / MESSAGE assistant add few-shot turns. TEMPLATE is a Go template with {{ .System }}, {{ .Prompt }}, {{ .Response }}. Do not casually edit a Library model’s template unless you imported a bare GGUF.

      Also: ADAPTER for LoRA, LICENSE for legal text, REQUIRES for a minimum Ollama version (e.g. 0.14.0).

      FROM gemma4
SYSTEM """Output JSON only. No Markdown fences."""
MESSAGE user What is the capital? country=France
MESSAGE assistant {"country":"France","capital":"Paris"}

      How this shows up in the API

      After ollama create:

      curl http://localhost:11434/api/chat -d '{
  "model": "kenhuang-tutor",
  "messages": [{"role": "user", "content": "What is a Modelfile?"}],
  "stream": false
}'

      /v1/chat/completions with "model": "kenhuang-tutor" works the same. That drifts less than copying a system prompt into every client.

      Practical notes

      • Persona change → create a new name (kenhuang-tutor-v2) so you can roll back.
      • Do not dump a whole manual into SYSTEM; put long knowledge in RAG (Embeddings, LangChain RAG).
      • Factual Q&A likes low temperature (0.1–0.4); brainstorming can go higher.
      • Full instruction list: Modelfile Reference.

      A complete coding-assistant file is in Practical examples.

      Next steps

      评论