Youtu-Parsing-Omni视频解析实战：从自然视频到OCR+ASR结构化报告的完整流程-育师

Youtu-Parsing-Omni视频解析实战：从自然视频到OCR+ASR结构化报告的完整流程

Youtu-Parsing-Omni是腾讯优图实验室开源的 5B 全模态解析模型，输入一段自然视频、图片或音频，即可输出统一结构的 JSON 解析结果。本文以"视频解析"为主线，带你走通从环境搭建、模型服务，到把一段讲课视频转换成OCR + ASR + Markdown 结构化报告的完整实战流程，新手也可以照着跑。

一、Youtu-Parsing-Omni 能解析哪些视频？

Youtu-Parsing-Omni 用同一个 JSON 信封（OmniSchema）覆盖 8 类输入。与视频直接相关的有两类任务：

视频类型	`--task`参数	核心输出内容
自然视频（vlog、活动记录等）	`natural_video`	时间分段内的视觉元素、动作、交互、镜头运动、音轨信息
富文本视频（讲课、字幕视频等）	`textrich_video`	各分段的OCR + ASR，以及整段视频的 Markdown`structured_report`

区别很简单：

natural_video：画面本身是主角，模型关注"发生了什么"——人物、动作、镜头运动；
textrich_video：画面上的文字和口播内容是主角，模型把字幕、板书、口播逐段对齐，最后汇总成一份可直接阅读的结构化报告。

所有输出的顶层结构统一为modality/subtype+ 内容字段 +global_description，坐标用<box><x_..><y_..></box>这类专用 token 编码到 0–1000 归一化网格，时间戳统一为HH:MM:SS格式。

二、搭建环境：一条命令装好依赖

1. 克隆代码仓库

git clone https://gitcode.com/tencent_hunyuan/Youtu-Parsing-Omni

注意：推理脚本位于官方youtu-parsing仓库的youtu_parsing_omni子目录下，模型权重则对应tencent/Youtu-Parsing-Omni这个 checkpoint。

2. 初始化 Python 环境

bash scripts/setup_env.sh # vLLM 服务模式（transformers==5.2.0） bash scripts/setup_env.sh --transformers # Transformers 直接推理（transformers==5.10.2）

三条新手必读的安装细节：

两种模式必须用不同的 Python 环境：vLLM 服务与 Transformers 推理锁定的transformers版本不同（5.2.0 vs 5.10.2）；
视频解析依赖ffmpeg抽帧和解码音轨，安装前请先确认ffmpeg -version可用；
vLLM 服务环境中不能安装peft，安装脚本会自动清理。

三、启动 vLLM 服务：最快的部署方式

MODEL=tencent/Youtu-Parsing-Omni DATA_ROOT=/path/to/media GPU=0 bash scripts/vllm.sh

启动后，服务在http://127.0.0.1:8000/v1提供 OpenAI 兼容接口，模型名Youtu-Parsing-Omni。

变量	默认值	含义
`MODEL`	必填	Hugging Face 模型 id 或本地 checkpoint 目录
`DATA_ROOT`	必填	服务端唯一允许读取本地媒体文件的目录
`GPU`	`0`	运行服务的 GPU（`CUDA_VISIBLE_DEVICES`）
`PORT`	`8000`	服务端口

服务端固定使用报文中报告的运行参数：--max-model-len 65536、--gpu-memory-utilization 0.70、每次请求限 4 个视频（--limit-mm-per-prompt '{"video": 4, ...}'），保证长视频也能完整解析。

四、核心实战：解析一段富文本视频

把待解析的视频放到DATA_ROOT目录之下，然后执行：

python examples/infer_vllm.py --task textrich_video --media /path/to/media/lecture.mp4

如果你要解析的是"发生了什么"类的自然视频，把任务换成natural_video即可：

python examples/infer_vllm.py --task natural_video --media /path/to/media/clip.mp4

用 Transformers 直接推理（不走服务）时，命令几乎一样：

MODEL=tencent/Youtu-Parsing-Omni python examples/infer_transformers.py --model $MODEL --task textrich_video --media /path/to/media/lecture.mp4

两种推理方式的差异：Transformers 模式对媒体路径没有DATA_ROOT限制，但要求用trust_remote_code=True加载仓库自带的模型代码（本仓库的 modeling_youtu_vita.py 就是被执行的实现）。

五、看懂输出：分段 OCR + ASR 与 structured_report

textrich_video任务返回一个 fenced ```json 代码块，结构上分三层：

modality/subtype：固定为video/text_rich_video；
segments（时间分段）：每个分段携带时间戳（HH:MM:SS）、画面内文字的OCR 结果与 bbox 坐标、对应时段的ASR 语音转写，画面上的文字和口播内容按时间轴逐段对齐；
Markdownstructured_report：对整个视频做全局汇总的 Markdown 报告，含标题结构、要点总结，可直接渲染阅读。

另外所有输出都带global_description（caption / narrative / scene）。解码采用贪心策略，在Finish/<|end_of_text|>处停止，且保留特殊 token——因为坐标就编码在这些专用 token 里，这也是 chat 模板要求开启解析模式的原因：

{"chat_template_kwargs": {"enable_thinking": false, "enable_parsing": true}}

该模板逻辑在随模型发布的 chat_template.jinja 中，enable_parsing开启后，媒体 token（<|video|>）会直接后接任务 prompt 渲染。

六、视频是怎么被"听看"的：音画融合机制

Youtu-Parsing-Omni 视频解析的核心，是在编码器内部完成音画对齐，而不是把帧和音频分开处理再交给解码器拼接：

时间顺序打包：视频帧与音频块按时间轴打包进同一条序列。音频处理器会把音轨切成 2–30 秒的块（见 video_processing_youtu_vita.py 中的video_audio_chunk_min_second/video_audio_chunk_max_second默认值）；
融合层（fusion layers）：大部分层里每个帧、每个音频块拥有独立注意力窗口；少数被标记的融合层在每个"音频→帧"边界开启新窗口，让画面帧能直接注意到同一时刻的声音。哪些层参与融合由 config.json 的video_fusion_layer_freq配置；
统一时间坐标：视觉 token 的t取自帧序号，音频 token 的t取自时间偏移，两种模态共享同一套 (t, h, w) 位置编码，跨模态对齐在感知阶段就算完了。

这一路径的模型实现是 modeling_youtu_vita.py 中的forward_video，由video_omni_fusion开关控制是否启用联合编码。

七、新手避坑清单

问题	解决方式
视频请求报媒体路径错误	vLLM 模式下文件必须位于`DATA_ROOT`之下
抽帧/解码失败	安装并配置`ffmpeg`到`PATH`
视频 token 预算不足	vLLM 插件通过`YOUTU_VITA_*`环境变量调节媒体 token 预算，原始请求建议`nframes: 64`
vLLM 装不上模型	确认`peft`已卸载、`transformers`为 5.2.0
输出坐标乱码	解码时不要跳过特殊 token（`skip_special_tokens=False`）

原始 OpenAI 请求里，视频需要发送file://形式的video_url，并在mm_processor_kwargs中开启"nframes": 64, "use_audio_in_video": true, "use_vision_in_video": true，插件才会同时解码音轨与画面帧。