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-VLQwen2.5-VL、Qwen3-VL 这类 Qwen-VL 系列模型都能接收图片和视频但原始文件的尺寸、像素数、帧数差异很大不能直接喂给模型。qwen-vl-utils 是 Qwen-VL 系列做视觉预处理的官方工具包负责统一的读取、缩放、抽帧。这篇教程面向第一次接触该系列模型的人按先跑通、再懂原理、最后调参数的顺序展开。问题场景原始文件为什么不能直接用模型的视觉编码器要求输入是规整的 patch 网格所以有几条硬性约束图像的宽高必须是 patch 因子factor的整数倍Qwen2.5-VL 是 28Qwen3-VL 是 32总像素数决定视觉 token 数量直接影响显存和推理耗时视频还要额外决定从任意长度里抽多少帧、每帧多大。qwen-vl-utils 把这几条规则封装进process_vision_info一次调用里你只需给出文件路径和提示词。最小上手路径第 1 步安装pip install qwen-vl-utils需要改源码时可先克隆仓库git clone https://gitcode.com/GitHub_Trending/qw/Qwen2.5-VL再对qwen-vl-utils/目录执行pip install -e。第 2 步跑通第一张图from qwen_vl_utils import process_vision_info messages [{role: user, content: [ {type: image, image: file:///path/to/photo.jpg}, {type: text, text: Describe this image.}, ]}] images, videos process_vision_info(messages) print(images[0].size) # 验证缩放后的实际尺寸先验证这一点打印出来的宽高应当都是 28或 32的倍数。图片支持本地路径、file://、http(s)://、base64 数据串和 PIL 对象带透明通道的 RGBA 图会自动铺白底转成 RGB。核心机制smart_resize 与 smart_nframes 各管什么函数职责关键约束smart_resize计算目标高宽宽高均为 factor 倍数总像素落在 [min_pixels, max_pixels] 内尽量保持宽高比长边/短边比值不能超过 200smart_nframes计算视频抽帧数fps与nframes二选一不能同时给帧数对齐到偶数且不超过视频总帧数process_vision_info统一入口扫描 messages把图像、视频条目分发给上面两个函数处理 factor 来自image_patch_size × 2Qwen2.5-VL 用默认值 14Qwen3-VL 要显式传 16。所以写resized_height/resized_width时不必自己凑倍数smart_resize会自动校正。分场景实践图像默认即可用有固定尺寸要求时再动手默认情况下按原图尺寸自动缩放。需要干预时固定输出尺寸传resized_height/resized_width适合多图对齐或省 token调整像素预算传min_pixels/max_pixels显存紧张时调低上限。这类竖版文档照片是像素预算的典型用户原图 1836×2448预处理后缩成对齐 factor 的较小尺寸在可读性和 token 数之间取平衡。视频先定抽帧数再谈分辨率抽帧策略二选一fps默认 2.0按帧率采样视频越长抽得越多被min_frames默认 4和max_frames默认 768夹住nframes显式指定帧数自动对齐为偶数。每帧分辨率由总像素预算 ÷ 帧数自动算出预算默认由MODEL_SEQ_LEN128000推导帧数越多每帧越小。所以帧多和帧清晰是此消彼长的关系——动作识别建议帧多一些静态场景理解可以少帧高分辨率。另外两个实用选项video_start/video_end单位秒只处理时间段适合长视频分段视频以帧路径列表传入时内部会用线程池并行读图最多 8 个 worker奇数帧会补最后一帧凑成偶数想保留时间信息时同时设置raw_fps。⚠️ Qwen2.5-VL 与 Qwen3-VL 的调用签名不同Qwen3-VL 需要额外传image_patch_size16和return_video_metadataTrue并把视频与元数据配对后传给 processor同时do_resizeFalse。照抄 Qwen2.5-VL 的示例跑 Qwen3-VL 容易对不上参数建议以qwen-vl-utils/README.md中对应模型的小节为准。参数与配置速查设置默认值作用什么时候调整fps2.0视频采样帧率需要更密/更疏的时间信息min_frames/max_frames4 / 768帧数上下限长视频、显存紧张nframes无显式帧数要精确对齐固定帧数resized_height/resized_width无固定输出尺寸多图对齐、控制 token 数min_pixels/max_pixels4×factor² / 16384×factor²每图帧像素上下限高分辨率任务或低端 GPUMODEL_SEQ_LEN128000视频总像素预算模型上下文更短或更长video_start/video_end整段按秒截取时间段长视频分段理解FORCE_QWENVL_VIDEO_READER自动锁定读取后端torchcodec / decord / torchvision某个后端出问题时TORCHCODEC_NUM_THREADS8torchcodec 解码线程数多任务并发export FORCE_QWENVL_VIDEO_READERdecord export MODEL_SEQ_LEN64000 export TORCHCODEC_NUM_THREADS4 视频读取后端的优先级是装了 torchcodec 用它其次 decord最后 torchvision进程启动时会在 stderr 打印当前使用的后端可以先确认这一行再排查其他问题。常见报错与排障报错或现象原因处理方式nframes should in interval [2, total_frames]nframes 超过视频总帧数或视频太短核对视频长度保证 nframes 不大于总帧数absolute aspect ratio must be smaller than 200图像过于细长裁剪或指定 resized 尺寸The given max_pixels exceeds limit每帧像素被总预算夹住属正常钳制减少帧数或提高预算日志出现后端降级 warning首选后端读取失败自动回退 torchvision用环境变量锁定后端或升级对应依赖torchvision 读 http 视频失败torchvision 低于 0.19升级到 0.19.0或换 decord 排障顺序建议先看日志里的后端名称、实际抽帧数和读取耗时这三个数字帧数不符合预期时优先检查fps与视频自身帧率的关系而不是怀疑缩放逻辑。下一步看哪里核心实现qwen-vl-utils/src/qwen_vl_utils/vision_process.py缩放、抽帧、后端切换逻辑都在这个文件里各模型的完整调用示例qwen-vl-utils/README.md场景化 Notebookcookbooks/下的 OCR、视频理解、文档解析、空间理解等示例配套的样例图片在同目录assets/中需要微调模型时qwen-vl-finetune/目录包含训练脚本与数据打包工具可对照预处理参数检查数据管线是否一致。【免费下载链接】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 视觉预处理入门：图像像素与视频帧数控制教程
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-VLQwen2.5-VL、Qwen3-VL 这类 Qwen-VL 系列模型都能接收图片和视频但原始文件的尺寸、像素数、帧数差异很大不能直接喂给模型。qwen-vl-utils 是 Qwen-VL 系列做视觉预处理的官方工具包负责统一的读取、缩放、抽帧。这篇教程面向第一次接触该系列模型的人按先跑通、再懂原理、最后调参数的顺序展开。问题场景原始文件为什么不能直接用模型的视觉编码器要求输入是规整的 patch 网格所以有几条硬性约束图像的宽高必须是 patch 因子factor的整数倍Qwen2.5-VL 是 28Qwen3-VL 是 32总像素数决定视觉 token 数量直接影响显存和推理耗时视频还要额外决定从任意长度里抽多少帧、每帧多大。qwen-vl-utils 把这几条规则封装进process_vision_info一次调用里你只需给出文件路径和提示词。最小上手路径第 1 步安装pip install qwen-vl-utils需要改源码时可先克隆仓库git clone https://gitcode.com/GitHub_Trending/qw/Qwen2.5-VL再对qwen-vl-utils/目录执行pip install -e。第 2 步跑通第一张图from qwen_vl_utils import process_vision_info messages [{role: user, content: [ {type: image, image: file:///path/to/photo.jpg}, {type: text, text: Describe this image.}, ]}] images, videos process_vision_info(messages) print(images[0].size) # 验证缩放后的实际尺寸先验证这一点打印出来的宽高应当都是 28或 32的倍数。图片支持本地路径、file://、http(s)://、base64 数据串和 PIL 对象带透明通道的 RGBA 图会自动铺白底转成 RGB。核心机制smart_resize 与 smart_nframes 各管什么函数职责关键约束smart_resize计算目标高宽宽高均为 factor 倍数总像素落在 [min_pixels, max_pixels] 内尽量保持宽高比长边/短边比值不能超过 200smart_nframes计算视频抽帧数fps与nframes二选一不能同时给帧数对齐到偶数且不超过视频总帧数process_vision_info统一入口扫描 messages把图像、视频条目分发给上面两个函数处理 factor 来自image_patch_size × 2Qwen2.5-VL 用默认值 14Qwen3-VL 要显式传 16。所以写resized_height/resized_width时不必自己凑倍数smart_resize会自动校正。分场景实践图像默认即可用有固定尺寸要求时再动手默认情况下按原图尺寸自动缩放。需要干预时固定输出尺寸传resized_height/resized_width适合多图对齐或省 token调整像素预算传min_pixels/max_pixels显存紧张时调低上限。这类竖版文档照片是像素预算的典型用户原图 1836×2448预处理后缩成对齐 factor 的较小尺寸在可读性和 token 数之间取平衡。视频先定抽帧数再谈分辨率抽帧策略二选一fps默认 2.0按帧率采样视频越长抽得越多被min_frames默认 4和max_frames默认 768夹住nframes显式指定帧数自动对齐为偶数。每帧分辨率由总像素预算 ÷ 帧数自动算出预算默认由MODEL_SEQ_LEN128000推导帧数越多每帧越小。所以帧多和帧清晰是此消彼长的关系——动作识别建议帧多一些静态场景理解可以少帧高分辨率。另外两个实用选项video_start/video_end单位秒只处理时间段适合长视频分段视频以帧路径列表传入时内部会用线程池并行读图最多 8 个 worker奇数帧会补最后一帧凑成偶数想保留时间信息时同时设置raw_fps。⚠️ Qwen2.5-VL 与 Qwen3-VL 的调用签名不同Qwen3-VL 需要额外传image_patch_size16和return_video_metadataTrue并把视频与元数据配对后传给 processor同时do_resizeFalse。照抄 Qwen2.5-VL 的示例跑 Qwen3-VL 容易对不上参数建议以qwen-vl-utils/README.md中对应模型的小节为准。参数与配置速查设置默认值作用什么时候调整fps2.0视频采样帧率需要更密/更疏的时间信息min_frames/max_frames4 / 768帧数上下限长视频、显存紧张nframes无显式帧数要精确对齐固定帧数resized_height/resized_width无固定输出尺寸多图对齐、控制 token 数min_pixels/max_pixels4×factor² / 16384×factor²每图帧像素上下限高分辨率任务或低端 GPUMODEL_SEQ_LEN128000视频总像素预算模型上下文更短或更长video_start/video_end整段按秒截取时间段长视频分段理解FORCE_QWENVL_VIDEO_READER自动锁定读取后端torchcodec / decord / torchvision某个后端出问题时TORCHCODEC_NUM_THREADS8torchcodec 解码线程数多任务并发export FORCE_QWENVL_VIDEO_READERdecord export MODEL_SEQ_LEN64000 export TORCHCODEC_NUM_THREADS4 视频读取后端的优先级是装了 torchcodec 用它其次 decord最后 torchvision进程启动时会在 stderr 打印当前使用的后端可以先确认这一行再排查其他问题。常见报错与排障报错或现象原因处理方式nframes should in interval [2, total_frames]nframes 超过视频总帧数或视频太短核对视频长度保证 nframes 不大于总帧数absolute aspect ratio must be smaller than 200图像过于细长裁剪或指定 resized 尺寸The given max_pixels exceeds limit每帧像素被总预算夹住属正常钳制减少帧数或提高预算日志出现后端降级 warning首选后端读取失败自动回退 torchvision用环境变量锁定后端或升级对应依赖torchvision 读 http 视频失败torchvision 低于 0.19升级到 0.19.0或换 decord 排障顺序建议先看日志里的后端名称、实际抽帧数和读取耗时这三个数字帧数不符合预期时优先检查fps与视频自身帧率的关系而不是怀疑缩放逻辑。下一步看哪里核心实现qwen-vl-utils/src/qwen_vl_utils/vision_process.py缩放、抽帧、后端切换逻辑都在这个文件里各模型的完整调用示例qwen-vl-utils/README.md场景化 Notebookcookbooks/下的 OCR、视频理解、文档解析、空间理解等示例配套的样例图片在同目录assets/中需要微调模型时qwen-vl-finetune/目录包含训练脚本与数据打包工具可对照预处理参数检查数据管线是否一致。【免费下载链接】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），仅供参考