目次
- 目次
- はじめに
- 環境
- Ollama と Aider について
- 環境構築の流れ
-
トラブルの発生と対応(
Waiting...のまま固まってしまう ) - 安定稼働のための対策手順
- レスポンスの「速度」を求めたい場合
- 付録：Aider での基本のファイル管理コマンド
- まとめ
- 参考
はじめに
後述の 環境 で Gemma4 + Aider で AI コーディングアシスタント の環境をローカルに構築したときの備忘録です。
M4 チップを搭載した Mac Mini では Gemma4 + Aider を動かすことはできるようなのですが、手元の環境は最小構成のメモリ 16GB 環境です。
そうした環境で
- 12B（120億パラメータ）クラスの最新モデル（例:
gemma4:12b） - Aider などの AI コーディングアシスタント
を連携させたときの手順とトラブル & 対応についてまとめてみました。
環境
| 項目 | 内容 | 備考 |
|---|---|---|
| マシンスペック | Mac mini M4 (メモリ 16GB / SSD 256GB) | 最小構成の16GB環境 |
| OS | macOS | Tahoe v26.5.1 |
| LLM実行環境 | Ollama | Context length: 8k に制限 |
| 使用モデル | Gemma 4 (12B) (ollama/gemma4:12b) |
推論型（Thinking）モデル |
| AIツール | Aider |
--map-tokens 0 で起動 |
Ollama と Aider について
環境構築に入る前に、今回使用する2つのツールについて簡単に紹介します。
🦙 Ollama とは？
**Ollama（オラマ）**は、ローカル環境（自分のPC上）でLLM（大規模言語モデル）を簡単かつ軽量に動かすためのオープンソースのプラットフォームです。
クラウドAPIを使わずに、完全にオフライン・無料でさまざまなAIモデル（Gemma 4、Llama 3、Qwenなど）をコマンド一つでダウンロードして実行することができます。
🤖 Aider とは？
**Aider（エイダー）**は、ターミナル（コマンドライン）から利用できる、Gitと強力に連携したAIコーディングアシスタントツールです。
OllamaなどのLLMと接続し、チャットで「〜の機能を実装して」「このバグを直して」と指示を出すだけで、プロジェクト内のソースコードを直接書き換え、さらに自動でGitコミットまで完了 してくれる、非常に強力なCUI開発パートナーです。
環境構築の流れ
1. Ollama のインストール
まずはローカルでLLM（大規模言語モデル）を動かすためのプラットフォームである Ollama をインストールします。
1. アプリのダウンロード
Ollamaの公式サイト から macOS 用のインストーラーをダウンロードし、アプリケーションフォルダに展開します（Homebrew を使用する場合は brew install --cask ollama でも可能です）。
2. Ollama の起動
アプリを起動すると、メニューバーにラマのアイコンが表示されます。
3. モデル（Gemma 4 12B）のダウンロード
ターミナルを開き、以下のコマンドを実行して今回使用するモデルをローカルにプルします。
ollama pull gemma4:12b
2. Aider のインストール
次に、ターミナルからシームレスにローカルLLMと連携してコードを自動生成・修正してくれるAIツール Aider をインストールします。macOS環境では Homebrew を使うのが一番簡単です。
1. Aider のインストール
ターミナルで以下のコマンドを実行します。
brew install universal-ctags
brew install aider
💡 universal-ctags は必要なの？
1universal-ctagsは Aider がプロジェクト内の関数やクラスの構造（リポジトリマップ）を解析するために裏で使うツールとのことです。
今回は後述の設定で 16GBメモリの節約のために --map-tokens 0（マップ機能を一旦オフにする）という対策を入れていますが、将来的にメモリに余裕ができたり、より軽量なモデル（qwen2.5-coder など）に切り替えて「マップ機能（Repo-map）を使おう！」となった時には、この universal-ctags が入っていないとエラーになるようです。
( この辺、まだ不勉強で AI の受け売りです )
2. Gitの事前準備
Aider は Git リポジトリと連携してコードを自動でコミットする仕組みになっています。
ターミナルで、Aider を動かしたいプロジェクトのディレクトリに移動します。
cd /Users/ユーザー名/path/to/your-project
※まだリポジトリがない場合は、git init を実行して Git 管理下にしてください
トラブルの発生と対応( Waiting... のまま固まってしまう )
Aider で こんにちは とプロンプトを打った際に、Waiting... のまま応答が返ってきませんでした。
しかしながら Ollama 単体（ollama run gemma4:12b）で「こんにちは」と送ると数秒で返ってくるのです。
このように、Aider を通した瞬間に固まってしまう場合、原因は主に 2 つあるようです。
原因①：コンテキスト長（Context Length）の肥大化によるメモリ不足
Aider は起動時に、AI に対して数千文字に及ぶ巨大な「システム指示（取扱説明書）」を送信します。
Ollama のコンテキスト長を 32k やデフォルトのままにしていると、この長文を受け取った瞬間に 16GB メモリの限界を突破。超高速な M4 チップといえども、ディスク（SSD）へのデータ退避（スワップ現象）が発生し、1文字目を出すまでに数十分かかるほどの超激重状態に陥ります。
原因②：Gemma 4 特有の「Thinking（思考）プロセス」
gemma4:12b は、回答を出力する前に内部で深く推論（思考プロセスを生成）するタイプのモデルです。
ターゲットが曖昧な質問を投げると、裏で猛烈に長い思考トークンを生成し始めるため、画面上はフリーズしているように見えてしまいます。
安定稼働のための対策手順
これらを解決し、16GB メモリで安定して動作させるための設定手順です。
Step 1: Ollama の Context length を「8k」に絞る
コンテキスト長（AI の記憶容量）を、16GB メモリの環境でもスワップを起こさない安全圏である 8k に制限します。
- Ollama アプリの Settings（設定） を開きます。
-
Context length のスライダーを
8kに合わせます。(自動背saveされます) - メニューバーのアイコンから「Quit Ollama」で一度アプリを終了し、再起動して設定を反映させます。
Step 2: Aider 起動時に「リポジトリマップ」を無効化する
Aider はデフォルトでリポジトリ全体の構造をスキャンして AI に送る「Repo-map」機能（約4096トークン消費）が有効になっています。
これがメモリを圧迫するため、起動オプションで明示的に無効化します。
ターミナルから以下のコマンドで Aider を起動します。
aider --model ollama/gemma4:12b --map-tokens 0
※ --map-tokens 0 を付与することで、Repo-map: disabled となり、初期起動時の消費トークンを数百トークン（500〜700点前後）にまで抑えることができます。
Step 2+: リポジトリマップの無効化と「日本語化」の強制
Aider はデフォルトのシステム指示が英語ベースなため、ローカル AI が頑なに英語で返答してしまう現象が起きます。
これを防ぐために「日本語の強制オプション」と、メモリ節約のための「マップ無効化オプション」を同時に指定して起動します。
aider --model ollama/gemma4:12b --map-tokens 0 --chat-language japanese
Step 3: 【超重要】プロンプトは「ターゲットのファイルを指定」して具体的に出す
環境が整っても、AI に「このプロジェクトの構造はわかりますか？」といった抽象的な質問を投げると、暗闇の中で AI が考え込んでしまい、再びレスポンスが止まります。
ローカル環境では、「触るファイルを明示して、具体的なタスクを振る」 のが鉄則です。
下記は私のリポジトリ( angular-work )で行った例です。
❌ 避けるべきプロンプト（迷子になって思考が長引く）
> `> あなたがいま居る github のプロジェクトはわかりますか？`
░█ Waiting for ollama/gemma4:12b
ターゲットを明示しないと、上記のままプロンプトの応答が返ってきません。
⭕ 爆速で返ってくるプロンプト（思考の標的を絞る）
> /add README.md
Added README.md to the chat
─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
README.md
> このファイルについて説明して
提供された README.md ファイルの内容を要約・解説します。
このファイルは、Angularの学習用プロジェクトの概要をまとめたドキュメントです。主な内容は以下の通りです。
1. プロジェクトの目的
このプロジェクトは、Angular CLIを使用して作成されたもので、Angularの理解を深めるための学習用リポジトリです。個人利用を目的としており、更新によって機能が削除される可能性があることも明記されています。
2. 環境情報
プロジェクトを実行するために必要な技術スタックとバージョンが詳細に記載されています。
• フレームワーク: Angular (v20.1.4), Angular Material, Angular CDK
• ライブラリ: RxJS (v6.6.7), ngx-toastr
• 言語・実行環境: TypeScript (v5.8.3), Node.js (v22.17.1) など
3. ブランチ構成（学習内容の整理）
このリポジトリの最大の特徴は、ブランチごとに特定の技術要素を学習・実装している点です。各ブランチは以下の内容に対応しています：
• 基本機能: コンポーネントのライフサイクル（ngDoCheck, ngAfterContentInit など）、コンポーネント間のデータ受け渡し、サービスの作成と共有。
• 高度な機能: HTTPクライアントの実装、バリデーション（Validation）の仕組み、ディレクティブの自作。
• 応用・高度な技術: 動的なコンポーネント切り替え（ngComponentOutlet）、ルーティングによる画面遷移、モーダルの実装、CSV/ZIPファイルの処理。
• 外部連携・その他: WebSpeechAPIを用いた音声認識、AWS Transcribe Streamingの利用、デザインパターンの適用など。
まとめ
この README.md
は、単なるプロジェクトの説明だけでなく、「どのブランチで何を学んだか」を体系的に整理するためのインデックスとしての役割を果たしています。特定の機能を調査したい場合は、該当するブランチを確認することで、その機能に特化したコードを確認できるようになってい
ます。
Tokens: 5.0k sent, 781 received.
このように指示を明確にターゲットへ絞り込むことで裏での不要な思考のループを防ぎ、数秒〜数十秒でサクッと応答が返ってくるようになります。
補足
/add .
という形で、カレントディレクトリ配下を丸ごと指定することもできますが、そうすると対象が多すぎて前掲のフリーズが発生します。
( 設定した 8k のコンテキスト上限を超えてしまい、メモリ（RAM）が溢れかえり Waiting for ollama... (スワップによるフリーズ) が発生します )
それでも「複数ファイル」をまとめて追加したいときは？
「関連するコンポーネント一式をまとめて追加したい」という場合は、ディレクトリ丸ごとではなくワイルドカードを使って、対象の種類やフォルダを絞り込んで追加するのがおすすめです。
# 特定のコンポーネントの ts, html, css だけをまとめて追加する
> /add src/app/component/*
# app ディレクトリ直下の TypeScript ファイルだけをまとめて追加する
> /add src/app/*.ts
こうすることで、不要な node_modules やビルド成果物、無関係なページの実装を巻き込むことなく、安全に必要な分だけをメモリに乗せることができます。
レスポンスの「速度」を求めたい場合
「ローカルの完全無料・プライバシー保護というメリットは捨てがたいけれど、12B モデルの初回応答のタイムラグが気になる」という場合は、思考プロセスを挟まない軽量なコーディング特化モデル（7B〜8Bクラス）への変更がおすすめです。
特に qwen2.5-coder:7b は非常に軽量かつコード生成能力が高いため、16GB メモリの Mac Mini でも 1文字目が出るまでの速度が劇的に向上します。
# モデルのダウンロード
ollama run qwen2.5-coder:7b
# Aiderでの起動
aider --model ollama/qwen2.5-coder:7b --map-tokens 0
付録：Aider での基本のファイル管理コマンド
ローカル環境ではメモリ節約のため、必要なファイルだけを「追加して、用が済んだら外す」のが鉄則です。
ファイルを指定して追加する
ファイルをチャットに追加します。
指示を明確にターゲットへ絞り込むことで裏での不要な思考のループを防ぎ、数秒〜数十秒でサクッと応答が返ってくるようになります。
> /add パス/ファイル名
ファイルを対象から外す（メモリ解放）
現在チャットに追加されているすべてのファイルを一括で解除したいときに便利です（バージョンや環境によっては、ファイルを個別指定する必要がある場合もありますが、基本は /ls で確認しながら /drop します）。
> /drop パス/ファイル名
現在どのファイルが追加されているか確認する
現在チャットの対象に入っているファイルの一覧（と、プロジェクト内にあるその他のファイルの一覧）をズラッと確認できます。対象に入っているファイルにはマークがつきます。
> /ls
まとめ
- 16GB メモリ環境でのローカル 12B モデル運用は、Ollama の Context length を 8k に絞る のが生命線
- Aider は
--map-tokens 0で初期トークンを節約する。 - 質問は抽象的な内容を避け、
/addでファイルを指定して具体的に指示を出す。
この制限事項とコツさえ掴めば、手元の Mac Mini の中だけで、完全にプライベートかつ無料で実用的な AI 開発環境を構築することができます。
同じ環境でフリーズに悩まされている方は、ぜひ試してみてください！