qwen-vl-utils 实战3 个函数管好图像缩放、视频帧采样与像素控制【免费下载链接】Qwen3-VLQwen3-VL is the multimodal large language model series developed by Qwen team, Alibaba Cloud.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen3-VL视觉预处理是推理管线里最容易翻车的环节图没对齐直接 OOM帧没限长 token 爆表。qwen-vl-utils 就是干这个的——图像缩放、像素上下限、视频帧采样一次调用全处理完你不用再手写 resize 代码。装完就能跑的最小示例装包只要一行命令下面 7 行代码跑通smart_resize和process_vision_info两个最常用函数。pip install qwen-vl-utilsfrom qwen_vl_utils import smart_resize, process_vision_info print(smart_resize(1080, 1920, factor28)) # (1092, 1932)两边都是 28 的整数倍 messages [{role: user, content: [ {type: image, image: file:///path/to/img.jpg}, {type: text, text: Describe this image.}]}] images, videos process_vision_info(messages) # [PIL.Image]或 None没有视频时输出就是可以直接塞给 processor 的 PIL 图像列表。注意utils 已经替你缩放过了后面调 processor 时传do_resizeFalse避免二次缩放官方 README 有明确提醒。像素控制到底在做什么一句话视觉 token 是按 patch 网格算的所以尺寸必须对齐网格总像素必须限上下限——不然 token 数不可控长视频直接把上下文吃穿。# 图像h、w 先取整到 factor 的倍数再夹进 [min_pixels, max_pixels] h_bar, w_bar round_by_factor(height, 28), round_by_factor(width, 28) if h_bar * w_bar max_pixels: ... # 等比缩小到上限内 elif h_bar * w_bar min_pixels: ... # 等比放大到下限以上fetch_image里 factor 14×2 28image_patch_size14默认min_pixels 4×28²、max_pixels 16384×28²。视频端fetch_video的帧级上限另有一套VIDEO_MAX_TOKEN_NUM768token/帧。从单张图到一段视频的完整链路整条链路是messages → extract_vision_info 提取 → fetch 缩放 → processor按顺序走一遍# 1. 输入图像用 file:// / URL / base64 / PIL 均可视频可以是文件也可以直接传帧列表 # 2. 处理extract_vision_info 扫出所有视觉元素 # 图像走 fetch_image帧列表走线程池并行缩放帧数向上取偶数补齐 # 视频走 后端读取 → smart_nframes 定帧数 → smart_resize 定帧尺寸 # 3. 输出images[PIL...]videos[Tensor(T,C,H,W)] messages [ {role: user, content: [ {type: image, image: file:///path/to/a.jpg}, {type: video, video: file:///path/to/b.mp4, fps: 2.0, max_frames: 768}, # 采样配置 {type: text, text: 发生了什么}]}] images, videos, video_kwargs process_vision_info( messages, return_video_kwargsTrue) # Qwen3-VL 还要加 image_patch_size16、return_video_metadataTrue inputs processor(texttext, imagesimages, videosvideos, paddingTrue, return_tensorspt, do_resizeFalse, **video_kwargs)帧数由smart_nframes算出总帧数/视频fps×目标fps夹进[4, 768]最后对齐到偶数。环境变量与进阶开关这些变量在qwen_vl_utils/vision_process.py里生效改环境变量即可不用动代码export FORCE_QWENVL_VIDEO_READERtorchcodec变量名作用典型值MODEL_SEQ_LEN模型上下文长度视频总像素预算按MODEL_SEQ_LEN×28²×0.9推导128000默认FORCE_QWENVL_VIDEO_READER强制视频解码后端优先级 torchcodec decord torchvisiontorchcodec/decord/torchvisionTORCHCODEC_NUM_THREADStorchcodec 的 FFmpeg 解码线程数8默认官方 README 的 Qwen2.5-VL 示例里还提到VIDEO_MAX_PIXELS环境变量但当前仓库源码中未检索到读取逻辑待验证建议以fetch_video的total_pixels参数为准。踩坑速查症状 → 原因 → 解法症状视频解码慢或卡在 decord 上不返回原因decord 有已知 hang 问题且停止维护未装 decord/torchcodec 时工具会自动降级到 torchvision解法装torchcodec并用FORCE_QWENVL_VIDEO_READER指定后端后端异常时日志会打印 warning 并回退 torchvision症状长视频跑 OOM 或序列超长原因帧数 × 每帧像素共同决定 token 数fps 和max_frames没压住解法调低fps、设小max_frames或在视频元素里传total_pixels限总预算默认预算由MODEL_SEQ_LEN推导症状ValueError: absolute aspect ratio must be smaller than 200原因smart_resize直接拒绝宽高比超过 200:1 的输入解法先裁剪再送入别指望它帮你救这种图症状断言报错Only accept either fps or nframes原因视频配置里同时写了fps和nframes解法二选一nframes会先对齐到偶数更多细节和完整示例见 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），仅供参考