メインコンテンツへスキップ
見出し画像

DGX SparkでQwen3.8-27Bを動かす-ollamaからvLLMへ移行した話


    ローカルLLM環境を、ollamaからvLLMという構成に切り替えました。

    きっかけは単純で、「もっと速く」「もっと同時に使えるように」という欲が出てきたからです。ollamaは一人で使う分には手軽で快適なのですが、複数人が同時にアクセスすると途端に詰まってしまいます。共有ツールとして使うなら、そこを何とかしたいと思っていました。

    結果的に、思っていたよりずっと長い道のりになりました。この記事は、その過程で踏んだ落とし穴と、そこから得た教訓の記録です。構成値や実際のログも含めて、できるだけそのまま残します。


    画像

    構成の概要

    ハードウェア: MSI EdgeXpert(OEM版DGX Spark, GB10 Blackwell, 128GB ユニファイドメモリ / 実効約121GB)

    モデル: Qwen/Qwen3.8-27B-FP8(29GB, 262K コンテキスト対応, マルチモーダル)

    推論エンジン: vLLM 0.27.2rc1(spark-vllm-docker 経由)

    Attention backend: FlashInfer(フルアテンション層に適用。詳細は後述)

    KV cache dtype: FP8

    投機的デコーディング: MTP (num_speculative_tokens=3)

    公開ポート: 8888 (API) / 3000 (Open WebUI)

    DGX Sparkは、GPUとメモリが一体になった「ユニファイドメモリ」という仕組みを持つマシンで、公称128GBという大きなメモリ空間をGPUとCPUの両方から使えるのが特徴です。ただし実際にはOSやシステムが一定量を予約するため、アプリケーションから使える実効容量はおおむね121GB前後になります(環境によって多少前後します)。本記事に出てくる構成値やメモリ計算も、この「実効約121GB」を前提にしています。そしてこの一体型メモリという特徴が、後述するトラブルの背景にもなっています。

    Qwen3.8-27B-FP8は、Alibabaが開発しているQwenシリーズの270億パラメータモデルをFP8形式に圧縮したものです。テキストだけでなく画像も理解できるマルチモーダルモデルで、最大26万トークンという大きなコンテキストに対応しています。

    なお、このモデルは全64層すべてが同じアテンションで動くわけではなく、16層がフルアテンション、残り48層がリニアアテンション(定数サイズの状態を持つ再帰型)というハイブリッド構成になっています。この点は起動時には意識しなくても動きますが、後述するKVキャッシュの容量計算(なぜこの構成で24万トークン分ものKVキャッシュが載るのか)を理解するうえでの伏線になるので、頭の片隅に置いておいてください。

    推論エンジンにはvLLMを選びました。ollamaより設定は複雑になりますが、複数リクエストの並列処理や、ツール呼び出し(AIが外部の関数を呼び出す機能)、投機的デコーディングまわりの対応が手厚く、実務で使うにはこちらが向いていると判断しました。


    事前準備

    今回の動作確認環境です。

    バージョン OS: Ubuntu 24.04.4 LTS

    NVIDIA driver: 595.71.05

    Docker: 29.2.1

    nvidia-container-toolkit: 1.19.1

    DGX Sparkにはあらかじめ NVIDIA driver・Docker・nvidia-container-toolkit がセットアップ済みの前提です。未導入の場合はNVIDIAのContainer Toolkitインストールガイドに従って導入してください。GPUがコンテナから見えるかは以下で確認できます。

    docker run --rm --gpus all nvidia/cuda:12.6.0-base-ubuntu24.04 nvidia-smi
    

    dockerコマンドをsudoなしで実行できるようにする

    自分のユーザーがdockerグループに入っていないと、dockerコマンドのたびにpermission deniedになったり、都度sudoが必要になります。以下でグループに追加し、一度ログアウト・ログインし直してください。

    sudo usermod -aG docker $USER
    

    反映されているかはgroupsコマンドで確認できます。出力にdockerが含まれていれば設定完了です。

    LANからのアクセスを許可する

    ファイアウォールが有効な場合、vLLM(8888番)とOpen WebUI(3000番)のポートを開けておく必要があります。ufwを使っている場合の例です。

    sudo ufw status
    sudo ufw allow 8888/tcp
    sudo ufw allow 3000/tcp
    

    spark-vllm-dockerの取得とビルド

    DGX Spark向けにチューニングされたDocker構成であるspark-vllm-dockerを利用しました。単体vLLMをそのままセットアップするより、DGX Spark固有の最適化(fastsafetensorsによるロード高速化など)が組み込まれている分、手間が省けます。

    git clone https://github.com/eugr/spark-vllm-docker.git
    cd spark-vllm-docker
    ./build-and-copy.sh
    

    build-and-copy.shは既定でeugr/spark-vllm:latest(動作確認済みのビルド済みイメージ)をpullします。回線が遅い場合は--use-wheelsを付けるとコンパイル済みのwheelだけをダウンロードする経路になり、フルビルドの20〜40分より短時間で済みます。

    なお、後述の起動スクリプトで使う--load-format fastsafetensorsは高速ロードに有効ですが、READMEには「モデルが利用可能RAMの0.85を超えて占有する場合は使わないこと」という注意書きがあります。今回のQwen3.8-27B-FP8(約29GB)は実効メモリの1/4程度なので問題になりませんが、より大きなモデルへこのスクリプトを流用する際は、この条件に注意してください。

    モデルのダウンロード

    Qwen3.8-27B-FP8(約29GB)は初回起動時にHugging Face Hubから自動的にダウンロードされ、~/.cache/huggingface/hub/に保存されます。事前に個別コマンドで落としておく必要はありませんが、回線速度によっては初回起動がその分長くなります。あらかじめ取得しておく場合は次のようにします。

    pip install -U "huggingface_hub[cli]"
    huggingface-cli download Qwen/Qwen3.8-27B-FP8
    

    ゲート付きモデル(利用申請が必要なモデル)を使う場合はhuggingface-cli loginでトークンを設定してください。今回使用したQwen3.8-27B-FP8はゲートなしで、トークン設定なしで取得できました。


    vLLMにQwen3.8を指定する方法

    起動コマンドの中身に入る前に、「vLLMにどのモデルを使わせるか」をどう指定しているかを整理します。

    モデル識別子とエイリアス

    vllm serveの最初の引数には、Hugging Face Hub上のリポジトリID(組織名/モデル名の形式)をそのまま渡します。

    vllm serve Qwen/Qwen3.8-27B-FP8 ...
    

    ローカルにキャッシュがなければ、この時点で自動的にダウンロードが始まります。

    API上でクライアントから呼ぶ名前は、このリポジトリIDとは別に--served-model-nameで指定します。

    --served-model-name qwen38-27b-fp8
    

    curlやOpenAI SDKから"model": "qwen38-27b-fp8"と指定するのはこちらの名前です。リポジトリIDをそのままAPI名にする必要はなく、短い呼び名を割り当てられます。

    Qwen系列で必要になる追加フラグ

    Qwen3.8-27B-FP8は、モデル名こそ「3.8」ですが、内部的にはQwen3_5ForConditionalGeneration(model_type: qwen3_5)というアーキテクチャで実装されています(Qwen3.5系のアーキテクチャ定義を継承しているためで、config.jsonのarchitecturesもこの名前になっています)。vLLM本体に組み込まれていないモデル定義コードを読み込むため、次のフラグが必須です。

    --trust-remote-code
    

    これを付けないと、モデル固有の実装コードが読み込めずロードに失敗します。

    Qwenファミリー特有の出力形式(reasoning用のタグ、ツール呼び出しのフォーマット)をAPIレスポンスとして正しくパースするために、以下も指定しています。

    --reasoning-parser qwen3
    --tool-call-parser qwen3_coder
    --enable-auto-tool-choice
    

    --reasoning-parser qwen3は、
    モデルが出力する思考過程(reasoning)のタグをreasoning_contentフィールドに分離するためのパーサーです。
    --tool-call-parser qwen3_coderは、
    Qwenのツール呼び出し出力をOpenAI互換のtool_calls形式に変換します。
    --enable-auto-tool-choiceを付けないと、
    そもそもツール呼び出し機能自体が有効になりません。

    これらのパーサー名はモデルファミリーごとに異なります(例えばGLM系ならglm47、MiniMax系ならminimax_m2)。使うモデルに対応したパーサー名を選ぶ必要があります。

    アテンションバックエンドの指定について

    構成表に挙げた通り、今回はFlashInferを使っています。ただし、このモデルは前述のハイブリッド構成のため、FlashInferが効くのはフルアテンションの16層で、残り48層のリニアアテンションは別の(再帰状態を使う)経路で処理されます。

    また、vLLMはモデルに応じてバックエンドを自動選択するため、--attention-backend flashinferの明示指定は本来必須ではありません(公式レシピでも「特別なバックエンド選択は不要」とされています)。今回は挙動を固定したい意図で明示していますが、外しても自動選択で問題なく動きます。

    思考モード(thinking)の制御

    Qwen3.8は応答の前に思考過程を生成する「thinking」機能を持っています。これをオン・オフする指定です。

    --default-chat-template-kwargs '{"enable_thinking": false}'
    

    思考モードをオンにしたい場合は、この行自体を削除するかtrueにします。オンにすると応答が長くなりますが、複雑な推論を要するタスクでは精度が上がる場合があります。


    最終的にたどり着いた起動スクリプト

    #!/bin/bash
    # Qwen3.8-27B-FP8 on DGX Spark (solo mode) — vLLM via spark-vllm-docker
    cd ~/spark-vllm-docker || exit 1
    
    ./launch-cluster.sh --solo -e VLLM_DISABLE_COMPILE_CACHE=1 exec \
      vllm serve Qwen/Qwen3.8-27B-FP8 \
        --served-model-name qwen38-27b-fp8 \
        --host 0.0.0.0 --port 8888 \
        --tensor-parallel-size 1 --trust-remote-code \
        --attention-backend flashinfer \
        --kv-cache-dtype fp8 \
        --gpu-memory-utilization 0.85 \
        --max-model-len 131072 \
        --max-num-seqs 4 \
        --max-num-batched-tokens 32768 \
        --enable-chunked-prefill \
        --enable-prefix-caching \
        --load-format fastsafetensors \
        --reasoning-parser qwen3 \
        --tool-call-parser qwen3_coder \
        --enable-auto-tool-choice \
        --generation-config vllm \
        --speculative-config '{"method":"mtp","num_speculative_tokens":3}' \
        --default-chat-template-kwargs '{"enable_thinking": false}'
    

    --gpu-memory-utilization 0.85、-- 、VLLM_DISABLE_COMPILE_CACHE=1の3つは、いずれも一度失敗してからたどり着いた値です。以下、その経緯を残します。


    ポートが公開される仕組み

    このスクリプトにはDockerの-p(ポートマッピング)オプションが見当たりません。それでもLANの他のPCから直接192.168.x.xxx:8888にアクセスできています。これはlaunch-cluster.sh --soloの仕様によるものです。

    spark-vllm-dockerの--soloモードは、既定でDockerのホストネットワーキングを使います。コンテナがホストと同じネットワーク名前空間で動くため、コンテナ内で--port 8888を指定すればそのままホストの8888番としてLANに公開されます。

    複数のvLLMインスタンスを1台のマシンで動かしたい場合などは、launch-cluster.shにDocker形式のポートマッピングを渡すこともできます(-p 8000:8000のように指定すると、その時点でホストネットワーキングからブリッジネットワーキングに切り替わります)。今回はホストIPに直接ポートを開ける構成をそのまま使っています。


    つまずき① 「メモリが足りない」というエラーに振り回された

    最初の起動は--gpu-memory-utilization 0.75、--max-model-len 262144(フルコンテキスト)で試し、こんなエラーで落ちました。

    ValueError: No available memory for the cache blocks.
    Try increasing `gpu_memory_utilization` when initializing the engine
    

    素直に読めば「utilizationを増やして」と書いてあるのですが、当時は「メモリが足りない」=「使用量の上限設定を下げれば直る」と考えてしまい、0.75 → 0.72 → 0.6 → 0.5 → 0.4と段階的に下げていきました。

    結果は、下げるたびに悪化しました。実際のログです。

    # 0.6 のとき
    Freed 8.55 GiB before KV cache sizing; non-torch profile increase is 55.15 GiB
    Available KV cache memory: -16.25 GiB   ← マイナス。下げるほど悪化
    
    # 最終的に 0.85 に上げたとき
    Available KV cache memory: 9.46 GiB     ← ようやくプラスに
    GPU KV cache size: 245,928 tokens
    Maximum concurrency for 131,072 tokens per request: 1.88x
    

    なぜこうなるのか。vLLMのメモリ計算は、こういう構造になっています。

    KVキャッシュ用メモリ = (GPU総メモリ × gpu_memory_utilization) − 重み − non-torch オーバーヘッド
    

    重みとnon-torchオーバーヘッド(CUDAグラフ、アクティベーション等)は、utilizationの値に関わらず一定です。つまりutilizationを下げると予算(左辺)だけが縮み、固定費(右辺の引く項)は変わらないため、KVキャッシュに残る余地はむしろ減ります。エラーメッセージが最初からTry increasingと言っていた通り、正解は逆方向でした。

    ちなみに、--max-model-lenを131072に半減させてもフルコンテキスト時とKVキャッシュがそれほど枯渇しなかったのは、このモデルがハイブリッド構成だからです。KVキャッシュが文脈長に比例して伸びるのはフルアテンションの16層分だけで、残り48層のリニアアテンションは文脈長によらず定数サイズの状態しか持ちません。ログの「GPU KV cache size: 245,928 tokens」という比較的大きな数字も、この「実質16層分しかKVを持たない」構造が効いています。

    教訓:「No available memory for the cache blocks」は空き容量不足ではなく予算不足のシグナル。エラーメッセージを額面通りに受け取るべきでした。


    つまずき② torch.compileのキャッシュが逆にメモリを食う

    utilizationを直した後も、同じ0.72の設定で「初回は成功したのに再起動後は失敗する」という再現性のない挙動に悩まされました。ログを比較すると差が見えました。

    初回起動と再起動後
    ・torch.compile 新規コンパイル(約40秒) → AOTキャッシュから読込(約16秒)
    ・non-torch profile increase 32.5 GiB → 59.4 GiB
    ・KVキャッシュ +28.9 GiB(成功) → -5.9 GiB(失敗)

    ~/.cache/vllm/torch_compile_cacheに保存されたAOTコンパイル済みグラフを再利用すると、起動は速くなる代わりに、non-torchのメモリプロファイリング値が膨らむという現象でした。vLLM公式ドキュメントにも「vLLMのコンパイラキャッシュは常に正しいとは限らない」という記載があり、疑わしい場合は無効化が推奨されています。

    export VLLM_DISABLE_COMPILE_CACHE=1
    

    起動のたびに約40秒のコンパイル時間を払う代わりに、メモリを安定して確保できるようにしました。


    つまずき③ 異常終了後にメモリが返ってこない

    起動失敗を繰り返す過程で、freeコマンド上の使用量が、実行中のプロセスの合計RSSをはるかに超える現象にも遭遇しました。

    free -g:                    used 87 GiB
    全プロセスの RSS 合計:        4.5 GB
    vllm / EngineCore プロセス:  なし(すでに終了済み)
    

    ユニファイドメモリ環境で、GPU側に割り当てられたメモリ領域がプロセス終了後も即座には解放されない挙動と見られます。page cacheの話とは別の問題で、起動に失敗した後はsudo rebootが最も確実な回復手段という結論に落ち着きました。ログ上の数値だけで判断せず、free -gのusedが数GB程度に戻っているかを再起動後に確認してから次の起動を試すようにしています。


    systemdによる自動起動

    失敗時の自動リトライはメモリの再利用に悪影響を及ぼしうるため、Restart=noにしています。落ちたら自動では上がってこず、原因を確認してから手動で対処する設計です。

    [Unit]
    Description=vLLM Qwen3.8-27B-FP8 (DGX Spark solo, spark-vllm-docker)
    Requires=docker.service
    After=docker.service network-online.target
    
    [Service]
    Type=simple
    User=xxxxx
    Group=docker
    WorkingDirectory=/home/xxxxx/spark-vllm-docker
    Environment=HOME=/home/xxxxx
    Environment=PATH=/home/xxxxx/.local/bin:/usr/local/cuda/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
    
    # 残骸コンテナの除去
    ExecStartPre=-/usr/bin/docker rm -f vllm_node
    # page cache を落として non-torch 計測の汚染を避ける
    ExecStartPre=+/bin/sh -c 'sync; echo 3 > /proc/sys/vm/drop_caches'
    
    ExecStart=/bin/bash /home/xxxxx/launch-qwen38.sh
    ExecStop=/usr/bin/docker rm -f vllm_node
    
    Restart=no
    TimeoutStartSec=1200
    TimeoutStopSec=120
    KillMode=mixed
    
    [Install]
    WantedBy=multi-user.target
    
    sudo systemctl daemon-reload
    sudo systemctl enable --now vllm-qwen38
    

    Open WebUIのインストールと接続先切り替え

    チャット画面としてOpen WebUIを使っています。今回はollama用に既に稼働していたコンテナをvLLM向けに設定し直しましたが、新規に構築する場合は次のコマンドで最初のコンテナを立ち上げます。

    docker run -d \
      --name open-webui \
      -p 3000:8080 \
      -e OPENAI_API_BASE_URL=http://192.168.x.xxx:8888/v1 \
      -e OPENAI_API_KEY=dummy \
      -v open-webui:/app/backend/data \
      ghcr.io/open-webui/open-webui:latest
    

    -p 3000:8080はOpen WebUIがコンテナ内部で8080番で待ち受けているためのマッピングで、-v open-webui:/app/backend/dataはチャット履歴やユーザー設定を保存する名前付きボリュームです。起動後、http://192.168.x.xxx:3000にブラウザでアクセスすると初期セットアップ画面(管理者アカウントの作成)が表示されます。

    既存環境の接続先を切り替える場合

    今回のように、すでにollama向けに稼働しているOpen WebUIの接続先だけをvLLMに切り替えたい場合は、環境変数の再設定だけでは反映されません。設定はwebui.dbのconfigテーブル(key-value形式、PersistentConfig)に保存されているため、こちらを直接書き換える必要があります。

    import sqlite3, json, time
    c = sqlite3.connect('/app/backend/data/webui.db')
    now = int(time.time())
    updates = {
        'openai.enable':        json.dumps(True),
        'openai.api_base_urls': json.dumps(['http://192.168.x.xxx:8888/v1']),
        'openai.api_keys':      json.dumps(['dummy']),
        'ollama.enable':        json.dumps(False),
    }
    for k, v in updates.items():
        c.execute('UPDATE config SET value = ?, updated_at = ? WHERE key = ?', (v, now, k))
    c.commit()
    

    変更前にcp webui.db webui.db.bak-$(date +%Y%m%d-%H%M%S)でバックアップを取ってから作業しています。反映にはコンテナの再起動が必要です。

    Open WebUI側でモデルごとのcapabilitiesが未設定の場合、vision(画像入力)はフロントエンドの既定値で有効(capabilities?.vision ?? true)になるため、qwen38-27b-fp8に個別レコードを作らなくても画像添付UIがそのまま使えました。


    動作確認

    起動後、実際にリクエストを送って機能ごとに確認しました。

    推論とツール呼び出し

    curl http://192.168.x.xxx:8888/v1/chat/completions \
      -H "Content-Type: application/json" \
      -d '{
        "model": "qwen38-27b-fp8",
        "messages": [{"role": "user", "content": "東京の天気を調べて"}],
        "tools": [{"type":"function","function":{"name":"get_weather","parameters":{"type":"object","properties":{"city":{"type":"string"}},"required":["city"]}}}],
        "tool_choice": "auto"
      }'
    

    finish_reason: tool_callsとともにget_weather({"city": "東京"})が正しく返ってきました。

    マルチモーダル

    上半分を赤、下半分を青に塗った96×96のテスト画像をdata URIで送信し、色を正しく認識することを確認しました。複数画像の同時投入(2枚)にも対応し、vllm:mm_cache_hits_totalのメトリクスから同一画像の再エンコードを省略するキャッシュが機能していることも確認できました。

    投機的デコーディング(MTP)の実測値

    メモリが安定した状態での実測です。

    Mean acceptance length: 3.3〜3.7
    Per-position acceptance rate: 0.91 / 0.74 / 0.61
    Avg Draft acceptance rate: 75〜89%
    

    メモリ逼迫時(KVキャッシュがほぼ枯渇していた状態)で計測すると受理率が54〜61%まで落ち込み、一時はnum_speculative_tokensを2に減らすことも検討しましたが、メモリ構成を修正した後の再計測で3のままが最適という結論になりました。投機的デコーディングのチューニングは、まずメモリが健全な状態であることを確認してから行うべきという教訓です。

    生成速度

    単独リクエストで15〜19 tok/s(3回計測の平均16.9 tok/s)。DGX Sparkのメモリ帯域とモデルサイズから見積もれる素の生成速度に、MTPによるおおむね2倍弱の高速化が乗った値で、実測とも整合しています。


    まとめ:得られた教訓

    1. 「No available memory for the cache blocks」は「予算不足」であって「空き容量不足」ではない。utilizationは下げるのではなく上げる方向で調整する。

    2. torch.compileのAOTキャッシュはメモリプロファイリングに影響することがある。疑わしい挙動が出たらVLLM_DISABLE_COMPILE_CACHE=1で切り分ける。

    3. 異常終了後のメモリは、ユニファイドメモリ環境では即座に戻らないことがある。起動失敗が続いたら再起動を選択肢に入れる。

    4. チューニングの実測は、メモリが健全な状態で行う。逼迫した環境での数値は参考にならない。

    5. Open WebUIのようなPersistentConfigを持つアプリは、環境変数ではなくDBの中身を確認する。

    6. 公称スペックと実効値、そしてモデルの内部構造(今回ならハイブリッドアテンション)を把握しておくと、メモリ計算のつじつまが合う。128GBのうち実際に使えるのは約121GB、KVが伸びるのは64層中16層だけ、といった前提を押さえるとログの数字が読み解きやすくなる。

    同じような環境でLLMを動かそうとしている方の参考になれば幸いです。


    参考リンク: spark-vllm-docker / vLLM: torch.compile integration / vLLM: debugging vLLM-torch.compile integration


    #DGXSpark #Qwen #Qwen38 #vLLM #Ollama #ローカルLLM #生成AI #AI #LLM #NVIDIA #Blackwell #GPU #Docker #Ubuntu #AI開発 #AIインフラ


    関連記事:


    あなたへのおすすめ