WeVisOne-VL API参数手册:predict()接口、任务类型与返回值完整参考
WeVisOne-VL API参数手册:predict()接口、任务类型与返回值完整参考
WeVisOne-VL-2B 是腾讯微信视觉团队推出的统一视觉感知大模型,一个模型即可同时完成目标检测、指代定位、计数、OCR、语义分割与抠图等 7 类视觉任务。本文是面向新手和开发者的 WeVisOne-VL API 参数手册,完整讲解 predict() 接口的每个参数、支持的任务类型(task)、query 查询写法以及返回值结构,帮你快速、正确地调用这个 All-in-One 视觉模型。
一、模型简介:一个模型搞定 7 种视觉任务
WeVisOne-VL(WeChat Vision All-in-One)由微信视觉团队开发,基于 Qwen3-VL 构建,约 2B 参数。它的核心思路是:用统一的结构化文本预测来覆盖不同粒度的视觉感知任务:
- 物体级感知(Object-level):开放词汇目标检测、指代定位(Referring)、物体计数、物体指向(Pointing)、OCR 文本定位
- 像素级感知(Pixel-level):指代分割(Referring Segmentation)、提示式抠图(Promptable Alpha Matting)
其中像素级能力来自模型附带的一个轻量级像素解码器 mask_decoder.pt(仅 9,511,460 个参数),它由三部分组成:
- Visual Feature Adapter:作用于 Qwen3-VL 多层 ViT 特征;
- Box-Guided Query Decoder:6 层可变形交叉注意力解码块;
- Instance-Conditioned Dense Prediction Head:在 S/4、S/2、S/1 三个尺度上逐级细化,输出全分辨率(stride 1)连续 alpha 抠图。
💡 细节说明见 README.md 中的 "Architecture & Released Revision" 一节。
二、环境准备与模型加载
调用 API 前,需要先安装官方推理包,然后加载模型权重。
pip install wevisone-vl
加载只需三行代码,指定模型名和精度即可:
from PIL import Image
from wevisone_vl import WeVisOneVL
model = WeVisOneVL("tencent/WeVisOne-VL-2B", device="auto", dtype="bfloat16")
| 参数 | 说明 |
|---|---|
device |
设备选择,"auto" 会自动分配 GPU/CPU |
dtype |
计算精度,推荐 "bfloat16"(模型 config.json 中默认精度) |
图片需用 PIL 打开并转换为 RGB 模式:
image = Image.open("example.jpg").convert("RGB")
三、predict() 接口参数详解
predict() 是 WeVisOne-VL 的核心推理入口,完整调用如下:
result = model.predict(image, task="matting", query="person", temperature=0.0)
3.1 参数一览
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
image |
PIL.Image | 是 | 输入的 RGB 图片(OpenCV 读取需转成 RGB) |
task |
str | 是 | 任务类型,决定模型执行哪类感知,见下文第四节 |
query |
str | 视任务 | 目标描述词,如 "person"、"red car";开放词汇检测可省略 query 表示"所有物体" |
temperature |
float | 否 | 采样温度。0.0 表示贪心解码,结果最稳定,结构化输出任务推荐 0.0 |
3.2 为什么推荐 temperature=0.0?
模型默认采样参数定义在 generation_config.json 中:
temperature: 0.7top_k: 20top_p: 0.8
这套参数适合"自然语言式"回答。但 WeVisOne-VL 输出的是结构化坐标 token(如 <250> <300> <450> <500> 这类归一化坐标),带随机采样会导致坐标抖动、框位置不稳定。因此在做检测、定位、计数等任务时,建议显式传入 temperature=0.0 获取确定性结果。
四、task 任务类型与 query 用法速查
task 参数决定了模型的"工作模式",不同任务对 query 的要求不同:
| task 值 | 任务类型 | query 示例 | 输出形态 |
|---|---|---|---|
"detection" |
开放词汇目标检测 | "car"(省略则检测所有物体) |
归一化边界框列表 |
"referring" |
指代定位 | "the red cup on the left" |
单个边界框 |
"counting" |
物体计数 | "bicycle" |
数量(文本) |
"pointing" |
物体指向 | "the dog" |
归一化坐标点 |
"ocr" |
文本定位 | "menu" 或具体文字 |
文本区域框 |
"segmentation" |
指代分割 | "the banana" |
文本 + 分割 mask |
"matting" |
提示式抠图 | "person" |
文本 + 全分辨率 alpha matte |
4.1 坐标体系:0~1000 归一化
模型使用专用的坐标 token(<0> 到 <1000>)来表示归一化后的边界框和点。也就是说,模型输出的坐标范围是 0~1000,还原到原图时只需按图片宽高做线性缩放:
# 假设模型返回归一化框 [x1, y1, x2, y2](0~1000)
W, H = image.size
x1 = x1 / 1000 * W
y1 = y1 / 1000 * H
x2 = x2 / 1000 * W
y2 = y2 / 1000 * H
对稠密任务(检测等),模型会在每个预测框后输出特殊实例 token <OBJ>(token ID 152678),用于分隔多个实例,推理包会自动解析,你拿到的是结构化结果而非原始 token。
4.2 目标不存在时返回 None
这是一个重要行为:当查询的目标在图中不存在时,模型返回 None,而不是报错或返回空框。业务代码中务必先判断返回值:
result = model.predict(image, task="referring", query="the white horse")
if result is None:
print("图中未找到目标")
五、返回值 result 结构解析
以 README 中的示例调用为例:
result = model.predict(image, task="matting", query="person", temperature=0.0)
print(result.response, len(result.masks))
返回值对象主要包含两个字段:
| 字段 | 说明 |
|---|---|
result.response |
模型的文本输出,如目标描述、计数结果、OCR 识别出的文字内容 |
result.masks |
像素级任务的 mask 列表(分割/抠图),len(result.masks) 即实例数量 |
不同任务下两个字段的"含金量"不同:
- 检测/指代/计数/指向/OCR:重点看
result.response,其中包含结构化的坐标与文本信息; - segmentation / matting:重点看
result.masks,每个元素对应一个实例的 mask;matting 任务输出的是连续 alpha matte(0~1 透明通道,支持毛发等精细边缘),分割任务输出的是二值 mask。
像素级输出由 mask_decoder.pt 生成,该文件是运行 matting/segmentation 任务的必需组件,加载模型时会自动加载,请勿单独删除。
六、生成参数与底层配置速查
| 文件 | 关键内容 | 对调用的影响 |
|---|---|---|
| generation_config.json | temperature=0.7、top_k=20、top_p=0.8 |
默认采样参数,结构化任务建议覆盖为 temperature=0.0 |
| config.json | 基于 qwen3_vl 架构,dtype=bfloat16 |
加载模型时的推荐精度 |
| processor_config.json | 图像预处理:缩放、归一化(均值/方差 0.5)、patch 大小 16 | 输入图片无需手动预处理,predict() 内部自动完成 |
| tokenizer_config.json | 分词器配置,model_max_length=8192 |
上下文长度上限 |
| chat_template.jinja | 对话模板 | 内部使用,无需手动配置 |
6.1 图片预处理要注意什么?
从 processor_config.json 可见,模型内部会自动完成:RGB 转换(do_convert_rgb)、缩放(do_resize,短边下限 65536 像素的 token 预算控制)、归一化(均值 0.5 / 标准差 0.5)。你只需要:
- 用 PIL 打开图片;
- 转成 RGB 三通道(灰度图、带 alpha 的 PNG 都需要转换);
- 直接传给
predict()。
七、常见问题与使用限制(FAQ)
Q1:视频能直接输入吗? 目前不支持。模型针对单轮图像感知设计,像素解码器会拒绝视频网格输入(video grids are rejected)。
Q2:抠图边缘不理想的常见原因? README 中明确列出的限制:精细 alpha 边缘对图片分辨率、严重遮挡、复杂透明物体(玻璃、纱帘)以及 prompt 措辞比较敏感。可以尝试提高输入分辨率、换一种 query 描述方式。
Q3:counting 任务的输出在哪看?
计数结果包含在 result.response 文本中,与检测框的解析方式不同,直接读取响应文本即可。
Q4:可以用它做自主决策或人脸识别吗? 官方声明本模型仅用于视觉感知研究,不应用于自主高影响决策,也不应用于个人身份识别。
Q5:许可证是什么? 腾讯作者代码遵循 Apache License 2.0,第三方组件保留各自原有许可,使用前建议查看对应源文件。
八、一页速查:从加载到出结果的完整流程
from PIL import Image
from wevisone_vl import WeVisOneVL
# 1. 加载模型
model = WeVisOneVL("tencent/WeVisOne-VL-2B", device="auto", dtype="bfloat16")
# 2. 准备图片
image = Image.open("example.jpg").convert("RGB")
# 3. 调用推理(task 决定任务,query 描述目标)
result = model.predict(image, task="matting", query="person", temperature=0.0)
# 4. 判空 + 解析结果
if result is None:
print("未找到目标")
else:
print(result.response, len(result.masks))
记住三个要点即可上手 WeVisOne-VL:
task定任务,query定目标——7 种任务共用一个predict()入口;temperature=0.0保证坐标输出稳定;- 目标不存在时返回
None,记得判空。
掌握以上内容,你就拿到了这份 WeVisOne-VL API 参数手册的全部核心信息,可以直接把它放进你的视觉理解项目里跑起来。