Ollama 技術スタック定義

SpecDojoでは、ドキュメント作成、コード生成、レビューなどでLLMを活用することを想定しており、ローカル実行基盤として Ollama を技術スタックの一部として定義する。なお、Ollama の使用は必須ではない。

1. Ollama実行環境

Ollama を対象とする。以下、macOSでの設定、常駐のさせ方、devcontainer からの疎通確認、モデル定義をまとめる。LinuxやWindowsでの設定については、今後追記予定。

2. mise + uv ベースの共通ツール環境

Ollama 本体は最新版を公式インストールスクリプトで導入し、macOS 上で常駐させる。LLM 周辺の補助CLIも運用できるように、Python と uv は mise で管理する。

SpecDojo では、ローカルLLM関連ツールの標準 Python を Python 3.12 とする。Python 3.12 は主要な ML / CLI パッケージとの互換性が安定しており、Python 3.13 固有の依存解決差分を避けやすい。

まず、mise をインストールする。

brew install mise

Python 3.12 と uv を mise でインストールする。

mise install python@3.12 uv@latest

グローバル既定として使う場合は、以下を設定する。

mise use -g python@3.12 uv@latest

リポジトリ単位で固定したい場合は、リポジトリルートで以下を実行する。

mise use python@3.12 uv@latest

有効化を確認する。

python --version
uv --version
mise current

Ollama 本体は、公式インストールスクリプトで最新版を導入する。

curl -fsSL https://ollama.com/install.sh | sh

macOS では、アプリ版（Ollama.app）を使う。アプリ版が最新の Ollama に最も早く対応するためである。公式インストールスクリプトは、macOS ではアプリ版を配置する（「macOSでの設定と常駐のさせ方」参照）。Homebrew の formula 版（brew install ollama、brew services start ollama）は使わない。

以前 Homebrew の formula 版を導入していた場合は、停止して削除してから、公式インストールスクリプトで導入し直す。

brew services stop ollama
brew uninstall ollama
curl -fsSL https://ollama.com/install.sh | sh

3. Ollamaモデルの選定

Ollama では、Ollama の公式ライブラリタグを優先して指定する。

用途	推奨モデル	備考
通常作業	qwen3.8:27b-mlx	設計、レビュー、通常のコード生成で使う標準モデル
Markdown生成・レビュー	gemma4:31b-mlx	Markdown の生成・レビューで使う標準モデル
軽作業	gemma4:e4b-mlx	短い要約、分類、文面調整、軽いMarkdown整理で使う軽量モデル
reporter の要約	gemma4:26b-mlx	速い MoE（全 25.2B・動作 3.8B）。判定には使わない
最終判断・難しい設計レビュー	Claude Code / Codex	ローカルLLMの結果を必要に応じて補完する

SpecDojo では、通常作業と重い実装を qwen3.8:27b-mlx、Markdown の生成・レビューを gemma4:31b-mlx、軽作業を gemma4:e4b-mlx、exec の reporter の要約を gemma4:26b-mlx に分担させる。

gemma4:26b-mlx は gemma4:31b-mlx の約3倍速く、日本語に中国語の字体が混ざらない。一方、grade の判定は 31B と同じく甘く、判定の規則や例を加えても変わらなかった（prj-0001:pjr-vqb5-agent-grade-comparison）。そのため、判定を伴わない reporter の文章要約と、英語で確定した grade finding の日本語表示文への翻訳に使う。grade の翻訳では英語文だけの配列を渡し、件数、訳文ごとの仮名、元の文と訳文のインラインコードの多重集合の一致をコードで検証する。元にないインラインコードが増えた項目も不合格とし、不合格項目だけを単件で1回再翻訳する。再び不合格なら英語正本を表示し、翻訳結果は判定へ反映しない。

qwen3.8:27b-mlx は Ollama 公式ライブラリ側のモデルタグである。サードパーティ名前空間のモデルは、公式ライブラリに必要な量子化やタグがない場合の代替候補として扱う。

4. メモリ安定化設定

複数Agentを使う場合、重いモデルを常時複数ロードしない方が安定するため、環境変数を設定して Ollama を起動する運用を採用する。

export OLLAMA_KEEP_ALIVE=10m
export OLLAMA_MAX_LOADED_MODELS=2

OLLAMA_MAX_LOADED_MODELS=2 にしておくと、重いモデルの同時常駐を抑えやすくなる。qwen3.8:27b-mlx と gemma4:31b-mlx は、同時に長時間常駐させない運用を推奨する。

但し、macOS では Ollama.app として常駐するため、export した環境変数は app に引き継がれない。app へ環境変数を渡すには launchctl setenv を使い、設定後に app を再起動する（次章参照）。

5. macOSでの設定と常駐のさせ方

公式インストールスクリプトは macOS では /Applications/Ollama.app を配置し、/usr/local/bin/ollama への symlink を作成したうえで Ollama.app を起動する。Ollama.app はメニューバー常駐アプリで、以降はログイン時に自動起動するため、常駐のための追加設定は不要である。

SpecDojo では「メモリ安定化設定」の環境変数を app に反映させる。macOS の GUI アプリは export した環境変数を引き継がないため、launchctl setenv で設定する。

launchctl setenv OLLAMA_KEEP_ALIVE 10m
launchctl setenv OLLAMA_MAX_LOADED_MODELS 2

設定を反映するため、Ollama.app を再起動する。

killall Ollama 2>/dev/null || true
open -a Ollama --args hidden

launchctl setenv はログインセッション単位のため、再起動すると設定が消える。ログインごとに自動で反映するには、環境変数の設定と Ollama.app の再起動だけを行う専用の LaunchAgent を用意する（Ollama 本体は app が常駐するため、この LaunchAgent はサーバを起動しない）。

環境変数設定用の LaunchAgent を作る。

code ~/Library/LaunchAgents/org.specdojo.ollama-env.plist

内容は ops/local/launchd/org.specdojo.ollama-env.plist を参照。ログイン時に launchctl setenv で環境変数を設定し、Ollama.app を再起動する。app のログイン項目より先に起動しても、この再起動で環境変数が確実に反映される。

読み込む。

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/org.specdojo.ollama-env.plist
launchctl kickstart -k gui/$(id -u)/org.specdojo.ollama-env

環境変数が設定されたことを確認する。

launchctl getenv OLLAMA_KEEP_ALIVE
launchctl getenv OLLAMA_MAX_LOADED_MODELS

常駐と API 到達を確認する。

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

モデル一覧の JSON が返れば、常駐と環境変数の反映まで確認できている。

ログを見る場合：

tail -f ~/.ollama/logs/server.log

6. devcontainerからの疎通確認

devcontainer 内から Host Mac 上の Ollama に接続する場合、localhost は devcontainer 自身を指すため、Docker Desktop が提供する host.docker.internal を使う。

まず、devcontainer のターミナルで Ollama API に到達できることを確認する。

curl http://host.docker.internal:11434/api/tags

モデル一覧の JSON が返れば、devcontainer から Host Mac の Ollama に疎通できている。

生成APIまで確認する場合は、軽量モデルで短いプロンプトを送る。

curl http://host.docker.internal:11434/api/generate \
  -H "Content-Type: application/json" \
  -d '{"model":"gemma4:e4b-mlx","prompt":"devcontainer から疎通確認しています。短く返答してください。","stream":false}'

response フィールドに文章が返れば、モデルのロードと生成まで確認できている。

CLIやアプリケーションから Ollama を参照する場合は、devcontainer 内で OLLAMA_HOST を設定する。

export OLLAMA_HOST=http://host.docker.internal:11434
ollama list

ollama CLI が devcontainer 内にない場合でも、HTTP API の curl 確認が通れば、アプリケーションからは同じURLで接続できる。

接続できない場合は、Host Mac 側で以下を確認する。

• Ollama が起動していること: curl http://localhost:11434/api/tags
• devcontainer が Docker Desktop 上で動作していること
• host.docker.internal が名前解決できること: getent hosts host.docker.internal

7. モデルのダウンロードとチューニング

Ollama のモデルは Host Mac 側でダウンロードする。devcontainer から利用する場合でも、モデル実体は Host Mac 上の Ollama が管理する。

まず、利用する元モデルを ollama pull で取得する。

ollama pull qwen3.8:27b-mlx
ollama pull gemma4:e4b-mlx
ollama pull gemma4:31b-mlx
ollama pull gemma4:26b-mlx

取得済みモデルを確認する。

ollama list

モデルを試しに実行し、初回ロードまで確認する。

ollama run qwen3.8:27b-mlx "通常作業用として、TypeScript の関数例を1つ示してください。"
ollama run gemma4:e4b-mlx "軽作業用として、短い設計書のタイトル案を3つ出してください。"
ollama run gemma4:31b-mlx "中量作業用として、設計書の要約を3文でまとめてください。"
ollama run gemma4:26b-mlx "reporter 用として、作業内容を3行で要約してください。"

不要になった元モデルまたは派生モデルは ollama rm で削除する。

ollama rm qwen3.8:27b-mlx
ollama rm gemma4:e4b-mlx
ollama rm gemma4:31b-mlx
ollama rm gemma4:26b-mlx

複数Agent運用前提のため、すべてのモデルを巨大コンテキストで動かさない設定を適用する。ダウンロード済みの元モデルを FROM に指定し、用途ごとにコンテキスト長と生成パラメータを分けた派生モデルを作成する。

Host Mac で以下のディレクトリを作成して、そこに以下のモデルファイルを作成する。

mkdir -p ~/ollama-modelfiles
cd ~/ollama-modelfiles

7.1. Qwen3.8-27B 通常作業用（レビュー・長文向け 64k）

qwen3.8-27b-mlx-work-64k/Modelfile:

FROM qwen3.8:27b-mlx
PARAMETER num_ctx 65536
PARAMETER temperature 0.2
PARAMETER top_p 0.9
PARAMETER repeat_penalty 1.05

作成:

ollama create qwen3.8:27b-mlx-work-64k -f qwen3.8-27b-mlx-work-64k/Modelfile

7.2. Gemma 4 E4B 軽作業用

gemma4-e4b-mlx-light-8k/Modelfile:

FROM gemma4:e4b-mlx
PARAMETER num_ctx 8192
PARAMETER temperature 0.3
PARAMETER top_p 0.9

作成:

ollama create gemma4:e4b-mlx-light-8k -f gemma4-e4b-mlx-light-8k/Modelfile

7.3. Gemma 4 31B Markdown生成・レビュー用（64k）

gemma4-31b-mlx-work-64k/Modelfile:

FROM gemma4:31b-mlx
PARAMETER num_ctx 65536
PARAMETER temperature 0.2
PARAMETER top_p 0.9
PARAMETER repeat_penalty 1.05

作成:

ollama create gemma4:31b-mlx-work-64k -f gemma4-31b-mlx-work-64k/Modelfile

7.4. Gemma 4 26B reporter の要約用（64k）

gemma4-26b-mlx-work-64k/Modelfile:

FROM gemma4:26b-mlx
PARAMETER num_ctx 65536
PARAMETER temperature 0.2
PARAMETER top_p 0.9
PARAMETER repeat_penalty 1.0

作成:

ollama create gemma4:26b-mlx-work-64k -f gemma4-26b-mlx-work-64k/Modelfile

context は 64k とする。計測では、入力が 64k に収まる範囲で 128k にしても精度は変わらなかった。repeat_penalty は、executor の出力の書き写しを妨げないよう 1.0 とする。

7.5. 動作確認

ollama run qwen3.8:27b-mlx-work-64k "レビュー用として、このMarkdownの構成上の問題点を指摘してください。"

ollama run gemma4:31b-mlx-work-64k "Markdown生成・レビュー用として、この設計書の構成上の改善点を挙げてください。"

ollama run gemma4:e4b-mlx-light-8k "軽作業用として、短い設計書のタイトル案を3つ出してください。"

ollama run gemma4:26b-mlx-work-64k "reporter 用として、次の作業内容を3行で要約してください。"

8. アンインストール

Ollama を削除する場合は、常駐設定、Ollama.app 本体、モデルデータを分けて扱う。モデルデータは容量が大きく、削除すると再ダウンロードが必要になるため、必要な場合だけ削除する。

8.1. 常駐設定の停止

Ollama.app を終了する。

killall Ollama 2>/dev/null || true

環境変数設定用の LaunchAgent を作成している場合は、停止・削除する。

launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/org.specdojo.ollama-env.plist 2>/dev/null || true
rm -f ~/Library/LaunchAgents/org.specdojo.ollama-env.plist

自動起動を止めるため、ログイン項目から Ollama を外す（システム設定 > 一般 > ログイン項目、または以下）。

osascript -e 'tell application "System Events" to delete login item "Ollama"' 2>/dev/null || true

「メモリ安定化設定」で設定した環境変数を解除する。

launchctl unsetenv OLLAMA_KEEP_ALIVE
launchctl unsetenv OLLAMA_MAX_LOADED_MODELS

8.2. Ollama 本体の削除

公式インストールスクリプトで配置した Ollama.app と symlink を削除する。

rm -rf /Applications/Ollama.app
sudo rm -f /usr/local/bin/ollama

削除後、API が応答しないことを確認する。

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

接続エラーになれば、常駐プロセスは停止している。

8.3. モデルデータの削除（任意）

モデルデータも削除する場合は、Ollama のデータディレクトリを削除する。ログ（~/.ollama/logs）もこのディレクトリに含まれる。

rm -rf ~/.ollama

SpecDojo 用に作成した Modelfile 作業ディレクトリも不要なら削除する。

rm -rf ~/ollama-modelfiles