vLLM-Omni 中的 LTX-2 家族：文生视频/图生视频与同步音频生成完整指南

vLLM-Omni 中的 LTX-2 家族文生视频/图生视频与同步音频生成完整指南【免费下载链接】vllm-omniA framework for efficient model inference with omni-modality models项目地址: https://gitcode.com/GitHub_Trending/vl/vllm-omniLTX-2 / LTX-2.3 是带有同步音频的文生视频T2V与图生视频I2V扩散模型家族。本文以 recipes/LTX/LTX-2.md 为主体结合 vLLM-Omni 仓库中 vllm_omni/diffusion/models/ltx2 的源码实现系统讲解其 Pipeline 体系、API 迁移、默认参数、序列并行约束、Serving 启动与请求、多模态 Guidance 控制以及自定义 Sigma 调度帮助你从配置到调用完整掌握 LTX-2 家族的部署与调优方法。一、LTX-2 家族总览与 Pipeline 体系LTX-2 家族覆盖两个模型版本LTX-2 与 LTX-2.3每个版本又区分**单阶段one-stage与双阶段two-stage**两种执行形态并各自支持 T2V 与 I2V 两种任务。仓库通过 vllm_omni/diffusion/models/ltx2/ltx2_recipes.py 中的声明式 Recipe 将「执行方式」与「组件加载」解耦resolve_ltx_pipeline_recipe(pipeline_kind, model_version)按(pipeline_kind, model_version)二元组索引到对应的LTXPipelineRecipeRecipe 中定义了阶段顺序、每阶段的 Guidance 规格、空间下采样倍数、Sigma 调度、负向提示词与请求能力开关。1.1 Pipeline 对照表下表给出--model-class-name可选值与对应任务、所需 checkpoint 仓库均为 Hugging Face 下载单位--model-class-name任务所需 checkpoint 仓库LTX2PipelineLTX-2 单阶段 T2V/I2VLightricks/LTX-2LTX2TwoStagePipelineLTX-2 常规双阶段 T2V/I2VLightricks/LTX-2LTX2DistilledOneStagePipelineLTX-2 合并蒸馏单阶段 T2V/I2Vrootonchair/LTX-2-19b-distilledLTX2DistilledTwoStagePipelineLTX-2 合并蒸馏双阶段 T2V/I2Vrootonchair/LTX-2-19b-distilledLTX2PipelineLTX-2.3 单阶段 T2V/I2Vdiffusers/LTX-2.3-DiffusersLTX2TwoStagePipelineLTX-2.3 常规双阶段 T2V/I2Vdiffusers/LTX-2.3-DiffusersLightricks/LTX-2.3LTX2DistilledOneStagePipelineLTX-2.3 合并蒸馏单阶段 T2V/I2Vdiffusers/LTX-2.3-Distilled-DiffusersLTX2DistilledTwoStagePipelineLTX-2.3 合并蒸馏双阶段 T2V/I2Vdiffusers/LTX-2.3-Distilled-DiffusersLightricks/LTX-2.3表中每一行是一个「下载单元」一个完整的 Pipeline 仓库内含 Transformer、文本编码器text encoder、连接器connectors、视频/音频 VAE、声码器vocoder、调度器scheduler与分词器tokenizer。补充仓库则提供 LoRA 或上采样器upsampler等 sidecar 组件。运行时runtime首先在模型根目录按官方文件名查找 sidecar找不到时再从对应的 Lightricks Hub 仓库下载对应实现见 vllm_omni/diffusion/models/ltx2/ltx2_components.py 中的_LTX_COMPONENT_SUBFOLDERS与 sidecar 解析逻辑。1.2 单阶段入口LTX2PipelineLTX2Pipeline是统一的单阶段入口声明于 pipeline_ltx2.py。它由 checkpoint 元数据自动选择 LTX-2 或 LTX-2.3 配置档案profile省略图像参数即 T2V提供一个起始图像即 I2V。由于两个单阶段仓库都声明了该类所以对单阶段场景--model-class-name可以省略。需要注意LTX-2.3 必须使用 Diffusers 格式的 checkpoint原始的Lightricks/LTX-2.3safetensors 仓库不可直接加载。这与 ltx2_components.py 中LTX23_COMPONENT_PROFILE的组件契约一致——它需要 Diffusers 侧的LTX2VocoderWithBWE等组件导入失败时回退到LTX2Vocoder只有 Diffusers 格式才能正确解析。1.3 双阶段与蒸馏 PipelineLTX2TwoStagePipeline先用常规模型在半分辨率如 768×512下采样生成再上采样并用蒸馏 LoRA 精修refine。对应源码 pipeline_ltx2_two_stage.py 中的LTX2TwoStagePipeline其 Recipe 为_official_two_stage_recipeltx2_recipes.py阶段 1generate_lowres使用与单阶段一致的 Guidance 规格并施加spatial_downscale2阶段 2refine固定 positive-only 且挂载蒸馏 LoRAadapter_slotltx_distilled。LTX2DistilledOneStagePipeline使用合并蒸馏后的 Transformer不做上采样直接在其原生单阶段分辨率下运行。源码中通过_distilled_one_stage_recipe把双阶段 Recipe 的阶段 1 提取出来并将spatial_downscale置 1、分辨率减半ltx2_recipes.py。LTX2DistilledTwoStagePipeline两个阶段都用合并蒸馏 Transformer阶段 1 在 512×768 低分辨率下用固定 8 步 Sigma 调度生成阶段 2 在 latent 空间上采样后用固定 3 步精修。源码见 ltx2_recipes.py固定调度LTX_DISTILLED_SIGMAS与LTX_STAGE_2_DISTILLED_SIGMAS定义在同文件顶部。废弃别名LTX2DistilledPipeline仍保留为LTX2DistilledTwoStagePipeline的向后兼容别名pipeline_ltx2_two_stage.py 与 registry.py 中均有登记。所有双阶段条目都支持 T2V 与 I2V使用时需显式指定--model-class-name。二、API 迁移位置参数收窄为req唯一统一入口后LTX2Pipeline的forward只允许req作为位置参数传入其余可选参数全部改为 keyword-only# 不再支持会抛 TypeError pipe(req, prompt) pipe(req, image, prompt) # 支持 pipe(req, promptprompt) pipe(req, imageimage, promptprompt)传入第二个位置参数现在一律抛出TypeError。此改动同时影响直接 Python 调用者与显式指定--model-class-name的场景离线与 Serving 入口本就使用具名字段因此不受影响。此次合并还移除了以下注册名无别名需改用上表对应写法已移除名称替代方案LTX23PipelineLTX2Pipeline由 checkpoint 元数据自动选择 LTX-2.3LTX2ImageToVideoPipelineLTX2Pipeline并传imageLTX23ImageToVideoPipelineLTX2Pipeline并传image元数据选择 LTX-2.3LTX2TwoStagesPipelineLTX2DistilledTwoStagePipelineLTX2ImageToVideoTwoStagesPipelineLTX2DistilledTwoStagePipeline并传image三、默认参数单阶段与双阶段 Recipe 对比3.1 单阶段默认值来自 Recipe参数LTX-2LTX-2.3宽 × 高768 × 512768 × 512帧数 / 帧率121 / 24121 / 24去噪步数4030视频/音频 CFG3.0 / 7.03.0 / 7.0视频/音频 STG1.0 / 1.01.0 / 1.0视频/音频跨模态引导3.0 / 3.03.0 / 3.0视频/音频 rescale0.7 / 0.70.7 / 0.7视频/音频 STG 块[29]/[29][28]/[28]这些默认值直接固化在 ltx2_recipes.py 的LTX2_ONE_STAGE_RECIPE与LTX23_ONE_STAGE_RECIPE中_official_guidance(29)/_official_guidance(28)生成视频侧cfg_scale3.0, stg_scale1.0, modality_scale3.0, rescale_scale0.7音频侧cfg_scale7.0其余相同num_inference_steps分别为 40LTX-2与 30LTX-2.3。Recipe 还提供默认负向提示词LTX_DEFAULT_NEGATIVE_PROMPT覆盖模糊、运动模糊、肢体畸形、口型不同步、机器人音色、回声、AI 伪影等 60 条目LTX-2.3 的LTX25_DEFAULT_NEGATIVE_PROMPT在开头额外追加has_subtitles, has_blurbox, transition from black, transition to black, speech_ending_short。当请求未显式传负向提示词时运行时按「请求值 → 直接传参 → Recipe 默认」的优先级链取用。顶层guidance_scale会同时覆盖视频与音频的 CFG 值。注意在线视频 API 默认num_frames为1必须显式设置而离线 LTX 脚本默认121。3.2 双阶段默认值参数常规双阶段全蒸馏双阶段最终宽 × 高1536 × 10241536 × 1024阶段 1 宽 × 高768 × 512768 × 512帧数 / 帧率121 / 24121 / 24阶段 1 / 阶段 2 步数40LTX-2或 30LTX-2.3/ 38 / 3引导方式阶段 1 带引导阶段 2 仅正样本固定仅正样本约束要点API 尺寸是最终尺寸必须能被 64 整除所有 LTX 请求要求num_frames 8k1如 121。常规双阶段的阶段 1 使用上文 3.1 的单阶段默认值LTX-2 或 LTX-2.3 各自对应。蒸馏调度固定num_inference_steps若提供必须为8两个蒸馏条目均拒绝自定义sigmas与输入 latents。常规双阶段对未量化 BF16 Transformer 使用层融合 LoRAlayer-fused LoRA启用量化时自动切换为动态 LoRA。四、序列并行Sequence Parallelism纯 Ulysses 约束LTX 家族仅支持严格 Ulysses形式的序列并行不支ring 形式的 SP其可整除性约束为((F - 1) / 8 1) * (H / 32) * (W / 32) 且 TP-local 的 SP attention head 数 必须能被 ulysses_degree 整除其中每个阶段需使用该阶段的H, W双阶段下分别对应半分辨率与全分辨率形状不可整除则直接报错。以默认的 121 帧、768×512H512, W768为例序列长度为((121-1)/81) * (512/32) * (768/32) 16 * 16 * 24 6144必须被ulysses_degree整除6144 2^11 × 3因此 2、3、4、6、8 等因子均可具体以实际配置校验为准。源码层面ltx2_sequence_parallel.py 实现了LTX2VideoToAudioParallelAttention视频 K/V 按序列维度分片而短得多的音频 query 采用复制replicated策略仅重分发 K/V 并按序切分音频 query 头最后聚合输出头——只需 3 次集合通信而非标准 Ulysses 的 4 次同时保持音频侧复制。构造函数中明确断言ring_degree必须为 1否则抛出NotImplementedError印证「纯 Ulysses only」的约束。五、Serving 部署启动与请求5.1 启动单阶段vllm serve Lightricks/LTX-2 --omni --stage-init-timeout 600vllm serve diffusers/LTX-2.3-Diffusers --omni --stage-init-timeout 600两个单阶段 checkpoint 都声明LTX2Pipeline因此无需--model-class-name。5.2 启动双阶段需显式指定类# LTX-2 全蒸馏双阶段 vllm serve rootonchair/LTX-2-19b-distilled --omni \ --model-class-name LTX2DistilledTwoStagePipeline --stage-init-timeout 600 # LTX-2.3 全蒸馏双阶段缺失时自动解析 v1.1 x2 上采样器 vllm serve diffusers/LTX-2.3-Distilled-Diffusers --omni \ --model-class-name LTX2DistilledTwoStagePipeline --stage-init-timeout 600 # LTX-2.3 常规双阶段 vllm serve diffusers/LTX-2.3-Diffusers --omni \ --model-class-name LTX2TwoStagePipeline \ --enable-layerwise-offload \ --stage-init-timeout 600同一个服务同时处理 T2V 与 I2V。T2V 请求使用所选 Recipe 的默认引导curl -X POST http://localhost:8000/v1/videos/sync \ -F promptA cinematic close-up of ocean waves at golden hour. \ -F negative_promptworst quality, inconsistent motion, blurry, jittery, distorted \ -F size768x512 \ -F num_frames121 \ -F fps24 \ -F seed42 \ -o ltx_t2v.mp4I2V 请求恰好提供一个起始图像curl -X POST http://localhost:8000/v1/videos/sync \ -F promptA plush toy astronaut gently waving while the camera slowly pushes in. \ -F negative_promptworst quality, inconsistent motion, blurry, jittery, distorted \ -F input_reference/absolute/path/to/reference.png \ -F size768x512 \ -F num_frames121 \ -F fps24 \ -F seed42 \ -o ltx_i2v.mp4若引用图片以 URL 或 JSON 安全形式给出改用image_reference字段不要与input_reference同时提供。在线视频 API 的完整字段说明可参考 docs/serving/videos_api.md 与 docs/user_guide/examples/online_serving/text_to_video.md。六、多模态 Guidance视频/音频独立控制单阶段与常规双阶段的阶段 1 支持视频/音频相互独立的文本 CFG、时空引导STG、跨模态引导modality guidance与引导重缩放rescale蒸馏阶段与常规双阶段的阶段 2 固定为 positive-only。参数默认值作用别名video_cfg_scale3.0视频文本 CFG1.0禁用video_cfg_guidance_scaleaudio_cfg_scale7.0音频文本 CFG1.0禁用audio_cfg_guidance_scalevideo_stg_scale1.0视频 STG0.0禁用video_stg_guidance_scaleaudio_stg_scale1.0音频 STG0.0禁用audio_stg_guidance_scalevideo_modality_scale3.0音频→视频引导1.0禁用a2v_guidance_scaleaudio_modality_scale3.0视频→音频引导1.0禁用v2a_guidance_scalevideo_rescale_scale0.7视频引导重缩放0.0禁用—audio_rescale_scale0.7音频引导重缩放0.0禁用—video_stg_blocks[29]/[28]被扰动的视频 Transformer 块—audio_stg_blocks[29]/[28]被扰动的音频 Transformer 块—STG 块默认值按 LTX-2 / LTX-2.3 展示。规范名优先于别名显式顶层guidance_scale优先于两个 CFG 字段——需要独立控制视频/音频 CFG 时应省略顶层guidance_scale。这些字段在在线请求中放入extra_params离线脚本用--extra-body# 附加到上文 curl 请求 -F extra_params{video_cfg_scale:3.0,audio_cfg_scale:7.0} # 附加到 text_to_video.py 或 image_to_video.py --extra-body {video_cfg_scale:3.0,audio_cfg_scale:7.0}离线示例脚本位于 examples/offline_inference/text_to_video/text_to_video.py 与 examples/offline_inference/image_to_video/image_to_video.py。Serving 入口可接受的extra_params字段白名单定义于 vllm_omni/model_extras/ltx2.pyLTX_EXTRA_BODY_PARAMS涵盖上述全部 Guidance 字段及sigmas、stage_1_sigmas、stage_2_sigmas等。6.1 Guidance 并行--cfg-parallel-size对 LTX 而言cfg_parallel_size表示并行执行完整 guidance 计划guidance plan的 rank 数量。虽然名字沿用了历史cfg前缀它实际覆盖文本 CFG、STG 与跨模态引导的所有 pass引导重缩放在所有 pass 预测收集完毕后再统一施加。默认单阶段 Recipe 与常规双阶段阶段 1 每个去噪步有 4 个 Transformer passcond条件、uncond无条件、ptbSTG 扰动、mod跨模态。这一 pass 集合由 ltx2_guidance.py 的LTXGuidancePlan.build依据 Guidance 规格动态构造只要 CFG、STG、跨模态任一开启即追加对应 pass。因此实用的均衡配置如下--cfg-parallel-size每 rank pass 数guidance 槽位利用率说明14100%单 rank 融合 guidance batch22100%推荐的双 rank 配置41100%每 rank 一个 guidance pass其他正整数也可用。当 pass 数不能被cfg_parallel_size整除时rank 会补齐到等量执行槽位LTX 会打印包含预期利用率的警告。例如 4 个 pass 跑在 3 个 rank 上占用 6 个槽位利用率 66.7%。启动带两路 guidance 并行的 LTX-2.3 服务vllm serve diffusers/LTX-2.3-Diffusers --omni \ --cfg-parallel-size 2 --stage-init-timeout 600总设备数 cfg_parallel_size× 其他已配置的并行维度之积。纯 positive-only 的蒸馏阶段不会从cfg_parallel_size 1获益。6.2 Python APIOmniDiffusionSamplingParams与DiffusionRequestBatch常规逐请求参数放在OmniDiffusionSamplingParams中然后把构造好的DiffusionRequestBatch作为唯一位置参数传入from vllm_omni.diffusion.request import OmniDiffusionRequest from vllm_omni.diffusion.worker.request_batch import DiffusionRequestBatch from vllm_omni.inputs.data import OmniDiffusionSamplingParams params OmniDiffusionSamplingParams( width768, height512, num_frames121, frame_rate24.0, num_inference_steps30, seed42, extra_args{video_cfg_scale: 3.0, audio_cfg_scale: 7.0}, ) req DiffusionRequestBatch([ OmniDiffusionRequest( prompt{prompt: Cherry blossoms moving in a light breeze}, sampling_paramsparams, request_idltx-example, ) ]) t2v_output pipe(req) i2v_output pipe(req, imageimage)直接关键字参数是底层回退手段例如pipe(req, promptprompt, width768)。请求对象字段优先除非下文另有说明。6.3 完整forward参数面参数类型/默认含义与约束reqDiffusionRequestBatch必填唯一位置参数内含提示词与逐请求采样参数。imageimage 或 batchNone直接值优先于请求内图像无图即 T2V。I2V 每个提示词接受一张图batch 内不能混用 T2V/I2V。promptstring 或 listNone正向文本回退请求提示词优先。与prompt_embeds互斥。negative_promptstring 或 listNone依次回退请求值、Recipe 默认与负向 embeddings 互斥。heightintNone请求 → 直接值 → Recipe 默认单阶段需被 32 整除双阶段需被 64 整除。widthintNone与height优先级和对齐要求一致。num_framesintNone请求 → 直接值 → Recipe 默认必须8k1同时与frame_rate共同决定音频时长。frame_ratefloatNone请求frame_rate→ 请求fps→ 直接值 → Recipe 默认。num_inference_stepsintNone请求 → 直接值 → Recipe 默认单阶段与常规阶段 1 最小 2蒸馏阶段 1 固定 8。单阶段自定义sigmas决定实际步数。sigmasfloat 列表None仅单阶段。请求值优先fused batch 内所有请求必须使用同一调度。timestepsint 列表None兼容槽位LTX 只接受None请用sigmas。guidance_scalefloatNone单阶段与常规阶段 1 的视频/音频公共 CFG 回退显式请求值优先。蒸馏阶段固定 positive-only。guidance_rescalefloatNone只接受None或0.0请用 modality rescale 字段。noise_scalefloat0.0兼容槽位LTX 只接受0.0。num_videos_per_promptint1输出数量回退请求侧正整数num_outputs_per_prompt优先。generatorgenerator 或 listNone显式 RNG否则汇总请求 generator/seed。列表须匹配有效输出 batch。latentstensorNone仅单阶段。请求 tensor 优先接受 packed[B, S, C]与经验证的非 packed 视频布局。audio_latentstensorNone仅单阶段。请求 tensor 优先并做 collate。prompt_embedstensorNone预计算正向条件须配套prompt_attention_mask不能与prompt同用。negative_prompt_embedstensorNone单阶段与常规阶段 1 的条件须配套 mask不能与negative_prompt同用。prompt_attention_masktensorNone正向 embeddings 的 mask请求侧prompt_attention_mask或attention_mask优先。negative_prompt_attention_masktensorNone负向 embeddings 的 mask请求侧负向 mask 字段优先。decode_timestepfloat 或 list0.0视频 VAE 解码时间步请求值优先。列表长度可匹配 1、提示词 batch 或输出 batch。decode_noise_scalefloat 或 listNone列表规则同上请求值优先默认等于decode_timestep。output_typestringnp请求值优先。np解码输出latent跳过 VAE/vocoder 解码。return_dictboolTrue兼容槽位只接受True。attention_kwargsdictNone单次调用不支持请在引擎启动时配置 attention。max_sequence_lengthintNone请求 → 直接值 → 分词器上限。请求对象命名仅少数几处不同num_videos_per_prompt对应请求侧num_outputs_per_prompt图像与提示词文本/embeddings 位于请求 prompt 载荷中LTX Guidance 字段位于采样参数的extra_args中。6.4 各 Recipe 的请求能力对照覆盖项单阶段常规双阶段蒸馏双阶段Guidance支持仅阶段 1阶段 2 positive-only固定 positive-only负向提示词/embeddings支持阶段 1 支持拒绝num_inference_steps支持控制阶段 1阶段 2 固定 3阶段 1 固定 8阶段 2 固定 3自定义sigmas支持拒绝拒绝两阶段均固定调度视频/音频 latents支持拒绝拒绝这些能力检查对直接forward关键字与OmniDiffusionSamplingParams中的值一视同仁不支持的取值会报错失败而非被静默忽略。6.5 自定义 Sigma 调度单阶段 Python 请求可以直接设置最终调度器的边界params OmniDiffusionSamplingParams(sigmas[1.0, 0.75, 0.5, 0.25])每个非终值产生一步去噪省略时自动追加终值0.0。该调度覆盖num_inference_stepsfused batch 内所有请求必须使用同一列表。注意视频表单 API 与随附离线 CLI 当前不暴露sigmas白名单 vllm_omni/model_extras/ltx2.py 中虽有sigmas字段但表单/CLI 层未接线。6.6 约束清单LTX 拒绝非默认的timesteps、flow_shift、guidance_rescale、noise_scale、attention_kwargs与return_dictFalse。请分别改用最终sigmas、modality rescale 字段、启动时 attention 配置与标准DiffusionOutput。fused 单阶段请求必须解析出相同的 LTX Guidance 与 Sigma 调度。请保持并发请求 guidance 同质或使用--max-num-seqs 1。--cfg-parallel-size对完整 LTX guidance 计划含 STG、跨模态引导与 rescale 兼容的预测收集进行分片。Ulysses 会对补齐后的音频 latents 做掩码视频序列须满足上文序列并行可整除性约束。Cache-DiT 仅限单阶段多阶段配置被拒绝LTX2_ONE_STAGE_RECIPE与LTX23_ONE_STAGE_RECIPE中supports_cache_ditTrue而双阶段 Recipe 未开启。七、运行注意事项与基准LTX-2 单阶段此前在一张 H200 141GB 上加载并达到约73.5 GiB 峰值显存请在部署 commit 与实际硬件上重新测量。LTX-2.3 包含 22B Transformer、Gemma 文本编码器、两个 VAE 与一个声码器。建议在96GB 级 GPU上启动或在小显存设备上使用 CPU/层间卸载layerwise offload见上文--enable-layerwise-offload示例。蒸馏上采样器使用配置的 pipeline dtype并参与组件发现/设备放置因仅在阶段边界使用去噪卸载期间它保持驻留。输出音频采样率来自已加载组件不是请求参数。基准测试请使用 tests/dfx/perf/tests/test_ltx2_vllm_omni.json 配合 tests/dfx/perf/scripts/run_diffusion_benchmark.py 执行。常规与全蒸馏双阶段的 T2V/I2V 均受支持HQ 执行不在范围内。八、进一步阅读在线视频生成文档Diffusion 执行模式T2V 离线示例I2V 离线示例LTX 系列源码实现vllm_omni/diffusion/models/ltx2Recipe、Guidance、组件契约、序列并行、两阶段 Pipeline 等相关测试tests/diffusion/models/ltx2Pipeline、并行、Transformer、VAE、vocoder 等与 tests/e2e/online_serving/test_ltx.py、tests/e2e/online_serving/test_ltx25.py【免费下载链接】vllm-omniA framework for efficient model inference with omni-modality models项目地址: https://gitcode.com/GitHub_Trending/vl/vllm-omni创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考