WeVisOne-VL 是腾讯 WeChat Vision 团队开源的统一视觉感知大模型（VLM），一个模型同时支持目标检测、指代定位、计数、指点、OCR、分割与抠图（Alpha Matting）等 8 类视觉任务。本文带你用 3 步在本地启动它的 Gradio Web Demo，讲解如何切换到 vLLM 后端加速推理，并详解--device、--mock、--share这 3 个最实用的进阶参数，让你在没有 GPU、多人共享或指定设备运行时都能顺利跑通。

一、快速上手：3 步在本地启动 Gradio Demo

Demo 入口是 demo/app.py，官方文档见 demo/README.md。整个过程只需 3 步。

第 1 步：克隆仓库

git clone https://gitcode.com/gh_mirrors/we/WeVisOne-VL.git cd WeVisOne-VL

第 2 步：创建环境并安装依赖

建议 Python 3.10，依赖清单见 requirements.txt（torch、transformers、gradio、vllm 等均已锁定版本）：

conda create -n wevisone-vl python=3.10 -y conda activate wevisone-vl pip install -r requirements.txt pip install -v -e .

第 3 步：一条命令启动

CUDA_VISIBLE_DEVICES=0 python demo/app.py --model tencent/WeVisOne-VL-4B

启动成功后浏览器打开http://localhost:8080即可使用。显存紧张可换成更轻量的 2B 版本：

CUDA_VISIBLE_DEVICES=0 python demo/app.py --model tencent/WeVisOne-VL-2B

💡 也可以直接执行封装好的启动脚本 demo/run_demo.sh，它会自动设置PYTHONPATH并透传参数；模型路径还可以通过环境变量WEVISONE_MODEL指定，命令行--model优先。

完整的命令行选项如下（摘自 demo/README.md）：

二、界面速览：8 种任务 + 示例图库，开箱即玩

Demo 界面遵循「选任务 → 传图/填 query → Run」三步操作：

1. Choose a task：顶部 8 个任务按钮，分为对象级（Grounding / Dense Detection / Counting / Pointing / OCR / Caption）和像素级（Segmentation / Matting）两组，切换任务会自动带出对应的示例 query；
2. Image & query：上传图片、输入查询语句，还可以展开 "Prompt sent to the model" 手改最终 prompt；
3. Result：右侧展示可视化结果、实例统计与耗时，"Model Output" 里能看到模型原始输出。

底部 Examples 图库内置 8 个一键示例（图片位于 demo/examples/images/），点击即可自动填入图片、任务和 query。比如 Dense Detection 任务会一次定位客厅里的沙发、抱枕、茶几、台灯等：

Pointing 任务则用点位逐一标出图中的狗：

像素级任务是 WeVisOne-VL 的招牌能力。Matting 任务内置 4 种显示模式：Green Screen / Overlay / Alpha Matte / Cutout，输入一张海边人像：

即可输出连续 Alpha Matte，无需 SAM，直接得到发丝级边缘：

而 Referring Segmentation 能根据自然语言描述精确分割目标，官方对比案例见 assets/case_study/refseg.jpg：

三、vLLM 加速：一键切换高吞吐推理后端

默认transformers后端适合单用户试用；多人共用或批量跑图时，切换到 vLLM 后端吞吐更高，只需加一个参数：

CUDA_VISIBLE_DEVICES=0 python demo/app.py \ --model tencent/WeVisOne-VL-4B \ --backend vllm \ --server-name 0.0.0.0 \ --server-port 8080

vLLM 引擎的初始化逻辑在 wevisone_vl/engine.py，默认gpu_memory_utilization=0.45，会与同卡其他进程共享显存；vllm已包含在 requirements.txt 中，无需额外安装。两种后端任务能力完全一致，切换不影响 8 类任务的输出。

⚠️ 建议：只有一张卡且单人使用就保持transformers默认值；需要对外提供在线服务或同时处理多图时选vllm。

四、3 个进阶参数详解

以下 3 个参数（定义见 demo/app.py）覆盖最常见的特殊场景：

1.--device：指定运行设备

默认auto会自动选择 GPU。多卡机器想固定用某张卡时写cuda:0、cuda:1；华为昇腾 NPU 环境可用npu:0；纯 CPU 调试写cpu（速度较慢，仅验证流程用）：

python demo/app.py --device cuda:1

2.--mock：无 GPU 也能预览界面

加上--mock会跳过模型加载，用一个内置的 MockEngine（demo/app.py）返回模拟的框和遮罩，CPU 上秒开界面，适合没有 GPU 时先熟悉交互、或在 CI 里做 UI 冒烟测试：

python demo/app.py --mock

3.--share：生成公网临时链接

Demo 默认监听0.0.0.0:8080，局域网同事可直接访问http://<你的IP>:8080；如果机器在云端或内网隔离，加--share可让 Gradio 生成一个公网临时分享链接直接发给别人试用：

python demo/app.py --model tencent/WeVisOne-VL-2B --backend vllm --share

五、进阶玩法与参考资料

• 生成参数面板：界面 "Generation Parameters" 折叠区暴露了temperature（默认 0.0）、top_p（0.95）、top_k（50）、max_new_tokens（4096）、repetition_penalty（1.05）等滑杆，调参结果无需重跑模型即可实时重绘（见 demo/app.py）；
• 可视化微调：Font Size、Line Width、框颜色、Mask 叠加透明度、分割阈值均可在线调整，纯 CPU 重绘不消耗 GPU；
• 官方 Cookbooks：三个 Notebook 手把手讲各任务用法——对象级流水线、OCR 流水线、分割与抠图流水线；
• 代码级示例：不想用网页也可以直接跑 demo/examples/detection_example.py，里面演示了model.predict()的标准调用方式；
• 评测流程：想复现官方 benchmark 结果，参考 evaluation/README.md。

装好环境、敲下启动命令，几分钟内你就能在自己的机器上体验 WeVisOne-VL 从「点框」到「像素」的完整视觉感知能力了 🚀