ollama-optimizer

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

スクリプトは標準出力に JSON を出力し、終了コード 0 で終了します。予期しないエラーが発生した場合は、標準エラー出力に Error: ... を出力し、終了コード 1 で終了します。終了コード 1 の場合は、そのメッセージを表示して修正のヒントに従い、もう一度実行してください。2 回目も終了コード 1 で終了した場合は、最終レポートの BLOCKED に従って停止してください。

JSON 出力を解析し、次の項目を特定します。

• OS とバージョン
• CPU のモデルとコア数
• RAM の合計／ユニファイドメモリ
• GPU の種類、VRAM、ドライバーバージョン
• Ollama の現在のインストール状況と環境変数
• hardware_tier — スクリプトが算出した category、max_model_size、recommended_quant

ollama.installed が false の場合は、フェーズ 2 に進んでください。その場合、プランはプラットフォーム固有のセットアップにあるインストール手順から始まります。Ollama のインストールは変更の適用に該当します。

フェーズ 2：分析と推奨事項

フェーズ 1 の hardware_tier をティア判定として使用してください。再判定は行わないでください。以下の表では各ティアの意味と、該当する最適化について説明しています。明確な理由（例：VRAM をディスプレイと共有している）がある場合に限り、スクリプトの判定を上書きし、その理由をレポートに記載してください。

VRAM が不明な場合。 スクリプトは vram_gb の値のみで GPU のティアを判定します。AMD ROCm GPU、VRAM の読み取り結果が [N/A] となる NVIDIA GPU、および Windows WMIC フォールバックでは vram_gb が報告されないため、スクリプトは low_vram を返します。ディスクリート GPU を搭載した Intel Mac では gpu リストが空になるため、スクリプトは cpu_only を返します。このような場合は、ユーザーに VRAM の容量を尋ねてください。容量がわかれば、表に基づいてティアを上書きし、その理由を記載してください。わからない場合は、スクリプトのティアを維持し、保守的なティアとして Uncertainty: に記載してください。

ハードウェアティアの分類：

Tier (category)	Script band	Max Model	主な最適化
cpu_only	GPU が検出されない	3B	num_thread の調整、Q4_K_M 量子化
low_vram	VRAM <6GB	3B	Flash attention、KV キャッシュ q4_0
entry	VRAM 6-10GB	8B	Flash attention、KV キャッシュ q8_0
prosumer	VRAM 10-16GB	14B	Flash attention、完全オフロード
workstation	VRAM 16-48GB	32B	標準構成、Q5_K_M オプション
high_end	VRAM 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 の VRAM またはユニファイドメモリが 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. 環境変数の設定先を選ぶ

シェルの初期化ファイルが適用されるのは、そのシェルから起動した ollama serve だけです。Ollama の実行方法を確認します。macOS では、Ollama.app が実行中か確認します（pgrep -x Ollama）。Linux では、systemctl is-active ollama を実行します。Windows では Windows の行を使用します。docker ps に Ollama コンテナーが表示される場合は、Docker の行を使用します。確認しても判断できない場合は、ユーザーに尋ねてください。その後、該当する行を使用します。コマンドは 環境変数 → 変数を永続的に設定する にあります。

Ollama の実行方法	環境変数の設定先	書き込み前のバックアップ	1 コマンドでのロールバック
ターミナルからの ollama serve（macOS、Linux）	$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 を実行し、1 行につなげます
systemd サービス（Linux）	専用のドロップインファイル /etc/systemd/system/ollama.service.d/zz-ollama-optimizer.conf に Environment= 行を記述し、sudo tee で書き込みます。ユーザー独自のドロップインも削除されるため、systemctl revert は使用しないでください	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 に設定し、1 行につなげます
Docker	-e フラグまたは compose の environment: リスト	compose ファイルをコピーします	コピーを復元して、コンテナーを再作成します

5. 実行チェックリスト

コピーして貼り付けられるコマンドを順番に提示します。ユーザーの承認を得てからコマンドを実行してください（安全ルール）。

1. ステップ 4 の設定場所をバックアップし、環境変数を書き込みます。シェルの初期化ファイルの場合（$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 と同じ場所で 1 つのコマンドを実行します）。シェルの初期化ファイルの場合は、cp "$RC.ollama-bak" "$RC" を実行し、その後 Ollama を再起動します。それ以外の場所では、ステップ 4 のロールバック列を使用します。

承認済みのコマンドが 0 以外の終了コードを返した場合は、チェックリストを中止し、エラーを表示して、バックアップを保持してください。ロールバックコマンドを提示し、ユーザーの承認を得てから実行してください。

フェーズ 4：検証

この時点で ollama --version が終了コード 0 を返し、ollama list に少なくとも 1 つのモデルが表示される場合に限り、フェーズ 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 は標準エラー出力に JSON の error を出力して 1 で終了します。無効な引数の場合は 2 で終了します。すべての実行結果が "success": false の場合、モデルに averages がなく、スクリプトが標準エラー出力に Warning: 行を出力するため、検証は失敗です。変更が適用されていない場合、数値は現在のベースラインであり、調整後の結果ではありません。その旨を Uncertainty: に記載します。

エッジケース

複数の行に該当する場合は、最終レポートのステータス判定ルールで最初に一致したものが適用されます。

ケース	対応	ステータス
Ollama がインストールされていない（ollama.installed: false）かつ実行中にもインストールされなかった	インストール手順を最初に含めて計画し、フェーズ 4 をスキップします	PARTIAL
ollama list にモデルがなく、実行中にもプルされなかった	ティアに応じたモデルを推奨し、フェーズ 4 をスキップします	PARTIAL
GPU の VRAM が不明	VRAM を確認し、不明のままであれば保守的なティアを維持します	ステータス判定ルールに従います。ティアを保守的なままにする場合は「不確実性」の行を追加します
ユーザーが推奨のみを希望する	何も適用せず、ガイドを提示します	COMPLETE
ユーザーが適用を承認した変更を拒否する	ガイド内で未適用と記載し、残りの項目を続行します	PARTIAL
承認済みのコマンドが失敗する、または検証に失敗する	チェックリストを中止し、ロールバックを提案します	PARTIAL
変更するものがない	ガイド内でその旨を伝え、現在の設定をベンチマークします	COMPLETE
detect_system.py が 2 回連続で終了コード 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 が 2 回連続で終了コード 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 のみ／低 VRAM／エントリー／プロシューマー／ワークステーション／ハイエンド）がレポート内で明示されています。
• 推奨モデルのサイズが、検出された VRAM／ユニファイドメモリの予算内に収まっています（8GB の Mac で 14B モデルを推奨しないこと）。
• 適用する環境変数は、バックアップを作成し、ユーザーの承認を得たうえで、実行中の Ollama が読み取る場所（環境変数の保存場所を選択する）に書き込まれています。推奨のみの実行では、コマンドを実行せずに一覧表示します。
• Apple Silicon が検出された場合は、特例が適用されています。ユニファイドメモリを VRAM と RAM として二重に計上していません。
• 検証手順で ollama run <model> を --verbose とともに実行し、実際のオフロード数とキャッシュ数を取得しています。フェーズ 4 をスキップした場合は、その理由をレポートに記載しています。
• すべての環境変数を 1 つのコマンドで元に戻すためのロールバック手順が含まれています。
• 最終要約がレポートテンプレート → 読者向けチェック項目の 4 項目を満たしています。ステータスが 1 行目にあること、事実と仮定が区別されていること、各主張が実行済みのチェックにたどれること、次の判断が明示されていることです。応答する人間からのフィードバックがない場合、人間の理解は未確認のままです。

ステップ完了レポート

各主要ステップの完了後、次の形式でステータスレポートを出力します。

◆ [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

チェック名は、そのステップで実際に検証する内容に合わせてください。合格には √、失敗には × を使い、簡単な補足には — を使います。「Criteria」行には、合格した受け入れ基準の数をまとめます。「Result」行には、全体の判定を記載します。各フェーズ（検出、分析、計画、検証）の例は、レポートテンプレート → ステップ完了レポートの例を参照してください。

参考ファイル

• VRAM の要件 - モデルのサイズと量子化に関するガイド
• 環境変数 - 環境変数の完全なリファレンス
• プラットフォーム固有の設定 - OS 固有のインストールと設定
• レポートテンプレート - ステップレポートの例、ガイドテンプレート、最終サマリーの記入ルール、読者向けチェック項目

期待される出力

レポートテンプレートのガイドテンプレートから、ollama-optimization-guide.md ファイルを生成します。保存先をユーザーに尋ねてください（~/.config/ollama/optimization-guide.md または現在のディレクトリを提案してください）。ユーザーがファイルの作成を希望しない場合は、返信にガイドを出力してください。その後、最終サマリー（Final Report）を出力してください。