Youtu-Parsing-Omni高性能部署指南vLLM插件调优与OpenAI兼容API实战Youtu-Parsing-Omni 是腾讯优图实验室推出的 5B 全模态解析模型一个模型即可把文档、图片、图表、几何图形、音频和视频解析成结构化 JSON。本指南带你用 vLLM 插件完成高性能部署并调用 OpenAI 兼容 API 实战解析真实文件全程只需三步。一、为什么选 Youtu-Parsing-Omni 部署对新手来说这个项目最大的吸引力是部署友好单模型覆盖 7 类任务文档页document、自然图像natural_image、图表graphics_chart、流程图graphics_flowchart、几何图形graphics_geometric、音频audio、视频natural_video/textrich_video官方 vLLM 插件仓库自带vllm-plugin-vita-omni插件和钉死的运行时参数开箱即服务OpenAI 兼容 API服务启动后就是一个标准的http://127.0.0.1:8000/v1接口可以直接用 OpenAI SDK 调用业务代码几乎零改造小模型强成绩在 OmniDocBench v1.6 上取得 96.96 OverallOmniParsingBench 上以 75.08 平均分成为最强开源权重模型模型本体与部署说明都在本仓库中核心文件包括 model.safetensors、config.json 和 generation_config.json。二、一键安装步骤环境准备清单部署前请先对照下面这张清单90% 的踩坑都发生在环境阶段检查项要求说明Python 3.10低于此版本安装脚本会失败GPUCUDA 显卡推理需要 GPU 支持vLLM 环境vllm0.19.0transformers5.2.0提供服务的专用环境Transformers 环境transformers5.10.2仅本地推理时需要ffmpeg必须可用音频/视频输入解码依赖⚠️两个最容易踩的坑vLLM 与 Transformers 环境必须分开。两者钉死的transformers版本不同5.2.0 vs 5.10.2混装会互相破坏vLLM 服务环境中不能安装peft官方安装脚本会自动卸载它推荐用官方脚本一键装好 vLLM 服务环境git clone https://gitcode.com/tencent_hunyuan/Youtu-Parsing-Omni cd Youtu-Parsing-Omni # vLLM 服务环境推荐 bash scripts/setup_env.sh # 或 Transformers 本地推理环境独立 Python 环境 bash scripts/setup_env.sh --transformers如果偏好手动安装按 README 中的顺序执行安装requirements/vllm.txt→ 覆盖安装transformers5.2.0→ 卸载peft→ 以--no-deps方式安装vllm-plugin-vita-omni插件。三、vLLM 插件调优启动高性能服务3.1 用官方脚本启动推荐新手MODELtencent/Youtu-Parsing-Omni DATA_ROOT/path/to/media GPU0 bash scripts/vllm.sh脚本会启动一个 OpenAI 兼容服务器地址http://127.0.0.1:8000/v1服务名Youtu-Parsing-Omni并带上官方报告成绩所用的全部运行时配置。四个变量含义如下变量默认值含义MODEL必填模型 id 或本地 checkpoint 目录DATA_ROOT必填服务器唯一可读取本地媒体的目录GPU0服务运行的显卡CUDA_VISIBLE_DEVICESPORT8000服务端口3.2 官方钉死的引擎参数可直接抄以下参数是经过调优、跑出官方评测成绩的配置新手直接照抄即可参数取值调优解读--max-model-len65536超长上下文容纳大文档与视频帧 token--max-num-batched-tokens65536与模型长度对齐单请求即可打满批处理--max-num-seqs1解析类任务吃满单序列吞吐避免长 JSON 输出被并发截断--gpu-memory-utilization0.70留 30% 显存给 KV cache 外的临时缓冲--limit-mm-per-prompt{image: 8, video: 4, audio: 8}限制单次请求的多模态数量防止显存爆掉--seed1234固定随机种子保证结果可复现dtypebfloat16与模型权重 config.json 中的dtype保持一致另外注意服务只监听127.0.0.1本地安全前台运行、日志直接打到终端Ctrl-C即可停止vLLM 内部端口为30000可用VLLM_PORT覆盖。3.3 媒体 token 预算插件环境变量脚本还会导出插件读取的YOUTU_VITA_*媒体 token 预算环境变量。图像和视频每帧的 token 消耗上限定义在 processor_config.json 里例如图像image_max_num_tokens 32768视频帧video_image_max_num_tokens 1024、video_max_num_frames 128理解这些上限你就知道一次请求最多能喂进去多少视觉信息便于预估显存与耗时。3.4 解码参数调优贪心 停止词解析任务是确定性输出官方采用贪心解码temperature0并在/think/|end_of_text|处停止通过stop_token_ids实现可用服务的/tokenize端点查询对应 token id同时保留特殊 tokenskip_special_tokensFalse因为坐标就是靠特殊 token 编码的例如bbox: boxx_85y_275x_1000y_1000/box聊天模板由随模型发布的 chat_template.jinja 定义请求时必须开启解析模式chat_template_kwargs: {enable_thinking: false, enable_parsing: true}开启enable_parsing后模板会把媒体 token 直接拼在 prompt 前面、不带角色标记——这是本模型的专用解析通道漏开会导致输出质量明显下降。四、OpenAI 兼容 API 实战解析第一个文件4.1 请求三条铁律媒体放在文字前面image_url/audio_url/video_url在text之前开启解析模式chat_template_kwargs {enable_thinking: false, enable_parsing: true}贪心解码 停止词temperature0配合stop_token_ids并保留特殊 token4.2 用 OpenAI SDK 发第一个请求from openai import OpenAI client OpenAI(base_urlhttp://127.0.0.1:8000/v1, api_keyEMPTY) response client.chat.completions.create( modelYoutu-Parsing-Omni, messages[{role: user, content: [ {type: image_url, image_url: {url: file:///path/to/media/page.png}}, {type: text, text: Please perform end-to-end document parsing on the provided image. ...} ]}], temperature0.0, max_tokens32768, extra_body{ chat_template_kwargs: {enable_thinking: False, enable_parsing: True}, skip_special_tokens: False, min_tokens: 16, stop_token_ids: stop_token_ids, # 由 /tokenize 端点查得 }, ) print(response.choices[0].message.content)音频文件用audio_url字段传递视频用file://的video_url文件必须位于DATA_ROOT之下并在extra_body中加上mm_processor_kwargs: {nframes: 64, use_audio_in_video: true, use_vision_in_video: true}这样插件会把视频音轨和画面帧一起解码实现音画同步解析。4.3 各任务类型与示例脚本对应关系官方示例脚本覆盖了全部 7 类任务--task参数选择任务 prompt完整 prompt 见prompts/youtu_parsing_omni.jsonpython examples/infer_vllm.py --task document --media /path/to/media/page.png python examples/infer_vllm.py --task natural_image --media /path/to/media/photo.jpg python examples/infer_vllm.py --task graphics_chart --media /path/to/media/chart.png python examples/infer_vllm.py --task graphics_flowchart --media /path/to/media/flowchart.png python examples/infer_vllm.py --task graphics_geometric --media /path/to/media/geometry.png python examples/infer_vllm.py --task audio --media /path/to/media/speech.wav python examples/infer_vllm.py --task natural_video --media /path/to/media/clip.mp4 python examples/infer_vllm.py --task textrich_video --media /path/to/media/lecture.mp4不想走 vLLM 也可以用 Transformers 直接推理examples/infer_transformers.py参数同上需独立安装transformers5.10.2环境。4.4 看懂输出统一 JSON 信封所有任务都输出同一个 JSON 结构便于下游系统统一处理{ modality: image, subtype: natural_image, elements: [ {id: e_000, category: entity, bbox: boxx_350y_465x_590y_715/box, tag: snake bookmark, content: {text: , caption: A silver snake-shaped bookmark ...}} ], global_description: {caption: ..., narrative: ..., scene: ...} }几个关键点坐标用专用 token 编码在 0–1000 网格上左上角 x/y、右下角 x/y这就是必须保留特殊 token 的原因时间戳格式为HH:MM:SS图像任务返回elements文档类任务还带reading_order音频/视频任务返回时间轴segments每个输出都有global_description五、常见问题速查现象原因与解法安装脚本报依赖冲突vLLM 与 Transformers 环境混用了请建两个独立虚拟环境请求 4xx / 找不到文件媒体文件不在DATA_ROOT目录下--allowed-local-media-path限制输出缺少坐标信息设置了skip_special_tokensTrue应改为False输出乱跑或格式错误未开启enable_parsing或媒体与文字顺序颠倒音频/视频解码失败服务器环境缺少ffmpeg安装后重启服务端口被占用服务端口改PORTvLLM 内部端口改VLLM_PORT六、总结环境隔离vLLM 5.2.0 / Transformers 5.10.2ffmpeg是部署地基直接沿用官方钉死的引擎参数--max-num-seqs 1、--gpu-memory-utilization 0.70等即可获得与报告一致的性能请求三铁律媒体在前、开启enable_parsing、贪心解码保留特殊 token输出统一 JSON 0–1000 网格坐标接入下游系统只需一层解析按照以上步骤一张 8G 以上显存的显卡就能跑起 Youtu-Parsing-Omni 的高性能解析服务。祝部署顺利创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考