
在 Ollama 中通过 Modelfile 自定义量化模型,可以让你在 Ollama 上运行任何 GGUF 格式的模型,并精确控制量化精度、推理参数和行为模板。本文将手把手教你掌握这一核心技能。
什么是 Modelfile?
Modelfile 是 Ollama 的模型配置文件,类似于 Dockerfile 之于 Docker。它是一个纯文本文件,用来定义:
- 模型文件的位置(
FROM指令) - 推理时的超参数(
temperature、top_p等) - 对话格式模板(
TEMPLATE) - 系统提示词(
SYSTEM) - 量化目标类型(通过
--quantize参数指定)
简单理解:Modelfile 就像一个配方,告诉 Ollama 如何从原始模型文件制作一个可直接运行的模型。
Modelfile 基本语法
Modelfile 的格式非常简单:
# 这是注释
INSTRUCTION arguments
关键特性:
- 指令不区分大小写,但习惯上用大写与参数区分
- 指令可以按任意顺序排列
- 使用
#开头的行作为注释
所有可用指令一览
| 指令 | 必须? | 描述 |
|---|---|---|
| FROM | 是 | 定义使用哪个基础模型 |
| PARAMETER | 否 | 设置模型运行时的参数(温度、上下文长度等) |
| TEMPLATE | 否 | 定义发送给模型的完整提示词模板 |
| SYSTEM | 否 | 指定系统消息(定义模型角色/行为) |
| ADAPTER | 否 | 指定要应用到模型的 (Q)LoRA 适配器 |
| LICENSE | 否 | 指定模型的法律许可协议 |
| MESSAGE | 否 | 预设对话历史,引导模型回答风格 |
| REQUIRES | 否 | 指定运行此模型所需的最低 Ollama 版本 |
考虑文章阅读体验,各指令详细说明放在文章末尾,有兴趣的自行翻阅哦。
准备工作:获取 GGUF 模型文件
在使用 Modelfile 之前,你需要先准备好模型文件。Ollama 推荐使用 GGUF 格式的模型文件,这是 llama.cpp 框架的标准格式,支持多种量化级别。
从哪里获取 GGUF 文件?
- Hugging Face:搜索
[模型名]-GGUF,例如Kimi-K2.5-GGUF - ModelScope(国内):同样搜索带 GGUF 后缀的模型仓库
- 自己转换:如果你有 Safetensors 格式的模型,可以用 llama.cpp 工具链转换
Hugging Face模型库网页地址: https://huggingface.co/models
量化级别选择
在下载时,你会看到多种后缀的 GGUF 文件,它们代表不同的量化精度:
| 量化类型 | 推荐度 | 适用场景 |
|---|---|---|
| Q4_K_M | ⭐⭐⭐⭐⭐ | 首选!性能和体积的最佳平衡 |
| Q5_K_M | ⭐⭐⭐⭐ | 对质量要求更高时选用 |
| Q8_0 | ⭐⭐⭐ | 几乎无损,适合基准测试 |
| Q3_K_M | ⭐⭐ | 内存极度受限时使用 |
| F16 | ⭐ | 原始半精度,仅供转换用 |
核心建议:对于大多数场景,直接下载
Q4_K_M版本的 GGUF 文件,无需再自行量化。
编写 Modelfile:核心指令详解
创建一个文本文件,命名为 Modelfile(无后缀名),内容结构如下:
FROM 指令:指定模型来源
# 方式一:直接引用本地 GGUF 文件路径
FROM /path/to/your/Qwen3.5-9B-Q4_K_M.gguf
# 方式二:引用已存在的 Ollama 模型
FROM qwen3.5:9b
PARAMETER 指令:设置推理参数
控制模型生成文本的行为:
# 温度参数:控制随机性,值越高输出越多样(推荐 0.5-0.9)
PARAMETER temperature 0.7
# Top-p 采样:只考虑概率累积到 p 的词(推荐 0.8-0.95)
PARAMETER top_p 0.9
# 重复惩罚:避免重复相同的词(推荐 1.05-1.1)
PARAMETER repeat_penalty 1.05
# 上下文长度:模型能"记住"的最大 token 数
PARAMETER num_ctx 4096
# 生成的最大 token 数
PARAMETER num_predict 2048
# 停止词:遇到这些词就停止生成
PARAMETER stop "###"
PARAMETER stop "User:"
TEMPLATE 指令:对话格式模板
这是让模型理解"谁在说话"的关键。不同模型的模板格式不同:
# Qwen 系列模板(ChatML 格式)
TEMPLATE """{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
{{ .Response }}<|im_end|>"""
# Llama 系列模板
TEMPLATE """<|start_header_id|>system<|end_header_id|>
{{ .System }}<|eot_id|>
<|start_header_id|>user<|end_header_id|>
{{ .Prompt }}<|eot_id|>
<|start_header_id|>assistant<|end_header_id|>
{{ .Response }}<|eot_id|>"""
SYSTEM 指令:系统提示词
定义模型的角色和行为:
SYSTEM """
你是一个技术专家助手,回答问题时:
1. 优先给出代码示例
2. 解释核心原理
3. 指出常见坑点和最佳实践
"""
完整的 Modelfile 示例
# 模型来源
FROM /path/to/your/Qwen3.5-9B-Q4_K_M.gguf
# 推理参数
PARAMETER temperature 0.7
PARAMETER top_p 0.9
PARAMETER repeat_penalty 1.05
PARAMETER num_ctx 8192
# 对话模板(Qwen ChatML 格式)
TEMPLATE """{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
{{ .Response }}<|im_end|>"""
# 系统提示词
SYSTEM """
你是周树人,笔名鲁迅。你说话的风格:
1. 冷嘲热讽,一针见血,不绕弯子
2. 喜欢用“大约”、“实在”、“罢了”这类词
3. 看到问题就想骂,但骂得有文化
4. 偶尔说“我家门前有两棵树,一棵是枣树,另一棵也是枣树”这种看似废话实则扎心的话
记住:你是来点醒世人的,不是来当老好人的。遇到蠢问题,不妨直说“这问题,大抵是没救的”。
"""
创建模型:两种场景
场景一:直接用 GGUF 创建(无需量化)
如果你已经下载了满意的量化版 GGUF 文件:
# 1. 编写 Modelfile,内容只需一行
FROM /path/to/your/model-q4_k_m.gguf
# 2. 执行创建命令
ollama create my-model -f ./Modelfile
# 3. 运行测试
ollama run my-model
场景二:从 FP16 模型量化创建
如果你只有未量化的 FP16 模型(.gguf 或 .bin 格式),可以在创建时指定量化目标:
# Modelfile 内容
FROM /path/to/your/model-f16.gguf
# 执行创建并量化
ollama create my-quantized-model --quantize q4_K_M -f ./Modelfile
这个过程会:
- 读取 FP16 模型
- 执行指定的量化算法
- 生成新的量化版本模型
⚠️注意:自行量化需要大量临时存储空间。对于 7B 模型,FP16 文件约 14GB,量化过程需要额外同等空间。
实战案例:部署 Qwen3.5-9B
以下是一个完整的实战流程:
Step 1:下载模型文件
# 从 Hugging Face 下载 Q4_K_M 版本
cd ~/models
wget https://huggingface.co/unsloth/Qwen3.5-9B-GGUF/resolve/main/Qwen3.5-9B-Q4_K_M.gguf
Step 2:创建 Modelfile
cat > Modelfile << 'EOF'
FROM /Users/yourname/models/Qwen3.5-9B-Q4_K_M.gguf
PARAMETER temperature 0.7
PARAMETER top_p 0.8
PARAMETER repeat_penalty 1.05
PARAMETER num_ctx 4096
TEMPLATE """{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
{{ .Response }}<|im_end|>"""
SYSTEM """
你是赛博毒舌侠,人送外号“互联网嘴替”。你的风格:
1. 极度不耐烦,但每次吐槽都精准命中要害
2. 开场白通常是“啊对对对”、“行行行”、“你开心就好”
3. 喜欢用括号加内心OS:像这样(翻白眼)(血压升高)(已拉黑)
4. 看谁都是小白,看啥问题都觉得蠢
5. 毒舌归毒舌,话糙理不糙,最后还是会给出正确结论
名句参考:
- “你这问题,但凡看过一行文档都不会问出来。”
- “能问出这种问题,你有考虑过键盘的感受吗?”
- (开始敲木鱼)功德+1,原谅你的无知。
"""
Step 3:创建并运行
ollama create qwen-dushe:latest -f ./Modelfile
ollama run qwen-dushe:latest
Ollama 支持的量化类型
通过 --quantize 参数可用的完整量化类型列表:
| 类型 | 推荐度 | 类型 | 推荐度 |
|---|---|---|---|
q8_0 | ⭐⭐⭐ | q4_K_M | ⭐⭐⭐⭐⭐ |
q6_K | ⭐⭐⭐ | q4_K_S | ⭐⭐⭐ |
q5_K_M | ⭐⭐⭐⭐ | q3_K_L | ⭐⭐ |
q5_K_S | ⭐⭐⭐ | q3_K_M | ⭐⭐ |
q5_0 | ⭐⭐ | q3_K_S | ⭐ |
q5_1 | ⭐⭐ | q2_K | ⭐ |
q4_0 | ⭐⭐ | q4_1 | ⭐ |
q4_1 | ⭐ |
最佳实践:优先使用
q4_K_M。这是官方文档推荐的类型,也是 Ollama 社区的默认标准。
常见问题与调试技巧
问题1:模型不按预期对话格式输出
原因:TEMPLATE 模板与模型训练格式不匹配。
解决:查看模型文档中的"对话模板"说明,常见格式有:
- ChatML(Qwen、Phi-3):
<|im_start|>system\n...<|im_end|> - Llama 3:
<|start_header_id|>user<|end_header_id|> - Mistral:
[INST] ... [/INST]
问题2:创建时报 “file not found”
解决:使用绝对路径指定 FROM 文件路径。
问题3:量化过程磁盘空间不足
解决:
# 检查可用空间
df -h
# 确保至少有模型文件大小 x 2 的剩余空间
问题4:查看模型当前配置
# 查看模型详情
ollama show my-model --modelfile
Modelfile 指令详细说明
FROM 指令
FROM 指令是必选指令,FROM 定义基础模型的来源,有三种使用方式:
方式一:使用 Ollama 现有模型(新手首选)
FROM llama3.2
# 或者指定标签
FROM llama3.2:70b
可用的基础模型见 Ollama 官方模型库 。
方式二:从本地 Safetensors 模型构建
FROM ./my-model-directory
目录需包含受支持架构的 Safetensors 权重文件。
目前支持的架构:
- Llama(Llama 2/3/3.1/3.2)
- Mistral(Mistral 1/2、Mixtral)
- Gemma(Gemma 1/2)
- Phi3
方式三:从本地 GGUF 文件构建
FROM ./ollama-model.gguf
GGUF 文件路径可以是绝对路径或相对于 Modelfile 位置的相对路径。
实用技巧:用
ollama show 模型名称 --modelfile查看已有模型的 Modelfile,可以直接复制拿来改。
PARAMETER 指令(参数调优)
语法
PARAMETER <参数名> <参数值>
完整参数列表
| 参数 | 描述 | 默认值 | 类型 | 示例 |
|---|---|---|---|---|
num_ctx | 上下文窗口大小(能“记住”的 token 数) | 2048 | int | num_ctx 4096 |
temperature | 控制创造性。越高越随机,越低越保守 | 0.8 | float | temperature 0.7 |
top_k | 限制候选词数量。越高越多样,越低越保守 | 40 | int | top_k 40 |
top_p | 核采样阈值,与 top_k 配合使用 | 0.9 | float | top_p 0.9 |
min_p | 最小概率阈值(top_p 的替代方案) | 0.0 | float | min_p 0.05 |
repeat_penalty | 重复惩罚。越高越阻止重复内容 | 1.1 | float | repeat_penalty 1.1 |
repeat_last_n | 回头检查重复的距离。0=禁用,-1=使用 num_ctx | 64 | int | repeat_last_n 64 |
num_predict | 最大生成 token 数。-1=无限 | -1 | int | num_predict 512 |
seed | 随机种子。固定值可使结果可复现 | 0 | int | seed 42 |
stop | 停止词。遇到即停止生成 | — | string | stop "AI assistant:" |
mirostat | Mirostat 采样控制。0=禁用,1=Mirostat,2=Mirostat 2.0 | 0 | int | mirostat 2 |
mirostat_eta | Mirostat 学习率 | 0.1 | float | mirostat_eta 0.1 |
mirostat_tau | Mirostat 平衡连贯性与多样性 | 5.0 | float | mirostat_tau 5.0 |
tfs_z | 尾部自由采样,减少低概率 token 的影响 | 1.0 | float | tfs_z 1.0 |
注意:
stop参数可以多次使用来设置多个停止词,每个stop一行。
TEMPLATE 指令(提示词模板)
TEMPLATE 定义模型的提示词格式——模型要求什么样的输入结构。
语法
TEMPLATE """模板内容"""
模板变量
| 变量 | 含义 |
|---|---|
{{ .System }} | 系统消息(你在 SYSTEM 中设定的内容) |
{{ .Prompt }} | 用户输入的提示词 |
{{ .Response }} | 模型的回复(生成后会忽略此变量之后的内容) |
模板示例(ChatML 格式,用于 Qwen/Phi-3 等模型)
TEMPLATE """{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
"""
不同模型的模板差异
| 模型系列 | 模板格式 | 特殊 token |
|---|---|---|
| Llama 3 | <|start_header_id|>system<|end_header_id|> | <|eot_id|> |
| Qwen / Phi-3 | <|im_start|>system | <|im_end|> |
| Mistral | [INST] / [/INST] | — |
关键提醒:模板必须与模型训练格式匹配,否则模型会输出乱码。你可以用
ollama show 模型名 --modelfile查看官方模型的模板作为参考。
SYSTEM 指令(定义角色行为)
为模型设定系统提示词,定义它的“人格”和行为准则。
SYSTEM """你是一名专业的知识博主,擅长用通俗易懂的语言讲解技术概念。
回答要严谨准确,分点清晰,不使用网络流行语。"""
效果:每次对话模型都会以这套系统提示作为行为指导。
ADAPTER 指令(LoRA 适配器)
应用微调后的 LoRA 适配器到基础模型上。
ADAPTER ./path/to/lora-adapter.safetensors
# 或使用 GGUF 格式的适配器
ADAPTER ./ollama-lora.gguf
重要:基础模型(通过 FROM 指定)必须与适配器微调时的基础模型一致,否则行为不稳定。
支持的 Safetensors 适配器架构:
- Llama(Llama 2/3/3.1)
- Mistral(Mistral 1/2、Mixtral)
- Gemma(Gemma 1/2)
LICENSE 指令
声明模型的使用许可协议。
LICENSE """
MIT License
Copyright (c) 2026 ...
"""
MESSAGE 指令(示例对话)
预设对话历史,引导模型的回答模式和风格。
语法
MESSAGE <role> <message>
有效角色
| 角色 | 说明 |
|---|---|
system | 系统消息(SYSTEM 的替代方式) |
user | 用户的示例问题 |
assistant | 模型的示例回复 |
示例:教模型学会“加拿大城市”问答
MESSAGE user Is Toronto in Canada?
MESSAGE assistant yes
MESSAGE user Is Sacramento in Canada?
MESSAGE assistant no
MESSAGE user Is Ontario in Canada?
MESSAGE assistant yes
效果:模型会学习示例中的问答逻辑,遇到类似问题时给出一致的答案风格。
REQUIRES 指令
声明此模型需要的最低 Ollama 版本。
REQUIRES 0.14.0
总结与最佳实践
推荐工作流
- 新手路线:直接使用 Ollama 官方库的模型(已默认量化)
- 进阶路线:下载预量化的 GGUF → 编写 Modelfile → 创建运行
- 专家路线:从 FP16 自行量化 → 测试不同量化级别 → 选择最优平衡点
核心要点
| 要素 | 建议 |
|---|---|
| 量化类型 | q4_K_M 是最佳平衡点 |
| 模型来源 | 优先用预量化 GGUF,省时省力 |
| Modelfile | 用绝对路径,写清晰注释 |
| 参数调优 | temperature 0.7 + top_p 0.9 起手 |
| 模板格式 | 务必与模型训练格式匹配 |
相关阅读: Ollama量化全指南:3种方法+量化级别参考,普通电脑也能跑大模型
希望这份指南能帮你在 Ollama 上自由部署任何 GGUF 模型。







