llama.cpp で LLM を実行する

はじめに

llama.cpp は、LLM を実行するための軽量で高性能な C/C++ 実装です。NVIDIA Jetson などの ARM64 デバイスをはじめとするコンシューマーハードウェアで効率的な LLM 推論を可能にします。その効率性と幅広いフォーマットサポートにより、ローカル LLM 推論のデフォルト標準となっています。

Ollama は llama.cpp のユーザーフレンドリーなラッパーですが、llama.cpp を直接理解することで、以下のような利点があります:

  • 推論パラメータの最大限の制御
  • LLM の内部動作のより深い理解
  • 特定のユースケースに最適化できる
  • カスタム量子化フォーマットのサポート

llama-cpp

llama.cpp の特徴

機能説明
純粋な C/C++ヘビーな依存関係がなく、占用面積が小さい
複数のバックエンドCPU、CUDA、Metal、OpenCL、Vulkan サポート
GGUF フォーマット量子化モデルのネイティブサポート
埋め込み可能アプリケーションに簡単に統合できる
CPU フォールバックGPU がなくても動作
ストリーミングリアルタイムトークンストリーミング

Jetson へのインストール

前提条件

ビルドツールがインストールされていることを確認してください:

bash
# パッケージリストの更新
sudo apt-get update

# ビルド essentials のインストール
sudo apt-get install -y build-essential git cmake

# CUDA 環境変数を .bashrc に追加
echo '
# CUDA Environment
export CUDA_HOME=/usr/local/cuda
export PATH=$CUDA_HOME/bin:$PATH
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH
export CUDACXX=$CUDA_HOME/bin/nvcc
' >> ~/.bashrc

# シェル設定をリロード
source ~/.bashrc

# CUDA インストールを確認
nvcc --version

llama.cpp のクローンとビルド

bash
# リポジトリをクローン
cd ~
git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp

# Jetson 用の CUDA サポートでビルド
#make -j$(nproc) GGML_CUDA=1

# 代替手段:CMake を使用
mkdir build && cd build
cmake .. -DGGML_CUDA=ON
cmake --build . --config Release -j$(nproc)

builded_llamacpp

インストールの確認

bash
# バイナリがビルドされたか確認
ls ~/llama.cpp/build/bin/llama-cli

# バージョンをテスト
~/llama.cpp/build/bin/llama-cli --version

llama_v

最初のモデルを取得する

llama.cpp は GGUF フォーマット(GGML Universal Format)を使用します。これは量子化モデルを保存するための効率的なバイナリフォーマットです。

モデルをダウンロードする

bash
# models ディレクトリを作成
mkdir -p ~/llama.cpp/models
cd ~/llama.cpp/models

# Llama 3.2 3B をダウンロード(Q4_K_M 量子化 - 4ビット)
wget https://huggingface.co/bartowski/Llama-3.2-3B-Instruct-GGUF/resolve/main/Llama-3.2-3B-Instruct-Q4_K_M.gguf

# または curl を使って Hugging Face からダウンロード
huggingface-cli download bartowski/Llama-3.2-3B-Instruct-GGUF Llama-3.2-3B-Instruct-Q4_K_M.gguf --local-dir ./models

GGUF 量子化の理解

量子化ビット数ファイルサイズ品質速度
Q2_K2ビット非常に小さい低い最速
Q3_K_M3ビット小さい許容可能非常に高速
Q4_K_M4ビット中程度良好高速
Q5_K_M5ビット中程度〜大非常に良好中程度
Q6_K6ビット大きい優秀やや遅い
Q8_08ビット非常に大きい元に近く最遅

Jetson デバイス向け:

  • Orin Nano 4GB:Q2_K または Q3_K_M を使用
  • Orin Nano 8GB:Q3_K_M または Q4_K_M を使用
  • Orin NX 16GB+:Q4_K_M または Q5_K_M を使用

Jetson 推奨モデル

bash
# Qwen3 4B をダウンロード(優れた多言語サポート)
wget https://huggingface.co/bartowski/Qwen3-4B-Instruct-GGUF/resolve/main/Qwen3-4B-Instruct-Q4_K_M.gguf

# DeepSeek-R1 1.5B をダウンロード(蒸留推論モデル)
wget https://huggingface.co/bartowski/DeepSeek-R1-Distill-Qwen-1.5B-GGUF/resolve/main/DeepSeek-R1-Distill-Qwen-1.5B-Q4_K_M.gguf

# Gemma3 4B をダウンロード
wget https://huggingface.co/bartowski/gemma-3-4b-it-GGUF/resolve/main/gemma-3-4b-it-Q4_K_M.gguf

基本的な使用方法

シンプルなテキスト生成

bash
cd ~/llama.cpp

# 基本的な推論
./build/bin/llama-cli \
  -m models/Llama-3.2-3B-Instruct-Q4_K_M.gguf \
  -p "The future of edge AI is"

チャットモード(会話)

bash
# インタラクティブなチャットセッションを開始
./build/bin/llama-cli \
  -m models/Llama-3.2-3B-Instruct-Q4_K_M.gguf \
  -cnv \
  --chat-template llama3

注意-cnv フラグは会話モードを有効にし、--chat-template は会話のフォーマット方法を指定します。

一般的な llama-cli フラグ

フラグ説明
-m, --modelモデルファイルパス-m models/model.gguf
-p, --prompt初期プロンプト-p "Hello world"
-cnv会話モード-cnv
-n, --n-predict生成するトークン数-n 256
-c, --ctx-sizeコンテキストサイズ(トークン単位)-c 4096
--temp温度(創造性)--temp 0.7
--top-p核サンプリング--top-p 0.9
-ngl, --n-gpu-layersオフロードする GPU レイヤー数-ngl 35
-t, --threadsCPU スレッド数-t 4

Jetson GPU 用の最適化

GPU オフロード

モデルレイヤーを GPU にオフロードすると、パフォーマンスが劇的に向上します:

bash
# 最適な GPU レイヤー数を決定
# -ngl 999 から開始(すべてのレイヤーをオフロード)
./build/bin/llama-cli \
  -m models/Llama-3.2-3B-Instruct-Q4_K_M.gguf \
  -p "Explain quantum computing" \
  -ngl 35 \
  -n 256

ヒント-ngl 999 を使用すると、可能なすべてのレイヤーを自動的に GPU にオフロードします。

パフォーマンス測定

bash
# パフォーマンス統計で実行
./build/bin/llama-cli \
  -m models/Llama-3.2-3B-Instruct-Q4_K_M.gguf \
  -p "What is the capital of France?" \
  -n 50 \
  -ngl 35 \
  --perf

llamacpp_test

重要な指標:トークンあたりの評価時間は良好なリアルタイムパフォーマンスのために 100ms 未満である必要があります。

高度な機能

API サーバーの実行

llama.cpp には REST API アクセス用のサーバーモードが含まれています:

bash
# サーバーを起動
./llama-server \
  -m models/Llama-3.2-3B-Instruct-Q4_K_M.gguf \
  --host 0.0.0.0 \
  --port 8000 \
  -ngl 35 \
  -c 4096

サーバーにアクセス:

bash
# シンプルクエリ
curl -X POST http://localhost:8000/completion \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Once upon a time",
    "n_predict": 100
  }'

# チャット補完
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "What is machine learning?"}
    ],
    "max_tokens": 256
  }'

システムプロンプト

システムプロンプトでモデルの動作を設定:

bash
./llama-cli \
  -m models/Llama-3.2-3B-Instruct-Q4_K_M.gguf \
  -p "You are a helpful coding assistant. Explain Python list comprehensions." \
  --system "You are an expert Python programmer. Provide concise, practical code examples."

バッチ処理

複数のプロンプトを効率的に処理:

python
# batch_inference.py
import subprocess
import json

prompts = [
    "Explain neural networks",
    "What is GPU acceleration?",
    "Describe edge computing"
]

model_path = "~/llama.cpp/models/Llama-3.2-3B-Instruct-Q4_K_M.gguf"

for prompt in prompts:
    result = subprocess.run(
        ["./llama-cli", "-m", model_path, "-p", prompt, "-n", "100", "--temp", "0.7"],
        capture_output=True,
        text=True
    )
    print(f"Prompt: {prompt}")
    print(f"Response: {result.stdout}\n")

モデルを GGUF に変換する

Hugging Face 形式(PyTorch/SafeTensors)のモデルをお持ちの場合は、GGUF に変換できます:

bash
cd ~/llama.cpp

# Python 要件をインストール
pip install -r requirements.txt

# Hugging Face モデルを GGUF に変換
python convert_hf_to_gguf.py \
  /path/to/model \
  --outfile output-model.gguf \
  --outtype q4_k_m

利用可能な出力タイプ:

  • f16:16 ビット浮動小数点(量子化なし)
  • q8_0:8 ビット量子化
  • q6_k:6 ビット量子化
  • q5_k_m:5 ビット量子化
  • q4_k_m:4 ビット量子化(推奨バランス)
  • q3_k_m:3 ビット量子化
  • q2_k:2 ビット量子化(最大圧縮)

統合例

Python バインディング

bash
# Python バインディングをインストール
pip install llama-cpp-python

# CUDA サポート用(Jetson)
CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python --upgrade --force-reinstall --no-cache-dir
python
from llama_cpp import Llama

# モデルを読み込む
llm = Llama(
    model_path="/path/to/model-Q4_K_M.gguf",
    n_gpu_layers=35,
    n_ctx=4096
)

# テキストを生成
output = llm(
    "Q: What is the capital of France?\nA:",
    max_tokens=50,
    temperature=0.7
)
print(output["choices"][0]["text"])

# チャット補完
output = llm.create_chat_completion(
    messages=[
        {"role": "user", "content": "Tell me a joke"}
    ],
    max_tokens=100
)
print(output["choices"][0]["message"]["content"])

パフォーマンスベンチマーク

Jetson 固有の最適化

bash
# Jetson Orin Nano 8GB の最適な設定
./llama-cli \
  -m models/Llama-3.2-3B-Instruct-Q4_K_M.gguf \
  -p "Explain transformers in machine learning" \
  -ngl 35 \
  -t 6 \
  -c 4096 \
  -n 200 \
  --temp 0.7

ベンチマークスクリプト

bash
#!/bin/bash
# benchmark.sh

MODEL="models/Llama-3.2-3B-Instruct-Q4_K_M.gguf"
PROMPT="Explain the concept of artificial intelligence and its applications."

echo "Benchmarking llama.cpp on Jetson"
echo "Model: $MODEL"
echo "Prompt: $PROMPT"
echo ""

for gpu_layers in 0 10 20 30 35; do
    echo "Testing with $gpu_layers GPU layers..."
    timeout 120 ./llama-cli \
        -m $MODEL \
        -p "$PROMPT" \
        -ngl $gpu_layers \
        -n 100 \
        --per-test 2>&1 | grep "eval time"
done

一般的な問題と解決策

問題 1:CUDA が検出されない

問題:GPU オフロードが動作しない

解決策

bash
# CUDA で再ビルド
make clean
make -j$(nproc) GGML_CUDA=1

# CUDA インストールを確認
nvidia-smi
nvcc --version

問題 2:メモリ不足

問題:モデルの読み込みが OOM で失敗

解決策

bash
# GPU レイヤーを削減
./llama-cli -m model.gguf -ngl 10  # -ngl 35 の代わりに

# 小さいコンテキストを使用
./llama-cli -m model.gguf -c 2048  # デフォルトの 4096 の代わりに

# より積極的な量子化を使用
# Q5_K_M から Q4_K_M または Q3_K_M に切り替え

問題 3:CPU のみのパフォーマンスが遅い

問題:GPU なしでの生成が遅すぎる

解決策

bash
# 更多的スレッドを有効にする
./llama-cli -m model.gguf -t 8  # 8 CPU スレッドを使用

# より小さいモデルまたはより積極的な量子化を使用

# CPU ガバナーがパフォーマンスに設定されていることを確認
sudo apt-get install cpufrequtils
sudo cpufreq-set -g performance

実践演習

以下のタスクを完了してください:

  1. CUDA サポートで llama.cpp をビルド する
  2. 3つの異なるモデルをダウンロード し、サイズを比較する
  3. 各モデルで -ngl 35 を使用して 推論を実行 する
  4. --perf フラグを使用して パフォーマンスを測定 する
  5. サーバーを起動 し、API リクエストをテストする
  6. 5つの異なるプロンプトをバッチ処理する Python スクリプトを作成 する

参考文献


次へモジュール 5.4: vLLM による高性能推論 で本番グレードの LLM Serving を学びましょう!