Apple Silicon 上の MLX LM

Libre WebUI には、M シリーズ Mac 上で MLX 形式の言語モデルを直接実行するための MLX LM (Apple Silicon) プラグインが含まれています。このプラグインは、MLX LM に組み込まれた OpenAI 互換 HTTP API へ接続します。

この方法は、MLX チェックポイントを Ollama や GGUF モデルへ変換せず、ネイティブの Metal 推論を利用したい場合に適しています。

アーキテクチャ

Libre WebUI in native development mode
  frontend http://localhost:5173
  backend  http://localhost:3001
                  |
                  | OpenAI-compatible chat request
                  v
mlx_lm.server http://127.0.0.1:8081
                  |
                  v
MLX model on Apple Silicon unified memory

ポート 8081 は意図的な指定です。MLX LM の既定値は通常 8080 で、パッケージ版の npx libre-webui サーバーと競合します。

要件

• Apple Silicon Mac（M1 以降）。
• Xcode コマンドラインツールを利用できる macOS。
• Python 3.10 以降。
• 選択したモデル、その KV キャッシュ、macOS に十分なユニファイドメモリ。
• ネイティブ実行中の Libre WebUI。両方のバックエンドが Mac のループバックインターフェイスを使えるため、ソースからの開発ワークフローが最も簡単です。

既定の Ternary Bonsai モデルはディスク上で約 8.5 GB あり、実行中はさらに多くのメモリを必要とします。ユニファイドメモリ 16 GB の Mac でも短いコンテキストなら処理できますが、実用上は 24 GB 以上の方が余裕があります。メモリが厳しい場合は小さい MLX チェックポイントを使い、そのリポジトリ ID をコピーしたプラグイン定義に追加してください。

MLX LM のインストール

uv を使うと、Homebrew の Python パッケージからコマンドを隔離できます。

brew install uv
uv tool install --upgrade mlx-lm
rehash
mlx_lm.server --help

ツールがすでに存在する場合:

uv tool upgrade mlx-lm
rehash

Qwen 3.5 モデルには mlx-lm 0.30.7 以降が必要です。リポジトリの例には 0.31.3 以降が必要です。

サーバーの起動

Ternary Bonsai モデルの場合:

mlx_lm.server \
  --model "prism-ml/Ternary-Bonsai-27B-mlx-2bit" \
  --host 127.0.0.1 \
  --port 8081 \
  --max-tokens 262144 \
  --allowed-origins "http://localhost:5173,http://127.0.0.1:5173"

初回実行時に Hugging Face からモデルをダウンロードします。それ以降はローカルキャッシュを使います。Ternary Bonsai が宣言する最大位置数は 262144 です。プロンプトと生成出力はこのコンテキストウィンドウを共有するため、サーバーの許容量をモデルの最大値に設定していても、プロンプトが長いほど生成可能なトークン数は減ります。

小さい入門モデルの場合:

mlx_lm.server \
  --model "mlx-community/Llama-3.2-3B-Instruct-4bit" \
  --host 127.0.0.1 \
  --port 8081 \
  --max-tokens 2048

リポジトリには再利用可能なランチャーも含まれています。

cd examples/mlx-lm-server
uv run server.py

モデルを読み込まず、解決されたコマンドを確認します。

uv run server.py --dry-run

OpenAI 互換 API の確認

正常性とモデル検出を確認します。

curl http://127.0.0.1:8081/health
curl http://127.0.0.1:8081/v1/models

非ストリーミングのチャットリクエストを送信します。

curl http://127.0.0.1:8081/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "prism-ml/Ternary-Bonsai-27B-mlx-2bit",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Reply with: MLX is ready."}
    ],
    "temperature": 0.7,
    "top_p": 0.95,
    "max_tokens": 64,
    "stream": false
  }'

"stream": true の場合、サーバーは Server-Sent Events によるストリーミングにも対応します。

Libre WebUI への接続

Libre WebUI リポジトリのルートから実行します。

npm install
npm run dev

http://localhost:5173 を開き、次の操作を行います。

1. 設定 > プラグインを開きます。
2. MLX LM (Apple Silicon) を探します。
3. エンドポイントが http://127.0.0.1:8081/v1/chat/completions であることを確認します。
4. プラグインを有効にします。ローカル MLX には API キーは不要です。
5. チャットへ戻り、MLX モデルを選択します。

組み込みのモデル一覧には次が含まれます。

• prism-ml/Ternary-Bonsai-27B-mlx-2bit

Libre WebUI で選択するモデルは、MLX サーバーで利用可能なモデルと一致する必要があります。別のチェックポイントを使うには、plugins/mlx-lm.json をエクスポートまたはコピーし、リポジトリ ID を model_map に追加して、編集した定義を設定 > プラグインからインポートします。

生成設定

公開されている Ternary Bonsai の推奨値は次のとおりです。

設定	値
Temperature	0.7
Top P	0.95
Top K	20

Libre WebUI は temperature と Top P をプラグイン経由で送信します。推奨される Top K を使う場合は、--top-k 20 を指定してサーバーを起動します。

mlx_lm.server \
  --model "prism-ml/Ternary-Bonsai-27B-mlx-2bit" \
  --host 127.0.0.1 \
  --port 8081 \
  --top-k 20 \
  --max-tokens 262144

Work とツール呼び出し

MLX プラグインは OpenAI 互換チャット形式を使うため、Work に表示されることがあります。モデルとそのチャットテンプレートが OpenAI 形式のツール呼び出しに確実に対応している場合にだけ、Work で選択してください。チャットで通常のテキスト生成が動作しても、そのチェックポイントがツールに対応している証拠にはなりません。

ツールパーサーとモデルテンプレートは急速に変化します。Work の実行が不正なツール呼び出しを返す場合は、mlx-lm を更新し、同じツールリクエストをサーバーへ直接送ってテストし、MLX のモデルカードにツール利用が明記されているモデルを試してください。

Docker ネットワーク

Libre WebUI はネイティブの開発環境で実行することを推奨します。コンテナから Mac の 127.0.0.1 には到達できません。

Libre WebUI を Docker で実行する場合:

1. --host 0.0.0.0 を指定して MLX LM を起動します。
2. プライベートな Mac の LAN アドレス（http://192.168.1.20:8081/v1/chat/completions など）をプラグインのエンドポイントに使います。
3. ポート 8081 を信頼できるローカルネットワークだけに許可します。

mlx_lm.server を公開インターネットへ直接公開しないでください。メンテナーは、基本的なセキュリティチェックだけを備えたローカルサーバーだと説明しています。ローカル以外へデプロイする場合は、認証済み HTTPS リバースプロキシを前段に置いてください。

トラブルシューティング

Model type qwen3_5 not supported

古いランチャーがまだ使われています。

rehash
which -a mlx_lm.server
uv tool upgrade mlx-lm

Libre WebUI にモデルは表示されるが、リクエストが失敗する

同じモデル ID が直接利用できることを確認します。

curl http://127.0.0.1:8081/v1/models

次に、プラグインのエンドポイントに /v1/chat/completions が含まれていることを確認します。

アドレスがすでに使用されている

Libre WebUI は通常のポートのままにして、MLX を移動します。

mlx_lm.server --model "owner/model" --port 8082

プラグインのエンドポイントを http://127.0.0.1:8082/v1/chat/completions に更新します。

最初のリクエストでモデルが遅い

初期読み込みとプロンプトのプリフィルは、トークン単位の生成より多くのリソースを使います。アクティビティモニタでメモリプレッシャーを確認し、macOS がスワップを始めたら小さいモデルまたは短い会話を選んでください。

関連ドキュメント

• プラグイン
• モデルの利用
• ハードウェア要件
• Work: 隔離ワークスペース