把图像视频喂给 Qwen2.5-VL 前qwen-vl-utils 如何替你管好视觉输入像素控制【免费下载链接】Qwen3-VLQwen3-VL is the multimodal large language model series developed by Qwen team, Alibaba Cloud.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen3-VL在 Qwen2.5-VL 的推理链路里qwen-vl-utils 负责视觉输入像素控制smart_resize 把图片对齐到 28 的倍数并卡住像素上下限smart_nframes 按 fps 或 nframes 决定视频抽多少帧process_vision_info 把整批消息里的图和视频统一预处理成模型可直接吃的张量。三者决定 token 消耗和显存占用本文带你把它们的用法和默认值一次讲清。先搞清楚为什么视觉输入要管像素多模态模型会把图像切成一小块一小块的 patch再映射成 token 送进模型像素越多token 越多单次推理的显存和耗时跟着涨像素太少细节丢失答案质量掉得明显如果你自己手动缩放缩法和模型内部的 patch 网格14×142×2 合并后按 28 对齐不一致还会白白浪费算力。这张桌面截图在演示里会被压到 28 的整数倍再切 patch。对一张整屏截图在模型眼里可能只值几十个 token全看像素预算给多少。所以缩放这件事交给工具包做你只负责定规则。3 分钟跑通第一个例子pip install qwen-vl-utils装完就能用。下面这段是图像输入的最小闭环跑通即算上手from transformers import Qwen2_5_VLForConditionalGeneration, AutoProcessor from qwen_vl_utils import process_vision_info messages [{role: user, content: [ {type: image, image: file:///path/to/img.jpg}, {type: text, text: 图里有什么}]}] images, videos process_vision_info(messages) # 随后交给 AutoProcessor / 模型即可processor(text..., imagesimages, videosvideos)process_vision_info(messages)扫描消息列表里的image/video条目读完文件就完成 smart_resize 对齐返回两个列表图片列表和视频张量列表。三个高频问题一次解决图片太大token 爆表怎么办先手算一遍缩放结果from qwen_vl_utils import smart_resize h, w smart_resize(height800, width600, factor28) print(h, w) # 476 336均为 28 的倍数smart_resize把高宽对齐到 28 的倍数、尽量保比例总像素被min_pixels/max_pixels卡住不传时默认 3136 ~ 12,845,056 像素对应 4 ~ 16,384 个 token。真调用时两种写法messages [{role: user, content: [ {type: image, image: file:///a.jpg, resized_height: 280, resized_width: 420}, # 指定目标尺寸 {type: image, image: file:///b.jpg, max_pixels: 512 * 28 * 28}, # 直接给像素预算 {type: text, text: 两图各是什么}]}]前者给目标宽高内部仍走一遍smart_resize后者用max_pixels直接圈定上限超了自动缩传值会取 min 值兜底。视频帧数怎么定才不拖慢速度一条 2 分钟、30fps 的视频默认 2fps 采样就是 240 帧逐帧过视觉编码器非常吃时间。用smart_nframes先算出该抽几帧from qwen_vl_utils import smart_nframes n smart_nframes({nframes: 12}, total_frames2100, video_fps30) print(n) # 12{nframes: 12}表示从 2100 帧里均匀抽 12 帧结果对齐到偶数{fps: 1.0}则按每秒抽 1 帧计算再用min_frames/max_frames兜底默认 4 ~ 768。注意fps和nframes二选一同时传会直接断言报错短视频若算出帧数超过总帧数会打一条 warning 后按全帧处理。显存不够怎么调视频是显存大户每帧都占 token总预算受最大序列长度约束。三个旋钮export VIDEO_MAX_PIXELS768*28*28 # 单帧上限 export MODEL_SEQ_LEN64000 # 序列长度上限MODEL_SEQ_LEN默认 128000决定视频总像素预算的上限VIDEO_MAX_PIXELS收紧单帧上限也可以在视频消息字段里直接传max_pixels/total_pixels逐条覆盖。降帧数nframes、降单帧像素max_pixels、降总预算MODEL_SEQ_LEN三条路按你的显存挑着拧。参数与环境变量速查参数所在位置默认值作用factorsmart_resize28高宽对齐因子patch(14) × 2×2 合并min_pixels/max_pixelssmart_resize3136 / 12,845,056图片总像素上下限4 / 16,384 tokennframessmart_nframes—直接指定抽帧数对齐到偶数fpssmart_nframes2.0按目标帧率换算抽帧数与 nframes 二选一min_frames/max_framessmart_nframes4 / 768fps 模式下的抽帧数兜底区间resized_height/resized_widthimage / video 消息不传自动目标尺寸内部仍经 smart_resize 对齐max_pixels/total_pixelsimage / video 消息16,384×28² / 按 MODEL_SEQ_LEN单图 / 视频总像素预算传值取较小者生效VIDEO_MIN_PIXELS/VIDEO_MAX_PIXELS环境变量128×28² / 768×28²视频单帧像素上下限MODEL_SEQ_LEN环境变量128000最大序列长度决定视频总预算FORCE_QWENVL_VIDEO_READER环境变量自动探测强制后端torchcodec / decord / torchvisionTORCHCODEC_NUM_THREADS环境变量8torchcodec 的 ffmpeg 解码线程数报错排查速答Q日志出现 video_reader_backend ... error, use torchvision as defaultA主后端decord 或 torchcodec解码失败工具包会自动降级到 torchvision 重读属于自愈留意 warning 即可。想固定某后端设FORCE_QWENVL_VIDEO_READER。Qabsolute aspect ratio must be smaller than 200A图片宽高比超过 200 时smart_resize拒绝处理不会自动裁切。先裁掉黑边或改走小图通道再送入。Qassert Only accept either fps or nframesAfps和nframes是互斥写法留一个删一个。短视频按 fps 算出的帧数超过总帧数时会打 warning 并退化为全帧采样属正常行为。下一步qwen-vl-utils 把视觉输入像素控制的三件事收口smart_resize 管像素对齐smart_nframes 管抽帧数process_vision_info 管整体预处理。建议先用默认配置跑通一条推理再按显存逐步收紧max_pixels与MODEL_SEQ_LEN遇到解码异常先看 stderr 里打印的后端名和total_frames信息答案基本就在那里。更多消息字段与 Qwen3-VL 的接入差异见qwen-vl-utils 的 README。【免费下载链接】Qwen3-VLQwen3-VL is the multimodal large language model series developed by Qwen team, Alibaba Cloud.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen3-VL创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考