qwen-vl-utils 避坑实战3 个函数搞定高分辨率图片与长视频的 Token 爆炸【免费下载链接】Qwen3-VLQwen3-VL is the multimodal large language model series developed by Qwen team, Alibaba Cloud.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen3-VL直接把 4K 截图或小时级长视频丢进 Qwen2.5-VL结果必然是视觉 token 激增、显存溢出、抽帧数量失控。qwen-vl-utils 是 Qwen2.5-VL 仓库里的视觉输入预处理组件图像智能缩放、视频智能抽帧、统一入口把素材喂给模型。qwen-vl-utils 解决什么问题一行命令装好调用链里你负责 messagesprocessor 负责 tokenization夹在中间的环节就是这个工具把图像/视频文件取回来、缩放到模型吃得下的尺寸、算出视频帧数再交给 processor。它管喂多少、怎么喂不碰推理和训练。安装一行搞定要求 Python ≥ 3.8pip install qwen-vl-utils想用 decord 视频后端就装pip install qwen-vl-utils[decord]。核心逻辑集中在 vision_process.py 一个文件里几百行可通读三版模型的用法示例见 README。值得记住的 3 个函数smart_resize把尺寸对齐到 token 预算先记住映射关系Qwen2.5-VL 里 28×28 像素 1 个视觉 token28 patch 14 × 合并 2所谓token 上限本质是像素上限。smart_resize 在三个约束下给出一对新尺寸宽高都能被 28 整除、总像素落在 [4, 16384] token 区间、宽高比尽量不变。from qwen_vl_utils import smart_resize h, w smart_resize(height800, width600, factor28) print(h, w) # 两者均能被 28 整除另一条硬约束宽高比必须小于 200否则直接抛 ValueError超宽全景图要先裁再传。smart_nframes视频抽帧数量的算法只有一行总帧数 / 原始fps × 采样fps再夹进 [min_frames, max_frames] 并对齐成偶数。默认 2.0 帧/秒边界是 4 帧和 768 帧fps 与 nframes 二选一同时传会直接断言失败。from qwen_vl_utils import smart_nframes n smart_nframes({fps: 2.0}, total_frames300, video_fps30) # 300 帧 / 30fps 10 秒 × 2fps 20 帧落在 [4, 768] 内process_vision_info统一入口把整份 messages 列表传进去返回 images、videos 两个列表原样交给 processor 即可。内部图片走 fetch_image、视频走 fetch_video即上面两个函数无需自己分流。from qwen_vl_utils import process_vision_info messages [{role: user, content: [ {type: image, image: file:///path/to/your/image.jpg}, {type: text, text: Describe this image.} ]}] images, videos process_vision_info(messages)接 Qwen2.5-VL 时记得加return_video_kwargsTrue把第三个返回值 video_kwargs 拆出来传给 processor否则采样 fps 信息会丢。最常用的两条上手路径图像 3 参数、视频 4 参数图像输入路径qwen-vl-utils 图像输入预处理示例smart_resize 自动调整尺寸什么都不传smart_resize 在 [4, 16384] token 区间内自选尺寸最常用resized_height / resized_width指定目标尺寸内部仍会对齐到 28 的倍数min_pixels / max_pixels调高或压低单图像素预算是控制 token 爆炸的直接旋钮image 字段的取值支持本地路径、file:// 路径、URL、base64 与内存中的 PIL 对象。视频输入路径fps默认 2.0抽帧密度与视频时长共同决定帧数随后夹进 [4, 768]min_frames / max_frames帧数边界配合 fps 生效长视频务必显式压上限resized_height / resized_width限制单帧尺寸直接影响每帧 token 数video_start / video_end按秒数裁剪再抽帧避免整段上传传预抽好的帧图片列表代替视频文件也可以内部用线程池并发读取并发数为 min(8, 帧数)。进阶调优4 个环境变量与后端选择VIDEO_MAX_PIXELS视频总像素上限官方示例32000 * 28 * 28 * 0.9按模型可接受的最大 token 数配置MODEL_SEQ_LEN默认 128000视频单帧像素上限按它折算上下文留得长可调大FORCE_QWENVL_VIDEO_READER强制指定后端取值 torchvision / decord / torchcodecTORCHCODEC_NUM_THREADStorchcodec 解码线程数默认 8CPU 紧张可下调后端优先级显式指定 torchcodec若已装 decord若已装 torchvision。首次读视频时会往 stderr 打印实际使用的后端启动时确认一次即可。常见坑与规避5 个高频问题格式/编解码不支持torchcodec 依赖 FFmpeg非 Linux 系统可能装不上 decord 轮子。选中的后端抛异常时会自动降级回 torchvision 并打 warning 日志查日志确认不是静默失败。URL 读视频torchvision 0.19.0 不支持任何 http(s) 地址decord 只支持 http 不支持 https仅 torchcodec 两者都支持在线视频先确认后端版本。网络超时图像 URL 下载没有重试机制超时会直接报错生产环境优先落成本地文件。超宽图宽高比 ≥ 200 是 smart_resize 的硬约束先裁剪再传。nframes 超过总帧数只告警不报错最终结果会被夹到总帧数长尾视频注意核对。动手前自查清单已安装 qwen-vl-utils 且 Python ≥ 3.8已确认视频后端首次读视频看 stderr 打印长视频预估过时长设置了 max_frames高分辨率图已决定用 max_pixels 还是 resized_* 控制像素预算Qwen2.5-VL 路径已加 return_video_kwargsTruevideo_kwargs 传进 processor改过环境变量后重启了进程均在导入时读取【免费下载链接】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），仅供参考 qwen-vl-utils 避坑实战：3 个函数搞定高分辨率图片与长视频的 Token 爆炸
qwen-vl-utils 避坑实战3 个函数搞定高分辨率图片与长视频的 Token 爆炸【免费下载链接】Qwen3-VLQwen3-VL is the multimodal large language model series developed by Qwen team, Alibaba Cloud.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen3-VL直接把 4K 截图或小时级长视频丢进 Qwen2.5-VL结果必然是视觉 token 激增、显存溢出、抽帧数量失控。qwen-vl-utils 是 Qwen2.5-VL 仓库里的视觉输入预处理组件图像智能缩放、视频智能抽帧、统一入口把素材喂给模型。qwen-vl-utils 解决什么问题一行命令装好调用链里你负责 messagesprocessor 负责 tokenization夹在中间的环节就是这个工具把图像/视频文件取回来、缩放到模型吃得下的尺寸、算出视频帧数再交给 processor。它管喂多少、怎么喂不碰推理和训练。安装一行搞定要求 Python ≥ 3.8pip install qwen-vl-utils想用 decord 视频后端就装pip install qwen-vl-utils[decord]。核心逻辑集中在 vision_process.py 一个文件里几百行可通读三版模型的用法示例见 README。值得记住的 3 个函数smart_resize把尺寸对齐到 token 预算先记住映射关系Qwen2.5-VL 里 28×28 像素 1 个视觉 token28 patch 14 × 合并 2所谓token 上限本质是像素上限。smart_resize 在三个约束下给出一对新尺寸宽高都能被 28 整除、总像素落在 [4, 16384] token 区间、宽高比尽量不变。from qwen_vl_utils import smart_resize h, w smart_resize(height800, width600, factor28) print(h, w) # 两者均能被 28 整除另一条硬约束宽高比必须小于 200否则直接抛 ValueError超宽全景图要先裁再传。smart_nframes视频抽帧数量的算法只有一行总帧数 / 原始fps × 采样fps再夹进 [min_frames, max_frames] 并对齐成偶数。默认 2.0 帧/秒边界是 4 帧和 768 帧fps 与 nframes 二选一同时传会直接断言失败。from qwen_vl_utils import smart_nframes n smart_nframes({fps: 2.0}, total_frames300, video_fps30) # 300 帧 / 30fps 10 秒 × 2fps 20 帧落在 [4, 768] 内process_vision_info统一入口把整份 messages 列表传进去返回 images、videos 两个列表原样交给 processor 即可。内部图片走 fetch_image、视频走 fetch_video即上面两个函数无需自己分流。from qwen_vl_utils import process_vision_info messages [{role: user, content: [ {type: image, image: file:///path/to/your/image.jpg}, {type: text, text: Describe this image.} ]}] images, videos process_vision_info(messages)接 Qwen2.5-VL 时记得加return_video_kwargsTrue把第三个返回值 video_kwargs 拆出来传给 processor否则采样 fps 信息会丢。最常用的两条上手路径图像 3 参数、视频 4 参数图像输入路径qwen-vl-utils 图像输入预处理示例smart_resize 自动调整尺寸什么都不传smart_resize 在 [4, 16384] token 区间内自选尺寸最常用resized_height / resized_width指定目标尺寸内部仍会对齐到 28 的倍数min_pixels / max_pixels调高或压低单图像素预算是控制 token 爆炸的直接旋钮image 字段的取值支持本地路径、file:// 路径、URL、base64 与内存中的 PIL 对象。视频输入路径fps默认 2.0抽帧密度与视频时长共同决定帧数随后夹进 [4, 768]min_frames / max_frames帧数边界配合 fps 生效长视频务必显式压上限resized_height / resized_width限制单帧尺寸直接影响每帧 token 数video_start / video_end按秒数裁剪再抽帧避免整段上传传预抽好的帧图片列表代替视频文件也可以内部用线程池并发读取并发数为 min(8, 帧数)。进阶调优4 个环境变量与后端选择VIDEO_MAX_PIXELS视频总像素上限官方示例32000 * 28 * 28 * 0.9按模型可接受的最大 token 数配置MODEL_SEQ_LEN默认 128000视频单帧像素上限按它折算上下文留得长可调大FORCE_QWENVL_VIDEO_READER强制指定后端取值 torchvision / decord / torchcodecTORCHCODEC_NUM_THREADStorchcodec 解码线程数默认 8CPU 紧张可下调后端优先级显式指定 torchcodec若已装 decord若已装 torchvision。首次读视频时会往 stderr 打印实际使用的后端启动时确认一次即可。常见坑与规避5 个高频问题格式/编解码不支持torchcodec 依赖 FFmpeg非 Linux 系统可能装不上 decord 轮子。选中的后端抛异常时会自动降级回 torchvision 并打 warning 日志查日志确认不是静默失败。URL 读视频torchvision 0.19.0 不支持任何 http(s) 地址decord 只支持 http 不支持 https仅 torchcodec 两者都支持在线视频先确认后端版本。网络超时图像 URL 下载没有重试机制超时会直接报错生产环境优先落成本地文件。超宽图宽高比 ≥ 200 是 smart_resize 的硬约束先裁剪再传。nframes 超过总帧数只告警不报错最终结果会被夹到总帧数长尾视频注意核对。动手前自查清单已安装 qwen-vl-utils 且 Python ≥ 3.8已确认视频后端首次读视频看 stderr 打印长视频预估过时长设置了 max_frames高分辨率图已决定用 max_pixels 还是 resized_* 控制像素预算Qwen2.5-VL 路径已加 return_video_kwargsTruevideo_kwargs 传进 processor改过环境变量后重启了进程均在导入时读取【免费下载链接】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），仅供参考