Qwen3.8-27B のゼロからのインストール：Mac でのローカルデプロイとパフォーマンスチューニングガイド

Qwen3.8-27B が登場

通常の Mac でも実行できる可能性が出てきました。

メモリ、速度、コンテキスト——

このガイドで一度にすべて説明します。

最近、2 つのニュースが重なりました。

8 月 14 日、Qwen3.8-27B が正式にウェイトを公開しました。その 2 週間足らず後、Apple は M5 Max と M5 Ultra を搭載した新しい Mac Studio をリリースし、ローカル AI パフォーマンスと最大 512GB のユニファイドメモリを強調しました。

これらの紹介を読むと、Mac で Qwen3.8-27B を実行するには、最新の Mac Studio を購入する必要がある、あるいは Ultra を直接選ぶべきだという錯覚に陥りがちです。

実際には、それほど大げさな話ではありません。

これまで、27B Dense モデルは確かにローカルユーザーの第一選択肢ではありませんでした。Dense モデルの特徴は、生成されるトークンごとに、すべての主要パラメータを読み取って計算する必要があることです。24GB クラスのデバイスでは、量子化後でもメモリに収まるのがやっとで、初期のコミュニティテストでは、1 秒あたり一桁から低い二桁のトークン数しか出ないことがよくありました。

対照的に、35B-A3B のような MoE モデルは、総パラメータ数は多いものの、生成ごとに約 3B のパラメータしかアクティブにならないため、数倍高速になる可能性があります。コードを継続的に読み取り、ツールを呼び出し、ファイルを繰り返し修正する必要があるエージェントにとっては、モデルの能力がどんなに高くても、毎ラウンドに時間がかかると、日常的なツールにはなりにくいです。そのため、これまで多くのローカルユーザーは MoE を優先していました。

現在、状況は変わり始めています。

量子化フォーマット、Apple Silicon 推論フレームワーク、そして新しい世代のデコード高速化手法が徐々に成熟し、27B Dense モデルが能力と速度のバランスを取る初めての機会を得ています。必ずしも最新の Ultra は必要ありません。24GB および 32GB の Mac は 4 ビット版から始められ、48GB 以上のものはより柔軟な選択肢があります。

本当の問題は、もはや「ロードできるか」だけではなく、量子化バージョンの選び方、コンテキストとメモリの制御方法、そして生成速度を実際に使えるように調整する方法です。

この記事では、再現可能なデプロイをゼロから完了します。まずメモリ要件を計算し、次に加速なしの基本速度を実行し、最後に同じタスクで A/B テストを実施し、OpenAI および Anthropic クライアントが呼び出せるローカル API としてモデルを起動します。

今すぐデプロイする予定がない場合は、まずブックマークしておくことをお勧めします。後でより大きなメモリの Mac にアップグレードするとき、またはローカルモデルをコードエージェント、ナレッジベース、自動化ワークフローに接続する準備をするときに、このガイドに従ってください。

結論から: あなたの Mac は実行できますか？

ユニファイドメモリだけを見て、この表で判断できます:

この表は「モデルが起動できるか」の絶対的な境界ではなく、「安定して動作できるか」の提案です。

一部の 24GB Mac は確かに 4 ビットをロードできますが、ロードに成功したからといって長期使用に適しているとは限りません。macOS、ブラウザ、開発ツール、モデル実行バッファ、コンテキストキャッシュ、そして DFlash 2 ドラフトモデルはすべて、同じユニファイドメモリを競合します。起動時にはモデルは問題なく見えても、長いコードを入力した後にスワップが発生し始めるのが最も一般的な障害です。

さらに、このチュートリアルは Apple Silicon にのみ適用されます。これには M1、M2、M3、M4、M5 シリーズの Mac が含まれます。Intel Mac はこの MLX ルートに従いません。

27B とは正確には何か？よくある誤解を正す

モデル名の 'B' は Billion を意味します。

つまり、27B は約 270 億パラメータを意味し、2700 億ではありません。

パラメータは、トレーニング後に保持される大きな数値のセットと考えてください。モデルが生成するトークンごとに、これらの数値を読み取って計算し、次のトークンを決定する必要があります。27B は、270 億のノブを持つ機械のようなものです。トレーニングはノブを正しい位置に調整する役割を担い、ローカル推論はこれらのノブをメモリにロードして継続的に読み取る役割を担います。

Qwen3.8-27B は Dense モデルです。Dense は簡単に言うと、生成されるトークンごとに、主要パラメータが計算に参加することを意味します。

これは、名前に A3B や A10B が含まれる MoE モデルとは異なります。たとえば、35B-A3B モデルは合計で 350 億のパラメータを保存する可能性がありますが、毎回約 30 億のパラメータしかアクティブになりません。すべてのウェイトのストレージスペースを準備する必要はありますが、トークンあたりの計算とメモリ読み取りははるかに少なくなります。

したがって、2 つのモデルが両方とも「約 30B」と言っているからといって、速度、メモリ使用量、能力レベルが類似していると想定することはできません。総パラメータ数、アクティブパラメータ数、モデルアーキテクチャ、量子化精度をすべて一緒に考慮する必要があります。

Qwen3.8-27B は、従来の「すべての層でフルアテンション」を行うモデルではありません。公式モデルカード によると、64 の層で構成され、Gated DeltaNet と Gated Attention のハイブリッドアーキテクチャを使用しています。おおよそ 3 層の線形アテンションごとに 1 層の標準アテンションが挿入されます。ネイティブで 262,144 トークンのコンテキストをサポートし、画像およびビデオ理解機能を備え、デフォルトで思考モードが有効になっており、reasoning_effort を通じて推論の深さを調整できます。

これらの機能は、コード、研究、長時間のタスク、エージェントに適している理由を説明しています。また、デプロイ時に単に「27B」だけを見てはいけない理由も説明しています。

その能力はどの程度ですか？

パソコン上のローカルモデルを大まかに分類すると:

• 3B–8B: 起動が速く、占有量が少なく、一般的な Q&A、簡単な抽出、軽量なツール呼び出しに適しています。複雑なタスクでは脱線しやすいです。
• 14B–30B: 現在最も実用的な高品質範囲で、コード生成、長文処理、構造化分析、エージェントワークを確実に処理し始めます。
• 70B 以上の Dense: 全体的な安定性は多くの場合優れていますが、メモリ容量と帯域幅の要件が大幅に増加し、個人でのデプロイコストがはるかに高くなります。

Qwen3.8-27B は、「個人デバイスが現実的にデプロイでき、能力が本番ワークフローに十分である」という位置にあります。

公式モデルカードでは、SWE-bench Pro で 61.7、Terminal Bench 2.1 で 73.0 をスコアしました。同じ表で、Opus 4.6 Max はそれぞれ 53.4 と 78.2 でした。この結果は、一部のコーディングおよびターミナルエージェントタスクにおいて、Qwen3.8-27B がクローズドソースのフラッグシップと同列に議論される資格があることを示しています。

しかし、これを「27B がクローズドソースのフラッグシップを完全に凌駕する」と書き換えないでください。

ベンチマークは、プロンプト、サンプリングパラメータ、ツール環境、テストフレームワーク、推論予算の影響を受けます。公式モデルカードは、異なるテストに使用されたハーネスも開示しています。スコアが高いということは、特定のテスト条件下でより良いパフォーマンスを発揮したことを意味するだけであり、知識の広さ、オープンエンドな推論、長文安定性、視覚能力、実際のワークフローでリードしていることを意味するわけではありません。

より正確な位置づけは、クローズドソースのフラッグシップを完全に置き換えるものではありませんが、真剣に仕事をこなせるローカルモデルであるということです。

本当の決定要因はメモリ計算

多くの人は「モデルパラメータ数」を「実行メモリ」に直接結び付けます。27B だから 27GB 必要だと。

この計算は間違っています。パラメータ数に、各パラメータが占めるビット数を掛ける必要があります。

270 億パラメータのおおよその計算:

• BF16: 1 パラメータあたり 2 バイト、元のウェイトは約 54GB。
• 8 ビット: 1 パラメータあたり約 1 バイト、理論値は約 27GB。
• 4 ビット: 1 パラメータあたり約 0.5 バイト、理論値は約 13.5GB。

理論値は主要なウェイトのみをカウントします。実際のモデルリポジトリには、量子化スケール、設定、語彙、ビジュアルコンポーネントなども含まれます。Hugging Face 上の MLX コミュニティバージョンは、4 ビットで約 16.1GB、8 ビットで約 29.5GB です。テキスト BF16 コミュニティ変換は、約 54GB と明示的に述べています。

これは単に「ファイルのサイズ」であり、「起動後の占有量」ではありません。モデルは実行時に少なくとも 4 種類のスペースを消費します。

1. コンテキストキャッシュ

モデルは既に読んだ内容を記憶する必要があります。そうしないと、新しいトークンごとにすべてをゼロから再計算する必要があります。標準アテンション部分は KV Cache を使用し、線形アテンション層には独自の状態があります。

コンテキストが長くなるほど、キャッシュは大きくなります。mlx-dspark プロジェクトのテストによると、Qwen3.8-27B の 128K コンテキストでは、キャッシュが約 11GB 追加される可能性があります。フル 256K コンテキストでは、約 23GB 追加される可能性があります。

これが、「モデルが 262K をサポートする」ことが、24GB Mac が 262K を開くべきだという意味ではない理由です。能力の限界はモデルが処理できるものであり、あなたのマシンの快適なデフォルトではありません。

2. 実行バッファと一時アクティベーション

モデルが長いプロンプトを読み取る段階は Prefill と呼ばれます。この段階では、大量の入力を一度に処理する必要があり、メモリと計算の負荷が急上昇する可能性があります。「hello」と言っただけのメモリスナップショットは、20,000 トークンのコードを貼り付けた後の状況を表していません。

3. macOS およびその他のアプリケーション

Apple Silicon の CPU と GPU はユニファイドメモリを共有します。これは MLX の効率性の基盤であり、メモリ予算を控えめにする必要がある理由でもあります。モデル、システム、Chrome、Cursor、Docker、その他のプログラムはすべて、同じプール内のスペースを競合します。

4. DFlash 2 ドラフトモデル

DFlash 2 は無料のスイッチではありません。追加のドラフトモデルと対応するキャッシュをロードする必要があります。プロジェクトは、ピークチャット長の参考値を提供しています。4 ビットターゲットモデルとドラフトで約 18GB、8 ビットで約 29GB です。これでも macOS 用のスペースは確保されていません。

したがって、完全な式は次のようになります:

実際のメモリ = モデルウェイト + コンテキストキャッシュ + 実行バッファ + ドラフトモデル + macOS およびその他のアプリ

この式を理解することは、ブロガーのコンピュータの速度を覚えることよりも重要です。

4 ビット、8 ビット、BF16: どのように選ぶか？

量子化は、モデルパラメータをよりコンパクトに記録することと理解できます。ビット数が低いほど、モデルはメモリを節約し、通常は高速になります。代償として、ある程度の精度が失われます。

一般的な Mac ユーザーには、次のように選択することをお勧めします:

24GB / 32GB: 直接 4 ビットから始める

モデルリポジトリ:

1mlx-community/Qwen3.8-27B-4bit

4 ビットファイルは約 16.1GB です。24GB は試せますが、大規模なバックグラウンドアプリケーションを積極的に閉じ、8K–16K のコンテキストから始める必要があります。32GB の方が日常的な使用に適しています。

24GB だから「ロードできる」という理由で、超長コンテキストと DFlash 2 を際限なく積み重ねないでください。まず安定して動作させ、その後で変数を 1 つずつ追加してください。

48GB / 64GB: 8 ビットを検討

モデルリポジトリ:

1mlx-community/Qwen3.8-27B-8bit

8 ビットファイルは約 29.5GB です。48GB は現実的な出発点であり、64GB の方が快適です。速度、コンテキストスペース、システムマージンをより重視する場合は、64GB でも 4 ビットを引き続き使用できます。「より高精度」という理由だけで 8 ビットを強制する必要はありません。

BF16: 「収まる」を「使用に適している」と扱わない

BF16 テキストウェイトは既に約 54GB です。64GB Mac は理論的には収まりますが、システム、キャッシュ、バッファを追加すると、マージンは非常に小さくなります。実際の長期使用には、96GB 以上を検討する方が良いでしょう。

ほとんどの人にとって、4 ビットと 8 ビットの体験の差は、「メモリ不足によるスワップの開始」によって生じる差よりもはるかに小さいです。継続的なスワップが発生すると、どんな量子化精度も応答速度を救えません。

デプロイ前の準備: チップ、メモリ、ディスクを確認

まず、ターミナルを開いてマシン情報を確認します:

1system_profiler SPHardwareDataType

Apple M シリーズチップとユニファイドメモリ容量を確認する必要があります。

次にディスクを確認します:

1df -h .

モデルボリュームの少なくとも 2 倍の空き容量を確保することをお勧めします。ダウンロードプロセスではキャッシュが生成され、その後ドラフトモデル、複数の量子化バージョン、ログが続きます。4 ビットの場合は 35GB 以上、8 ビットの場合は 60GB 以上の空き容量を準備するのが最善です。

このチュートリアルでは、Python 環境の管理に uv を使用します。インストールされていない場合:

1brew install uv

独立したディレクトリと仮想環境を作成します:

1mkdir -p qwen38-local/models
2cd qwen38-local
3
4uv venv .venv
5source .venv/bin/activate

これの利点は、「プロフェッショナルに見える」ことだけでなく、MLX、Transformers、その他のプロジェクト間の依存関係の相互汚染を回避できることです。後で使用したくない場合は、このプロジェクトディレクトリを削除するだけです。

必要なツールをインストールします:

1uv pip install -U huggingface_hub mlx-dspark

mlx-dspark は現在、Apple Silicon と Python 3.10 以上を必要とし、mlx-lm、mlx-vlm、および適切な MLX 依存関係を自動的にインストールします。

モデルのダウンロード: ブラウザでファイルを 1 つずつクリックしない

大規模モデルは通常、複数のウェイトシャードに分割されています。ブラウザで 1 つずつダウンロードすると、中断、ファイル欠落、再開の不便さが発生しやすくなります。より信頼性の高い方法は、公式の Hugging Face hf コマンドを使用することです。

4 ビットダウンロードコマンド

1MODEL_DIR="$PWD/models/Qwen3.8-27B-4bit"
2
3hf download mlx-community/Qwen3.8-27B-4bit \
4  --local-dir "$MODEL_DIR"

8 ビットダウンロードコマンド

1MODEL_DIR="$PWD/models/Qwen3.8-27B-8bit"
2
3hf download mlx-community/Qwen3.8-27B-8bit \
4  --local-dir "$MODEL_DIR"

新しいバージョンの Hugging Face Hub は Xet チャンクダウンロードを使用し、デフォルトでネットワークに基づいて適応的な同時実行数になります。ほとんどの人は、以前のチュートリアルから古い hf_transfer 設定をコピーする必要はありません。

この「高性能ダウンロード」スイッチも表示される可能性があります:

1HF_XET_HIGH_PERFORMANCE=1 hf download ...

盲目的に有効にしないでください。Hugging Face の公式ドキュメントによると、同時実行数、バッファリング、CPU 使用率が増加し、少なくとも 64GB のメモリを搭載した高帯域幅マシンにより適しています。低メモリ Mac では、リソース競合により実際には遅くなる可能性があります。24GB および 32GB のマシンは、最初にデフォルト設定を使用する必要があります。

ダウンロード後、ディレクトリサイズを確認します:

1du -sh "$MODEL_DIR"

初回実行: まず基本速度をテストし、DFlash 2 を急いで有効にしない

ローカルモデルをデプロイする際の最も一般的な間違いは、10 個の最適化オプションを一度にオンにすることです。最終的に高速に実行されるかもしれませんが、誰のおかげかわかりません。遅い場合は、誰をオフにすればいいかわかりません。

正しい順序は、最初にベースラインを実行することです。

固定プロンプトを準備します。できれば実際の作業に近いものが良いです。たとえば、主にコーディングに使用する場合は、次を使用できます:

1Please implement a thread-safe cache in Python that supports expiration time and LRU eviction. Explain the design first, then provide the full code and tests.

ベースラインテスト:

1mlx-dspark generate \
2  --model "$MODEL_DIR" \
3  --mode baseline \
4  --prompt "Please implement a thread-safe cache in Python that supports expiration time and LRU eviction. Explain the design first, then provide the full code and tests." \
5  --max-new-tokens 600

4 つの数値を記録します:

1. モデルロード時間。
2. プロンプト処理速度 (Prefill tok/s)。
3. 最初のトークンまでの時間 (TTFT)。
4. 正式な生成速度 (generation tok/s)。

生成速度は「単語が 1 つずつ出てくる速さ」を決定しますが、Prefill と TTFT は「Enter キーを押した後の待ち時間」を決定します。コードエージェントの場合、毎ラウンドで大量のシステムプロンプトとコードを再読み取りする必要がある可能性があるため、Prefill は純粋な生成速度よりもユーザーエクスペリエンスに影響を与えることがよくあります。

テスト中は、「アクティビティモニタ → メモリ」も開いて、メモリプレッシャーとスワップを観察します。黄色はすぐに問題があるとは限りませんが、スワップが増加し続ける場合は、この構成に安定したマージンがないことを意味します。

50 トークンだけ実行しないでください。短い回答では、ロードとウォームアップ時間の割合が高くなりすぎ、継続生成中の真の速度がわかりません。少なくとも 400～1000 トークンを生成することをお勧めします。

DFlash 2 はどのように 27B を高速化するのか？

通常のデコードはシリアルです。Qwen3.8-27B が 1 つのトークンを生成し、フルターゲットモデルが 1 回実行されます。次のトークンを生成し、また実行されます。1000 トークンを生成するには、約 1000 回の連続ラウンドが必要です。

DFlash 2 は、より軽量なドラフトモデルを追加します。ドラフトモデルはまず、並列で一連の候補トークンを提案し、その後 27B メインモデルがそれらをまとめて検証します。正しい推測は一度に複数受け入れられ、間違ったものはメインモデルによって修正されます。

次のように考えることができます:

• ドラフトモデルは、迅速な下書きを担当するアシスタントです。
• 27B メインモデルは、最終決定権を持つ編集長です。
• アシスタントが連続して正しく推測するほど、編集長が担当するフルラウンドは少なくなります。

ドラフトモデルが出力を独立して決定することはありません。DFlash 2 モデルカードによると、グリーディデコードでは、出力はターゲットモデルと一致します。ランダムサンプリング中は、ターゲットモデルの分布を維持します。

また、すべてのシナリオで高速化が保証されているわけでもありません。

タスクによってドラフトモデルが予測しやすい場合、たとえばコード補完や安定したフォーマットの長文などでは、受入長は通常高くなります。内容が大きく飛躍する場合、回答が非常に短い場合、またはサンプリングのランダム性が高い場合、ドラフトは拒否されることが多く、余分な計算が利得を消費する可能性があります。

DFlash 2 の有効化: ツールに自己調整させ、他人のパラメータをコピーしない

まず、プロジェクトに組み込まれているベンチマークを実行します:

1mlx-dspark benchmark \
2  --model "$MODEL_DIR" \
3  --modes dflash \
4  --caps auto \
5  --trials 3

ここで明示的に --modes dflash を指定します。現在のバージョンのベンチマークはデフォルトで DSpark と lookup をテストし、Qwen3.8-27B の DFlash 2 に自動的に切り替わらないためです。初回実行時には、一致するドラフトモデルがダウンロードされます。--caps auto は、Mac、ターゲットモデル、量子化バージョンに基づいて適切なドラフトキャップをテストします。M1 Max、M4 Pro、M5 Max はメモリ帯域幅と計算コストが異なるため、最適なパラメータはまったく同じであるべきではありません。

したがって、誰かが --max-draft 7 と書いているのを見たからといって、それを恒久的にコピーすることはお勧めしません。自動キャリブレーションに最初に答えを出させ、その後実際のタスクで再テストしてください。

同じプロンプトを使用して自動モードを有効にします:

1mlx-dspark generate \
2  --model "$MODEL_DIR" \
3  --mode auto \
4  --prompt "Please implement a thread-safe cache in Python that supports expiration time and LRU eviction. Explain the design first, then provide the full code and tests." \
5  --max-new-tokens 600

次に、ベースラインと比較します:

• 出力テキストは一貫していますか？
• TTFT が大幅に長くなりましたか？
• generation tok/s はどの程度向上しましたか？
• 平均受入長はどのくらいですか？
• ピークメモリとスワップは悪化しましたか？

これらのコマンドはデフォルトでグリーディデコードを使用するため、ベースラインと auto の出力テキストは、非常にまれな浮動小数点の同点の場合を除いて、一貫している必要があります。回答が大幅に異なる場合は、速度について議論する前に、プロンプト、思考モード、サンプリングパラメータ、ソフトウェアバージョンが同一であるかどうかを確認してください。ランダムサンプリング中、DFlash 2 はターゲット分布を維持しますが、2 回生成された特定の単語が同一であることを保証するものではありません。

mlx-dspark プロジェクト の M4 Pro 48GB でのプロジェクトベンチマークでは、8 ビットは約 8.4 tok/s から 30.5 tok/s に向上し、平均約 3.63 倍でした。4 ビットは約 14.7 tok/s から 33.8 tok/s に向上し、平均約 2.30 倍でした。

これらは、特定のバージョン、マシン、ホットスタート状態、テストプロンプトでの結果であり、約束ではありません。プロジェクト自身の分割データも、チャット、コード、数学タスクで高速化率が異なることを示しています。

本当に役立つ基準は、「他の人が 30 tok/s に達した」ではなく、あなたの高頻度タスクが高速化されたかどうかです。

通常、モデルにコードを修正させる場合は、実際のリポジトリで修正タスクをテストします。記事を書くために使用する場合は、1500 トークンを継続的に生成します。エージェントに接続したい場合は、完全なツール呼び出しを実行します。実際のタスクの合計時間が短縮された場合にのみ、DFlash 2 をオンにしておく価値があります。

モデルをローカル API として起動する

基本モードと自動モードの両方が安定していることを確認したら、モデルを常駐サービスにすることができます。24GB Mac の場合は、まずコンテキストを 8K に制限します:

1mlx-dspark serve \
2  --model "$MODEL_DIR" \
3  --mode auto \
4  --context-window 8192

32GB は 16K から開始し、安定した後、徐々に 32K に増やします:

1mlx-dspark serve \
2  --model "$MODEL_DIR" \
3  --mode auto \
4  --context-window 16384

サービスが開始したら、別のターミナルでステータスを確認します:

1curl http://127.0.0.1:8080/health
2curl http://127.0.0.1:8080/v1/models

/health は実際のモード、コンテキスト制限、メモリ警告を返します。/v1/models は、クライアントが入力する必要のあるモデル ID を提供します。

2 種類のクライアントのアドレスを混同しないでください:

1OpenAI Base URL: http://127.0.0.1:8080/v1
2Anthropic Base URL: http://127.0.0.1:8080
3Anthropic Messages route: /v1/messages

OpenAI と Anthropic の両方の互換性のあるインターフェースを提供します。カスタム Base URL をサポートするチャットクライアント、コードツール、エージェントは通常接続できます。

curl で会話テストを実行します。以下では、4 ビット用に返されたモデル ID を例として使用します。8 ビットをダウンロードした場合は、/v1/models によって返された実際の値に置き換えてください:

1curl http://127.0.0.1:8080/v1/chat/completions \
2  -H "Content-Type: application/json" \
3  -d '{
4    "model": "Qwen3.8-27B-4bit",
5    "messages": [
6      {"role": "user", "content": "Explain what unified memory is in three sentences."}
7    ],
8    "max_tokens": 200
9  }'

ローカルマシンでのみ使用する場合、127.0.0.1 が最も安全で簡単な選択です。一部のクライアントは API Key の入力を強制します。任意のプレースホルダー文字列を入力できます。認証が有効になっていない場合、ローカルサービスはそれを検証しません。

LAN アクセスが必要な場合にのみ、リスニングアドレスとファイアウォールの変更を検討してください。認証、TLS、レート制限なしでインターフェースをパブリックインターネットに直接公開しないでください。モデルがローカルで実行されているからといって、サービスが本質的に安全であるとは限りません。

メモリが爆発しないようにコンテキストを設定する方法

最も信頼性の高い方法は推測ではなく、段階的に増やすことです:

1. 24GB は 8K から開始し、安定したら 16K を試す。
2. 32GB は 16K から開始し、その後 32K を試す。
3. 48GB / 64GB は 32K から開始し、必要に応じて 64K を試す。
4. 本当に超長文書や大規模なコードベースを処理する場合にのみ、128K まで増やす。

レベルを上げるたびに、同じテストを繰り返す：固定プロンプト、固定最大出力、TTFT、生成速度、ピークメモリ、Swap を記録する。

「モデルは 262K をサポート」は能力パラメータであり、デフォルトの推奨ではない。日常のチャット、文章作成、およびほとんどのコーディングタスクでは、16K～32K で既に多くのシナリオをカバーできる。

コンテキストが大きいほど賢いとは限らない。無関係なコンテンツを詰め込みすぎると、重要な情報が薄まり、モデルが遅くなり、コストが高くなり、脱線しやすくなる。

サービスを Agent で使用する場合は、Prefix Cache の保持を優先する。コード Agent のシステムプロンプトやツール定義は非常に長くなることが多く、複数ラウンド間でプレフィックスを再利用することで、繰り返しの Prefill を大幅に削減できる。

思考モードの選び方：テストで最も見落とされがちな変数

Qwen3.8 はデフォルトで回答前に思考する。複雑なコード修正、数学的推論、研究分析、マルチラウンド Agent タスクでは、デフォルトの思考モードを維持できる。一般的なチャット、翻訳、要約、フォーマット変換では、思考プロセスは待ち時間と出力トークンを増やすだけである。

思考を維持しつつ推論の深さを減らしたい場合は、完全なコマンドを使用する：

1mlx-dspark serve \
2  --model "$MODEL_DIR" \
3  --mode auto \
4  --context-window 16384 \
5  --reasoning-effort low

タスクが非常に直接的な場合は、思考をオフにできる：

1mlx-dspark serve \
2  --model "$MODEL_DIR" \
3  --mode auto \
4  --context-window 16384 \
5  --no-thinking

これらの 2 つのパラメータは、サービスのデフォルト動作を設定する。関連フィールドをサポートするクライアントは、リクエストごとにこれらを上書きできるため、ツールを接続した後、クライアントが静かに独自のデフォルトに戻していないか確認する。

すべてのタスクに適した単一の答えはない。「低」は 1 ラウンドあたり高速に見えるかもしれないが、分析不足により Agent が繰り返し再試行し、タスク全体が遅くなる可能性がある。最も信頼できる方法は、最初のラウンドの回答だけを比較するのではなく、タスク全体の合計時間を計算することである。

覚えておくべきルールが 1 つある：ベースラインと DFlash 2 の A/B テストを行う場合、思考モードは同一でなければならない。一方が思考オンで他方がオフの場合、トークン数とタスクパスが変わり、計算された速度に比較意味がなくなる。サンプリングパラメータ、プロンプト、最大出力長、コンテキスト、コールド/ホットスタート状態も一貫している必要がある。

最短デプロイルート：必要なコマンドをまとめて圧縮する

これまで説明してきたのは、各ステップの理由である。原理を理解しており、すぐに再現したいだけなら、以下の順序で実行できる。例では 4 ビットと 8K コンテキストを選択しており、24GB Mac での控えめな開始に適している。ダウンロードとベンチマークの実際の時間はネットワークとチップに依存し、「最短」には含まれない：

1brew install uv
2
3mkdir -p qwen38-local/models
4cd qwen38-local
5uv venv .venv
6source .venv/bin/activate
7
8uv pip install -U huggingface_hub mlx-dspark
9
10MODEL_DIR="$PWD/models/Qwen3.8-27B-4bit"
11hf download mlx-community/Qwen3.8-27B-4bit \
12  --local-dir "$MODEL_DIR"
13
14mlx-dspark generate \
15  --model "$MODEL_DIR" \
16  --mode baseline \
17  --prompt "ユニファイドメモリについて説明し、ローカルで大規模モデルを実行するための 3 つの提案をしてください。" \
18  --max-new-tokens 400
19
20mlx-dspark benchmark \
21  --model "$MODEL_DIR" \
22  --modes dflash \
23  --caps auto \
24  --trials 3
25
26mlx-dspark serve \
27  --model "$MODEL_DIR" \
28  --mode auto \
29  --context-window 8192

この一連のコマンドの目標は「まず安全に実行する」ことであり、ハードウェアを限界まで引き出すことではない。正常に実行できたら、メモリの余裕に応じて 16K と 32K のコンテキストを順に試すか、4 ビットのリポジトリを 8 ビットに置き換える。テストデータに意味を持たせるために、一度に変更する変数は 1 つだけにする。

サービスが起動したら、すぐにサードパーティのクライアントに接続せず、まず /health と /v1/models にアクセスする。前者はメモリ警告がなく、期待されるモードが実際に有効であることを確認し、後者はモデル ID を確認する。次に、約 400 トークンの長い回答を完了し、アクティビティモニタでメモリプレッシャーと Swap を観察する。これら 4 つすべてが正常であれば、Base URL を日常のツールに入力する。この数分間のチェックで、ほとんどの「クライアントが接続できない」「しばらく実行するとマシン全体が遅くなる」問題を排除できる。

翌日再起動する方法は？

仮想環境と MODEL_DIR は、現在のターミナルセッションでのみ有効である。翌日ターミナルを開き直すときは、再ダウンロードや再インストールは不要。ディレクトリに戻り、環境をアクティベートし、パスを再宣言するだけ：

1cd qwen38-local
2source .venv/bin/activate
3MODEL_DIR="$PWD/models/Qwen3.8-27B-4bit"
4
5mlx-dspark serve \
6  --model "$MODEL_DIR" \
7  --mode auto \
8  --context-window 8192

ツールをアップグレードする場合は、仮想環境内で実行する：

1uv pip install -U huggingface_hub mlx-dspark

アップグレード後、まず短いベースラインと /health を実行してモデルがまだロードできることを確認してから、長期サービスを再開する。推論ツールは急速に更新されるため、古いバージョンで機能したパラメータが常に最適とは限らない。独自のベースライン記録を保持することは価値がある。

LAN アクセス：少なくともロックを追加する

デフォルトの 127.0.0.1 はローカルマシンからのみアクセスできる。同じ Wi-Fi 上の別の Mac や iPad から呼び出せるようにするには、すべてのネットワークカードでリッスンし、同時に API Key を設定する：

1mlx-dspark serve \
2  --model "$MODEL_DIR" \
3  --mode auto \
4  --context-window 16384 \
5  --host 0.0.0.0 \
6  --api-key "十分に長いランダムな文字列に置き換えてください"

クライアントは 127.0.0.1 をこの Mac の LAN IP に置き換え、リクエストに Authorization: Bearer your_key を送信する。また、macOS ファイアウォールを確認して、信頼できるネットワークのみがポート 8080 にアクセスできるようにする。

これは依然として LAN ソリューションに過ぎない。インターネット経由でアクセスするには、TLS、リバースプロキシ、アクセス制御、レート制限も必要。ルーターで 8080 を直接マッピングしないでください。最も簡単な方法は、信頼できる VPN を介してホームネットワークに戻り、ローカルサービスにアクセスすることである。

よくある問題のトラブルシューティング

1. ロード中にモデルがシステムによって強制終了される

まず、正しい量子化バージョンを選択したことを確認する。24GB と 32GB は 8 ビットを誤ってダウンロードしてはならず、BF16 には絶対に触れない。Docker、仮想マシン、多数のブラウザタブ、その他のローカルモデルを閉じてから、4 ビットを再試行する。

2. 実行できるが、Mac 全体が非常に遅くなる

アクティビティモニタを開いて Swap を確認する。Swap が上昇し続ける場合は、まずコンテキストを短くし、次に DFlash 2 をオフにする。モデルプロセス自体の数値だけを見ないでください。ユニファイドメモリのプレッシャーはシステム全体によって引き起こされるためである。

3. DFlash 2 が実際には遅い

比較条件が一貫していることを確認する：同じプロンプト、同じ出力長、同じ思考モード、同じコールドスタートまたはホットスタート。短い回答は投機的デコードの利点を判断するのに適さない。3 ラウンド以上実行し、実際の長いタスクでテストする。

それでも遅い場合は、現在のタスクの受理率が低いか、ドラフトモデルによってもたらされた追加メモリがシステムのスワップを開始させたことを意味する。オフにすることは失敗ではない。安定したベースラインはすでに効果的なソリューションである。

4. 最初のトークンは非常に遅いが、その後の生成は問題ない

これは Prefill のボトルネックである。入力が長すぎないか、毎ラウンド大量の無関係なファイルが繰り返し詰め込まれていないか、Prefix Cache がヒットしているかを確認する。Agent の場合、プロンプトの長さを最適化することは、生成 tok/s を追求し続けるよりも効果的であることが多い。

5. ダウンロード速度が非常に遅い、または中断される

同じ hf download コマンドを再実行するだけで、キャッシュと再開機能を利用できる。未完了のディレクトリを削除してゼロから開始しないでください。Hugging Face へのアクセスが不安定な場合は、公式推奨の ModelScope ルートを検討する。

6. 画像を認識させたい

「モデルに視覚能力がある」ことと「現在のサービスが視覚入力をサポートしている」ことを区別する。前述の MLX リポジトリは視覚コンポーネントを保持しているが、mlx-dspark は現在テキスト推論サービスを提供しており、送信された画像コンテンツはモデルに入力されない。

画像をテストするには、一時的に DFlash 2 をバイパスし、代わりに mlx-vlm を使用する必要がある：

1uv run python -m mlx_vlm.generate \
2  --model "$MODEL_DIR" \
3  --max-tokens 200 \
4  --temperature 0 \
5  --prompt "この画像を説明してください。" \
6  --image "/絶対パス/example.jpg"

視覚入力は処理の複雑さとメモリ使用量を増加させる。主な用途がコード、文章作成、Agent である場合は、まずテキストチェーンを安定させ、その後視覚タスクを個別にテストする。

最も失敗しにくいデプロイ手順

実行チェックリスト：

1. Apple Silicon Mac であることを確認する。
2. 16GB では 27B を諦める。24GB/32GB では 4 ビットを選択する。48GB/64GB では 8 ビットを検討する。
3. モデル用に十分なディスク容量を確保し、uv を使用して独立した環境を作成する。
4. hf download を使用して完全なリポジトリをダウンロードする。ブラウザでウェイトファイルを 1 つずつクリックしない。
5. まず --mode baseline で固定プロンプトを実行し、ロード、Prefill、TTFT、生成速度、メモリを記録する。
6. 8K、16K、または 32K のコンテキストから開始する。いきなり完全な 262K を開かない。
7. mlx-dspark benchmark --modes dflash --caps auto --trials 3 を実行し、ツールにマシンを較正させる。
8. ベースラインと auto をまったく同じ実タスクで比較する。
9. 速度が大幅に向上し、メモリプレッシャーが安定している場合にのみ、DFlash 2 を長期的に有効にする。
10. 最後に、ローカル API を起動し、コードツール、ナレッジベース、または Agent に接続する。

ローカルデプロイの意義は、API 費用を節約することだけではない。

Qwen3.8-27B が Mac 上のいつでも呼び出せるローカルサービスになれば、機密のコードやドキュメントを自分のマシンに保持し、オフラインで資料を処理し、自動化タスク、個人ナレッジベース、長時間実行される Agent ワークフローに接続できる。

私自身の合格ラインはシンプルである：一般的なタスクでスワップが発生せず、回答速度が許容範囲であり、翌日も積極的に開く気になる。これら 3 つが満たされて初めて、デプロイは真に成功したと言える。

すでに実行できている方は、コメントに「チップモデル、ユニファイドメモリ、4/8 ビット、コンテキスト長、ベースラインと DFlash 2 の tok/s」を自由に残してください。十分なデータが集まれば、Mac 構成テストテーブルとしてまとめ続けることができます。

それでもデプロイが面倒な場合

この記事で説明したインストールコマンド、モデルダウンロード、速度テスト、DFlash 2 高速化、ローカル API 起動、よくある問題のトラブルシューティングを、直接従えるデプロイチェックリストにまとめました：

1https://github.com/wdwxw/macRunqwen38_27b_install

自分で順番にコピーして実行するか、この GitHub リポジトリを直接 Codex や Claude Code に渡し、README.md を読ませ、Mac の構成を確認させ、チェックリストに従ってインストールを完了させることができます。これにより、長い記事からコマンドを繰り返し探す必要がなくなり、その後の更新やトラブルシューティングもより便利になります。