mcpField
M
mlx-serving

mlx-serving

github.com/aeyeopsクラウド・DevOps411 回インストール9 週間前に更新
リポジトリ

mlx-serving について

mlx-servingは、Apple Siliconでmlx-lmとoMLXを使ったローカルLLM推論の運用ガイドです。運用担当者がバックエンドを選び、障害を診断し、ベンチマークを基に設定を調整できます。

主な機能

  1. 01mlx-lmとoMLXのバックエンド案内
  2. 02環境とバックエンドの確認
  3. 03症状に基づくトラブルシューティング
  4. 04機能フラグの調整指針
  5. 05ベンチマークと品質確認

活用シーン

  1. 01ローカル推論用バックエンドの選択
  2. 02メモリや起動障害の診断
  3. 03ツール呼び出しやバッチ処理の調査
  4. 04設定変更の効果測定

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/aeyeops/aeo-skill-marketplace --skill mlx-serving

インストール後、Claude Code で/mlx-servingを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
bench-methodology.md
omlx-feature-flags.md
symptoms.md
upstream-bug-patterns.md

詳細

Apple Silicon LLM サービング（MLX / oMLX）

Apple Silicon（Mシリーズ）上でローカル LLM 推論を実行、調整するための運用ガイダンスです。一般的な 2 つのバックエンド、Apple の mlx-lm と MLX を基盤に構築された oMLX サーバーを扱います。

どちらも OpenAI 互換の HTTP API を公開するため、クライアントコードを共通化できます。違いは機能、パッケージング、ユニファイドメモリの限界近くまでモデルを動かしたときに発生する障害の種類にあります。

実行前の確認：環境を検証する

サービングに関する問題のデバッグを始める前に、基本事項を確認してください。

# Hardware: confirm Apple Silicon and unified-memory size
system_profiler SPHardwareDataType | grep -E "Model|Chip|Memory"

# Activate the venv where mlx-lm is installed before the next two probes,
# otherwise they hit system Python and may report nothing useful.
python -c "import mlx.core as mx; print(mx.__version__, mx.default_device())"
python -c "import mlx_lm; print(mlx_lm.__version__)"

# oMLX (DMG install): inspect available subcommands and run health checks
omlx --help
omlx diagnose menubar   # checks Tahoe ControlCenter visibility (oMLX-specific)

# Confirm a process is actually listening
lsof -nP -iTCP -sTCP:LISTEN | grep -E "omlx|mlx_lm"

デバッグの前に、どのバックエンドがバインドされているかを確認してください。どちらもユーザーが指定したポートで OpenAI 互換のエンドポイントを提供できます。クライアントからのリクエストが誤ったバックエンドに到達すると、一見正しそうでも無関係な出力が返されます。

バックエンドの選択：mlx-lm と oMLX

懸念事項mlx-lmoMLX
インストールpip install mlx-lmDMG（macOS アプリバンドル）
プロセスモデルmlx_lm.server プロセスあたり 1 モデル組み込みレジストリ、複数モデル
設定項目最小限の CLI フラグモデルごとの豊富な JSON（model_settings.json）
機能フラグ--temp、--top-p、基本機能turboquant_kv、dflash、MTP、specprefill、thinking budget
ツール呼び出し形式はチャットテンプレートによって異なりますモデルごとのパーサー（設定可能）
RAM を超えるモデル非対応（ロード時に OOM）OptiQ プロキシビルド（感度に基づく量子化）
GUIなしネイティブ macOS アプリ + メニューバー
デフォルトポート80808000
最適な用途ライブラリ中心のスクリプト、Python への組み込み長時間稼働するデーモン、複数モデル、GUI 操作

スキルの重点： ここでは oMLX をより詳しく扱い、機能フラグ、キャッシュ制御、上流のバグパターンを取り上げます。mlx-lm の説明は簡潔で、共通基盤に重点を置いています。

次の場合は mlx-lm を選んでください：Python プロセスを制御でき、設定項目を最小限にしたく、一度に 1 つのモデルをサービングし、モデルが RAM に十分収まる場合。

次の場合は oMLX を選んでください：ターミナルのセッション終了後も稼働するデーモンが必要で、1 つのエンドポイントの背後で複数モデルをサービングし、自分で実装することなく機能フラグ（turboquant、dflash、MTP）を使いたい場合、またはモデルが RAM を超えるため OptiQ プロキシが必要な場合。

どちらのバックエンドにも、ユニファイドメモリ、KV キャッシュの負荷、モデルアーキテクチャ固有の挙動など、根本的な制約は共通しています。そのため、このスキルのトラブルシューティングの大部分はどちらにも当てはまります。

症状 → 原因の切り分け

症状考えられる原因最初に行うこと
モデルのロード中に OOMモデル + KV スクラッチ領域が利用可能な RAM を超過より小さい量子化モデルを使う、OptiQ プロキシ（oMLX）を使う、ほかのアプリを終了する
長いコンテキストの推論中に OOMKV キャッシュの増加turboquant_kv を有効にする。SSD への退避には --paged-ssd-cache-dir を設定する（実際の制御に使われるのは CLI フラグです。dflash_* キーはバージョン依存の上書き設定です）
バッチサイズが 1 より大きいとクラッシュ／ハングするアーキテクチャとキャッシュの形状が一致しない--max-concurrent-requests 1 を指定する（oMLX）。upstream-bug-patterns を参照
ツール呼び出しがプレーンテキストのコンテンツとして返されるパーサーがモデルのツール呼び出し JSON 形式を認識しないupstream-bug-patterns を参照し、レスポンスの tool_calls フィールドを確認する
設定変更後にスループットが低下する機能フラグの相互作用ベンチマークを使い、フラグを 1 つずつ切り分ける
サーバーが起動時にハングするコールドディスクからの大きなチェックポイントの読み込み待機する。server.log の末尾を確認し、iostat でディスク I/O を確認する
出力が誤っている／文字化けする量子化が強すぎる、またはチャットテンプレートが誤っているturboquant_kv_bits の値を下げるか無効にする。チャットテンプレートがモデルカードと一致することを確認する
最初のリクエストは遅く、以降は速いプレフィックスキャッシュがコールド状態specprefill を有効にし、ダミーリクエストでキャッシュをウォームアップする
出力が文の途中で途切れるmax_tokens が低すぎる、または思考予算を使い切ったmax_tokens を増やし、thinking_budget_enabled を確認する

各症状の詳細な切り分けについては、references/symptoms.md を参照してください。

基本原則

  1. バッチ処理に弱いアーキテクチャでは、--max-concurrent-requests を 1 に下げます。 oMLX の --max-concurrent-requests のデフォルト値は 8 です。同時実行数が大きいと、アーキテクチャ固有のバッチ処理に関するバグが表面化します（特に、Llama-4 で使用される ChunkedKVCache などのキャッシュ実装）。該当するアーキテクチャでは、起動時の同時実行数を 1 に固定し、バッチサイズが 1 を超えても問題なく出力されることを確認してから、段階的に引き上げてベンチマークします。

  2. フラグは一度に 1 つだけ変更します。 フラグ同士は影響し合います（例：dflash と turboquant_kv はどちらも KV キャッシュの処理経路に影響します）。2 つのフラグを同時に変更して性能低下が見られた場合、原因の特定は不可能になります。変更ごとにベンチマークを実行してください。

  3. 推測せずにベンチマークします。 「速くなった気がする」は、チューニングの判断材料にはなりません。小規模なベンチマークスイート（チャット／コーディング／ツール呼び出しの正確性とスループット）を用意し、設定を変更するたびに再実行してください。references/bench-methodology.md を参照してください。

  4. チャットテンプレートはモデルカードに合わせます。 ツール呼び出しや推論の動作は、リクエスト時に適用されるチャットテンプレートに依存します。モデルの HuggingFace カードを基準にしてください。

  5. 量子化はオン／オフではなく、段階的に調整するものです。 turboquant_kv_bits=4.0 では品質の大部分が保たれます。ビット数を下げると、品質と引き換えにメモリを節約できます。ベンチマークスイートには必ず品質評価項目を含めてください。スループットの基準を満たしてもコーディングに失敗する設定は、遅くても正しく動作する設定より劣る場合があります。

  6. OptiQ プロキシは「モデルサイズが RAM を超える」場合にのみ使用します。 モデル全体をメモリに保持せずにレイヤーごとの量子化設定を決定できるよう、感度に基づいたモデルのプロキシを構築します。一般的な高速化機能ではありません。モデルが RAM に収まる場合、実行時のメリットはなく、起動コストだけが増加します。

  7. サーバー側のバグが設定の問題に見えることがあります。 複数の設定の組み合わせで同じ症状が再現する場合は、フラグをさらに試すのではなく、上流の問題を疑ってください。references/upstream-bug-patterns.md を参照してください。

参考資料

  • references/symptoms.md — 診断と修正方法を含む症状のトリアージ（OOM、バッチサイズが 1 を超える場合のクラッシュ、テキストとして出力されるツール呼び出し、スループットの低下、ログのトリアージ）
  • references/omlx-feature-flags.md — フラグごとのリファレンス（turboquant_kv、dflash、MTP、specprefill、thinking budget、max-concurrent-requests、force_sampling）と相互作用
  • references/bench-methodology.md — 推測せずにベンチマークする方法：スイートの設計、バックエンドに依存しないハーネスの構成、スコアリング、変更の影響の特定
  • references/upstream-bug-patterns.md — 上流の問題と設定の問題を見分ける方法、繰り返し発生する 2 つのバグパターン（バッチスケジューリング時のキャッシュ形状の不一致、モデルのツール呼び出し形式が解析されない問題）と、診断および報告のガイダンス

このスキルの対象外

  • クラウドでの LLM ホスティング（Bedrock、OpenAI API、Anthropic API）— 対象とする範囲がまったく異なります
  • MLX 以外のローカルバックエンド（llama.cpp、Ollama、vLLM）— 問題領域は重なりますが、使用するツールは異なります
  • モデルのトレーニング、ファインチューニング、LoRA — MLX のトレーニングチュートリアルを参照してください
  • MLX に関係しない一般的な Python／HTTP のデバッグ
  • モデルカードの作成や HuggingFace へのアップロードのワークフロー

コメント

Markdown 対応