Ollama 命令完整手册

本章节介绍 Ollama 相关执行命令，内容覆盖安装、模型管理、运行参数、Modelfile、REST API、环境变量与常见排障，均基于 Ollama 0.17.x 整理。

---

安装与启动

三平台各有标准安装方式，安装完成后 Ollama 会自动作为后台服务运行，监听 127.0.0.1:11434。

平台	安装方式	说明
macOS	brew install ollama	也可从官网下载 dmg 安装包
Linux	curl -fsSL https://ollama.com/install.sh	sh
Windows	官网下载安装包	按向导安装，自动注册为系统服务
Docker	docker run -d -v ollama:/root/.ollama -p 11434:11434 ollama/ollama	数据卷 ollama 持久化保存模型

绝大多数场景下不需要手动启动服务，但排障和临时改配置时会用到 ollama serve。

实例

# 前台启动服务，日志直接打印到终端，排障时最常用

ollama serve

# 验证服务是否就绪：返回 "Ollama is running" 即正常

curl http://localhost:11434

如果提示端口被占用，说明后台服务已在运行。此时另开一个终端执行 ollama serve 会报错，属正常现象，直接使用命令行或 API 即可。

---

模型管理命令全表

模型管理是 Ollama 命令行的主体，共十个左右，全部列在下面这张表里。

命令	功能	示例
ollama pull <model>	从模型库下载模型，不写 tag 默认拉取 latest	ollama pull qwen3.5:4b
ollama run <model>	交互式运行模型，本地没有会自动 pull	ollama run qwen3.5
ollama list / ollama ls	列出本地模型、大小与修改时间	ollama list
ollama show <model>	查看模型详情：参数、模板、系统提示等	ollama show qwen3.5
ollama ps	查看已加载到内存的模型及剩余存活时间	ollama ps
ollama stop <model>	立即停止并卸载正在运行的模型	ollama stop qwen3.5
ollama cp <src> <dst>	复制或重命名模型	ollama cp qwen3.5 runoob-clone
ollama rm <model>	删除本地模型，释放磁盘空间	ollama rm qwen3.5:0.8b
ollama create <name> -f <file>	基于 Modelfile 创建自定义模型	ollama create runoob-coder -f Modelfile
ollama push <model>	把模型推送到远程模型库，需先登录	ollama push myteam/runoob-coder
ollama serve	启动后台服务，一般随系统自动运行	ollama serve

日常使用频率最高的组合是 run、list、ps、rm 四个：跑模型、盘库存、看内存、清空间。

实例

# 下载指定规格的模型

ollama pull qwen3.5:0.8b

# 复制一份改个自己的名字

ollama cp qwen3.5 runoob-clone

# 确认复制成功后，删除不再需要的规格

ollama rm qwen3.5:0.8b

rm 删除的是该标签对应的模型文件，若有其他标签共用同一份底层权重（blobs），磁盘空间要等最后一个引用它的标签被删除后才会真正释放。

---

run 命令与交互模式

run 既能当一次性问答工具，也能进入多轮对话的交互模式，还支持运行时改参数。

命令行参数

参数写在模型名后面，只对本次运行生效，不会写入模型配置。

实例

# 交互式对话

ollama run qwen3.5

# 单次问答：提示词跟在模型名后，回答完自动退出

ollama run qwen3.5 "用一句话介绍 runoob 菜鸟教程"

# 显示 token 统计：总耗时、每秒 token 数等性能指标

ollama run qwen3.5 --verbose

# 强制模型以 JSON 格式输出

ollama run qwen3.5 --format json

# 调大上下文窗口（单位为 token）

ollama run qwen3.5 --num-ctx 8192

# 尽可能多地把模型层放进 GPU（999 表示不设限）

ollama run qwen3.5 --num-gpu 999

交互模式内的斜杠命令

进入交互模式后，以斜杠开头的命令用来调整会话状态，这些调整只对当前会话生效。

命令	功能
/set parameter <name> <value>	临时调整推理参数，如 temperature
/set system <prompt>	临时设置 system 提示词
/show info	显示当前模型信息
/show modelfile	显示当前模型对应的 Modelfile
/save <name>	把当前会话的设置保存为新模型
/load <name>	加载已保存的模型或会话
/clear	清空当前对话上下文，重新开始
/bye	退出交互模式

斜杠命令调好的参数想长期保留，用 /save 存成新模型，背后就是帮你生成了一份 Modelfile。

退出交互模式的另一个快捷方式是按 Ctrl+D，效果与 /bye 相同。

---

Modelfile 自定义模型

Modelfile 用一套类 Dockerfile 的语法，把"基础模型 + 参数 + 系统提示"打包成一个新模型。

实例

# 文件路径：Modelfile

# FROM 指定基础模型（必填），也可以是本地 GGUF 文件路径

FROM qwen3.5

# 常用推理参数（可选）

PARAMETER temperature 0.2

PARAMETER num_ctx 8192

# 系统提示词，决定模型的角色与行为（可选）

SYSTEM 你是一名资深 Python 工程师，输出简洁、带类型标注、可测试的代码。

实例

# 用 Modelfile 构建新模型

ollama create runoob-coder -f Modelfile

# 像普通模型一样运行

ollama run runoob-coder "写一个快速排序，含测试"

导入本地 GGUF 权重只需要把 FROM 指向文件路径，常用于运行开源社区下载的模型文件。

实例

# 文件路径：Modelfile

# FROM 指向本地 GGUF 权重文件

FROM ./model-file.gguf

Modelfile 全部指令见下表，前三行是最常用的组合。

指令	作用	是否必填
FROM	指定基础模型或 GGUF 文件路径	必填
PARAMETER	设置推理参数：temperature、num_ctx、top_p、stop 等	可选
SYSTEM	设置系统提示词	可选
TEMPLATE	自定义对话提示模板	可选
ADAPTER	加载 LoRA 适配器	可选
MESSAGE	预置对话示例，实现 few-shot 引导	可选
LICENSE	声明模型许可证	可选

想基于现有模型改造又不想从零写，先执行 ollama show --modelfile 模型名 导出完整配方，改完再 create 即可。

---

REST API 速查

Ollama 服务启动后默认监听 http://localhost:11434，所有 CLI 能做的事 API 都能做。

端点	方法	功能
/api/generate	POST	单轮文本生成，默认流式返回
/api/chat	POST	多轮对话，按 messages 数组传入历史
/api/embed	POST	生成文本向量嵌入，供 RAG 检索使用
/api/tags	GET	列出本地模型，对应 ollama list
/api/show	POST	查看模型详情，对应 ollama show
/api/pull	POST	拉取模型，对应 ollama pull
/api/delete	DELETE	删除模型，对应 ollama rm

实例

# 单轮生成（流式）

curl http://localhost:11434/api/generate -d '{

  "model": "qwen3.5",

  "prompt": "用 Python 写一个 Hello World"

}'

# 多轮对话

curl http://localhost:11434/api/chat -d '{

  "model": "qwen3.5",

  "messages": [{"role": "user", "content": "解释一下什么是 REST API"}]

}'

# 生成向量嵌入

curl http://localhost:11434/api/embed -d '{

  "model": "nomic-embed-text",

  "input": "你的文本内容"

}'

# 列出本地模型

curl http://localhost:11434/api/tags

# 查看模型详情

curl http://localhost:11434/api/show -d '{"model": "qwen3.5"}'

# 删除模型

curl -X DELETE http://localhost:11434/api/delete -d '{"model": "qwen3.5"}'

OpenAI 兼容接口

Ollama 提供 OpenAI 兼容端点 /v1/chat/completions，现有 OpenAI 生态的代码把 base_url 指向本地就能直接用。

实例

# 文件路径：openai_compat.py

from openai import OpenAI

# base_url 指向本地 Ollama；api_key 任意非空字符串即可

client = OpenAI(base_url="http://localhost:11434/v1", api_key="ollama")

resp = client.chat.completions.create(

    model="qwen3.5",  # 本地已下载的模型名

    messages=[{"role": "user", "content": "你好，请介绍一下 runoob"}],

)

print(resp.choices[0].message.content)

$ python3 openai_compat.py
你好！runoob（菜鸟教程）是一个面向初学者的编程学习网站，提供大量免费的基础技术教程。

---

环境变量速查

环境变量是配置 Ollama 服务行为的主要方式，改完需要重启服务才生效。

变量	说明	默认值
OLLAMA_HOST	服务监听地址，0.0.0.0 表示允许局域网访问	127.0.0.1:11434
OLLAMA_MODELS	模型存储路径，换大盘时常用	~/.ollama/models
OLLAMA_NUM_GPU	放进 GPU 的模型层数，999 表示全部	自动
OLLAMA_NUM_PARALLEL	同一模型并发的请求数	自动
OLLAMA_MAX_LOADED_MODELS	同时驻留内存的最大模型数	自动
OLLAMA_FLASH_ATTENTION	启用 Flash Attention，长上下文时建议开启	关闭
OLLAMA_KEEP_ALIVE	模型闲置多久后从内存卸载	5m
OLLAMA_DEBUG	开启调试日志，输出更详细的运行信息	关闭

实例

# 允许局域网访问 + 模型挪到数据盘

export OLLAMA_HOST=0.0.0.0:11434

export OLLAMA_MODELS=/data/ollama-models

ollama serve

OLLAMA_KEEP_ALIVE 设为 0 表示每次请求后立即卸载模型，省内存但每次请求都要重新加载；想常驻就设为 -1。该值的写法随版本有差异，以 ollama serve --help 与官方文档为准。

---

常见问题排查

遇到异常先对照下表定位，大部分问题属于"模型名不对、服务没起来、资源不够"三类。

问题	排查思路
显存 / 内存不足（OOM）	换更小的模型规格或更低量化精度，如用 4b 代替 9b
提示 model not found	检查模型名与 tag 是否正确，标签用冒号分隔，如 qwen3.5:4b 而非 qwen3.5-4b
connection refused	确认服务是否在运行，检查 11434 端口是否被占用
响应速度慢	用 ollama ps 查看 PROCESSOR 列，确认模型是否真的跑在 GPU 上；适当调小 num_ctx
多版本模型混淆	不写 tag 时会按内部规则挑"最新"版本，建议始终显式指定完整标签

---

一句话速查表

最后把最高频的命令压缩成一张表，复制即用。

命令	功能
ollama pull <model>	下载模型
ollama run <model>	运行模型 / 进入交互对话
ollama list	查看已下载的模型
ollama show <model>	查看模型详情
ollama ps	查看正在运行的模型
ollama stop <model>	停止并卸载模型
ollama rm <model>	删除模型
ollama cp <old> <new>	复制 / 重命名模型
ollama create <name> -f Modelfile	用 Modelfile 创建自定义模型
ollama serve	启动服务

Ollama 更新较快，个别参数与命令行为可能随版本调整，动手前以 ollama --help 及官方文档为准。

AI 思考中...

Ollama 版本升级与迁移