Ollama 本地大模型完全配置指南：Modelfile 参数与系统环境变量深度解析
在本地部署大语言模型时，Ollama 以其极简的安装体验和出色的性能表现成为众多开发者的首选。然而，要真正发挥模型的全部潜力，仅使用默认配置是远远不够的。本文将系统性地讲解 Ollama 中两大核心配置体系------Modelfile 模型参数 与系统环境变量，帮助你精准调控模型行为、优化推理性能、适配业务场景。
一、Modelfile 概述
Modelfile 是 Ollama 用于定义和定制模型的蓝图文件，类似于 Docker 的 Dockerfile。通过一系列指令，你可以基于基础模型创建定制化版本，调整推理参数、设定系统提示、修改对话模板，甚至加载 LoRA 适配器。
基本格式
# 这是注释
INSTRUCTION arguments注意：Modelfile 指令不区分大小写，惯例使用大写以增强可读性；指令顺序不影响执行结果。
二、Modelfile 核心指令详解
2.1 FROM（必填）
指定构建模型的基础来源，是 Modelfile 中唯一的必填指令。
语法：
FROM <model name>:<tag>三种使用方式：
-
基于现有 Ollama 模型构建
FROM llama3.2
FROM qwen2.5:7b -
基于本地 GGUF 文件构建
FROM ./my-model.gguf
路径可以是绝对路径或相对于 Modelfile 的相对路径。
-
基于 Safetensors 目录构建
FROM ./safetensors-model-dir
支持 Llama、Mistral、Gemma、Phi3 等架构。
2.2 PARAMETER
设置模型运行时的推理参数，是调优模型输出质量和性能的核心手段。每条 PARAMETER 指令设置一个参数。
语法：
PARAMETER <parameter_name> <value>完整参数列表
| 参数名 | 类型 | 默认值 | 详细说明 |
|---|---|---|---|
| num_ctx | int | 2048 | 上下文窗口大小（token 数）。决定模型能"记住"多长的对话历史。值越大，处理长文本能力越强，但显存占用越高。 |
| num_predict | int | -1 | 最大生成 token 数。-1 表示无限制（受上下文窗口约束）。用于控制回复长度，避免模型无限输出。 |
| temperature | float | 0.8 | 采样温度。控制输出随机性：值越高（如 1.5）越有创意但可能胡言乱语；值越低（如 0.1）越确定但可能重复。常用范围 0.1--1.0。 |
| seed | int | 0 | 随机种子。设为固定数值（如 42）可使相同 prompt 产生完全相同的输出，用于结果复现和测试。0 表示完全随机。 |
| top_k | int | 40 | 限制候选 token 数量。仅从概率最高的 K 个 token 中采样。值越小越保守，越大越多样。40 是较平衡的默认值。 |
| top_p | float | 0.9 | 核采样（Nucleus Sampling）。累积概率达到 P 的 token 集合作为候选。0.9 表示只考虑累计概率占 90% 的 token。与 top_k 共同生效。 |
| min_p | float | 0.0 | 最小概率采样。token 概率必须大于「最可能 token 概率 × min_p」才会被考虑。例如 0.05 表示过滤掉概率不足最高 token 5% 的候选。0 表示禁用。 |
| repeat_penalty | float | 1.1 | 重复惩罚强度。值越高越不容易重复，但过高可能导致语句不通顺。1.0 表示禁用惩罚。建议范围 1.0--1.3。 |
| repeat_last_n | int | 64 | 回溯检查重复的 token 数量。0 = 禁用，-1 = 等于 num_ctx。控制模型向后看多长距离来检测重复。 |
| stop | string | --- | 停止序列。模型遇到该字符串时立即终止生成。可多次设置多个停止序列。常用于匹配模型的特殊标记。 |
| mirostat | int | 0 | Mirostat 采样算法。0=禁用，1=Mirostat v1，2=Mirostat v2。通过动态调整困惑度来平衡生成质量与多样性。 |
| mirostat_eta | float | 0.1 | Mirostat 学习率。影响算法对生成反馈的响应速度。值越低调整越慢，值越高响应越快。 |
| mirostat_tau | float | 5.0 | Mirostat 目标熵。控制连贯性与多样性的平衡。值越低输出越聚焦连贯，值越高越多样发散。 |
| num_gpu | int | 自动 | 卸载到 GPU 的层数。macOS 默认为 1（启用 Metal），0 表示纯 CPU 推理，设为 999 通常表示全部层走 GPU。 |
| num_thread | int | 自动 | CPU 推理线程数。建议设为物理核心数（而非超线程数）以获得最佳性能。Ollama 默认自动检测。 |
| draft_num_predict | int | 4 | 推测解码（Speculative Decoding）的草稿 token 数。仅在有草稿模型时生效，设为 0 可禁用推测解码。 |
2.3 TEMPLATE
定义传递给模型的完整提示词模板，决定了系统消息、用户输入和模型回复的组织格式。不同模型有不同的对话模板格式（如 Llama 3 的 <|start_header_id|>、ChatML 的 <|im_start|>）。
语法：
TEMPLATE """
{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
"""模板变量
| 变量 | 说明 |
|---|---|
{``{ .System }} |
系统提示词内容，由 SYSTEM 指令提供 |
{``{ .Prompt }} |
用户输入的提示词 |
{``{ .Response }} |
模型响应的占位符，生成时该变量之后的内容会被截断 |
重要提示 ：模板格式必须与基础模型训练时的格式严格一致，否则模型表现会大幅下降。使用
ollama show --modelfile <model>可查看官方模型的原始模板。
2.4 SYSTEM
设置系统消息，用于定义模型的角色定位、行为规范和输出风格。
语法：
SYSTEM """
你是一名专业的嵌入式开发工程师，精通 C 语言和 AUTOSAR 标准。
回答问题时请给出具体的代码示例和技术细节。
"""系统消息会被注入到 TEMPLATE 的 {``{ .System }} 位置。
2.5 ADAPTER
加载 LoRA / QLoRA 适配器，在基础模型上应用微调权重。适用于领域定制、风格迁移等场景。
语法：
ADAPTER ./my-lora-adapter.safetensors
ADAPTER ./my-lora-adapter.gguf支持 Safetensors 和 GGUF 两种格式的适配器。注意：适配器训练时使用的基础模型必须与 FROM 指定的模型一致，否则行为不可预期。
2.6 LICENSE
声明模型的法律许可证。
语法：
LICENSE """
MIT License
Copyright (c) 2024 Your Name
...
"""2.7 MESSAGE
预设对话历史，通过少样本（Few-shot）方式引导模型按照特定风格回答。
语法：
MESSAGE user 多伦多在加拿大吗？
MESSAGE assistant 是的
MESSAGE user 萨克拉门托在加拿大吗？
MESSAGE assistant 不是可用角色
| 角色 | 说明 |
|---|---|
system |
替代 SYSTEM 指令提供系统消息 |
user |
用户示例提问 |
assistant |
模型示例回答 |
2.8 REQUIRES
指定运行该模型所需的最低 Ollama 版本。
语法：
REQUIRES 0.3.0三、系统环境变量详解
环境变量用于控制 Ollama 服务端的全局行为，包括网络、存储、并发、GPU 调度等。这些变量在 Ollama 服务启动前设置生效。
3.1 服务与网络配置
| 变量名 | 默认值 | 详细说明 |
|---|---|---|
| OLLAMA_HOST | 127.0.0.1:11434 |
API 服务绑定地址与端口。设为 0.0.0.0:11434 可允许局域网访问。注意：直接暴露到公网存在安全风险，需配合反向代理和认证使用。 |
| OLLAMA_ORIGINS | 本地域名集合 | CORS 允许的来源列表，逗号分隔。默认允许 localhost、127.0.0.1、0.0.0.0 及 app://、file://、vscode-webview:// 等协议。设为 * 允许所有来源。 |
| OLLAMA_MODELS | ~/.ollama/models |
模型文件存储目录。Windows 默认为 C:\Users\<用户名>\.ollama\models。建议空间不足时迁移到其他磁盘。 |
3.2 并发与生命周期管理
| 变量名 | 默认值 | 详细说明 |
|---|---|---|
| OLLAMA_KEEP_ALIVE | 5m |
模型在内存中保留的时长。格式支持 300s、5m、1h 等。0 = 请求结束后立即卸载；-1 = 永久驻留内存。频繁使用时建议设为 -1 避免重复加载。 |
| OLLAMA_NUM_PARALLEL | 1 |
单个模型同时处理的并行请求数。提高并发会增加显存占用，单用户场景保持 1 速度最快。 |
| OLLAMA_MAX_LOADED_MODELS | 自动 | 同时加载到内存/显存中的最大模型数量。0 表示自动（每 GPU 约 3 个）。多模型切换频繁时可适当增大。 |
| OLLAMA_MAX_QUEUE | 512 |
请求队列最大长度。服务繁忙时超出队列的请求会被拒绝（返回 503）。高并发场景可适当调大。 |
| OLLAMA_LOAD_TIMEOUT | 5m |
模型加载超时时间。加载超大模型时可能需要延长。 |
| OLLAMA_CONTEXT_LENGTH | 自动 | 全局默认上下文窗口大小。根据显存自动调整：<23GB 显存为 4K，≥23GB 为 32K，≥47GB 为 256K。 |
3.3 GPU 与性能优化
| 变量名 | 默认值 | 详细说明 |
|---|---|---|
| OLLAMA_FLASH_ATTENTION | 自动 | 启用 Flash Attention。支持的 GPU（NVIDIA Ampere 及以上）可减少 20--40% 显存占用并提升推理速度。设 1 强制开启，0 强制关闭。 |
| OLLAMA_KV_CACHE_TYPE | f16 |
KV 缓存量化类型。可选值：f16（半精度，质量最好）、q8_0（8位量化，省显存）、q4_0（4位量化，最省显存）。显存紧张时设为 q8_0 性价比最高。 |
| OLLAMA_GPU_OVERHEAD | 0 |
每块 GPU 预留的显存（字节）。用于给系统和其他程序留出空间。例如预留 2GB 设为 2147483648。 |
| OLLAMA_SCHED_SPREAD | false |
多 GPU 时是否将模型层分散到所有 GPU。设为 1 启用跨卡调度，适合单模型推理利用多卡显存；并行推理多个模型时建议关闭。 |
| CUDA_VISIBLE_DEVICES | 全部 | 指定使用的 NVIDIA GPU，逗号分隔 ID。如 0,1 使用前两张卡，-1 强制纯 CPU。 |
| ROCR_VISIBLE_DEVICES | 全部 | AMD ROCm 平台的 GPU 选择变量。 |
| GGML_VK_VISIBLE_DEVICES | 全部 | Vulkan 后端的 GPU 选择变量，适用于 Intel/AMD 等通用 GPU。 |
3.4 调试与高级选项
| 变量名 | 默认值 | 详细说明 |
|---|---|---|
| OLLAMA_DEBUG | 0 |
日志详细程度。0=INFO，1=DEBUG，2=TRACE。排查问题时设为 1 可输出详细调试信息。 |
| OLLAMA_LLM_LIBRARY | 自动检测 | 手动指定 LLM 后端库路径，绕过自动检测。用于自定义编译或特殊后端场景。 |
| OLLAMA_NOPRUNE | false |
禁用启动时自动清理未使用的模型 blob 文件。设为 1 保留所有文件，避免意外删除。 |
| OLLAMA_NOHISTORY | false |
禁用 CLI 命令历史记录。共享机器或敏感场景下使用，防止 prompt 泄露。 |
| OLLAMA_MULTIUSER_CACHE | false |
启用多用户场景的提示缓存优化。多用户不同 prompt 时可提升缓存命中率。 |
| OLLAMA_AUTH | false |
启用客户端-服务端认证（实验性功能）。 |
| OLLAMA_MAX_TRANSFER_STREAMS | 4 |
拉取/推送 Safetensors 模型时的并行传输流数。 |
四、典型配置示例
4.1 一个完整的 Modelfile 示例
# 基础模型
FROM qwen2.5:7b
# 推理参数调优
PARAMETER temperature 0.7
PARAMETER num_ctx 8192
PARAMETER top_p 0.9
PARAMETER repeat_penalty 1.1
PARAMETER seed 42
# 停止序列（匹配模型对话格式）
PARAMETER stop "<|im_end|>"
PARAMETER stop "<|im_start|>"
# 系统角色设定
SYSTEM """
你是一名资深的汽车电子嵌入式工程师，专注于 BMS 和动力域控制。
请用专业、严谨的技术语言回答问题，必要时给出代码示例。
"""
# 对话模板
TEMPLATE """
{{ if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}{{ if .Prompt }}<|im_start|>user
{{ .Prompt }}<|im_end|>
{{ end }}<|im_start|>assistant
"""
# 最低 Ollama 版本要求
REQUIRES 0.3.04.2 Linux 系统环境变量配置（systemd）
# /etc/systemd/system/ollama.service.d/environment.conf
[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"
Environment="OLLAMA_MODELS=/data/ollama/models"
Environment="OLLAMA_KEEP_ALIVE=-1"
Environment="OLLAMA_FLASH_ATTENTION=1"
Environment="OLLAMA_KV_CACHE_TYPE=q8_0"
Environment="OLLAMA_NUM_PARALLEL=2"
Environment="OLLAMA_MAX_LOADED_MODELS=3"4.3 Windows 常用优化配置
# 设置模型存储路径到 D 盘
[Environment]::SetEnvironmentVariable("OLLAMA_MODELS", "D:\ollama\models", "User")
# 启用 Flash Attention
[Environment]::SetEnvironmentVariable("OLLAMA_FLASH_ATTENTION", "1", "User")
# 模型常驻内存
[Environment]::SetEnvironmentVariable("OLLAMA_KEEP_ALIVE", "-1", "User")五、调优建议与最佳实践
5.1 性能优化方向
- 显存不足时 ：降低
num_ctx、开启OLLAMA_KV_CACHE_TYPE=q8_0、启用 Flash Attention - 追求速度时 ：保持
OLLAMA_NUM_PARALLEL=1、设置OLLAMA_KEEP_ALIVE=-1避免重复加载 - 长文本场景 ：增大
num_ctx，但注意显存线性增长；可配合 KV 量化使用
5.2 输出质量调优
- 创意写作：temperature 0.8--1.2，top_p 0.9--0.95
- 精准问答：temperature 0.1--0.5，top_p 0.5--0.8
- 代码生成：temperature 0.2--0.7，适当提高 repeat_penalty
- 可复现实验：设置固定 seed 值
5.3 注意事项
- Modelfile 中的 PARAMETER 优先级高于全局环境变量
- 修改环境变量后必须重启 Ollama 服务才能生效
- 不同模型架构支持的参数可能略有差异，以官方文档为准
- 生产环境对外暴露 API 时务必增加认证和反向代理层
六、总结
Ollama 的配置体系分为两个层面：Modelfile 控制单个模型的推理行为 ，侧重输出质量与对话格式；环境变量控制 Ollama 服务全局，侧重性能、并发与资源调度。两者配合使用，才能在有限的硬件条件下获得最佳的模型体验。
建议从默认配置开始，根据实际使用场景逐步调整参数，观察响应速度、显存占用和输出质量的变化，找到最适合自己的平衡点。
查看当前模型的原始 Modelfile：
ollama show --modelfile <model-name>查看官方文档：docs.ollama.com