LingBot-World-v2 部署教程：无限交互世界模型

LingBot-World-v2 是一个先进的交互式世界模型，能够根据文本指令和动作输入，持续生成高质量、多样化的视频内容。它支持长达数百帧的视频生成，并允许用户通过文本或动作（如攻击、射箭）实时影响视频的演变。本教程将指导你在本地环境中完成模型部署和基础推理。

重要提示：该项目模型体积大（14B 参数），对硬件要求极高，且目前仅限非商业用途 (CC BY-NC-SA 4.0 许可证)。在开始前，请仔细评估你的硬件资源。

核心概念与模型变体

模型能力：LingBot-World-v2 能够生成长时间、高质量且交互可控的视频。它通过将用户提供的起始图像、文本提示和动作序列（如移动、攻击）作为输入，逐帧“想象”并生成后续视频内容。
模型变体：项目提供了多个模型版本，适用于不同的场景：
- causal-fast (推荐)：针对实时交互进行优化的版本，推理速度更快，适合需要快速响应的场景。
- causal-pretrain：因果预训练基础模型。
- bid：双向模型，可能用于特定任务。
- 1.3B 版本：参数量较小的轻量级版本，对硬件要求稍低。
硬件要求（基于 14B 模型推断）：
- GPU：强烈建议使用多块高性能 GPU（如 8x A100/H100 80GB），用于模型并行和序列并行。官方推理脚本默认使用 8 块 GPU (--nproc_per_node=8)。
- 显存：14B 模型需要极大的显存，单卡 80GB 是基本要求。
- 内存：建议 256GB 以上系统内存。
- 存储：模型文件约 30-60 GB，需预留充足空间。

第一步：环境准备

克隆项目仓库：

1 2	git clone https://github.com/Robbyant/lingbot-world-v2.git cd lingbot-world-v2

安装 Python 依赖：
项目基于 Wan2.2，需要特定的 Python 环境。建议使用 Conda。

# 创建并激活环境 (Python 3.10 或 3.11)
conda create -n lingbot python=3.10 -y
conda activate lingbot

# 安装 PyTorch (需 >= 2.4.0，并与你的 CUDA 版本匹配)
# 请参考 https://pytorch.org/get-started/locally/ 选择正确的安装命令
# 例如 CUDA 12.1:
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# 安装项目依赖
pip install -r requirements.txt

# 安装 flash-attn 以加速 (需编译，请确保已安装 CUDA 开发工具)
pip install flash-attn --no-build-isolation

第二步：下载模型权重

根据你的需求选择合适的模型版本并下载。以下以 14B causal-fast 版本为例。

从 Hugging Face 下载：

1 2	pip install "huggingface_hub[cli]" huggingface-cli download robbyant/lingbot-world-v2-14b-causal-fast --local-dir ./lingbot-world-v2-14b-causal-fast

从 ModelScope 下载 (国内用户推荐)：

1 2	pip install modelscope modelscope download robbyant/lingbot-world-v2-14b-causal-fast --local_dir ./lingbot-world-v2-14b-causal-fast

第三步：运行推理

项目提供了 generate.py 脚本用于执行因果推理（带 KV 缓存，逐块处理视频帧）。

准备输入：
- 起始图像：准备好一张初始图像，用于引导视频生成。示例图像在 examples/03/image.jpg。
- 动作序列：在 examples/03/ 目录下，准备好描述动作的文本文件或参数。
- 文本提示：描述你希望生成的视频内容。

执行推理命令：
这是一个使用 8 块 GPU 生成 361 帧 480P 视频的示例。

torchrun --nproc_per_node=8 generate.py \
  --task i2v-A14B \
  --size 480*832 \
  --ckpt_dir lingbot-world-v2-14b-causal-fast \
  --image examples/03/image.jpg \
  --action_path examples/03 \
  --dit_fsdp \
  --t5_fsdp \
  --ulysses_size 8 \
  --frame_num 361 \
  --local_attn_size 18 \
  --sink_size 6 \
  --prompt "A serene lakeside scene with a lone tree standing in calm water..."

--nproc_per_node=8：使用 8 块 GPU。
--frame_num 361：生成 361 帧视频（约 12 秒，按 30fps 估算）。
--ckpt_dir：模型权重目录。
--image：起始图像路径。
--action_path：动作数据路径。
--prompt：文本提示词。

你也可以使用提供的快捷脚本：

1 2	bash run_fast.sh <权重目录> <帧数> # 例如: bash run_fast.sh lingbot-world-v2-14b-causal-fast 361

故障排查与常见问题

显存不足 (CUDA Out of Memory)：
- 降低分辨率：尝试使用 --size 360*640 等更小分辨率。
- 减少帧数：设置 --frame_num 为较小的值（如 121）。
- 减少并行度：如果 GPU 显存有限，可尝试减少 --ulysses_size 或 --nproc_per_node，但这会显著降低生成速度或导致失败。
- 使用更小的模型：如果硬件条件有限，尝试下载 1.3B 版本的模型 (lingbot-world-v2-1.3b-causal-fast)。
flash-attn 安装失败：确保 CUDA 工具包和 PyTorch 版本兼容。可以尝试使用预编译的 wheel 包，或参考 flash-attn 官方文档进行源码编译。
模型下载中断或缓慢：Hugging Face 在国内访问可能不稳定，建议使用 ModelScope 源，或使用下载工具（如 aria2）配合镜像加速。
无法复现演示效果：演示视频可能使用了特定的输入（如更高精度的动作控制）或经过后期处理。请确保你的输入提示和动作序列与模型训练数据分布相似。

LingBot-World-v2 代表了当前交互式世界模型的前沿水平，但其部署门槛极高。对于普通研究者和开发者，强烈建议优先体验官方提供的在线演示（如 Reactor 平台），以评估其效果和交互方式。如果确实需要本地部署，请确保你拥有顶级的计算集群，并准备好投入大量时间进行环境调试和参数优化。请严格遵守其非商业许可条款。