🌠Qwen3-VL：如何运行指南

了解如何使用 Unsloth 在本地微调并运行 Qwen3-VL。

Qwen3-VL 是 Qwen 的新视觉模型，具有 指导（instruct） 和 思考（thinking） 版本。2B、4B、8B 和 32B 模型为密集模型，而 30B 和 235B 为 MoE。235B thinking 大规模语言模型在视觉和编码性能上达到了与 GPT-5（高）和 Gemini 2.5 Pro 竞争的 SOTA 水平。 Qwen3-VL 具有视觉、视频和 OCR 能力，并支持 256K 上下文（可扩展到 1M）。 Unsloth 支持 Qwen3-VL 的微调和 强化学习（RL）。使用我们的 笔记本（notebooks）可免费训练 Qwen3-VL（8B）.

运行 Qwen3-VL微调 Qwen3-VL

🖥️ 运行 Qwen3-VL

要在 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 上所述.

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 模型的第二轮对话后，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 量化文件和 Unsloth 的量化文件。它们现在在第二次对话后都应能正常工作 - 其他量化文件在第二次对话后将无法加载。

Qwen3-VL Unsloth 上传内容:

自 2025 年 10 月 30 日起，llama.cpp 已支持 Qwen3-VL 的 GGUF，因此您可以在本地运行它们！

动态 GGUF（用于运行）	4-bit BnB Unsloth 动态	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，这只是我们的迷你徽标，展示了 finetune 如何使用 Unsloth 制作：

1. 让我们下载这张图片

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

1. 我们来获取第二张图片，地址为 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. 现在通过以下命令加载第二张图片： /image picture.png 然后按 ENTER 并询问 “这张图片是什么？”

1. 最后，我们来问两张图片之间的关系（它是可以的！）

这两张图片直接相关，因为它们都以树懒（tree sloth）为主题，这是“made with unsloth”项目的核心主体。

- 第一张图片是“made with unsloth”项目的官方徽标。它以绿色圆圈内的卡通化树懒形象为主，旁边有“made with unsloth”的文字。这是该项目的视觉标识。
- 第二张图片是一张真实树懒在其自然栖息地的照片。该照片捕捉了动物在野外的外观和行为。

两张图片之间的关系是：徽标（图片一）是用于宣传“made with unsloth”项目的数字化表示或符号，而照片（图片二）是对实际树懒的真实世界描绘。该项目可能将徽标中的角色用作图标或吉祥物，而照片则用于展示树懒在自然环境中的真实样貌。

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 支持对 Qwen3-VL（包括更大的 32B 和 235B 模型）进行微调和强化学习（RL）。这包括对视频和目标检测的微调支持。如往常一样，Unsloth 使 Qwen3-VL 模型训练速度提升 1.7 倍，显存降低 60%，并在不降低准确性的情况下实现 8 倍更长的上下文长度。 我们制作了两个 Qwen3-VL（8B）训练笔记本，您可以在 Colab 上免费训练：

• 常规 SFT 微调笔记本

• GRPO/GSPO 强化学习笔记本

现在将 Qwen3-VL 保存为 GGUF 已可行，因为 llama.cpp 刚刚支持它！

如果您想使用任何其他 Qwen3-VL 模型，只需将 8B 模型更换为 2B、32B 等即可。

GRPO 笔记本的目标是使视觉语言模型通过 RL 在给定如下图像输入的情况下解决数学问题：

该 Qwen3-VL 支持还集成了我们最新的更新，以实现更省内存且更快速的 RL，包括我们的 待机（Standby）功能，该功能在与其他实现相比时，能独特地限制速度退化。您可以阅读更多关于如何使用 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 处理规则，这些规则可能更严格且更复杂以定义。