Ollama Modelfile 配置文件全指南

一、背景认知

1. 什么是 Modelfile

Modelfile 是 Ollama 官方定义的纯文本模型构建蓝图文件，功能和逻辑类比 Docker 的 Dockerfile。它通过标准化的指令，定义了自定义模型的基础底座、行为规则、推理参数、对话格式等全部核心配置，最终通过一条命令构建为可直接运行的 Ollama 本地模型镜像。

一句话核心总结：Modelfile = 基础模型 + 自定义配置 → 一键生成专属可复用 AI 模型，无需每次运行时手动输入大量参数。

2. 核心价值（为什么初学者必须掌握）

固化模型行为 ：一次性写好系统提示、推理参数，永久生效，避免每次ollama run重复配置
一键复现与分发：仅需一个 Modelfile 文件，即可在任何安装 Ollama 的设备上复刻完全一致的模型，团队协作、分享极其方便
全场景自定义：可实现提示词工程、推理性能优化、LoRA 微调权重加载、多模态模型配置、对话格式定制等进阶需求
零代码门槛：纯文本配置，无需 Python / 深度学习基础，初学者也能快速上手
版本化管理：可对模型配置进行迭代、回溯，精准控制模型行为变化

3. 前置条件与环境准备

在开始前，请务必完成以下准备，避免后续操作踩坑：

安装 Ollama ：前往Ollama 官网下载对应系统的安装包，一键完成安装；安装后打开终端（Windows 用 CMD/PowerShell，macOS/Linux 用终端），执行ollama --version，能输出版本号即安装成功
基础模型拉取 ：Modelfile 必须基于一个基础模型构建，初学者建议先拉取轻量、低配置要求的模型，执行ollama pull llama3.2:3b（3B 参数，约 1.6GB，4G 以上内存即可流畅运行）
验证基础环境 ：执行ollama run llama3.2:3b，输入你好，模型能正常回复即环境正常，输入/bye退出对话
工作目录规范 ：新建一个纯英文、无空格的文件夹（如 Windows：D:\OllamaCustomModel，macOS/Linux：~/Documents/OllamaCustomModel），后续所有操作均在该目录下执行，避免中文 / 空格路径导致的识别失败

4. 核心工作原理

Ollama 处理 Modelfile 的核心流程为：

读取 Modelfile 中的指令，校验语法合法性
加载FROM指令指定的基础模型
依次应用系统提示、推理参数、对话模板、适配器等所有配置
将配置与基础模型打包，生成一个全新的本地模型镜像
后续可直接通过ollama run调用该模型，所有配置永久固化

二、核心配置（Modelfile 全指令详解）

1. 基础语法规则（初学者必记）

注释：以#开头，行内#后的内容全部为注释，不执行
指令规范：官方推荐指令全大写 （如FROM、SYSTEM），不区分大小写，但大写更易读
长文本：多行内容用三个双引号"""包裹，支持换行
文件名：默认文件名为Modelfile（无任何后缀名 ），自定义文件名需在构建时用-f指定
执行顺序：指令按文件中从上到下的顺序执行，FROM必须放在文件第一行

2. 必选指令：FROM（模型底座定义）

FROM是 Modelfile 中唯一必填的指令，必须放在文件第一行，用于指定自定义模型的基础底座。

语法与用法

用法场景	语法示例	说明
官方远程模型	`FROM llama3.2:3b`	直接使用 Ollama Hub 上的模型，必须提前用`ollama pull`拉取到本地
本地 GGUF 模型	`FROM ./my-custom-model.gguf`	加载本地下载的 GGUF 格式模型文件，用相对路径 / 绝对路径均可
本地权重目录	`FROM ./safetensors-folder`	加载本地 Safetensors 格式的模型权重目录，支持 Llama、Mistral 等主流架构

初学者必看注意事项

必须锁定模型版本标签：不要写FROM llama3.2（默认 latest 标签，模型更新后行为会变化），必须写全模型名:标签，如FROM llama3.2:3b-instruct-q4_0
基础模型必须提前拉取 / 存在：否则构建时会报错model not found
一个 Modelfile 只能有一个FROM指令，不支持多底座合并

3. 核心行为指令：SYSTEM（系统提示词）

SYSTEM指令用于定义模型的核心人设、行为规则、输出规范、知识库边界，是提示词工程的核心，也是初学者最常用的指令。

语法与示例

复制代码

# 单行写法
SYSTEM "你是一个只说中文的小学生科普老师，回答通俗易懂，不超过3句话。"

# 多行写法（推荐，长提示词更清晰）
SYSTEM """
你是一名资深Java开发工程师，专注于后端开发答疑。
核心规则：
1. 所有代码必须附带详细注释
2. 回答必须先给核心解决方案，再补充原理
3. 禁止回答与Java开发无关的内容
4. 遇到错误代码，先指出问题，再给出修复后的完整代码
"""

注意事项

系统提示词最终会注入到对话模板的{``{ .System }}变量中，若自定义TEMPLATE时未包含该变量，系统提示会失效
多行内容必须用"""包裹，单双引号不能混用

4. 核心推理指令：PARAMETER（运行参数配置）

PARAMETER指令用于调整模型的推理行为、性能、输出效果，是优化模型体验的核心，可多次使用，每行配置一个参数。

下面是初学者必须掌握的高频参数，按使用优先级排序，包含作用、默认值、取值范围、示例、使用场景：

参数名	核心作用	默认值	取值范围	示例	初学者使用建议
`temperature`	温度值，控制回答的创造性 / 随机性。值越低，回答越稳定、严谨；值越高，回答越发散、有创意	0.8	0.0~2.0	`PARAMETER temperature 0.3`	代码 / 科普 / 严谨场景用 0.1~0.4；创作 / 聊天场景用 0.6~1.0；超过 1.5 容易出现乱码
`num_ctx`	上下文窗口大小，单位为 token，决定模型能记住的对话长度 / 文本长度	2048	最大为模型支持的上限	`PARAMETER num_ctx 8192`	长文本 / 多轮对话场景调大，注意：值越大，内存 / 显存占用越高，低配电脑建议 4096 以内
`top_p`	核采样，控制生成的词汇多样性，与 temperature 配合使用，值越低，输出越集中	0.9	0.0~1.0	`PARAMETER top_p 0.85`	严谨场景调低，创作场景调高，一般不与 top_k 同时大幅修改
`repeat_penalty`	重复惩罚，抑制模型生成重复内容，值越高，惩罚越强	1.1	0.0~2.0	`PARAMETER repeat_penalty 1.2`	模型出现重复回答时调高，建议不超过 1.5，否则会导致输出不通顺
`num_predict`	单次生成的最大 token 数，限制模型回答的长度	-1（无限）	正整数 /-1	`PARAMETER num_predict 1024`	避免模型输出过长内容时设置，比如客服场景限制 512token
`stop`	停止词，模型遇到该词汇时立即停止生成，可多次设置	模型默认值	字符串	`PARAMETER stop "###"``PARAMETER stop "<	end_of_text	>"`	自定义输出格式时使用，比如 markdown 输出时设置停止词，避免模型生成多余内容
`num_gpu`	分配给模型的 GPU 层数，控制显卡加速的程度	0（自动）	0~ 模型总层数 / 100	`PARAMETER num_gpu 100`	有独立显卡的设备设置为 100，最大化 GPU 加速；显存不足时调低，比如 50；纯 CPU 运行设置为 0
`seed`	随机数种子，设置固定值后，相同的输入会得到完全相同的输出	0（随机）	整数	`PARAMETER seed 42`	测试 / 需要稳定输出的场景使用，固定 seed 可复现模型回答
`top_k`	限制候选 token 的数量，值越低，输出越保守	40	0~100	`PARAMETER top_k 20`	严谨场景调低，创作场景调高，一般保持默认即可

高频组合示例（初学者可直接复制）

复制代码

# 严谨代码助手参数配置
PARAMETER temperature 0.2
PARAMETER num_ctx 8192
PARAMETER top_p 0.9
PARAMETER repeat_penalty 1.1
PARAMETER num_gpu 100
PARAMETER stop "```"
PARAMETER seed 42

# 日常聊天助手参数配置
PARAMETER temperature 0.8
PARAMETER num_ctx 4096
PARAMETER top_p 0.95
PARAMETER repeat_penalty 1.05
PARAMETER num_predict 2048

5. 对话格式指令：TEMPLATE（提示词模板）

TEMPLATE指令用于定义模型的输入输出对话格式，决定了系统提示、用户输入、模型回复如何拼接成最终的 prompt，适配模型训练时的格式，避免模型输出异常Ollama。

模板基于 Go template 语法，核心内置变量如下：

变量名	作用
{``{ .System }}	对应`SYSTEM`指令定义的系统提示词
{``{ .Prompt }}	对应用户输入的 prompt 内容
{``{ .Response }}	对应模型的回复内容，生成时该变量后的内容会被忽略
{``{ .Messages }}	多轮对话历史，用于多轮对话场景

语法与示例

最简基础模板（初学者首选）

复制代码

TEMPLATE """
{{ if .System }}系统提示：{{ .System }}
{{ end }}用户：{{ .Prompt }}
助手：{{ .Response }}
"""

主流 ChatML 通用模板（适配绝大多数开源模型）

复制代码

TEMPLATE """{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
{{ .Response }}"""

初学者注意事项

不自定义TEMPLATE时，Ollama 会自动使用基础模型的官方默认模板，绝大多数场景无需修改，避免格式错误导致模型输出异常
只有当你需要自定义对话格式、适配微调模型、实现特殊功能时，才需要修改TEMPLATE
若自定义模板，必须确保包含{``{ .Prompt }}和{``{ .Response }}变量，否则用户输入和模型回复会失效

6. 其他进阶指令（基础阶段了解即可）

指令名	核心作用	基础语法示例
`ADAPTER`	加载 (Q) LoRA 微调适配器，将自己微调的 LoRA 权重挂载到基础模型上	`ADAPTER ./my-lora-folder`
`LICENSE`	定义模型的许可证，声明商用 / 分发权限	`LICENSE """MIT License"""`
`MESSAGE`	预设对话历史，通过少样本示例引导模型输出格式	MESSAGE user "Java怎么定义一个类?"``MESSAGE assistant "Java通过class关键字定义类，示例：..."
`PROJECTOR`	多模态模型专用，加载视觉投影层文件，适配 Llava 等图文模型	`PROJECTOR ./mmproj-model-f16.gguf`
`TOOLS`	定义函数调用工具，让模型支持调用外部 API / 工具	`TOOLS """[{"name": "get_weather", ...}]"""`

三、基础实操（从零构建你的第一个自定义模型）

本部分全程无省略步骤，初学者严格按顺序执行，100% 可成功构建。

步骤 1：进入工作目录

打开终端（Windows 用 PowerShell，macOS/Linux 用终端）
执行 cd 命令进入你提前创建的工作目录：
- Windows 示例：cd D:\OllamaCustomModel
- macOS/Linux 示例：cd ~/Documents/OllamaCustomModel
执行后，终端路径会切换到该目录，后续所有操作均在此目录下执行

步骤 2：创建 Modelfile 文件

Windows 系统操作

打开文件夹内的空白处，右键→新建→文本文档
打开该文档，将后面步骤 3 的示例代码复制进去
点击左上角「文件」→「另存为」
- 文件名：Modelfile（必须删除.txt 后缀）
- 保存类型：所有文件
- 编码：UTF-8
- 点击保存，删除原来的新建文本文档
确认：文件名为Modelfile，没有任何后缀，类型为「文件」

macOS/Linux 系统操作

终端在工作目录下，执行vim Modelfile（或nano Modelfile）
按i进入编辑模式，复制后面步骤 3 的示例代码
按Esc，输入:wq回车，保存并退出
执行ls，能看到Modelfile文件即创建成功

步骤 3：编写最简可运行 Modelfile

将以下代码完整复制到你的 Modelfile 文件中，每一行都有注释，初学者可直接使用：

复制代码

# ======================
# 必选：指定基础模型，必须提前用ollama pull llama3.2:3b拉取
# ======================
FROM llama3.2:3b

# ======================
# 核心：定义模型人设与行为规则
# ======================
SYSTEM """
你是一个专属初学者的AI学习助手，专注于解答Ollama相关的问题。
核心规则：
1. 所有回答必须用通俗易懂的中文，避免专业术语，必须举例子
2. 回答必须分步骤，步骤编号清晰，不能省略关键操作
3. 遇到用户报错，先给解决方案，再讲原因
4. 禁止回答与Ollama、AI学习无关的内容
5. 每次回答结尾加一句鼓励的话
"""

# ======================
# 核心：推理参数配置，适配初学者学习场景
# ======================
# 温度调低，回答更稳定，适合教学场景
PARAMETER temperature 0.3
# 上下文窗口设为4096，支持多轮长对话，低配电脑也能跑
PARAMETER num_ctx 4096
# 最大化GPU加速，有显卡的设备自动启用，无显卡不影响
PARAMETER num_gpu 100
# 抑制重复内容，避免模型啰嗦
PARAMETER repeat_penalty 1.1
# 固定随机种子，相同问题得到相同回答，方便学习
PARAMETER seed 42

步骤 4：基于 Modelfile 构建自定义模型

确保终端在 Modelfile 所在的工作目录
执行构建命令，初学者直接复制：
复制代码
```
ollama create my-ollama-helper -f Modelfile
```
命令解释：
- ollama create：固定的模型构建命令
- my-ollama-helper：你自定义的模型名称，全英文小写，可修改
- -f Modelfile：指定 Modelfile 文件路径，若文件名不是默认的，需修改为对应的文件名
构建成功标志：终端输出success，且无报错信息
验证模型是否存在：执行ollama list，能看到你创建的my-ollama-helper模型即构建成功

步骤 5：运行并验证自定义模型

执行运行命令，直接复制：
复制代码
```
ollama run my-ollama-helper
```
进入对话界面后，输入测试问题，验证模型是否符合预期：
- 测试 1：什么是Modelfile？，看模型是否按人设用通俗语言、分步骤讲解
- 测试 2：我构建模型报错model not found怎么办？，看模型是否先给解决方案，再讲原因
若模型完全符合你在 SYSTEM 中定义的规则，说明 Modelfile 配置生效，构建成功
退出对话：输入/bye回车，即可退出模型交互界面

步骤 6：修改与迭代模型

用文本编辑器重新打开 Modelfile 文件，修改你想要调整的内容（比如修改 SYSTEM 人设、调整 temperature 参数）
保存修改后的 Modelfile 文件
重新执行构建命令，直接覆盖原有模型：
复制代码
```
ollama create my-ollama-helper -f Modelfile
```
重新执行ollama run my-ollama-helper，即可验证修改后的效果
不需要的模型可执行ollama rm 模型名删除，释放存储空间

四、高阶用法

掌握基础操作后，可通过以下高阶玩法，实现更专业的模型定制。

1. 自定义对话模板，适配专属对话格式

适用场景：自定义对话角色、适配微调模型、实现固定输出格式。

实操示例：情侣聊天助手专属模板

编写 Modelfile：

复制代码

FROM llama3.2:3b

SYSTEM "你是用户的专属陪伴助手，语气温柔可爱，用叠词，结尾加语气词~"

# 自定义对话模板，固定对话格式
TEMPLATE """
{{ if .System }}【系统提示】{{ .System }}
{{ end }}【男朋友】：{{ .Prompt }}
【女朋友】：{{ .Response }}
"""

PARAMETER temperature 0.9
PARAMETER num_ctx 4096

构建模型：ollama create my-girlfriend -f Modelfile
运行测试：ollama run my-girlfriend，输入今天上班好累啊，看模型是否按模板格式回复

2. 加载本地 GGUF 模型，打造离线专属模型

适用场景：使用网上下载的 GGUF 格式模型，不在 Ollama 官方库中的模型。

实操步骤：

下载 GGUF 格式模型（比如从 Hugging Face 下载），放到 Modelfile 同级目录，命名为my-model.gguf

编写 Modelfile：

复制代码

# 加载本地GGUF模型，相对路径
FROM ./my-model.gguf

SYSTEM "你是一个专业的本地离线AI助手，所有回答均在本地生成，不联网。"

PARAMETER temperature 0.4
PARAMETER num_ctx 8192
PARAMETER num_gpu 100

构建模型：ollama create my-offline-model -f Modelfile
运行验证：ollama run my-offline-model

3. 预设对话历史，实现少样本学习

适用场景：让模型严格按照你指定的格式输出，比如固定的报表格式、代码格式、回答模板。

实操示例：固定 JSON 格式输出

复制代码

FROM llama3.2:3b

SYSTEM "你是一个数据提取助手，用户输入文本后，严格按JSON格式提取关键信息，只输出JSON，不输出其他内容。"

# 预设对话示例，让模型学习输出格式
MESSAGE user "我叫张三，今年25岁，在互联网公司做产品经理，月薪20000元"
MESSAGE assistant {"name": "张三", "age": 25, "job": "产品经理", "salary": 20000}

MESSAGE user "我是李四，30岁，是一名医生，月收入15000元"
MESSAGE assistant {"name": "李四", "age": 30, "job": "医生", "salary": 15000}

PARAMETER temperature 0.1
PARAMETER stop "}"

4. 模型性能深度优化，低配电脑也能跑大模型

低显存 / 内存优化配置方案（初学者可直接复制）

复制代码

FROM llama3.2:3b-instruct-q4_0

# 核心优化参数
# 限制GPU层数，显存不足时调低，比如30，纯CPU设为0
PARAMETER num_gpu 50
# 限制上下文窗口，降低内存占用
PARAMETER num_ctx 2048
# 限制单次生成长度，避免内存溢出
PARAMETER num_predict 512
# 启用CPU线程优化，根据你的CPU核心数设置，比如4核设为4
PARAMETER num_thread 4
# 关闭MMap，减少内存占用（Windows低配电脑推荐）
PARAMETER use_mmap false

5. 模型导出与分发

场景 1：导出为 GGUF 文件，分享给他人

复制代码

# 将自定义模型导出为GGUF格式
ollama save my-ollama-helper ./my-ollama-helper.gguf

场景 2：推送到 Ollama Hub，在线分享

注册 Ollama 账号，在官网创建模型仓库
终端执行ollama login，登录你的账号
构建模型时命名为「用户名 / 模型名」：
复制代码
```
ollama create 你的用户名/my-ollama-helper -f Modelfile
```

推送到 Hub：

复制代码

ollama push 你的用户名/my-ollama-helper

五、拓展建议

1. 初学者最佳学习路径（循序渐进，避免踩坑）

入门阶段（1-2 天） ：只使用FROM+SYSTEM+2 个核心PARAMETER，跑通构建→运行→修改的完整流程，不碰其他进阶指令
进阶阶段（3-7 天） ：逐个测试PARAMETER的核心参数，理解每个参数对模型输出的影响，找到适合自己场景的参数组合
熟练阶段（1-2 周） ：学习TEMPLATE模板的用法，适配不同模型，尝试加载本地 GGUF 模型、预设对话历史
精通阶段（2 周 +）：学习 LoRA 适配器加载、多模态模型配置、函数调用、API 对接，实现生产级应用

2. 生产级最佳实践

版本锁定 ：FROM指令必须指定完整的模型标签，比如llama3.2:3b-instruct-q4_0，绝对不要用latest标签，避免模型更新后行为异常
注释规范：每个指令、每个参数都加注释，方便后续迭代、团队协作和分享
最小化配置：只修改你需要的参数，其他参数保持默认值，避免过度配置导致模型输出异常
路径规范：本地文件一律使用相对路径，不要用绝对路径，方便跨设备、跨系统分享 Modelfile
基准测试：每次修改 Modelfile 后，用固定的 3-5 个测试问题验证模型行为，确保符合预期

3. 高频常见问题与排查方案

常见报错 / 问题	核心原因	解决方案
构建报错`model "xxx" not found`	1. 基础模型名写错；2. 基础模型未提前 pull 到本地	1. 核对模型名和标签，与`ollama list`中的一致；2. 先执行`ollama pull 模型名:标签`，再重新构建
SYSTEM 系统提示不生效	自定义的 TEMPLATE 模板中，没有包含{``{ .System }}变量	在 TEMPLATE 中添加{``{ .System }}变量，或删除自定义 TEMPLATE，使用默认模板
模型运行时内存 / 显存不足，闪退	1. 模型太大，配置不够；2. num_ctx 设置过大；3. num_gpu 设置过高	1. 换更小参数、更高量化级别的模型；2. 调低 num_ctx 到 2048 以内；3. 调低 num_gpu 数值，纯 CPU 运行设为 0
模型回答重复、啰嗦、无限循环	1. temperature 过高；2. repeat_penalty 过低；3. 缺少 stop 停止词	1. 调低 temperature 到 1.0 以内；2. 调高 repeat_penalty 到 1.1-1.2；3. 设置合适的 stop 停止词
Windows 系统 Modelfile 不识别	1. 文件名有.txt 后缀；2. 编码不是 UTF-8；3. 路径有中文 / 空格	1. 重命名文件，删除.txt 后缀；2. 用记事本另存为，编码选 UTF-8；3. 把文件夹移到纯英文路径
模型输出乱码、格式异常	自定义 TEMPLATE 模板格式错误，与模型训练时的格式不匹配	删除自定义 TEMPLATE，使用模型默认模板，或使用官方推荐的 ChatML 模板

4. 进阶学习资源

官方文档 ：Ollama Modelfile 官方参考文档（最权威、最新的指令说明）
中文文档 ：Ollama Modelfile 中文参考
社区资源 ：GitHub awesome-ollama 仓库，包含大量 Modelfile 示例和最佳实践
模型模板：Ollama Hub 上每个模型的详情页，都有官方推荐的 Modelfile 模板和 TEMPLATE 格式

5. 安全与合规提示

注意基础模型的开源许可证，商用前务必确认模型是否允许商用，避免侵权
自定义系统提示时，做好提示词注入防护，避免用户通过特殊输入绕过你的人设规则
本地模型处理敏感数据时，确保不联网、不泄露，保护数据隐私
分享和分发模型时，遵守对应的许可证要求，不得擅自修改、售卖开源模型

Ollama Modelfile 配置文件 全指南

一、背景认知

1. 什么是 Modelfile

2. 核心价值（为什么初学者必须掌握）

3. 前置条件与环境准备

4. 核心工作原理

二、核心配置（Modelfile 全指令详解）

1. 基础语法规则（初学者必记）

2. 必选指令：FROM（模型底座定义）

语法与用法

初学者必看注意事项

3. 核心行为指令：SYSTEM（系统提示词）

语法与示例

注意事项

4. 核心推理指令：PARAMETER（运行参数配置）

高频组合示例（初学者可直接复制）

5. 对话格式指令：TEMPLATE（提示词模板）

语法与示例

最简基础模板（初学者首选）

主流 ChatML 通用模板（适配绝大多数开源模型）

初学者注意事项

6. 其他进阶指令（基础阶段了解即可）

三、基础实操（从零构建你的第一个自定义模型）

步骤 1：进入工作目录

步骤 2：创建 Modelfile 文件

Windows 系统操作

macOS/Linux 系统操作

步骤 3：编写最简可运行 Modelfile

步骤 4：基于 Modelfile 构建自定义模型

步骤 5：运行并验证自定义模型

步骤 6：修改与迭代模型

四、高阶用法

1. 自定义对话模板，适配专属对话格式

实操示例：情侣聊天助手专属模板

2. 加载本地 GGUF 模型，打造离线专属模型

实操步骤：

3. 预设对话历史，实现少样本学习

实操示例：固定 JSON 格式输出

4. 模型性能深度优化，低配电脑也能跑大模型

低显存 / 内存优化配置方案（初学者可直接复制）

5. 模型导出与分发

场景 1：导出为 GGUF 文件，分享给他人

场景 2：推送到 Ollama Hub，在线分享

五、拓展建议

1. 初学者最佳学习路径（循序渐进，避免踩坑）

2. 生产级最佳实践

3. 高频常见问题与排查方案

4. 进阶学习资源

5. 安全与合规提示

Ollama Modelfile 配置文件全指南