third_party/diffsynth/docs/zh/Model_Details/LingBot-Video.md

LingBot-Video

LingBot-Video 是由 LingBot 团队研发的 flow-matching 视频生成模型，单个模型即可完成文生视频、图生视频和文生图三种任务。

特别感谢 NancyFyong 在模型接入中做出的杰出贡献！

安装

在使用本项目进行模型推理和训练前，请先安装 DiffSynth-Studio。

git clone https://github.com/modelscope/DiffSynth-Studio.git
cd DiffSynth-Studio
pip install -e .

更多关于安装的信息，请参考安装依赖。

快速开始

运行以下代码可以快速加载 Robbyant/lingbot-video-dense-1.3b 模型并进行推理。显存管理已启动，框架会自动根据剩余显存控制模型参数的加载，最低 6G 显存即可运行。

import torch
import json
from diffsynth.utils.data import save_video, VideoData
from diffsynth.pipelines.lingbot_video import LingBotVideoPipeline, ModelConfig
from modelscope import dataset_snapshot_download

vram_config = {
    "offload_dtype": "disk",
    "offload_device": "disk",
    "onload_dtype": torch.float8_e4m3fn,
    "onload_device": "cpu",
    "preparing_dtype": torch.float8_e4m3fn,
    "preparing_device": "cuda",
    "computation_dtype": torch.bfloat16,
    "computation_device": "cuda",
}

pipe = LingBotVideoPipeline.from_pretrained(
    torch_dtype=torch.bfloat16,
    device="cuda",
    model_configs=[
        ModelConfig(model_id="Robbyant/lingbot-video-dense-1.3b", origin_file_pattern="transformer/diffusion_pytorch_model.safetensors", **vram_config),
        ModelConfig(model_id="Qwen/Qwen3-VL-4B-Instruct", origin_file_pattern="*.safetensors", **vram_config),
        ModelConfig(model_id="Robbyant/lingbot-video-dense-1.3b", origin_file_pattern="vae/diffusion_pytorch_model.safetensors", **vram_config),
    ],
    processor_config=ModelConfig(model_id="Qwen/Qwen3-VL-4B-Instruct", origin_file_pattern=""),
    vram_limit=torch.cuda.mem_get_info("cuda")[1] / (1024 ** 3) - 0.5,
)

dataset_snapshot_download(
    dataset_id="DiffSynth-Studio/diffsynth_example_dataset",
    local_dir="data/diffsynth_example_dataset",
    allow_file_pattern="lingbot_video/lingbot-video-dense-1.3b_t2v/*",
)
with open("data/diffsynth_example_dataset/lingbot_video/lingbot-video-dense-1.3b_t2v/t2v_example_1.json", "r", encoding="utf-8") as f:
    caption = json.load(f)

video = pipe(
    prompt=caption,
    negative_prompt=pipe.default_negative_prompt,
    height=480, width=832, num_frames=81,
    num_inference_steps=40, cfg_scale=3.0,
    seed=0,
)
save_video(video, "video.mp4", fps=15, quality=10)

模型总览

模型 ID	推理	低显存推理	全量训练	全量训练后验证	LoRA 训练	LoRA 训练后验证
Robbyant/lingbot-video-dense-1.3b: T2V	code	code	code	code	code	code
Robbyant/lingbot-video-dense-1.3b: TI2V	code	code	code	code	code	code
Robbyant/lingbot-video-dense-1.3b: T2I	code	code	-	-	-	-

模型推理

模型通过 LingBotVideoPipeline.from_pretrained 加载，详见加载模型。

LingBotVideoPipeline 推理的输入参数包括：

• prompt: 描述视频内容的提示词，接受结构化 JSON caption（dict）或纯字符串。LingBot-Video 在结构化 caption 上训练，Pipeline 会自动对 dict 进行归一化。示例数据集中提供了发布版的结构化 caption（见下方提示词改写）。
• negative_prompt: 描述不应出现内容的负向提示词。pipe.default_negative_prompt 提供了官方 T2V/V2V/TI2V 负向提示词；pipe.default_negative_prompt_image 是移除时序项后的 T2I 版本。
• input_image: 图生视频（TI2V）的首帧 PIL 图像。该帧被 VAE 编码成 clean latent，在每个采样步之后重新写入第一个时间槽，使模型只生成后续帧。T2V / V2V / T2I 时留 None。
• input_video: 视频到视频生成的输入视频（帧列表或 VideoData），与 denoising_strength 配合使用。
• denoising_strength: 去噪强度，范围 [0, 1]，默认 1.0。较小值保留更多输入视频结构。仅当 input_video 提供时生效。
• height: 视频 / 图像高度，默认 480，必须是 16 的倍数。
• width: 视频 / 图像宽度，默认 480，必须是 16 的倍数。
• num_frames: 帧数，默认 81，须满足 4k+1（VAE 时间上 4× 压缩）。文生图使用 num_frames=1。
• cfg_scale: 无分类器指导强度，默认 3.0。
• num_inference_steps: 推理步数，默认 40。
• sigma_shift: Flow-matching 时间步 shift，默认 3.0。
• seed: 随机种子，默认 None（完全随机）。
• rand_device: 生成初始噪声的设备，默认 "cpu"。
• progress_bar_cmd: 进度条，默认 tqdm，可设为 lambda x: x 关闭。

显存不足时请参考显存管理启用显存管理功能。我们在示例代码中提供了每个任务的推荐低显存配置，见上方"模型总览"中的表格。

提示词改写

LingBot-Video 训练时使用的是结构化 JSON caption，直接喂平铺句子属于分布外输入，会明显降低生成质量。Pipeline 接受 dict 形式的 caption（与训练一致的格式）或纯字符串，dict 会被内部归一化。

发布版的结构化 caption 已通过 DiffSynth-Studio/diffsynth_example_dataset 示例数据集提供（t2v_example_*.json、ti2v_example.json、t2i_example.json，推理示例脚本会自动下载）。用 json.load 读入后作为 dict 传入 Pipeline，或作为编写自定义 caption 的模板。

如需将一段简短描述改写为结构化 caption，可使用 examples/lingbot_video/model_training/scripts/prompt_rewriter.py 中的两阶段改写器：阶段 1 将想法扩展为自然语言描述，阶段 2 将其映射为结构化 JSON。改写器是独立的 VLM + 阶段二 LoRA 适配器，需要另外下载：

角色	模型 ID	大小
改写器 base VLM（阶段 1 + 2）	Qwen/Qwen3.6-27B	~55 GB
改写器阶段二 LoRA 适配器	Robbyant/lingbot-video-rewriter-lora	~0.5 GB

import os
os.environ["REWRITER_BASE_MODEL"] = "./models/Qwen/Qwen3.6-27B"
os.environ["REWRITER_ADAPTER"] = "./models/Robbyant/lingbot-video-rewriter-lora"

# 在仓库根目录下运行，此包式 import 才能解析。
from examples.lingbot_video.model_training.scripts.prompt_rewriter import rewrite_prompt
caption = rewrite_prompt("a puppy running across a meadow", mode="t2v", duration=5)
video = pipe(prompt=caption, height=480, width=832, num_frames=81, cfg_scale=3.0)

除环境变量外，也可以直接向 rewrite_prompt 传 base= / adapter=；或者提供一个实现了 generate(text, image, use_lora) 方法的自定义对象作为 backend=，从而对接托管服务或 OpenAI-compatible 端点。

模型训练

LingBot-Video 系列模型统一通过 examples/lingbot_video/model_training/train.py 进行训练，脚本的参数包括：

• 通用训练参数
  • 数据集基础配置
    • --dataset_base_path: 数据集的根目录。
    • --dataset_metadata_path: 数据集的元数据文件路径。
    • --dataset_repeat: 每个 epoch 中数据集重复的次数。
    • --dataset_num_workers: 每个 Dataloader 的进程数量。
    • --data_file_keys: 元数据中需要加载的字段名称，通常是图像或视频文件的路径，以 , 分隔。
  • 模型加载配置
    • --model_paths: 要加载的模型路径。JSON 格式。
    • --model_id_with_origin_paths: 带原始路径的模型 ID。用逗号分隔。
    • --extra_inputs: 模型 Pipeline 所需的额外输入参数，以 , 分隔。
    • --fp8_models: 以 FP8 格式加载的模型，目前仅支持参数不被梯度更新的模型。
  • 训练基础配置
    • --learning_rate: 学习率。
    • --num_epochs: 轮数（Epoch）。
    • --trainable_models: 可训练的模型，例如 dit、vae、text_encoder。
    • --find_unused_parameters: DDP 训练中是否存在未使用的参数。
    • --weight_decay: 权重衰减大小。
    • --task: 训练任务，默认为 sft。
  • 输出配置
    • --output_path: 模型保存路径。
    • --remove_prefix_in_ckpt: 在模型文件的 state dict 中移除前缀。
    • --save_steps: 保存模型的训练步数间隔。
  • LoRA 配置
    • --lora_base_model: LoRA 添加到哪个模型上。
    • --lora_target_modules: LoRA 添加到哪些层上。
    • --lora_rank: LoRA 的秩（Rank）。
    • --lora_checkpoint: LoRA 检查点的路径。
    • --preset_lora_path: 预置 LoRA 检查点路径，用于 LoRA 差分训练。
    • --preset_lora_model: 预置 LoRA 融入的模型，例如 dit。
  • 梯度配置
    • --use_gradient_checkpointing: 是否启用 gradient checkpointing。
    • --use_gradient_checkpointing_offload: 是否将 gradient checkpointing 卸载到内存中。
    • --gradient_accumulation_steps: 梯度累积步数。
  • 分辨率配置
    • --height: 视频的高度，必须能被 16 整除。
    • --width: 视频的宽度，必须能被 16 整除。
    • --max_pixels: 最大像素面积，动态分辨率时大于此值的图片会被缩小。
    • --num_frames: 视频的帧数，须满足 4k+1。
• LingBot-Video 专有参数
  • --processor_path: Qwen3-VL processor 目录（或 model_id:origin_file_pattern 形式）路径，用于对 prompt 进行 tokenize。
  • --first_frame_as_condition: 启用图生视频（TI2V）的 LoRA / 全量训练。每段视频以自己的第一帧作为条件：该帧被 VAE 编码为 clean latent 固定到第一个时间槽（同时作为视觉输入送入 Qwen3-VL 文本编码器），并从 flow-matching 损失中排除。
  • --max_timestep_boundary: 训练时时间步的上边界，取值 [0, 1] 表示相对训练调度的比例。
  • --min_timestep_boundary: 训练时时间步的下边界，取值 [0, 1] 表示相对训练调度的比例。
  • --initialize_model_on_cpu: 是否在 CPU 上初始化模型。

我们构建了一个样例数据集供您测试，可通过以下命令下载：

modelscope download --dataset DiffSynth-Studio/diffsynth_example_dataset --include "lingbot_video/lingbot-video-dense-1.3b_t2v/*" --local_dir ./data/diffsynth_example_dataset

训练时 prompt 字段应存放结构化 JSON caption（与推理时使用的分布内格式一致）。如果数据集里存的是原始散文，可先使用 examples/lingbot_video/model_training/scripts/rewrite_captions.py 离线改写一次。

我们为每个任务编写了推荐的训练脚本，请参考前文"模型总览"中的表格。关于如何编写模型训练脚本，请参考模型训练；更多高阶训练算法，请参考训练框架详解。