Macでllama.cppを導入する方法：Apple Silicon最適化ガイド

この記事でわかること

Apple Silicon Macへllama.cppを導入し、公式の小型GGUFまたは手元のGGUFでCLI、API server、benchmarkを確認する手順です。Homebrewで素早く始める方法と、releaseを固定してsource buildする方法を分けて説明します。

Homebrewとsource buildの使い分け
macOSでのMetalの扱い
再現可能な実行・性能確認の方法

確認日時: 2026年8月23日 11:15（Asia/Tokyo）
対象版: 安定版 llama.cpp v0.2.0（commit bb4caa7540188872173c44d161602d9271386413）。最新nightlyはb10588ですが、導入例は安定版へ固定しています。
検証区分: 公式docs、repository、releaseを照合した机上調査です。ここに記載したinstall、build、model download、推論、benchmarkは実行していません。

事前に確認するもの

Apple Silicon搭載Macと、利用できる空きstorage・unified memory
macOS用Command Line Tools
source buildを行う場合はCMake（Homebrewならbrew install cmake）
取得するmodelのlicense、配布元、GGUF file size
対象modelが利用中のllama.cpp版で対応しているか

必要memoryはparameter数だけでは決まりません。量子化、context長、KV cache、GPU offload、並列数で変わるため、固定の「何Bなら何GB」という表は目安以上に扱えません。

方法1：Homebrewで導入する

公式install documentはHomebrew formulaを案内しています。まずCommand Line ToolsとHomebrewが利用できる状態にします。

xcode-select --install
brew install llama.cpp
llama-cli --version

xcode-select --installは導入済みならその旨を表示します。Homebrew版は更新しやすい一方、formula更新により導入されるbuildが変わります。検証結果を再現したい場合は、表示されたversionを記録するか、次のsource buildでtagを固定します。

方法2：v0.2.0をsource buildする

git clone https://github.com/ggml-org/llama.cpp.git
cd llama.cpp
git checkout v0.2.0
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --config Release -j
./build/bin/llama-cli --version

cmakeが見つからない場合は、Homebrewでbrew install cmakeを実行してからbuildします。Homebrew版のllama.cppだけを使う場合、この追加installは不要です。

macOSではMetal backendがdefaultで有効です。通常のApple Silicon buildに古いLLAMA_METAL optionを追加する必要はありません。公式build documentではMetalを無効にするCMake optionを-DGGML_METAL=OFFとしています。--n-gpu-layers 0でも一部処理にGPUを使う場合があるため、実行時にCPUだけを使う比較は--device noneを指定します。

正確なbuild optionはv0.2.0のbuild documentで確認してください。以前のbuild directoryを別のoptionで再利用して問題が出る場合は、新しいbuild directoryを作って比較します。

公式例のGGUFをCLIで動かす

Homebrew版では次のcommandを利用できます。source build版なら先頭を./build/bin/llama-cliへ置き換えます。

llama-cli -hf ggml-org/Qwen3.5-0.8B-GGUF

-hfはHugging Faceからmodelを取得するため、初回はnetworkとstorageを使います。repository名を似た名前へ置き換えず、model card、license、fileを確認してください。

外付けSSDは導入に必須ではありません。内蔵ストレージの空き容量が不足する場合に限り、GGUFの保存先を分ける選択肢として、Mac側のUSB4／Thunderbolt対応と必要容量を確認して検討します。

手元のGGUFを使う場合は絶対pathで指定すると、current directoryの取り違えを減らせます。

llama-cli \
  -m /Users/your-name/models/model.gguf \
  -p "日本語で三つの要点にまとめてください" \
  -n 128

起動logでMetal backend、model metadata、context設定を確認します。chat modelではGGUF内のchat templateが使える場合がありますが、配布元のmodel cardも照合してください。

llama-serverをローカルで試す

llama-server \
  -hf ggml-org/Qwen3.5-0.8B-GGUF \
  --host 127.0.0.1 \
  --port 8080

source build版では./build/bin/llama-serverを使います。別terminalからhealth endpointを確認します。

curl --fail http://127.0.0.1:8080/health

model loading中はHTTP 503、readyになると200と{"status":"ok"}が返る仕様です。127.0.0.1に限定したまま試し、外部公開はTLSと認証を設計してから行います。

Metalを含む性能を比較する

llama-benchはprompt processingとtext generationを分けて測れます。source build版の例です。

./build/bin/llama-bench \
  -m /Users/your-name/models/model.gguf \
  -p 512 \
  -n 128 \
  -r 5

比較時はGGUF、llama.cpp commit、prompt token数、生成token数、context、温度状態、電源状態を固定します。llama-benchの測定はtokenizationとsamplingの時間を含まないため、application全体の応答時間とは一致しません。

CPUとの比較が必要なら、同じbinaryとGGUFで--device none（llama-benchは-dev none）を使う実行も測ります。実際に利用できるoptionは対象binaryの--helpで確認してください。

Python wrapperを使う場合

llama-cpp-pythonは別repository・別release cycleのprojectです。2026年6月6日の固定commitにある公式READMEのMetal build指定はGGML_METALです。

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
CMAKE_ARGS="-DGGML_METAL=on" python -m pip install llama-cpp-python

この手順はPython package側の固定READMEに基づく例であり、llama.cpp v0.2.0とのすべての組み合わせを保証しません。問題調査ではPython package versionとbundleされたllama.cpp commitも記録します。

よくある問題

Metalが使われているか分からない

起動logとbuild optionを確認します。まずdefault buildを使い、CPU限定の--device noneとの実測差を比較します。

modelを読み込めない

file path、download完了、GGUF metadata、対応model architectureを確認します。古いbinaryなら、いきなり最新版へ置き換えず、別directoryで対象releaseをbuildして比較します。

memory不足で終了する

より小さいmodelまたは量子化、短いcontext、少ない並列数で切り分けます。固定のmemory見積もりではなく、起動logと実使用量を確認してください。

情報源と未検証範囲

2026-06-06: llama-cpp-python公式README（commit 7f16fe1963bbca25b7b8f59410153d46d48dea0f）
2026-08-21: llama.cpp v0.2.0 stable release
2026-08-22: Homebrew formula（stable 0.2.0）
2026-08-23確認: v0.2.0 build document、install document、README

未検証: macOS version別のbuild可否、Homebrew formulaの実際のinstall結果、個別GGUFの互換性、download量、Metal・CPUの速度、unified memory使用量、発熱、llama-cpp-pythonとの組み合わせは実機確認していません。