WeVisOne-VL API参数手册:predict()接口、任务类型与返回值完整参考

原创2026-10-24 17:15:091,952 阅读
文章标签:人工智能多模态计算机视觉深度学习OCR图像处理

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 个参数),它由三部分组成:

  1. Visual Feature Adapter:作用于 Qwen3-VL 多层 ViT 特征;
  2. Box-Guided Query Decoder:6 层可变形交叉注意力解码块;
  3. 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.7
  • top_k: 20
  • top_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)。你只需要:

  1. 用 PIL 打开图片;
  2. 转成 RGB 三通道(灰度图、带 alpha 的 PNG 都需要转换);
  3. 直接传给 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:

  1. task 定任务,query 定目标——7 种任务共用一个 predict() 入口;
  2. temperature=0.0 保证坐标输出稳定;
  3. 目标不存在时返回 None,记得判空。

掌握以上内容,你就拿到了这份 WeVisOne-VL API 参数手册的全部核心信息,可以直接把它放进你的视觉理解项目里跑起来。

登录后查看全文
WeVisOne-VL-2B