ollama-optimizer

Ollama 优化器

根据系统硬件分析优化 Ollama 配置。

适用场景

当用户要求优化 Ollama、配置 Ollama、提升 Ollama 速度、解决 Ollama 运行缓慢的问题、设置本地 LLM、调整推理速度、减少内存使用量，或选择适合其 GPU/RAM 的模型时，使用此技能。此技能会分析硬件（GPU、VRAM、RAM、CPU），并提供量身定制的建议。

不要用于 LM Studio、llama.cpp、vLLM 或托管 API 的 LLM 提供商（OpenAI、Anthropic）——这些产品使用不同的运行时和调优方式。

安全规则

• 阶段 1 和阶段 2 为只读操作。它们会运行 scripts/detect_system.py、ollama --version、ollama list 和 ollama ps，不会更改任何内容。
• 已应用的更改是指对设备进行的任何写入：写入环境变量、重启服务或应用、运行 ollama pull、通过 Modelfile 运行 ollama create，或运行任何 sudo 命令。每次应用更改前，都要显示其准确命令，并等待用户同意该项更改。
• 将指南保存到用户选择的路径不属于已应用的更改。
• 如果用户只要求建议，则不要应用任何更改，并提供指南。仅要求建议不等于拒绝。
• 首次写入每个配置位置前，先备份该位置（选择环境变量的存放位置）。
• 切勿删除模型，也不要运行 ollama rm。在指南中列出过大的模型即可。
• 除非用户要求网络访问，否则切勿设置 OLLAMA_HOST=0.0.0.0。如果用户提出此要求，请警告他们：这会在没有身份验证的情况下将 Ollama API 暴露到网络中。

工作流

快速路径（仅限用户主动选择）： 只有在用户明确要求时，才跳过完整的硬件分析。否则，始终运行阶段 1 至 4，并遵循基于硬件等级的建议——默认不要采用捷径，也不要让捷径覆盖已做出的硬件等级判断。各平台的捷径命令和环境变量请参阅平台专属设置和环境变量。

阶段 1：系统检测

运行检测脚本以收集硬件信息：

python3 scripts/detect_system.py

脚本会在 stdout 上输出 JSON，并以状态码 0 退出。发生意外错误时，脚本会在 stderr 上输出 Error: ... 并以状态码 1 退出。如果以状态码 1 退出，请显示错误消息，按其修复提示操作，然后再运行一次。如果第二次运行仍以状态码 1 退出，则以 BLOCKED 状态停止（最终报告）。

解析 JSON 输出，确定以下信息：

• 操作系统及版本
• CPU 型号和核心数
• 总 RAM / 统一内存
• GPU 类型、VRAM 和驱动程序版本
• 当前 Ollama 安装情况和环境变量
• hardware_tier — 脚本计算出的 category、max_model_size 和 recommended_quant

如果 ollama.installed 为 false，则继续阶段 2。此时计划从平台专属设置中的安装步骤开始。安装 Ollama 属于已应用的更改。

阶段 2：分析并给出建议

将阶段 1 中的 hardware_tier 作为层级判定结果。不要重新推导；下表说明了各层级的含义及其对应的优化措施。只有在有明确理由时（例如显存与显示共享）才覆盖脚本结果，并在报告中说明该理由。

显存未知。 脚本仅根据 vram_gb 为 GPU 划分层级。AMD ROCm GPU、读取到的显存为 [N/A] 的 NVIDIA GPU，以及 Windows WMIC 回退路径均不会报告 vram_gb，因此脚本会返回 low_vram。配备独立 GPU 的 Intel Mac 会报告空的 gpu 列表，因此脚本会返回 cpu_only。遇到这些情况时，请询问用户显存大小。如果用户提供了显存大小，请根据表格覆盖层级并说明理由。如果用户没有提供，则保留脚本判定的层级，并将其作为保守层级列在 Uncertainty: 下。

硬件层级分类：

层级（category）	脚本判定范围	最大模型	主要优化
cpu_only	未检测到 GPU	3B	调整 num_thread、使用 Q4_K_M 量化
low_vram	显存 <6GB	3B	Flash attention、KV cache q4_0
entry	显存 6-10GB	8B	Flash attention、KV cache q8_0
prosumer	显存 10-16GB	14B	Flash attention、完全卸载
workstation	显存 16-48GB	32B	标准配置、可选 Q5_K_M
high_end	显存 48GB 以上	70B+	多个模型、Q5/Q6 量化

Apple Silicon 特殊情况：

• 统一内存 = CPU/GPU 共享 RAM；脚本会直接根据统一内存总量划分层级
• 8GB Mac → entry
• 16GB Mac → prosumer
• 32GB Mac → workstation；64GB 及以上 Mac → high_end

无需更改。 current_env_vars 仅显示脚本运行环境中的变量。对于 Ollama.app 或 systemd 服务，还要读取 Ollama 实际使用的值（launchctl getenv VAR、systemctl show ollama -p Environment）。如果所有推荐的环境变量在该环境中都已设为推荐值，且所有已安装模型都符合该层级要求，则指南会说明这一点，并且本次运行不会提出任何应用更改。

阶段 3：生成优化方案

阅读 报告模板，然后按以下章节生成指南：

1. 系统概览

列出检测到的硬件规格，并指出限制（例如，“8GB 统一内存将可用模型限制为 8B”）。

2. 依赖项评估

根据平台列出所需内容：

• macOS：仅需 Ollama（Metal 会自动启用）
• Linux NVIDIA：Ollama + NVIDIA 驱动 450+
• Linux AMD：Ollama + ROCm 5.0+
• Windows：Ollama + NVIDIA 驱动 452+

3. 配置建议

必要的环境变量：

# Always recommended
export OLLAMA_FLASH_ATTENTION=1

# Memory-constrained systems (<12GB)
export OLLAMA_KV_CACHE_TYPE=q8_0  # or q4_0 for severe constraints

当 GPU 的显存或统一内存低于 12GB 时，设置 OLLAMA_KV_CACHE_TYPE：low_vram 使用 q4_0，其他层级使用 q8_0。OLLAMA_KV_CACHE_TYPE 需要 OLLAMA_FLASH_ATTENTION=1。

模型选择指南：

• 根据 ollama list 的输出推荐具体模型
• 建议合适的量化方式（默认使用 Q4_K_M；有余量时使用 Q5_K_M）
• 如果当前模型超出硬件容量，发出警告

Modelfile 调优（需要时）：

PARAMETER num_gpu <layers>    # Partial offload for limited VRAM
PARAMETER num_thread <cores>  # CPU threads (physical cores, not hyperthreads)
PARAMETER num_ctx <size>      # Reduce context for memory savings

4. 选择环境变量的设置位置

Shell 初始化文件只会影响从该 Shell 启动的 ollama serve。先查明 Ollama 的运行方式：在 macOS 上，检查是否有正在运行的 Ollama.app（pgrep -x Ollama）；在 Linux 上，运行 systemctl is-active ollama；在 Windows 上，使用 Windows 行；如果 docker ps 列出了 Ollama 容器，则使用 Docker 行。如果检查结果无法确定，请询问用户。然后使用匹配的行；相关命令见环境变量 → 永久设置变量。

Ollama 的运行方式	环境变量的设置位置	写入前备份	一条命令回滚
在终端中运行 ollama serve（macOS、Linux）	$SHELL 使用的 Shell 初始化文件	cp "$RC" "$RC.ollama-bak"	cp "$RC.ollama-bak" "$RC"
Ollama.app（macOS）	launchctl setenv VAR value，然后退出并重新打开应用；该值重启后不会保留，因此要在 Uncertainty: 下说明这一点	记录 launchctl getenv VAR 的结果	对每个变量运行 launchctl unsetenv VAR，串联在一行中
systemd 服务（Linux）	在专用 drop-in 文件 /etc/systemd/system/ollama.service.d/zz-ollama-optimizer.conf 中写入 Environment= 行，并使用 sudo tee；绝不要使用 systemctl revert，因为它也会删除用户自己的 drop-in 文件	systemctl cat ollama > ~/ollama.service.bak	sudo rm /etc/systemd/system/ollama.service.d/zz-ollama-optimizer.conf && sudo systemctl daemon-reload && sudo systemctl restart ollama
Windows	使用 SetEnvironmentVariable(..., "User") 设置用户环境变量	记录当前值	将每个变量在 "User" 作用域下设为 $null，串联在一行中
Docker	使用 -e 标志或 compose 的 environment: 列表	复制 compose 文件	恢复副本并重新创建容器

5. 执行清单

按顺序提供可复制粘贴的命令。只有在用户批准后才运行命令（安全规则）：

1. 备份第 4 步中的配置位置并写入环境变量。对于 Shell 初始化文件（由 $SHELL 决定：~/.zshrc、~/.bashrc 或 ~/.bash_profile）：

   RC=~/.zshrc  # or ~/.bashrc / ~/.bash_profile, matching $SHELL
   cp "$RC" "$RC.ollama-bak"
   printf '\n# ollama-optimizer start\nexport OLLAMA_FLASH_ATTENTION=1\n<KV cache + other export lines from section 3, per tier>\n# ollama-optimizer end\n' >> "$RC"
   

2. 按照第 4 步对应行所述的方式重启 Ollama：重启 ollama serve，退出并重新打开 Ollama.app，运行 sudo systemctl daemon-reload && sudo systemctl restart ollama，从 Windows 任务栏退出并重新打开 Ollama，或重新创建容器
3. 拉取推荐的模型
4. 使用 ollama run <model> --verbose 测试
5. 回滚（使用与第 1 步相同位置的一条命令）：对于 Shell 初始化文件，运行 cp "$RC.ollama-bak" "$RC" — 然后重启 Ollama。其他位置使用第 4 步回滚列中的命令。

如果已批准的命令以非零状态退出，请停止清单，显示错误并保留备份。提供回滚命令，但只有在用户批准后才运行。

阶段 4：验证

只有当此时 ollama --version 以 0 状态退出，且 ollama list 显示至少一个模型时，才运行阶段 4。否则，跳过并记录原因。

# Benchmark current performance
python3 scripts/benchmark_ollama.py --model <model>
# Expected output: tokens/s and generation latency — record as the post-tuning baseline.

# Check GPU memory usage (NVIDIA only)
nvidia-smi

# Verify config is applied
ollama run <model> "test" --verbose 2>&1 | head -20

当 Ollama 缺失或未运行、未安装任何模型，或请求的模型不存在时，benchmark_ollama.py 会以 1 状态退出，并在 stderr 上输出 JSON error；参数无效时则以 2 状态退出。如果每次运行都报告 "success": false，模型没有 averages，且脚本在 stderr 上输出 Warning: 行，则验证失败。如果没有应用任何更改，这些数字就是当前基线，而不是调优后的结果；请在 Uncertainty: 下说明。

边缘情况

当多行匹配时，按 最终报告 中的首个匹配状态规则判定。

情况	处理方式	状态
未安装 Ollama（ollama.installed: false），且运行期间未安装	先规划安装步骤；跳过阶段 4	PARTIAL
ollama list 中没有模型，且运行期间未拉取模型	根据硬件档位推荐模型；跳过阶段 4	PARTIAL
GPU 的显存未知	询问显存；否则保留保守档位	按状态规则判定；档位保持保守时添加一行不确定性说明
用户只想要推荐	不应用任何更改；提供指南	COMPLETE
用户拒绝已应用的更改	在指南中标记为未应用；继续处理其余内容	PARTIAL
已批准的命令失败，或验证失败	停止检查清单；提供回滚方案	PARTIAL
无需更改	在指南中说明；对当前配置进行基准测试	COMPLETE
detect_system.py 连续两次退出代码为 1	在给出任何建议前停止	BLOCKED

最终报告

每次运行结束时（包括提前停止的情况），都以此摘要收尾。填写规则： 报告模板 → 最终摘要填写规则。

Result: COMPLETE | PARTIAL | BLOCKED — <tier>; <what changed>
Evidence: <checks that ran, with observed values>
Uncertainty: <untested or assumed items, or "none">
Decision: <approval needed, or "No approval needed.">
Remaining action: <one user action per line; omit when none>
Guide: <saved path, or "printed inline">

按第一个匹配的规则选择状态：

1. BLOCKED — 未提供指南：detect_system.py 连续两次退出代码为 1，或用户在指南交付前停止了运行。
2. PARTIAL — 已提供指南，且满足以下任一条件：因 Ollama 或模型缺失而跳过阶段 4，或用户在进入阶段 4 前停止运行；用户拒绝更改或停止运行，导致推荐的更改未应用；已批准的命令失败；或阶段 4 已运行但未通过。
3. COMPLETE — 已提供指南，且用户批准的所有已应用更改均已在阶段 4 成功完成并通过验证。仅提供建议的运行和无需更改的运行均为 COMPLETE。

用户拒绝更改不会导致状态变为 BLOCKED。

示例

在运行 Ollama.app、使用 8GB Apple Silicon Mac 的情况下，用户批准了两个环境变量：

Result: COMPLETE — entry; OLLAMA_FLASH_ATTENTION=1 and OLLAMA_KV_CACHE_TYPE=q8_0 applied
Evidence: detect_system.py exit 0 (entry, 8GB unified); launchctl setenv exit 0 for both vars; benchmark_ollama.py llama3.1:8b avg 21.7 tokens/s after reopening Ollama.app
Uncertainty: launchctl values reset at reboot; not re-checked after a reboot
Decision: No approval needed.
Remaining action: after a reboot, re-run the two launchctl setenv commands from the guide
Guide: ~/.config/ollama/optimization-guide.md

验收标准

满足以下所有条件即为运行通过：

• 报告中明确标出硬件档位（仅 CPU / 低显存 / 入门级 / 进阶用户 / 工作站 / 高端）。
• 推荐的模型大小适合检测到的显存／统一内存容量（不得在 8GB Mac 上推荐 14B 模型）。
• 每个已应用的环境变量都写入正在运行的 Ollama 会读取的位置（选择环境变量的存放位置），且此前已备份并获得用户批准。仅提供建议的运行会列出这些命令，但不会执行。
• 检测到 Apple Silicon 时应用特殊处理——不得将统一内存重复计算为独立的显存和 RAM。
• 验证步骤使用 ollama run <model> 和 --verbose，并记录实际的卸载／缓存数值；或者报告说明跳过阶段 4 的原因。
• 包含回滚说明，让用户可以用一条命令还原所有环境变量更改。
• 最终摘要通过报告模板 → 读者检查中的四项检查：状态位于第一行，事实与假设分开，每项声明都可追溯到已运行的检查，且明确说明下一步决策。若没有得到及时的人类反馈，则无法确认人类是否理解。

步骤完成报告

完成每个主要步骤后，按以下格式输出状态报告：

◆ [Step Name] ([step N of M] — [context])
··································································
  [Check 1]:          √ pass
  [Check 2]:          √ pass (note if relevant)
  [Check 3]:          × fail — [reason]
  [Check 4]:          √ pass
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

根据步骤实际验证的内容调整检查项名称。通过使用 √，失败使用 ×，并使用 — 补充简要说明。“标准”行概述满足了多少项验收标准。“结果”行给出总体判定。检测、分析、计划和验证各阶段的示例：报告模板 → 步骤完成报告示例。

参考文件

• VRAM 要求 - 模型大小与量化指南
• 环境变量 - 完整的环境变量参考
• 平台特定设置 - 操作系统特定的安装和配置
• 报告模板 - 步骤报告示例、指南模板、最终摘要填写规则、读者检查

预期输出

根据 报告模板 中的指南模板生成 ollama-optimization-guide.md 文件。询问用户要将其保存到哪里（建议保存到 ~/.config/ollama/optimization-guide.md 或当前目录）。如果用户不需要文件，则在回复中打印指南。然后打印最终摘要（最终报告）。