# 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](https://github.com/unslothai/unsloth) 支持 **Qwen3-VL 的微调和** [**强化学习（RL）**](https://unsloth.ai/docs/zh/kai-shi-shi-yong/reinforcement-learning-rl-guide/vision-reinforcement-learning-vlm-rl)。使用我们的 [笔记本（notebooks）可免费训练 Qwen3-VL（8B）](#fine-tuning-qwen3-vl). 运行 Qwen3-VL 微调 Qwen3-VL ## 🖥️ **运行 Qwen3-VL** 要在 llama.cpp、vLLM、Ollama 等中运行该模型，以下是推荐设置： ### :gear: 推荐设置 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 上所述](https://github.com/QwenLM/Qwen3-VL/tree/main?tab=readme-ov-file#generation-hyperparameters). {% columns %} {% column %} Instruct 设置： ```bash 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 ``` {% endcolumn %} {% column %} Thinking 设置： ```bash 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 ``` {% endcolumn %} {% endcolumns %} ### :bug:聊天模板错误修复在 Unsloth，我们最关心准确性，因此我们调查了为什么在运行 Thinking 模型的第二轮对话后，llama.cpp 会崩溃，情况如下所示： {% columns %} {% column %}

{% endcolumn %} {% column %} 错误代码： ``` terminate called after throwing an instance of 'std::runtime_error' what(): Value is not callable: null at row 63, column 78: {%- if '' in content %} {%- set reasoning_content = ((content.split('')|first).rstrip('\n').split('')|last).lstrip('\n') %} ^ ``` {% endcolumn %} {% endcolumns %} 我们已成功修复了 VL 模型的 Thinking 聊天模板，因此我们重新上传了所有 Thinking 量化文件和 Unsloth 的量化文件。它们现在在第二次对话后都应能正常工作 - **其他量化文件在第二次对话后将无法加载。** ### **Qwen3-VL Unsloth 上传内容**: 自 2025 年 10 月 30 日起，llama.cpp 已支持 Qwen3-VL 的 GGUF，因此您可以在本地运行它们！ | 动态 GGUF（用于运行） | 4-bit BnB Unsloth 动态 | 16-bit 全精度 | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |

| ### 📖 Llama.cpp：运行 Qwen3-VL 教程 1. 获取最新的 `llama.cpp` 在 [此处的 GitHub](https://github.com/ggml-org/llama.cpp)。您也可以按照下面的构建说明进行操作。将 `-DGGML_CUDA=ON` 更改为 `-DGGML_CUDA=OFF` 如果您没有 GPU 或只想使用 CPU 推理。 **对于 Apple Mac / Metal 设备**，设置 `-DGGML_CUDA=OFF` 然后照常继续 - Metal 支持默认启用。 ```bash 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 ``` 2. **先获取一张图片吧！** 您也可以上传图片。我们将使用，这只是我们的迷你徽标，展示了 finetune 如何使用 Unsloth 制作：

3. 让我们下载这张图片 {% code overflow="wrap" %} ```bash wget https://raw.githubusercontent.com/unslothai/unsloth/refs/heads/main/images/unsloth%20made%20with%20love.png -O unsloth.png ``` {% endcode %} 4. 我们来获取第二张图片，地址为

{% code overflow="wrap" %} ```bash 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 ``` {% endcode %} 5. 然后，使用 llama.cpp 的自动模型下载功能，试试下面针对 8B Instruct 模型的命令： ```bash ./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 ``` 6. 进入后，您将看到下面的界面：

7. 通过以下命令加载图片： `/image PATH` 例如 `/image unsloth.png` 然后按 ENTER

8. 当您按下 ENTER 时，会显示“unsloth.png image loaded”

9. 现在我们可以问一个问题，例如 “这张图片是什么？”：

10. 现在通过以下命令加载第二张图片： `/image picture.png` 然后按 ENTER 并询问 “这张图片是什么？”

11. 最后，我们来问两张图片之间的关系（它是可以的！） {% code overflow="wrap" %} ``` 这两张图片直接相关，因为它们都以树懒（tree sloth）为主题，这是“made with unsloth”项目的核心主体。 - 第一张图片是“made with unsloth”项目的官方徽标。它以绿色圆圈内的卡通化树懒形象为主，旁边有“made with unsloth”的文字。这是该项目的视觉标识。 - 第二张图片是一张真实树懒在其自然栖息地的照片。该照片捕捉了动物在野外的外观和行为。两张图片之间的关系是：徽标（图片一）是用于宣传“made with unsloth”项目的数字化表示或符号，而照片（图片二）是对实际树懒的真实世界描绘。该项目可能将徽标中的角色用作图标或吉祥物，而照片则用于展示树懒在自然环境中的真实样貌。 ``` {% endcode %}

12. 您也可以通过以下方式下载模型（在安装 `pip install huggingface_hub hf_transfer` ）之后使用 HuggingFace 的 `snapshot_download` ，这对于大型模型下载很有用， **因为 llama.cpp 的自动下载器有时可能会滞后。** 您可以选择 Q4\_K\_M 或其他量化版本。 ```python # !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*"], ) ``` 13. 运行模型并尝试任意提示词。 **对于 Instruct：** ```bash ./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 ``` 14. **对于 Thinking**: ```bash ./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 ``` ### :magic\_wand:运行 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 或其他量化版本。 ```python # !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：** {% code overflow="wrap" %} ```bash ./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 \ ``` {% endcode %} **Thinking：** {% code overflow="wrap" %} ```bash ./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" ``` {% endcode %} 4. 编辑， `--ctx-size 16384` 用于上下文长度， `--n-gpu-layers 99` 用于 GPU 卸载的层数。若 GPU 出现内存不足，请尝试调整该值。如仅使用 CPU 推理，则移除该设置。 {% hint style="success" %} **使用 `--fit on` （在 2025 年 12 月 15 日引入）以最大化 GPU 和 CPU 的使用。** 可选地，使用 `-ot ".ffn_.*_exps.=CPU"` 将所有 MoE 层卸载到 CPU！这实际上允许您将所有非 MoE 层放入 1 块 GPU，从而提升生成速度。如果您有更多 GPU 容量，可以自定义正则表达式以适配更多层。 {% endhint %} ### 🐋 Docker：运行 Qwen3-VL 如果您已安装 Docker Desktop，要从 Hugging Face 运行 Unsloth 的模型，只需运行以下命令即可： ```bash docker model pull hf.co/unsloth/Qwen3-VL-8B-Instruct-GGUF:UD-Q4_K_XL ``` 或者您也可以运行 Docker 上传的 Qwen3-VL 模型： ```bash 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 微调笔记本](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Qwen3_VL_\(8B\)-Vision.ipynb) * [GRPO/GSPO 强化学习笔记本](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Qwen3_VL_\(8B\)-Vision-GRPO.ipynb) {% hint style="success" %} **现在将 Qwen3-VL 保存为 GGUF 已可行，因为 llama.cpp 刚刚支持它！** 如果您想使用任何其他 Qwen3-VL 模型，只需将 8B 模型更换为 2B、32B 等即可。 {% endhint %} GRPO 笔记本的目标是使视觉语言模型通过 RL 在给定如下图像输入的情况下解决数学问题：

该 Qwen3-VL 支持还集成了我们最新的更新，以实现更省内存且更快速的 RL，包括我们的 [待机（Standby）功能](https://unsloth.ai/docs/zh/kai-shi-shi-yong/reinforcement-learning-rl-guide/memory-efficient-rl#unsloth-standby)，该功能在与其他实现相比时，能独特地限制速度退化。您可以阅读更多关于如何使用 RL 训练视觉 LLM 的内容，详见我们的 [VLM GRPO 指南](https://unsloth.ai/docs/zh/kai-shi-shi-yong/reinforcement-learning-rl-guide/vision-reinforcement-learning-vlm-rl). ### 多图像训练为了对 Qwen3-VL 进行多图像微调或训练，最直接的更改是将 ```python ds_converted = ds.map( convert_to_conversation, ) ``` 替换为： ```python ds_converted = [convert_to_converation(sample) for sample in dataset] ``` 使用 map 会触发数据集标准化和 Arrow 处理规则，这些规则可能更严格且更复杂以定义。