Splash 1.3.0でQwen3.8-27Bのプリフィルとキャッシュを設定する

Qwen3.8-27BのモデルIDを指定してSplashを起動すると、重みと対応するDFlash2を準備します。完了するとローカルアドレスへの質問を処理し、回答を返します。

長いコードや文書を送ると、モデルは入力を読み込んでから最初のトークンを出します。この入力処理をプリフィルと呼びます。その後のデコード⁷では、回答を一語ずつ生成します。Splash 1.3.0は対応する高密度モデルの長いプリフィルにNeural Engineを使い、Qwen3.8-27Bの回答生成はGPUで処理します。

長い入力の後に最初のトークンが遅い場合はNeural Engineによるプリフィルを比べ、回答がゆっくり続く場合はデコード速度を別に確認します。Splashは起動時にMacとモデルに合わせて調整し、入力の長さごとに処理を分担します。

Apple M3以降のMac、macOS 26.4以降、Homebrewが必要です。Qwen3.8-27Bの4ビット版には統合メモリ36GB以上が必要で、48GBを推奨します。初回はモデルと補助モデルをダウンロードするため、保存容量とネット接続も用意してください。

まずHomebrewでインストールし、1つ目のターミナルでサーバーを起動します。サーバーを実行したままReadyと表示されるまで待ち、以下のAPI確認は2つ目のターミナルで行います。

サーバーのターミナルにReadyと表示されたら、ブラウザーでhttp://127.0.0.1:8000を開きます。Splashのチャット画面から質問を送り、回答を受け取れます。標準ではMac内のローカルアドレスで待ち受けます。ターミナルを閉じるかCtrl+Cを押すとサーバーが停止します。

2つ目のターミナルから下のAPIリクエストを送り、モデルまで接続できるか確認します。返されたJSONのchoices配列に回答文があれば、リクエストは処理されています。

oMLX 0.7.1rc1ではモデル一覧とAPIを保ったまま推論をSplashへ任せられます。Splash 1.3.0以降を導入し、Settings → Integrations → External enginesを開きます。検出された実行ファイルのパスと版が表示されたら、Qwen3.8-27Bのモデルフォルダーとz-lab/Qwen3.8-27B-DFlash2を用意します。

1.3.0ではmlx-community/Qwen3.8-27B-4bitなど、affine 4bit・group 64のMLX⁸チェックポイント⁹を使います。1.3.1はmixed-bitにも対応します。oMLXの外部エンジンには、従来のincoai/*-Splash事前パッケージではなく対応するMLXファイルを指定します。

Model Settings → AdvancedでUse external engineを有効にしてSplashを選びます。oMLXがローカルポートとAPIキーを管理し、別プロセスとして起動します。短い質問を送り、ダッシュボードのprefill進行と生成速度を確認します。起動しない場合はIntegrationsのパス、モデル形式、drafterのファイルを順に調べてください。

メモリ上限、KV精度、SSDキャッシュ、Neural Engine prefillはSplashのIntegrations項目で調整します。Splashでは同エンジンのDFlash2とキャッシュ設定を使います。他のoMLXモデルに設定したLightning MTP¹⁰やTurboQuantはそのままにし、同じ文書をSplashと標準エンジンで実行してTTFT¹¹と完了時間を比べます。

--disable-aneを付けない場合、Splash 1.3.0は対応する高密度モデルのFFN計算をGPUとNeural Engineに分けます。起動時にMacとモデルに合わせて分担を調整し、効果が見込める入力長を選んで設定を記憶します。評価に失敗した場合や時間切れ、無効な計算結果が出た場合は、その部分をGPUで再計算します。

Splash 1.3.0のリリースに記録されたQwen3.8-27Bの測定です。MLX 4ビットの重みを使い、リクエスト1件、キャッシュを再利用しない14,096トークン入力でプリフィルと最初のトークンまでの時間（TTFT）を比べています。M5 MaxはGPUのみで14.09秒、GPUとNeural Engineの併用で12.36秒、M5 Proはそれぞれ28.28秒、21.57秒でした。TTFTは入力処理から最初のトークン出力までの時間です。回答生成の速さとは分けて比べます。

プリフィルの分担にはKVキャッシュ¹²用のメモリも使います。そのため、長文入力に使えるコンテキスト上限はGPUのみの場合より低くなることがあります。Macの起動時の要約と/statusのmaximum_context_tokensを確認してください。回答が続く速さはデコード処理量で別に比べます。

同じ文書や指示を含む追加の質問では、冒頭部分を読み直すことがあります。Splash 1.3.0は長い共通部分を含む会話で、処理済みのプリフィル状態を再利用し、2つ目の会話が分岐する位置から処理を続けられます。19Kトークンを共有する公開例では、2つ目の会話のTTFTが39.6秒から6.3秒に短縮され、16,384トークンを再利用しました。

この測定では27Bモデルの復元地点1つにつき、187MiBのメモリを追加で使いました。ディスクキャッシュを有効にすると、メモリから退避した状態をSSDに書き込めます。--max-cache-disk 16Gのように容量を指定すると、現在のサーバー起動中にSSDを使います。再起動後も残すには--persistent-cacheを追加してください。

まずディスク関連の設定を加えず、同じ長文書を含む会話を2つ送り、共通部分が再利用されるか確認します。メモリ不足が続く、または状態が退避される場合に限り、SSDの空き容量を確認してディスクキャッシュを追加します。SSDキャッシュでコンテキスト上限は増えません。作業データより割当容量が小さいと、読み書きが繰り返されることがあります。

再利用されるキャッシュ量は、入力の共通部分の長さによって変わります。同じモデル、文書、質問を2回送り、初回と再質問のTTFTを別々に記録してください。

まずprefix・SSDキャッシュの再利用条件をそろえます。同じモデルと長い入力でGPU＋Neural EngineのTTFTを記録し、--disable-aneを付けて再起動してGPU単体を測ります。各設定の初回と反復実行を分け、調整・コンパイル時間の影響も確認します。

Neural Engineの初回起動では、プログラムのコンパイルと処理分担の調整に時間がかかる場合があります。/statusのane_ffnには分担状態、比率、最小入力単位、評価回数、GPUで再実行した回数が表示されます。短い入力で効果が見込めない場合は、GPUのみの経路が自動選択されます。

サーバーが起動しない場合は、ターミナルの最初のエラーとmacOSのバージョンを確認します。ブラウザーがつながらない場合は、Readyの表示と8000番ポートの使用状況を確認してください。コンテキスト長が原因でモデルを起動できない場合は、起動時の要約と/statusで自動上限を調べ、必要なら--max-contextを下げます。Neural Engineが不安定な場合や比較条件を固定したい場合は、--disable-aneでGPUのみのプリフィルに切り替えます。

同じ長文入力でNeural Engine使用時のTTFTが短くなり、必要なコンテキスト長も確保できるなら標準設定を使います。コンテキストが足りない、または結果が安定しない場合は--disable-aneでGPUのみを選びます。

初回のsplash serveでは、指定したQwenの重みと対応するDFlash2補助モデルの重みをHugging Faceから取得します。Qwen3.8-27Bの4-bit例では、両方合わせて最大約21GBの保存容量を使うことがあります。進行が止まったように見えたら、サーバーを止める前にターミナルの最後の進行表示とネット接続を確認してください。再実行すると取得済みのファイルを再利用します。

ターミナルにモデルの保存先が見つからないと表示されたら、--modelの値を確認します。このガイドで使うMLXのIDはmlx-community/Qwen3.8-27B-4bitです。非公開または利用申請が必要な保存先には、Hugging FaceにログインするかHF_TOKENを設定してください。モデル名とアクセス権を直して、同じコマンドを再実行します。

重みの取得後にメモリ予算のエラーが出ても、モデルを再ダウンロードする必要はありません。選んだモデルとコンテキスト長がMacのメモリ予算を超えています。--max-contextを下げて再起動してください。メモリ24GBのMacでは、対応モデル一覧からより小さなGGUF¹³版を選びます。