🌠Qwen3-VL: 実行ガイド

Unsloth を使って Qwen3-VL をローカルでファインチューニングし、実行する方法を学びます。

Qwen3-VL は、Qwen の新しいビジョンモデルで、 instruct と thinking 版があります。2B、4B、8B、32B モデルは dense、30B と 235B は MoE です。235B thinking LLM は、GPT-5 (high) と Gemini 2.5 Pro に匹敵する SOTA の視覚・コーディング性能を提供します。 Qwen3-VL は、視覚・動画・OCR 機能に加え、256K のコンテキスト（1M まで拡張可能）を備えています。 Unsloth は Qwen3-VL のファインチューニングと RLをサポートしています。私たちの ノートブック.

で Qwen3-VL (8B) を無料で学習できます。Qwen3-VL のファインチューニング

🖥️ で Qwen3-VL (8B) を無料で学習できます。

llama.cpp、vLLM、Ollama などでモデルを実行するには、推奨設定は次のとおりです:

⚙️ 推奨設定

Qwen は両方のモデルに対して次の設定を推奨しています（Instruct と Thinking では少し異なります）:

Instruct 設定:	Thinking 設定:
Temperature = 0.7	Temperature = 1.0
Top_P = 0.8	Top_P = 0.95
presence_penalty = 1.5	presence_penalty = 0.0
出力長 = 32768（最大 256K）	出力長 = 40960（最大 256K）
Top_K = 20	Top_K = 20

Qwen3-VL は、GitHub で述べられているように、ベンチマーク結果に以下の設定も使用しています GitHub 上で.

Instruct 設定:

export greedy='false'
export seed=3407
export top_p=0.8
export top_k=20
export temperature=0.7
export repetition_penalty=1.0
export presence_penalty=1.5
export out_seq_length=32768

Thinking 設定:

export greedy='false'
export seed=1234
export top_p=0.95
export top_k=20
export temperature=1.0
export repetition_penalty=1.0
export presence_penalty=0.0
export out_seq_length=40960

🐛チャットテンプレートのバグ修正

Unsloth では精度を最も重視しているため、Thinking モデルを 2 回目に実行した後に llama.cpp が壊れる理由を調査しました。以下のようになります:

エラーコード:

terminate called after throwing an instance of 'std::runtime_error'
  what():  Value is not callable: null at row 63, column 78:
            {%- if '</think>' in content %}
                {%- set reasoning_content = ((content.split('</think>')|first).rstrip('\n').split('<think>')|last).lstrip('\n') %}
                                                                             ^

VL モデル向けの Thinking チャットテンプレートの修正に成功したため、すべての Thinking quant と Unsloth の quant を再アップロードしました。これで 2 回目の会話以降もすべて動作するはずです - 他の quant は 2 回目の会話の後に読み込みに失敗します。

Qwen3-VL Unsloth アップロード:

2025 年 10 月 30 日時点で、Qwen3-VL は llama.cpp により GGUF 対応になったため、ローカルで実行できます！

Dynamic GGUF（実行用）	4-bit BnB Unsloth Dynamic	16-bit フル精度
2B-Instruct 2B-Thinking 4B-Instruct 4B-Thinking 8B-Instruct 8B-Thinking 30B-Instruct 30B-Thinking 32B-Instruct 32B-Thinking 235B-A22B-Instruct 235B-A22B-Thinking	2B-Instruct 2B-Thinking 4B-Instruct 4B-Thinking 8B-Instruct 8B-Thinking 32B-Instruct 32B-Thinking	2B-Instruct 4B-Instruct 4B-Thinking 8B-Instruct 8B-Thinking 30B-Instruct 30B-Thinking 32B-Instruct 32B-Thinking 235B-A22B-Thinking 235B-A22B-Instruct

📖 Llama.cpp: Qwen3-VL 実行チュートリアル

1. 最新の llama.cpp を GitHub からこちらで入手してください。以下のビルド手順に従うこともできます。 -DGGML_CUDA=ON を -DGGML_CUDA=OFF に変更してください。GPU がない場合、または CPU 推論だけを使いたい場合です。 Apple Mac / Metal デバイスでは、 -DGGML_CUDA=OFF を設定し、その後は通常どおり続けてください - Metal サポートは既定で有効です。

apt-get update
apt-get install pciutils build-essential cmake curl libcurl4-openssl-dev -y
git clone https://github.com/ggml-org/llama.cpp
cmake llama.cpp -B llama.cpp/build \\
    -DBUILD_SHARED_LIBS=OFF -DGGML_CUDA=ON -DLLAMA_CURL=ON
cmake --build llama.cpp/build --config Release -j --clean-first
cp llama.cpp/build/bin/llama-* llama.cpp

1. まず画像を取得しましょう！ 画像をアップロードすることもできます。ここでは https://raw.githubusercontent.com/unslothai/unsloth/refs/heads/main/images/unsloth%20made%20with%20love.pngを使います。これは、Unsloth でファインチューンがどのように作られるかを示す、私たちのミニロゴです:

1. この画像をダウンロードしましょう

wget https://raw.githubusercontent.com/unslothai/unsloth/refs/heads/main/images/unsloth%20made%20with%20love.png -O unsloth.png

1. 2 枚目の画像を次の場所から取得しましょう https://files.worldwildlife.org/wwfcmsprod/images/Sloth_Sitting_iStock_3_12_2014/story_full_width/8l7pbjmj29_iStock_000011145477Large_mini__1_.jpg

wget https://files.worldwildlife.org/wwfcmsprod/images/Sloth_Sitting_iStock_3_12_2014/story_full_width/8l7pbjmj29_iStock_000011145477Large_mini__1_.jpg -O picture.png

1. では、llama.cpp の自動モデルダウンロード機能を使いましょう。8B Instruct モデルでこれを試してください:

./llama.cpp/llama-mtmd-cli \\
    -hf unsloth/Qwen3-VL-8B-Instruct-GGUF:UD-Q4_K_XL \\
    --n-gpu-layers 99 \\
    --jinja \\
    --top-p 0.8 \\
    --top-k 20 \\
    --temp 0.7 \\
    --min-p 0.0 \\
    --flash-attn on \\
    --presence-penalty 1.5 \\
    --ctx-size 8192

1. 入ると、以下の画面が表示されます:

1. 以下で画像を読み込みます /image PATH つまり /image unsloth.png の後に ENTER を押します

1. ENTER を押すと、「unsloth.png image loaded」と表示されます

1. では、「この画像は何ですか？」のように質問してみましょう:

1. 次に 2 枚目の画像を以下で読み込みます /image picture.png その後 ENTER を押して「この画像は何ですか？」と質問します

1. 最後に、2 枚の画像がどのように関連しているかを尋ねてみましょう（動作します！）

2 枚の画像はどちらも **tree sloth** を特徴としているため、直接関連しています。これは、「made with unsloth」プロジェクトの中心的な被写体です。

- 1 枚目の画像は、「made with unsloth」プロジェクトの **公式ロゴ** です。緑の円の中にデフォルメされた漫画風の tree sloth のキャラクターが描かれており、横に「made with unsloth」という文字があります。これはプロジェクトのビジュアルアイデンティティです。
- 2 枚目の画像は、自然の生息地にいる本物の tree sloth の **写真** です。この写真は、野生での動物の外見と行動を捉えています。

2 枚の画像の関係は、ロゴ（画像 1）が「made with unsloth」プロジェクトを宣伝するためのデジタル表現またはシンボルであるのに対し、写真（画像 2）は実在の tree sloth の現実世界での描写である、ということです。おそらくこのプロジェクトはロゴのキャラクターをアイコンやマスコットとして使用しており、写真は tree sloth が自然環境でどのように見えるかを示すためのものです。

1. 次を使えばモデルをダウンロードすることもできます（をインストールした後で pip install huggingface_hub hf_transfer ）HuggingFace の snapshot_download は、大きなモデルのダウンロードに便利です。 llama.cpp の自動ダウンローダーが遅い場合があるためです。 Q4_K_M、または他の量子化版を選べます。

# !pip install huggingface_hub hf_transfer
import os
os.environ["HF_HUB_ENABLE_HF_TRANSFER"] = "1"
from huggingface_hub import snapshot_download
snapshot_download(
    repo_id   = "unsloth/Qwen3-VL-8B-Instruct-GGUF", # または "unsloth/Qwen3-VL-8B-Thinking-GGUF"
    local_dir = "unsloth/Qwen3-VL-8B-Instruct-GGUF", # または "unsloth/Qwen3-VL-8B-Thinking-GGUF"
    allow_patterns = ["*UD-Q4_K_XL*", "*mmproj-F16*"],
)

1. モデルを実行して、任意のプロンプトを試してください。 Instruct の場合:

./llama.cpp/llama-mtmd-cli \\
    --model unsloth/Qwen3-VL-8B-Instruct-GGUF/Qwen3-VL-8B-Instruct-UD-Q4_K_XL.gguf \\
    --mmproj unsloth/Qwen3-VL-8B-Instruct-GGUF/mmproj-F16.gguf \\
    --n-gpu-layers 99 \\
    --jinja \\
    --top-p 0.8 \\
    --top-k 20 \\
    --temp 0.7 \\
    --min-p 0.0 \\
    --flash-attn on \\
    --presence-penalty 1.5 \\
    --ctx-size 8192

1. Thinking の場合:

./llama.cpp/llama-mtmd-cli \\
    --model unsloth/Qwen3-VL-8B-Thinking-GGUF/Qwen3-VL-8B-Thinking-UD-Q4_K_XL.gguf \\
    --mmproj unsloth/Qwen3-VL-8B-Thinking-GGUF/mmproj-F16.gguf \\
    --n-gpu-layers 99 \\
    --jinja \\
    --top-p 0.95 \\
    --top-k 20 \\
    --temp 1.0 \\
    --min-p 0.0 \\
    --flash-attn on \\
    --presence-penalty 0.0 \\
    --ctx-size 8192

🪄Qwen3-VL-235B-A22B と Qwen3-VL-30B-A3B の実行

Qwen3-VL-235B-A22B では、最適化された推論と豊富なオプションのために llama.cpp を使用します。

1. 上記と同様の手順に従いますが、今回はモデルが非常に大きいため、追加の手順も必要です。

2. 次をインストールした後でモデルをダウンロードします pip install huggingface_hub hf_transfer ）。UD-Q2_K_XL、または他の量子化版を選べます。.

   # !pip install huggingface_hub hf_transfer
   import os
   os.environ["HF_HUB_ENABLE_HF_TRANSFER"] = "1"
   from huggingface_hub import snapshot_download
   snapshot_download(
       repo_id = "unsloth/Qwen3-VL-235B-A22B-Instruct-GGUF",
       local_dir = "unsloth/Qwen3-VL-235B-A22B-Instruct-GGUF",
       allow_patterns = ["*UD-Q2_K_XL*", "*mmproj-F16*"],
   )

3. モデルを実行してプロンプトを試してください。Thinking と Instruct で正しいパラメータを設定します。

Instruct:

./llama.cpp/llama-mtmd-cli \\
    --model unsloth/Qwen3-VL-235B-A22B-Instruct-GGUF/UD-Q2_K_XL/Qwen3-VL-235B-A22B-Instruct-UD-Q2_K_XL-00001-of-00002.gguf \\
    --mmproj unsloth/Qwen3-VL-235B-A22B-Instruct-GGUF/mmproj-F16.gguf
    --jinja \\
    --top-p 0.8 \\
    --top-k 20 \\
    --temp 0.7 \\
    --min-p 0.0 \\
    --flash-attn on \\
    --presence-penalty 1.5 \\
    --ctx-size 8192 \\

Thinking:

./llama.cpp/llama-mtmd-cli \\
    --model unsloth/Qwen3-VL-235B-A22B-Thinking-GGUF/UD-Q2_K_XL/Qwen3-VL-235B-A22B-Thinking-UD-Q2_K_XL-00001-of-00002.gguf \\
    --mmproj unsloth/Qwen3-VL-235B-A22B-Thinking-GGUF/mmproj-F16.gguf \\
    --n-gpu-layers 99 \\
    --jinja \\
    --top-p 0.95 \\
    --top-k 20 \\
    --temp 1.0 \\
    --min-p 0.0 \\
    --flash-attn on \\
    --presence-penalty 0.0 \\
    --ctx-size 8192 \\
    -ot ".ffn_.*_exps.=CPU"

1. 編集、 --ctx-size 16384 はコンテキスト長のため、 --n-gpu-layers 99 は、GPU にオフロードする層数のためです。GPU のメモリ不足になる場合は調整してください。CPU のみの推論を行う場合はこれも削除してください。

使用してください --fit on が 2025 年 12 月 15 日に導入され、GPU と CPU を最大限に活用できます。

必要に応じて、 -ot ".ffn_.*_exps.=CPU" を使ってすべての MoE 層を CPU にオフロードできます！これにより、非 MoE 層を 1 枚の GPU に収められるようになり、生成速度が向上します。GPU の容量がもっとある場合は、正規表現をカスタマイズしてより多くの層を収めることができます。

🐋 Docker: Qwen3-VL を実行

すでに Docker Desktop があるなら、Hugging Face から Unsloth のモデルを実行するには、以下のコマンドを実行するだけで完了です:

docker model pull hf.co/unsloth/Qwen3-VL-8B-Instruct-GGUF:UD-Q4_K_XL

または、Docker にアップロードされた Qwen3-VL モデルを実行できます:

docker model run ai/qwen3-vl

🦥 Qwen3-VL のファインチューニング

Unsloth は、より大きな 32B および 235B モデルを含む Qwen3-VL のファインチューニングと強化学習（RL）をサポートしています。これには、動画と物体検出のためのファインチューニング対応も含まれます。いつものように、Unsloth により Qwen3-VL モデルは、精度低下なしで VRAM を 60% 削減し、コンテキスト長を 8 倍にしつつ、1.7 倍高速に学習できます。 Colab で無料で学習できる Qwen3-VL (8B) の学習ノートブックを 2 つ作成しました:

• 通常の SFT ファインチューニング ノートブック

• GRPO/GSPO RL ノートブック

Qwen3-VL を GGUF に保存する機能は、llama.cpp が対応したため今では動作します！

他の Qwen3-VL モデルを使いたい場合は、8B モデルを 2B、32B などのモデルに置き換えるだけです。

GRPO ノートブックの目的は、以下のような画像入力を与えて、RL によって視覚言語モデルに数学の問題を解かせることです:

この Qwen3-VL のサポートには、さらにメモリ効率が高く高速な RL のための最新アップデートも統合されています。これには私たちの スタンバイ機能も含まれ、他の実装と比べて速度低下を独自に抑えます。RL を使って視覚 LLM を学習する方法については、私たちの VLM GRPO ガイド.

複数画像学習

Qwen3-VL を複数画像でファインチューニングまたは学習するための、最も簡単な変更は次を置き換えることです

ds_converted = ds.map(
    convert_to_conversation,
)

を次に:

ds_converted = [convert_to_converation(sample) for sample in dataset]

map を使うとデータセットの標準化と arrow の処理ルールが有効になりますが、これらは厳格で、定義がより複雑になることがあります。