在本地运行 Qwen3-VL，并从任意位置调用它

Qwen3-VL is Qwen’s dedicated vision-language family — it reads text, images, and video, supports long context on the local-friendly sizes, and ships in both dense and mixture-of-experts (MoE) sizes with separate Instruct and reasoning-enhanced Thinking editions. It supersedes the older Qwen2.5-VL; if you’re picking a vision model to run today, start here — it is the line with verified Ollama tags, while the newer Qwen3.8-27B also takes image and video input but runs only through llama.cpp, LM Studio, or a server runtime for now. Run whichever size fits your hardware locally, then pair the Tokios connector to call it from any machine, teammate, or hosted agent through https://api.tokios.com — no inbound ports, no VPN.

利用 Ollama 在本地运行该模型

在 Ollama 资源库中，Qwen3-VL 对应的标识名为 qwen3-vl。下载并运行默认标签对应的版本即可（即 8B 密集型指令微调版）。

ollama run qwen3-vl

如需其他版本，只需添加对应标签即可：例如使用 ollama run qwen3-vl:30b-a3b 标签获取混合专家型版本，或选用 ollama run qwen3-vl:8b-thinking 标签获取强化推理能力的版本。完整的标签列表可查阅 Ollama 资源库页面；该页面主要说明连接方法，并未涵盖所有运行细节。

Ollama 默认的上下文窗口容量较小（仅能容纳 2048 个令牌），这一数值远低于 Qwen3-VL 原生支持的 256K 令牌容量。若需扩展上下文容量，需在 Modelfile 配置文件中或客户端请求中设置 num_ctx 参数。

版本类型与标签说明

以下所有数据均引自 Hugging Face 模型说明文档及 Ollama 资源库信息。随着各类量化版本陆续发布，相关标签与下载体积也会随之变动——在最终选定某一版本前，请务必核对 ollama.com/library/qwen3-vl/tags 获取最新信息。

属性说明	`8B` 版本为标准密集型版本	`30B-A3B`（混合专家系统）
Ollama 标签	`qwen3-vl:8b`（别名为 `:latest`）	`qwen3-vl:30b-a3b`
下载体积（默认量化版本）	约 6.1 GB	约 20 GB
下载体积（`bf16`版本）	约 18 GB	约 62 GB
参数数量	8B 密集型模型	30B total / 3B active (128 experts, 8 routed)
上下文窗口	262,144 原生支持	262,144 原生支持
模态类型	文本、图片与视频	文本、图片与视频
版本分类	指令模式与思考模式	指令模式与思考模式
许可协议	Apache-2.0	Apache-2.0
Hugging Face	`Qwen/Qwen3-VL-8B-Instruct`	`Qwen/Qwen3-VL-30B-A3B-Instruct`

来源包括：ollama.com/library/qwen3-vl/tags、Qwen/Qwen3-VL-8B-Instruct 配置说明以及Qwen/Qwen3-VL-30B-A3B-Instruct 配置说明。Ollama 资源库还列出了 2B、4B、32B 和 235B-A22B 这几种规格；本表仅介绍经过验证且适合本地部署的规格。

The 30B-A3B model is mixture-of-experts — only 3B parameters are active per token, so it decodes faster than a dense model of the same total size. But all parameters still have to fit in memory. Don’t size your GPU off the active-parameter count alone. See how inference works for why.

量化方式与格式说明

Ollama 提供的标签包含默认量化版本以及 -q8 版本，此外还针对每种规格分别设有 -bf16 标签，且各版本均提供 -instruct 与 -thinking 两种格式。可运行的格式取决于硬件条件，完整对照表请查阅各类量化格式及其对应的硬件要求，关于量化名称的解读方式可参考量化概念解析，其中还以 Q4_K_M 为例做了说明。

硬件适配性分析

在上下文长度适中时，所需显存约为 Q4。所有数值仅为估算值，实际需求为 GGUF 大小的显存再加上用于存储上下文的 KV 缓存。关于显存需求的计算方式，可参阅何种尺寸的模型适合您的显卡？。

适用场景	`8B` 版本（约 6 GB）	`30B-A3B` 混合专家版（约 20 GB）
RTX 3090 / 4090 系列（约 24 GB）	适合处理超长上下文场景	毫无压力
RTX 5090（内存容量达32 GB，采用 Blackwell 架构）	毫无压力，可处理超长上下文	毫无压力
RTX 6000 Ada / A6000 版本（内存容量达48 GB）	毫无压力，可处理超长上下文	毫无压力，可处理超长上下文
RTX 5080 / 4080 版本（内存容量达16 GB）	毫无压力	较为紧张——需缩减上下文长度
Apple Silicon 芯片（内存容量达36 GB 及以上，采用统一内存架构）	毫无压力	使用体验良好
AMD Strix Halo（支持 ROCm/Vulkan，显存容量≤96 GB）	使用体验良好	使用体验良好

操作指南——从入门到进阶

Ollama（最为简便）
LM Studio（图形化界面）
vLLM（适合高级用户）
SGLang（高级版）

ollama run qwen3-vl

保持 Ollama 在默认的 http://127.0.0.1:11434 端口上持续监听。适当调高 num_ctx 数值即可获得更大的上下文容量；发送聊天请求时，只需像使用其他 Ollama 视觉模型一样附上图片即可。

在 LM Studio 的模型目录中搜索 Qwen3-VL，下载一个与自身显存容量相匹配的 GGUF 量化版本（建议从 Q4_K_M 起步），随后启动 LM Studio 的本地服务器。该服务器会在 http://127.0.0.1:1234/v1 端口提供兼容 OpenAI 规范的 API，且同样支持视觉输入功能。

通义千问建议使用 vLLM (vllm>=0.11.0) 来实现通义千问3-VL的高效部署。官方示例针对的是配备多块显卡的大型服务器，您可根据自身硬件配置相应调整相关参数：

vllm serve Qwen/Qwen3-VL-8B-Instruct \
  --max-model-len 262144 \
  --media-io-kwargs '{"video": {"num_frames": -1}}'

Add --tensor-parallel-size <N> to shard across GPUs. Qwen’s own README does not publish a --tool-call-parser or --reasoning-parser flag for Qwen3-VL — check the vLLM multimodal serving docs and the model card before relying on structured tool calls or thinking-tag parsing in production.

python -m sglang.launch_server \
  --model-path Qwen/Qwen3-VL-8B-Instruct \
  --host 0.0.0.0 \
  --port 22002

为张量并行性添加 --tp <N> 参数。相关标志参数可参考 Qwen3-VL GitHub 说明文档。

功能特性

视觉能力： 多模态支持——可在同一请求中处理文本、图片及视频；原生支持长文档光学字符识别、图形用户界面及智能体屏幕内容解析，以及空间定位功能。
Long context: 262,144 tokens natively (confirmed for the 8B and 30B-A3B configs); Qwen’s model card describes it as expandable further with YaRN scaling on vLLM.
推理能力： 不同参数规格的模型均提供两种版本：指令版（直接输出答案）与推理增强版（具备更强的逻辑推导能力，例如在 Ollama 环境下使用 qwen3-vl:8b-thinking 参数）。目前 Qwen 官方发布的 vLLM 与 SGLang 部署示例尚未提供专门用于 Qwen3-VL 的推理解析器参数，因此需自行配置。
工具调用： Hugging Face 上的聊天模板规定了一种 <tool_call> 格式的 JSON 结构，Ollama 会自动应用该格式。不过在 Qwen3-VL 的官方 vLLM/SGLang 部署示例中并未出现 --tool-call-parser 参数，因此在正式部署前请务必在运行环境中测试一下工具调用功能。

通过 Tokios 连接器实现对接

待 Qwen3-VL 在本地环境成功运行后，即可配置 Tokios 连接器，从而从 Claude Code、Cline 或其他兼容客户端以 https://api.tokios.com 方式调用该模型，而无需仅通过 localhost:11434 方式访问。

配置 Tokios 连接器

登录 tokios.com/console 页面后，进入 Setup 选项卡并点击 Start pairing 按钮即可获取一次性使用的令牌（TKS-XXXX-XXXX）。随后在运行 Ollama 的计算机上安装并启动该连接器。

Windows

irm https://tokios.com/downloads/install/windows | iex; tokios-install -Code 'TKS-XXXX-XXXX'

macOS

curl -fsSL https://tokios.com/downloads/install/macos | sh -s -- --code TKS-XXXX-XXXX

Linux

curl -fsSL https://tokios.com/downloads/install/linux | sh -s -- --code TKS-XXXX-XXXX

Then approve the device on the Setup or Connectors tab.

将连接器指向 Ollama 的 /v1 API 接口。

Ollama 在 /v1 处提供了与 OpenAI 兼容的接口。在仅使用单一模型的情况下，控制台的设置向导会自动填入 http://127.0.0.1:11434/v1。若需使用多个模型，则需在 tokios-connector.json 处手动设定，详情可参阅连接器配置。

执行部署注册操作。

In the Models tab, register the model and choose a public deployment name, for example qwen3-vl-tunnel. This name — not Ollama’s local model id — is what clients send in the model field.

生成 API 密钥。

进入 Keys 标签页后点击 Create key。此时请立即复制 sk-tok-… 令牌，该令牌仅显示一次。

随时调用该接口即可。

curl https://api.tokios.com/v1/chat/completions \
  -H "Authorization: Bearer sk-tok-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3-vl-tunnel",
    "messages": [
      {
        "role": "user",
        "content": [
          {"type": "text", "text": "What is in this image?"},
          {"type": "image_url", "image_url": {"url": "https://example.com/photo.jpg"}}
        ]
      }
    ]
  }'

export ANTHROPIC_BASE_URL=https://api.tokios.com
export ANTHROPIC_API_KEY=sk-tok-YOUR_KEY
claude --model qwen3-vl-tunnel

调用时使用的 model 字段值始终为您注册的部署名称（即上文中的 qwen3-vl-tunnel），而非 Ollama 的本地模型 ID。关于各客户端的完整配置流程，可参考 Claude Code 使用指南与 Cline 使用指南。

注意事项。

Qwen3-VL 将指令模式与思考模式分别打包为独立下载包，而非整合为带切换开关的单一模型；因此需提前选定所需的标签类型，即 qwen3-vl:8b 或 qwen3-vl:8b-thinking。
Qwen’s official README and model cards don’t publish explicit --tool-call-parser or --reasoning-parser flags for Qwen3-VL on vLLM/SGLang, unlike some other Qwen3 releases. Test tool-calling and thinking-tag behavior on your runtime before relying on it in production.
对于 30B-A3B 类型的 MoE 模型而言，即便每个令牌仅激活 3B 个参数，整个模型的所有参数仍需载入内存；因此硬件配置应基于完整下载体积而非活跃参数数量来规划。
The 32B and 235B-A22B variants need more hardware than most local Tokios users will have. Treat them as advanced pulls and confirm their exact files, context settings, and runtime support before planning around them.

快速入门

配置连接器并完成首个模型的端到端注册流程。

何种规模的模型适合您的显卡呢？

在下载 Qwen3-VL 之前，请先确认该模型与您现有显存容量的匹配程度。

量化处理与硬件适配

Qwen3-VL 提供的 GGUF 与 bf16 两种格式中，哪一种最适合您的硬件设备呢？

针对各类任务应如何挑选合适的本地模型呢？

通过任务类型对比，可了解 Qwen3-VL 与其他本地视觉模型的性能差异。

​利用 Ollama 在本地运行该模型

​版本类型与标签说明

​量化方式与格式说明

​硬件适配性分析

​操作指南——从入门到进阶

​功能特性

​通过 Tokios 连接器实现对接

​随时调用该接口即可。

​注意事项。

快速入门

何种规模的模型适合您的显卡呢？

量化处理与硬件适配

针对各类任务应如何挑选合适的本地模型呢？

利用 Ollama 在本地运行该模型

版本类型与标签说明

量化方式与格式说明

硬件适配性分析

操作指南——从入门到进阶

功能特性

通过 Tokios 连接器实现对接

随时调用该接口即可。

注意事项。