mlx

Apple Silicon で LLM に MLX を使用する

MLX-LM は、MLX フレームワークを活用してユニファイドメモリアーキテクチャでパフォーマンスを最適化し、Apple Silicon 上で大規模言語モデルを実行するための Python パッケージです。

目次

• コアコンセプト
• インストール
• テキスト生成
• 対話型チャット
• モデル変換
• 量子化
• LoRA によるファインチューニング
• モデルのサービング
• ベストプラクティス
• 参考資料

コアコンセプト

MLX を選ぶ理由

項目	Mac 上の PyTorch	MLX
メモリ	CPU/GPU ごとに個別のコピー	ユニファイドメモリでコピー不要
最適化	汎用 Metal バックエンド	Apple Silicon ネイティブ
モデルの読み込み	遅く、より多くのメモリを使用	遅延読み込みで効率的
量子化	サポートが限定的	4/8 ビットを標準サポート

MLX 配列は共有メモリ上にあり、データ転送のオーバーヘッドなしに CPU と GPU の両方からアクセスできます。

サポート対象モデル

MLX-LM は、Llama、Mistral、Qwen、Phi、Gemma、Cohere など、一般的なアーキテクチャのほとんどをサポートしています。Hugging Face の mlx-community で、変換済みモデルをご確認ください。

インストール

pip install mlx-lm

macOS 13.5 以降と Apple Silicon（M1/M2/M3/M4）が必要です。

テキスト生成

Python API

from mlx_lm import load, generate

# Load model (from HF hub or local path)
model, tokenizer = load("mlx-community/Llama-3.2-3B-Instruct-4bit")

# Generate text
response = generate(
    model,
    tokenizer,
    prompt="Explain quantum computing in simple terms:",
    max_tokens=256,
    temp=0.7,
)
print(response)

ストリーミング生成

from mlx_lm import load, stream_generate

model, tokenizer = load("mlx-community/Mistral-7B-Instruct-v0.3-4bit")

prompt = "Write a haiku about programming:"
for response in stream_generate(model, tokenizer, prompt, max_tokens=100):
    print(response.text, end="", flush=True)
print()

バッチ生成

from mlx_lm import load, batch_generate

model, tokenizer = load("mlx-community/Qwen2.5-7B-Instruct-4bit")

prompts = [
    "What is machine learning?",
    "Explain neural networks:",
    "Define deep learning:",
]

responses = batch_generate(
    model,
    tokenizer,
    prompts,
    max_tokens=100,
)

for prompt, response in zip(prompts, responses):
    print(f"Q: {prompt}\nA: {response}\n")

CLI での生成

# Basic generation
mlx_lm.generate --model mlx-community/Llama-3.2-3B-Instruct-4bit \
    --prompt "Explain recursion:" \
    --max-tokens 256

# With sampling parameters
mlx_lm.generate --model mlx-community/Mistral-7B-Instruct-v0.3-4bit \
    --prompt "Write a poem about AI:" \
    --temp 0.8 \
    --top-p 0.95

対話型チャット

CLI チャット

# Start chat REPL (context preserved between turns)
mlx_lm.chat --model mlx-community/Llama-3.2-3B-Instruct-4bit

Python チャット

from mlx_lm import load, generate

model, tokenizer = load("mlx-community/Llama-3.2-3B-Instruct-4bit")

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "What's the capital of France?"},
]

prompt = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True
)

response = generate(model, tokenizer, prompt=prompt, max_tokens=256)
print(response)

モデル変換

Hugging Face のモデルを MLX 形式に変換します。

CLI 変換

# Convert with 4-bit quantization
mlx_lm.convert --model meta-llama/Llama-3.2-3B-Instruct \
    -q  # Quantize to 4-bit

# With specific quantization
mlx_lm.convert --model mistralai/Mistral-7B-Instruct-v0.3 \
    -q \
    --q-bits 8 \
    --q-group-size 64

# Upload to Hugging Face Hub
mlx_lm.convert --model meta-llama/Llama-3.2-1B-Instruct \
    -q \
    --upload-repo your-username/Llama-3.2-1B-Instruct-4bit-mlx

Python 変換

from mlx_lm import convert

repo = "meta-llama/Llama-3.2-3B-Instruct"
convert(
    repo,
    quantize=True,
    mlx_path="./llama-3.2-3b-mlx",
    q_bits=4,
    q_group_size=64,
)

変換オプション

オプション	デフォルト	説明
--q-bits	4	量子化ビット数（4 または 8）
--q-group-size	64	量子化のグループサイズ
--dtype	float16	量子化しない重みのデータ型

量子化

MLX は、さまざまな用途に対応する複数の量子化方式をサポートしています。

方式	最適な用途	コマンド
Basic	すばやい変換	mlx_lm.convert -q
DWQ	品質の維持	mlx_lm.dwq
AWQ	アクティベーションを考慮	mlx_lm.awq
Dynamic	レイヤーごとの精度	mlx_lm.dynamic_quant
GPTQ	実績のある方式	mlx_lm.gptq

すばやい量子化

# 4-bit quantization during conversion
mlx_lm.convert --model mistralai/Mistral-7B-v0.3 -q

# 8-bit for higher quality
mlx_lm.convert --model mistralai/Mistral-7B-v0.3 -q --q-bits 8

各方式の詳細については、reference/quantization.md をご覧ください。

LoRA によるファインチューニング

MLX は、Apple Silicon 上で効率的に適応させるための LoRA と QLoRA によるファインチューニングをサポートしています。

クイックスタート

pip install "mlx-lm[train]"

# Prepare training data (JSONL format)
# ./data/train.jsonl is required for --train
# ./data/valid.jsonl is optional
# Supported rows include {"text": "..."} and chat {"messages": [...]}

# Fine-tune with LoRA
mlx_lm.lora --model mlx-community/Llama-3.2-3B-Instruct-4bit \
    --train \
    --data ./data \
    --iters 1000

# Completion-only loss for chat/completion datasets
mlx_lm.lora --model mlx-community/Llama-3.2-3B-Instruct-4bit \
    --train \
    --data ./data \
    --mask-prompt

# Generate with adapter
mlx_lm.generate --model mlx-community/Llama-3.2-3B-Instruct-4bit \
    --adapter-path ./adapters \
    --prompt "Your prompt here"

アダプターをモデルに統合する

# Merge LoRA weights into base model
mlx_lm.fuse --model mlx-community/Llama-3.2-3B-Instruct-4bit \
    --adapter-path ./adapters \
    --save-path ./fused-model

# Or export to GGUF
mlx_lm.fuse --model mlx-community/Llama-3.2-3B-Instruct-4bit \
    --adapter-path ./adapters \
    --export-gguf

LoRA の詳細な設定とトレーニングパターンについては、reference/fine-tuning.md をご覧ください。

MLX-LM は、標準的な LoRA よりも高い容量が必要なタスク向けに、--fine-tune-type dora と --fine-tune-type full もサポートしています。

モデルのサービング

OpenAI 互換サーバー

# Start server
mlx_lm.server --model mlx-community/Llama-3.2-3B-Instruct-4bit --port 8080

# Use with OpenAI client
curl http://localhost:8080/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "default",
        "messages": [{"role": "user", "content": "Hello!"}],
        "max_tokens": 256
    }'

Python クライアント

from openai import OpenAI

client = OpenAI(base_url="http://localhost:8080/v1", api_key="not-needed")

response = client.chat.completions.create(
    model="default",
    messages=[{"role": "user", "content": "Explain MLX in one sentence."}],
    max_tokens=100,
)
print(response.choices[0].message.content)

ベストプラクティス

1. 量子化済みモデルを使用する：Hugging Face の mlx-community からダウンロードすれば、すぐに使用できます。

2. ハードウェアに合わせて量子化を選ぶ：8GB の M1/M2 では 4-bit を使用します。M2/M3 Pro/Max では、品質を重視する場合は 8-bit を使用します。

3. ユニファイドメモリを活用する：CUDA とは異なり、MLX モデルはスワップを使用することで「GPU メモリ」を超えて動作できます（速度は低下しますが、動作します）。

4. UX のためにストリーミングを使用する：stream_generate を使うと、インタラクティブなアプリケーションで応答性の高い出力が得られます。

5. プロンプトのプレフィックスをキャッシュする：サフィックスだけが異なるプロンプトを繰り返し使う場合は、mlx_lm.cache_prompt を使用します。

6. 長い生成では KV キャッシュを制限する：長距離の品質を犠牲にしてメモリを制限するには、--max-kv-size を使用します。

7. 類似したリクエストをバッチ処理する：batch_generate は逐次生成より効率的です。

8. 4-bit 量子化から始める：品質とサイズのバランスに優れています。品質に問題がある場合は 8-bit に切り替えます。

9. デプロイ時にアダプターを統合する：ファインチューニング後、アダプターを統合すると、個別に読み込まずに推論を高速化できます。

10. アクティビティモニタでメモリを監視する：スワップの過剰な使用を避けるため、メモリプレッシャーを確認します。

11. チャットテンプレートを使用する：指示チューニング済みモデルでは、必ず tokenizer.apply_chat_template() を適用します。

参考資料

詳細なドキュメントについては、reference/ を参照してください。

• quantization.md - 量子化方式の詳細と、それぞれの使いどころ
• fine-tuning.md - データ形式と設定を含む、LoRA/QLoRA トレーニングの完全ガイド

外部ドキュメント：

• MLX-LM GitHub
• MLX-LM LoRA ガイド