# 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 处理规则，这些规则可能更严格且更复杂以定义。 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://unsloth.ai/docs/zh/mo-xing/tutorials/qwen3-how-to-run-and-fine-tune/qwen3-vl-how-to-run-and-fine-tune.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.