Your copilot for local LLM management — safely pull, benchmark, alias, and clean up models with confidence.安全高效管理本地大模型,包括测试大模型的实际运行能力以及各种情况的应对。
---
name: Model Pilot
description: "Your copilot for local LLM management — safely pull, benchmark, alias, and clean up models with confidence."
description_zh: "本地大模型管理副驾驶——安全拉取、测速、别名、清理,全程可控无忧。"
agent_created: true
tags: [ollama, llm, local-models, benchmark, model-management, safety, no-think]
source: "https://clawhub.ai/skills/model-pilot"
---
# Model Pilot — 本地大模型管理技能(安全增强版)
> **语言**:中文(简体) | English version: `SKILL.en.md`
## 用途
本 skill 是 Ollama 本地模型生命周期管理的**操作指南与检查清单**,用于帮助用户安全地完成:
- 拉取新模型
- 记录模型台账
- 进行可复盘 Benchmark
- 创建模型别名
- 创建 no-think / low-think 使用方式
- 扫描脚本中的模型引用
- 清理旧模型
- 处理国内镜像回退和常见故障
触发词:Ollama、拉模型、下载模型、测速、Benchmark、模型对比、模型别名、清理模型、ModelScope、GGUF、no-think、think false、模型台账、模型生命周期。
---
## 0. 安全边界
本 skill 默认遵循"只读优先、确认后修改、破坏性操作单独确认"的原则。
### 默认允许的只读操作
可以直接执行或建议执行:
```bash
ollama list
ollama --version
curl http://localhost:11434/api/version
curl http://localhost:11434/api/tags
pwd
ls
rg "ollama run|MODEL_NAME|model_name|\"model\"|ollama\.chat|ollama\.generate" .
du -sh ~/.ollama/models/
```
### 必须用户确认后才能执行的操作
以下操作涉及下载、复制、创建、删除或修改配置,必须先说明影响,再等待用户确认:
```bash
ollama pull <model>
ollama cp <source_model> <alias>
ollama create <new_model> -f <Modelfile>
ollama rm <model>
brew upgrade ollama
```
### 不应自动执行的操作
除非用户明确要求,不要自动执行:
- 删除模型:`ollama rm`
- 覆盖已有 Modelfile
- 修改 `~/.zshrc`、`~/.bashrc`、`~/.profile`
- 修改系统级环境变量
- 改动 `OLLAMA_CONTEXT_LENGTH`、`OLLAMA_NUM_PARALLEL`、`OLLAMA_MAX_LOADED_MODELS`
- 批量下载多个大模型
### 删除模型前必须输出确认信息
删除任何模型前,必须先输出:
1. 当前 `ollama list` 摘要
2. 待删除模型名称
3. 模型用途判断
4. 是否发现脚本引用
5. 是否存在替代模型
6. 删除后能否重新拉取
7. 用户确认语句
推荐确认语句:
```text
请确认是否删除模型:<model_name>。删除后如需恢复,需要重新下载或重新 create。
```
---
## 1. 适用场景与不适用场景
### 适用场景
- 本地模型越来越多,需要建立台账
- 想比较多个模型在同一设备上的速度和质量
- 想创建简短别名,方便命令行调用
- 想判断某个模型是否可以安全删除
- 想处理 Ollama 官方 registry 下载慢、卡住、失败
- 想为不同工作流选择不同模型
- 想规范 no-think / think false 使用方式
### 不适用场景
- 自动替用户决定删除哪些模型
- 自动替用户选择"最强模型"
- 自动修改生产脚本中的模型名称
- 自动处理涉及隐私材料的 Benchmark 输入
- 代替模型质量评估或专业任务评审
---
## 2. 环境检查
在做任何模型管理前,先检查环境。
```bash
ollama --version
curl http://localhost:11434/api/version
ollama list
du -sh ~/.ollama/models/
```
建议记录:
```markdown
## Ollama 环境记录
- 日期:YYYY-MM-DD
- 操作系统:
- 芯片/CPU/GPU:
- 内存:
- Ollama CLI 版本:
- Ollama Server 版本:
- 模型目录占用:
- 当前主要用途:聊天 / RAG / 长文分析 / 代码 / 视觉 / 其他
```
如果 CLI 和 server 版本不一致,优先重启 Ollama 服务后再测试。
---
## 3. 模型台账
生命周期管理的核心不是"模型多就删",而是知道每个模型为什么存在。
建议维护一个 `Ollama模型台账.md`。
```markdown
# Ollama 模型台账
| 模型名 | 类型 | 当前用途 | 绑定脚本/应用 | 状态 | 是否可删 | 替代模型 | 最近测试日期 | 备注 |
|---|---|---|---|---|---|---|---|---|
| gemma4:26b | 通用文本 | 长文分析 | batch_xxx.py | 核心 | 否 | - | 2026-xx-xx | 稳定 |
| qwen3-vl | 视觉模型 | 图片理解 | photo_app | 核心 | 否 | - | 2026-xx-xx | 保留 |
| gpt-oss:20b | 通用文本 | 测试 | 无 | 观察 | 可考虑 | xxx | 2026-xx-xx | 速度慢 |
```
### 状态分层
建议把模型分为五类:
1. **核心模型**:默认工作流正在使用,不能删除。
2. **任务模型**:embedding、vision、coding、long-context 等特殊用途模型。
3. **备用模型**:核心模型失效或质量不足时备用。
4. **测试模型**:新模型观察期,建议 7—30 天后复盘。
5. **废弃模型**:无明确用途、无脚本引用、已有替代,可考虑删除。
---
## 4. 脚本引用扫描
清理模型前,先扫描当前项目是否有脚本引用模型名称。
在项目根目录执行:
```bash
rg "ollama run|MODEL_NAME|model_name|\"model\"|ollama\.chat|ollama\.generate" .
```
如果没有 `rg`,可用:
```bash
grep -R "ollama run\|MODEL_NAME\|model_name\|\"model\"" . 2>/dev/null
```
输出后整理成:
```markdown
## 模型引用扫描结果
| 模型名 | 文件 | 行号/位置 | 用途 | 是否影响删除 |
|---|---|---|---|---|
| gemma-doc-nothink | batch_qwen_cards.py | MODEL_NAME | 资料抽取 | 是 |
| mistral-qa | qa_ask.py | model_name | 深度问答 | 是 |
```
删除模型前必须回答:
1. 是否被脚本硬编码引用?
2. 是否是 alias 的源模型?
3. 是否用于 embedding / RAG / 视觉 / 代码 / 长上下文?
4. 是否已有质量和速度都更好的替代模型?
5. 删除后是否容易恢复?
---
## 5. 拉取新模型流程
### 5.1 官方 registry 优先
```bash
ollama pull <model_name>:<tag>
```
拉取前先确认:
- 模型来源
- 模型尺寸
- 量化等级
- 预计磁盘占用
- 本机内存是否足够
- 是否已有同类模型
- 是否有明确测试任务
### 5.2 下载失败后的回退流程
如果官方 registry 卡住或超时:
1. 先等待一段合理时间,确认不是短暂网络波动。
2. 终止卡住的下载。
3. 到 ModelScope 或 Hugging Face 查找对应模型。
4. 核对发布者、文件名、量化格式、更新时间、license。
5. 使用完整路径重新拉取或手动导入。
ModelScope 示例:
```bash
ollama pull modelscope.cn/<org>/<model_name>:<tag>
```
### 5.3 ModelScope 风险提示
使用镜像源时必须注意:
- 路径和 tag 以模型页面为准。
- 同名模型可能不是官方发布者上传。
- template、chat format、license、量化格式可能与官方版本不同。
- 拉取后必须用固定测试集验证输出格式、速度和质量。
- 工作流模型不要只因下载成功就直接替换生产模型。
---
## 6. Benchmark 标准流程
不要只用 `ollama run + subprocess` 统计总耗时。总耗时会混入模型加载、命令行包装和输出渲染,不适合严肃对比。
优先调用 Ollama API,读取:
- `total_duration`
- `load_duration`
- `prompt_eval_count`
- `prompt_eval_duration`
- `eval_count`
- `eval_duration`
核心速度指标:
```text
tokens_per_second = eval_count / (eval_duration / 1e9)
```
### 6.1 Benchmark 场景
建议至少分四类测试:
1. **短问答**:100—300 字输出,测试日常响应。
2. **长文写作**:800—1500 字输出,测试持续生成。
3. **长文档摘要**:输入 5000—15000 字,测试上下文处理。
4. **结构化输出**:要求 JSON 或固定 Markdown,测试工作流稳定性。
### 6.2 冷启动与热启动
- 冷启动:包含模型加载时间,用于判断首次响应体验。
- 热启动:先预热一次,再测试,用于判断真实连续使用速度。
### 6.3 API Benchmark 脚本
保存为 `ollama_benchmark.py`:
```python
#!/usr/bin/env python3
import argparse
import json
import statistics
import time
import urllib.request
from typing import Any, Dict, List
OLLAMA_URL = "http://localhost:11434/api/generate"
def call_ollama(model: str, prompt: str, think: str | None = None, timeout: int = 600) -> Dict[str, Any]:
payload: Dict[str, Any] = {
"model": model,
"prompt": prompt,
"stream": False,
}
if think is not None:
if think.lower() == "false":
payload["think"] = False
elif think.lower() == "true":
payload["think"] = True
else:
payload["think"] = think
req = urllib.request.Request(
OLLAMA_URL,
data=json.dumps(payload).encode("utf-8"),
headers={"Content-Type": "application/json"},
method="POST",
)
start = time.time()
with urllib.request.urlopen(req, timeout=timeout) as resp:
data = json.loads(resp.read().decode("utf-8"))
wall_sec = time.time() - start
eval_count = data.get("eval_count") or 0
eval_duration = data.get("eval_duration") or 0
prompt_eval_count = data.get("prompt_eval_count") or 0
prompt_eval_duration = data.get("prompt_eval_duration") or 0
load_duration = data.get("load_duration") or 0
total_duration = data.get("total_duration") or 0
response = data.get("response", "")
tps = None
if eval_count and eval_duration:
tps = eval_count / (eval_duration / 1e9)
prompt_tps = None
if prompt_eval_count and prompt_eval_duration:
prompt_tps = prompt_eval_count / (prompt_eval_duration / 1e9)
return {
"model": model,
"wall_sec": round(wall_sec, 3),
"total_sec_api": round(total_duration / 1e9, 3) if total_duration else None,
"load_sec": round(load_duration / 1e9, 3) if load_duration else None,
"prompt_eval_count": prompt_eval_count,
"prompt_eval_sec": round(prompt_eval_duration / 1e9, 3) if prompt_eval_duration else None,
"prompt_tokens_per_sec": round(prompt_tps, 2) if prompt_tps else None,
"eval_count": eval_count,
"eval_sec": round(eval_duration / 1e9, 3) if eval_duration else None,
"tokens_per_sec": round(tps, 2) if tps else None,
"response_chars": len(response),
"preview": response[:160].replace("\n", " ") + ("..." if len(response) > 160 else ""),
}
def run_benchmark(models: List[str], prompt: str, rounds: int, warmup: bool, think: str | None) -> None:
if warmup:
for model in models:
try:
call_ollama(model, "请用一句话回答:测试。", think=think)
except Exception as e:
print(f"[WARMUP FAIL] {model}: {e}")
for model in models:
results = []
for i in range(rounds):
try:
result = call_ollama(model, prompt, think=think)
results.append(result)
print(json.dumps(result, ensure_ascii=False))
except Exception as e:
print(json.dumps({"model": model, "round": i + 1, "error": str(e)}, ensure_ascii=False))
speeds = [r["tokens_per_sec"] for r in results if r.get("tokens_per_sec") is not None]
if speeds:
summary = {
"model": model,
"rounds": len(speeds),
"tokens_per_sec_avg": round(statistics.mean(speeds), 2),
"tokens_per_sec_min": round(min(speeds), 2),
"tokens_per_sec_max": round(max(speeds), 2),
}
print("[SUMMARY] " + json.dumps(summary, ensure_ascii=False))
if __name__ == "__main__":
parser = argparse.ArgumentParser(description="Ollama API benchmark")
parser.add_argument("models", nargs="+", help="Models to benchmark")
parser.add_argument("--prompt", default="请写一段约500字的中文说明,介绍本地大模型的实际用途。")
parser.add_argument("--rounds", type=int, default=1)
parser.add_argument("--warmup", action="store_true")
parser.add_argument("--think", default=None, help="true / false / low / medium / high, if supported by model and Ollama")
args = parser.parse_args()
run_benchmark(args.models, args.prompt, args.rounds, args.warmup, args.think)
```
使用示例:
```bash
python3 ollama_benchmark.py gemma4:26b qq36 --rounds 2 --warmup
python3 ollama_benchmark.py qq36-nothink qq36 --think false --rounds 2 --warmup
```
### 6.4 质量评估必须用真实任务
速度测试不能代替质量测试。模型用于生产工作流前,必须用真实材料或脱敏材料测试:
- 是否漏事实
- 是否编造
- 是否能按固定格式输出
- 是否能处理长文本
- 是否容易过度推断
- 是否会输出思考过程
- 是否符合任务角色定位
---
## 7. 创建模型别名
### 7.1 Ollama 模型别名
```bash
ollama cp <source_model> <alias_name>
```
示例:
```bash
ollama cp qwen3.6:35b-a3b-q4_k_m qq36
```
注意:
- `ollama cp` 创建的别名通常共享底层模型存储。
- 删除 alias 不等于删除源模型。
- 删除源模型前要确认 alias 是否仍可用。
- alias 名称应短、稳定、能反映模型家族或任务用途。
### 7.2 Shell 命令别名
只建议输出命令,不自动写入 shell 配置。
```bash
alias qq36='ollama run qq36'
alias g26='ollama run gemma4:26b'
```
如需写入:
```bash
echo "alias qq36='ollama run qq36'" >> ~/.zshrc
source ~/.zshrc
```
写入前必须提醒用户:这会修改 shell 配置文件。
---
## 8. no-think / thinking 控制规范
### 8.1 关键原则
SYSTEM 提示词只能要求模型"不输出思考过程",不等于底层关闭 thinking。
如果 Ollama 和模型支持 `think` 参数,应优先用 API 显式设置:
```bash
curl http://localhost:11434/api/generate -d '{
"model": "<model>",
"prompt": "请总结这段材料。",
"think": false,
"stream": false
}'
```
如果模型支持 thinking levels,也可以测试:
```json
"think": "low"
```
或:
```json
"think": "medium"
```
具体是否生效,必须以模型实际输出和 Ollama API 支持情况为准。
### 8.2 Modelfile 方式只是弱约束
对不支持 `think` 参数的模型,可用 Modelfile 提示减少显式思考,但不能保证真正关闭 thinking。
```text
FROM <model_name>:<tag>
SYSTEM "直接输出最终答案。不要输出思考过程、推理草稿或隐藏分析。"
PARAMETER temperature 0.4
```
创建:
```bash
ollama create <model_name>-nothink -f Modelfile.<model_name>-nothink
```
建议文件命名:
```text
Modelfile.<source_model>.<purpose>.nothink
```
不要覆盖已有 `Modelfile`。
---
## 9. 清理旧模型
### 9.1 查看模型与占用
```bash
ollama list
du -sh ~/.ollama/models/
```
### 9.2 清理判断标准
不要机械执行"只保留 3—5 个模型"。更合理的判断是:
- 无明确用途
- 无脚本引用
- 非 embedding / vision / coding / RAG 等特殊任务模型
- 最近 30 天未使用或已确认不再使用
- benchmark 明显落后
- 已有同类替代模型
- 删除后可重新下载或重建
### 9.3 删除前检查模板
```markdown
## 删除模型前检查
- 待删除模型:
- 当前用途:
- 是否在台账中:是 / 否
- 是否发现脚本引用:是 / 否
- 是否是 alias:是 / 否
- 是否有替代模型:
- 删除风险:低 / 中 / 高
- 恢复方式:重新 pull / 重新 create / 无法恢复
- 建议:删除 / 暂缓 / 保留
```
删除命令:
```bash
ollama rm <model_name>
```
删除后确认:
```bash
ollama list
du -sh ~/.ollama/models/
```
---
## 10. 量化级别选择指南
| 量化 | 体积 | 质量 | 速度/内存 | 适用场景 |
|---|---:|---|---|---|
| Q3_K_M | 小 | 一般 | 压力小 | 内存紧张、粗略任务 |
| Q4_K_M | 中 | 良好 | 平衡 | 日常首选 |
| Q5_K_M | 较大 | 较好 | 压力略高 | 对质量更敏感 |
| Q8_0 | 大 | 接近原始 | 压力大 | 质量优先且内存充足 |
选择原则:
- 普通聊天、摘要、轻量工作流:优先 Q4_K_M。
- 高质量长文、复杂分析:可测试 Q5_K_M 或 Q8_0。
- 小内存设备:先试 Q3_K_M 或更小模型。
- 不同量化版本必须用同一测试集比较,不要凭感觉判断。
---
## 11. 常见故障
### 11.1 Ollama 版本过旧导致模型加载失败
症状:
```text
unable to load model
```
可能原因:
- Ollama 版本不支持新版 GGUF
- CLI 和 server 版本不一致
- server 未重启
处理:
```bash
ollama --version
curl http://localhost:11434/api/version
```
然后根据安装方式升级或重启 Ollama。
### 11.2 模型下载卡住
处理顺序:
1. 确认网络是否正常。
2. 重新执行 `ollama pull`,Ollama 通常可断点续传。
3. 官方源长期卡住时,考虑 ModelScope 或 Hugging Face。
4. 换源后必须重新验证模型质量和格式。
### 11.3 模型加载慢或内存不足
检查:
```bash
ollama list
du -sh ~/.ollama/models/
```
建议:
- 降低模型尺寸或量化等级。
- 减少并发。
- 避免同时驻留多个大模型。
- 不要盲目提高 `OLLAMA_CONTEXT_LENGTH`。
- 长上下文只在任务确实需要时开启。
### 11.4 输出格式不稳定
可能原因:
- 模型不适合结构化输出
- temperature 过高
- prompt 太松
- 上下文过长导致指令稀释
处理:
- 降低 temperature。
- 增加固定模板。
- 用短样本测试格式遵循能力。
- 必要时更换模型。
---
## 12. 推荐工作流
### 新模型进入流程
```text
发现模型 → 检查来源 → 判断用途 → 拉取/导入 → 环境记录 → Benchmark → 真实任务测试 → 写入台账 → 决定是否绑定脚本
```
### 模型替换流程
```text
候选模型测试 → 与现有模型对比 → 检查输出质量 → 小范围替换 → 保留旧模型一段观察期 → 稳定后更新台账 → 再决定是否删除旧模型
```
### 模型清理流程
```text
ollama list → 台账核对 → 脚本引用扫描 → 判断替代关系 → 输出删除建议 → 用户确认 → 删除 → 复查空间 → 更新台账
```
---
## 13. 最小可复制命令清单
```bash
# 环境
ollama --version
curl http://localhost:11434/api/version
ollama list
du -sh ~/.ollama/models/
# 拉模型
ollama pull <model_name>:<tag>
# ModelScope 回退
ollama pull modelscope.cn/<org>/<model_name>:<tag>
# 创建 Ollama alias
ollama cp <source_model> <alias_name>
# 扫描脚本引用
rg "ollama run|MODEL_NAME|model_name|\"model\"|ollama\.chat|ollama\.generate" .
# 删除模型,必须确认后执行
ollama rm <model_name>
# API no-think 测试
curl http://localhost:11434/api/generate -d '{
"model": "<model>",
"prompt": "请用一句话回答:测试。",
"think": false,
"stream": false
}'
```
---
## 14. 输出要求
当用户请求"帮我管理 Ollama 模型"时,应优先输出:
1. 当前判断
2. 安全风险
3. 建议执行的只读检查
4. 是否需要用户确认
5. 下一步命令
当用户请求"清理模型"时,应输出:
1. 模型分层
2. 不可删模型
3. 可观察模型
4. 可删除候选
5. 删除前引用扫描命令
6. 删除确认提示
当用户请求"测试模型"时,应输出:
1. 测试目标
2. 测试场景
3. Benchmark 命令
4. 质量评估维度
5. 是否建议进入生产工作流
don't have the plugin yet? install it then click "run inline in claude" again.
by @clawhub