3.2 Modelfile 自定义模型

3.2 Modelfile 自定义模型

本节摘要：Modelfile 是 Ollama 的"模型配方"——几行声明就能在既有基座之上固化系统提示词、采样参数、对话模板甚至外部知识，产出一条随叫随到的私有 tag。本节逐条拆解指令语法，给出从零构建一个"代码评审助手"的完整过程，并说明 ollama create 在底层做了什么、如何迭代与分发。

从一个最小的 Modelfile 开始

假设每周都要让模型用同一套口吻写周报。与其每次粘贴提示词，不如把口吻固化成模型：

# Modelfile：日报助手
FROM qwen2.5:7b
SYSTEM """
你是一个日报写作助手。用户给你今天做的事项列表，
你把它们整理成三段式日报：今日完成、遗留问题、明日计划。
语气克制，每条不超过一行，不使用感叹号。
"""
PARAMETER temperature 0.4
​

保存后两条命令即可拥有私有模型：

ollama create dailyreport -f Modelfile
ollama run dailyreport 修接口bug 开评审会 改部署脚本
​

此后 dailyreport 与官方模型无异：能出现在 ollama list 里，能被 API 以 "model": "dailyreport" 调用，团队其他人拿到这份 Modelfile 也能在各自机器上复刻出完全一致的行为。这就是 Modelfile 的价值——把"提示词工程"的成果沉淀为可版本管理的文本文件。

指令全览：九条指令各管什么

FROM 是唯一必需的指令，指定基座。可以写官方 tag（qwen2.5:7b），可以写本地 GGUF 绝对或相对路径（FROM ./models/qwen-q4km.gguf），甚至可以写另一个自定义模型，实现层叠定制。

SYSTEM 设定系统提示词，即对话中始终排在最前、定义角色身份的那段文字。CLI 里临时改用 /set system，但只有写进 Modelfile 才是永久的。

PARAMETER 逐条设置推理期参数，常用几项：temperature（随机性，事实型任务调低到 0.2-0.4，创意写作调高到 0.8+）、num_ctx（上下文窗口，Ollama 默认 2048，做长文档必须显式调大，代价是 KV 缓存内存随之增长）、top_p 与 top_k（候选词截断）、repeat_penalty（抑制复读）、num_predict（限制最大生成长度，-1 为不限）。

PARAMETER temperature 0.3
PARAMETER num_ctx 8192
PARAMETER repeat_penalty 1.1
PARAMETER num_predict 512
​

TEMPLATE 改写对话模板，控制消息如何拼成模型输入。绝大多数场景直接继承基座模板即可；只有引入未经 Ollama 适配的新 GGUF、对话格式错乱时才需要手写。模板里可用的变量是 {{ .System }}、{{ .Prompt }}、{{ .Messages }} 等，语法与 Go text/template 一致。

ADAPTER 挂载 LoRA 适配器文件（.gguf 格式），基座与适配器的基模型必须一致。MESSAGE 预置示例对话，相当于把 few-shot 样例写死进模型。LICENSE 附许可文本，STOP 等价于 PARAMETER stop。

知识注入：Modelfile 能不能当"数据库"用

把项目规范塞进 SYSTEM 是低成本方案，但要清楚边界：模型上下文有上限，塞 30KB 文档既挤占对话空间，也不见得都能被有效利用。合理做法是分层——少量关键规则进 SYSTEM，大量文档走第 6.1 节的 RAG 检索。介于两者之间的 MESSAGE 示例适合放"输入输出对"：

FROM llama3.1:8b
SYSTEM "你是 SQL 助手，只输出 PostgreSQL 方言的语句，不加解释。"
MESSAGE user 把用户表的过期账号删掉
MESSAGE assistant DELETE FROM users WHERE expired_at < now();
MESSAGE user 统计最近 7 天注册量，按天分组
MESSAGE assistant SELECT date_trunc('day', created_at) d, count(*) FROM users WHERE created_at > now() - interval '7 days' GROUP BY d ORDER BY d;
PARAMETER temperature 0
​

ollama create sqlhelper -f Modelfile
ollama run sqlhelper 查一下库存小于10的商品
​

ollama create 底层做了什么，以及如何迭代

ollama create 读取 Modelfile 后，为 SYSTEM、TEMPLATE 这类新增文本各生成一个 blob（同样以 SHA-256 命名存入 blobs 目录），再写一份新 manifest 引用"基座的权重层 + 新增层"。所以创建几乎是瞬时的，不复制权重文件；对同一个名字反复 create 是安全的覆盖式更新。

调试技巧：ollama show <name> --modelfile 会吐出模型当前生效的完整 Modelfile（包含从基座继承的部分），把它重定向到文件即可作为下一轮修改的起点——这也是研究官方模型提示词写法的捷径：

ollama show sqlhelper --modelfile > Modelfile.v2
# 编辑 Modelfile.v2 后覆盖更新
ollama create sqlhelper -f Modelfile.v2
# 验证系统提示词是否如预期
ollama show sqlhelper --system
​

分发：从单机文件到团队资产

Modelfile 是纯文本，放进 Git 仓库即可随代码走。三种分发形态按重量递增：其一，直接提交 Modelfile + README 说明基座 tag，成员自行 ollama create；其二，基座来自本地 GGUF 时，把 Modelfile 与量化文件一起打包，注意 FROM 写相对路径以免绑死他人目录结构；其三，ollama push 发布到自己在 registry 的命名空间（ollama push <用户名>/sqlhelper），团队 ollama pull 即用——push 要求先 ollama cp <用户名>/sqlhelper 改成带命名空间的全名。

# 发布到个人命名空间
ollama cp sqlhelper yourname/sqlhelper
ollama push yourname/sqlhelper

# 团队成员
ollama pull yourname/sqlhelper
ollama run yourname/sqlhelper
​

一个常被忽略的坑：Modelfile 里的相对路径在 create 时就被解析固化，之后移动 GGUF 文件、删除源文件都不影响已创建的模型（数据已进 blobs）；但反过来，删掉 Modelfile 不会瘦身模型，两者自此互不依赖。

到这一步，模型侧的准备全部就绪。下一章把视角切到"怎么用"：CLI 的进阶技巧与 REST API 的完整能力。