LingBot-Video DiT 推理参数完全手册:T2I/T2V/TI2V 与 Refiner 全流程配置详解
LingBot-Video DiT 推理参数完全手册:T2I/T2V/TI2V 与 Refiner 全流程配置详解
LingBot-Video 是首个面向具身智能的开源大规模 MoE 视频生成模型。它的 DiT 推理通过统一入口 scripts/inference.py 驱动,支持 T2I(文生图)、T2V(文生视频)、TI2V(图生视频)三种模式,并可叠加 Refiner 精修阶段提升视频画质。本文把 --steps、--guidance_scale、--shift 等全部关键 DiT 推理参数按功能分组讲清楚,帮你快速搭出一套稳定可用的生成配置。
1. 先搞懂推理三阶段流水线
DiT 不接受随手写的自然语言 prompt,推荐的完整流程是:
- Prompt Rewriter:把普通 prompt 改写成结构化 JSON caption(TI2V 需把首帧图一并传入),见 docs/zh/prompt_preparation.md;
- Auto Negative(可选):针对该样本裁剪 negative prompt,输出
negative.json; - DiT 推理:用 scripts/inference.py 加载结构化 JSON 跑生成,MoE 模型可追加
--run_refiner启用 Refiner。
仓库在 assets/cases/ 下为三种模式都备好了现成的 prompt.json(TI2V 还带 first_frame.png),可直接拿来试跑,完整清单见 assets/cases/manifest.json。
2. 模式与输入参数:选对起点
| 参数 | 说明 | 默认值 |
|---|---|---|
--mode |
生成模式,t2i / t2v / ti2v 三选一 |
必填 |
--model_dir |
LingBot-Video 模型根目录(Dense 或 MoE 权重包) | 必填 |
--backend |
diffusers 直跑;sglang 走 SGLang Diffusion(未安装时自动回退并告警) |
diffusers |
--prompt_json |
Rewriter 输出的结构化 JSON,duration 字段会自动推导帧数 |
— |
--negative_prompt_json |
Auto Negative 输出的 negative.json;不传则用内置默认值 |
内置 |
--image |
TI2V 的首帧图,必须与 Rewriter 传入的首帧是同一张 | — |
--output |
输出文件路径,目录会自动创建 | 必填 |
内置默认 negative prompt 分别存放在 lingbot_video/default_negative_prompt.json(视频)和 lingbot_video/default_negative_prompt_image.json(图片)。注意:跳过 Auto Negative 时请删掉 --negative_prompt_json 参数,而不是留空。
3. 画质与节奏参数:steps、guidance_scale、shift
这三个参数决定"去噪去多久、多听 prompt 的话、噪声调度怎么排":
| 参数 | 作用 | 推荐值 |
|---|---|---|
--steps |
base DiT 去噪步数,越大越细腻但越慢 | 40 |
--guidance_scale |
CFG 引导强度,越大越贴合 prompt、越易过饱和 | 3.0 |
--shift |
flow matching 时间步偏移,影响画面质感分布 | 3.0 |
--seed |
随机种子,固定后可复现结果 | 42 |
--fps |
输出帧率,也参与帧数计算 | 24 |
帧数规则:视频任务的 num_frames 必须是 1 或 4n+1。5s @ 24fps 对应 121 帧——prompt.json 里写了 duration 时 runner 会按 duration × fps 自动算好;也可以显式传 --num_frames 覆盖,或用 --duration 5 在命令行指定。
⚠️ 结构化 caption 中动作时间戳形如
[0.0s - 5.0s],--duration必须与时间戳覆盖的总时长一致,否则动作会被截断或拉伸。
分辨率通过 --height / --width 指定(常用 480×832),也可用 --resolution + --ratio 按桶选择,两者必须成对出现。
4. TI2V 模式:首帧图是关键
TI2V(文生图生视频)比 T2V 多一个硬性要求:必须传 --image。配置要点:
- Rewriter 和 DiT 推理使用同一张首帧:Rewriter 传
--first-frame,DiT 传--image; - TI2V 当前不支持 CFG parallel(
--cfg_parallel_degree只能为 1),多卡请只走 FSDP + context parallel; - 示例首帧可直接用 assets/cases/ti2v/example_4/first_frame.png。
5. Refiner 精修参数:MoE 视频的"最后一公里"
Refiner 是一个二次精修 DiT,把 base 生成的低分辨率视频提升为更清晰的成品。仅 MoE 模型包(含 refiner/ 子目录)和视频模式支持,T2I 明确不支持。
开启方式:加 --run_refiner(runner 会自动从 --model_dir 下加载 refiner/),并指定 --refiner_output 保存精修结果。
| 参数 | 说明 | 默认值 |
|---|---|---|
--refiner_output |
精修后视频输出路径 | — |
--refiner_height / --refiner_width |
精修输出分辨率 | 1088 / 1920 |
--refiner_steps |
精修去噪步数(远少于 base) | 8 |
--refiner_guidance_scale |
精修引导强度 | 3.0 |
--refiner_shift |
精修时间步偏移 | 3.0 |
--refiner_t_thresh |
时间步截断阈值,控制精修介入区间 | 0.85 |
--refiner_sigma_tail_steps |
尾部噪声调度步数 | 2 |
--refiner_vae_dtype |
精修 VAE 精度 | fp32 |
--refiner_batch_cfg |
多卡时启用 batched CFG(与 CFG parallel 互斥) | 关 |
--reuse_condition_features |
让 Refiner 复用 base 的条件特征,省算力 | 建议开 |
TI2V + Refiner 时,Refiner 以干净首帧为条件,--image 必传,否则直接报错。完整的 Base + Refiner 命令示例见 docs/zh/dit_inference.md。
6. 精度与性能开关
| 参数 | 说明 |
|---|---|
--transformer_dtype |
DiT transformer 精度,推荐 bf16 |
--text_encoder_dtype |
文本编码器精度,推荐 bf16 |
--vae_dtype / --refiner_vae_dtype |
VAE 精度,推荐 fp32 保证解码稳定 |
--diffusers_attn_backend |
覆盖 attention 实现,多卡脚本默认 _native_flash |
--allow_tf32 |
开启 TF32 加速(默认开启) |
--quiet_progress |
关闭加载日志与进度条,适合批量任务 |
MoE 模型还多一组环境变量控制专家内核(Dense 模型无效):
export DIFFUSERS_ATTN_BACKEND=_native_flash
export LINGBOT_MOE_PAD_BACKEND=vectorized
export LINGBOT_MOE_EXPERT_BACKEND=grouped_mm # 质量优先(默认)
# export LINGBOT_MOE_EXPERT_BACKEND=sglang_triton_fp8 # 速度优先
7. 多卡并行:FSDP、CFG 与 Context Parallel
三个并行维度各司其职,参数互有约束:
--enable_fsdp_inference:用 FSDP 把 base / refiner DiT 切分到多卡,降显存;注意初始化阶段每个 rank 仍需在 host memory 构建一份 transformer,大 MoE 权重请确保系统内存充足;--cfg_parallel_degree:拆分 CFG 的条件/无分支,只能取1或2,与--batch_cfg互斥;--context_parallel_degree:序列切分到多卡(建议配合--context_parallel_ulysses_anything);- 进程数必须等于
cfg_parallel_degree × context_parallel_degree,用torchrun --nproc_per_node启动。
常用布局速查(详见 docs/zh/sglang_diffusion.md):
| GPU 数 | 推荐布局 |
|---|---|
| 1 | 单卡直跑,两个 parallel degree 均为 1 |
| 2 | CFG×CP:--cfg_parallel_degree 2 --context_parallel_degree 1 |
| 8 | 仅 CP:--cfg_parallel_degree 1 --context_parallel_degree 8 + --batch_cfg + --enable_fsdp_inference |
8. 脚本化一键运行:环境变量覆盖
不想手写长命令时,官方脚本支持环境变量覆盖,例如:
MODEL_DIR="$MOE_MODEL_DIR" ./scripts/multi-gpus/run_moe_t2v_refiner_fsdp_cp8.sh
可覆盖的变量包括 PROMPT_JSON、IMAGE、OUT_DIR、HEIGHT、WIDTH、STEPS、GUIDANCE_SCALE、SHIFT、SEED、FPS、BACKEND、NPROC、CP;Refiner 脚本额外支持 REFINER_HEIGHT、REFINER_WIDTH、REFINER_STEPS、REFINER_GUIDANCE_SCALE、REFINER_SHIFT、REFINER_T_THRESH、REFINER_SIGMA_TAIL_STEPS。脚本目录结构:
- 单卡(base only):scripts/single-gpu/
- 多卡无 Refiner(CP8 + FSDP):scripts/multi-gpus-no-refiner/
- 多卡带 Refiner(MoE T2V/TI2V):scripts/multi-gpus/
9. 常见问题速查
- 报错 "Refiner is only supported for video modes":T2I 传了
--run_refiner,去掉即可; - 报错 "
--imageis required":TI2V 开 Refiner 忘传首帧; - 帧数不合法:检查
num_frames是否为1或4n+1; - SGLang 没生效:日志出现回退警告时,安装
requirements-sglang.txt即可启用; - 所有参数定义:完整 argparse 定义可查 lingbot_video/runner.py。
把本文第 3、4、5 节的参数组合到你的模式上,再对照第 7、8 节按硬件选并行布局,就是一套可长期复用的 LingBot-Video 推理配置基线。




