LingBot-World 2.0 本地小模型部署实操 SOP

一、适用判断：这篇 SOP 给谁看

先把话说在前面。LingBot-World 2.0（仓库别名 LingBot-World-Infinity）是 Robbyant 团队开源的"世界模型"视频生成系统，基于 Wan2.2（Wan-Video）改造，核心是因果式（causal）逐 chunk 推理，可以在给定首帧和相机轨迹的条件下，持续往外生成交互式视频。它和常见的文生视频工具不一样：输入不是一段 prompt 就完事，而是"一张图 + 一条相机/动作轨迹 + 一段文字事件描述"，输出是顺着轨迹延展的长视频。

这篇 SOP 面向的是想在自己机器上把这套东西真正跑起来、并且能稳定复现官方 demo 效果的中国技术从业者。如果你属于下面这几类人，建议直接读下去：其一，做世界模型、视频生成、具身智能相关研究，需要本地复现并做二次开发的同学；其二，团队想评估这套方案能不能进产品，需要先做技术可行性验证的工程负责人；其三，已经在用 Wan 系列模型，想把交互式长视频能力接进现有管线的开发者。

反过来，有几类人我劝你先别浪费时间。第一，只想点开网页试玩、不想碰命令行的用户，官方已经给了 Reactor（国际 Web）和灵光（国内移动端）两个实时体验入口，你不需要自己部署。第二，指望拿来直接做商业产品、甚至已经准备上线的团队，请先跳到第七节和第十节，许可证是 CC BY-NC-SA 4.0，非商用，商业化的第一步不是写代码，而是去确认授权。第三，手里只有一张消费级显卡、且显存不到 24G 的朋友，官方代码仓里没有单卡实时复现路径，下面会如实讲清楚，别抱不切实际的期待。

一句话判断：这是一份"把官方代码仓跑通并调稳"的实操手册，不是概念科普，也不是商业部署方案。能接受这个定位，往下看。

二、环境与依赖

先讲清楚硬件门槛，因为这一条是整个部署里最容易踩坑、也最容易和官方宣传对不上的地方。代码仓里口径是分裂的，我如实并列，不替任何一方圆场。

硬件方面，1.3B 小模型有两种官方参考配置：README 里给出的示例命令是 4 卡（--nproc_per_node=4），而仓库 run_fast.sh 的注释明确写"1.3B 的参考设置是 2 卡（ulysses_size=2），对应 1.3B causal-ODE CP=1 recipe"。14B 模型则是 8 卡（--nproc_per_node=8）。媒体和官方 demo 对外宣称"1.3B Small 可在消费级单卡 GPU 实时运行"，但这句话在官方代码仓里没有任何可复现的命令或配置——也就是说，单卡实时属于"官方未确认"，你自己别把它当承诺。以官方代码仓为准，1.3B 最低可复现参考是 2 卡；想省事直接用 run_fast.sh，它会自动按权重目录名推断卡数。

软件依赖从官方 requirements.txt 摘出要点：torch>=2.4.0、torchvision>=0.19.0、diffusers>=0.31.0、transformers>=4.49.0,<=4.51.3（注意上限，装高了会出兼容问题）、flash_attn、numpy>=1.23.5,<2（numpy 2.x 不兼容，必须锁死在 1.x）、opencv-python>=4.9.0.80 等。Python 环境建议 3.10，CUDA 建议 12.1 以上，和 Wan2.2 一致。

安装命令逐字照抄官方，分三步：

git clone https://github.com/robbyant/lingbot-world-v2.git
cd lingbot-world-v2
pip install -r requirements.txt
pip install flash-attn --no-build-isolation

flash-attn 用 --no-build-isolation 是因为它需要从源码编译、且依赖当前环境的 torch，不加这个参数容易在隔离环境里编译失败。requirements.txt 里没有锁定 flash-attn 版本，编译耗时较长，建议放在最后单独装，出问题好定位。如果你本地已经有 Wan2.2 的环境，可以直接复用，安装遇到问题对照 Wan-Video 官方文档排障即可，因为本仓库代码就是基于 Wan2.2 改的。

三、权重下载（含 1.3B 缺件处理）

权重有四个变体，选哪个取决于你的硬件和想要的质量：

• lingbot-world-v2-14b-causal-fast：14B，蒸馏少步模型，默认推理模式。
• lingbot-world-v2-14b-causal-pretrain：14B，预训练因果模型，质量更高但更慢更重。
• lingbot-world-v2-14b-bid：14B，双向模型。
• lingbot-world-v2-1.3b-causal-fast：1.3B，蒸馏少步模型，小模型首选。

下载用 huggingface-cli，官方命令逐字如下。特别注意 1.3B 那行的 --local-dir 带 /transformers 后缀，这是官方写法，不要自己去掉：

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

14B 的下载不带后缀，示例：

huggingface-cli download robbyant/lingbot-world-v2-14b-causal-fast --local-dir ./lingbot-world-v2-14b-causal-fast

如果你在国内、HuggingFace 拉不动，官方也给了 ModelScope 途径，命令格式是 modelscope download robbyant/... --local_dir ./...，把上面的 huggingface-cli download 换成 modelscope download 即可，目录结构和参数一一对应。

这里要重点讲清本篇最关键的一个坑：1.3B 的 HuggingFace 权重包目前只包含 DiT 权重，T5、VAE 和 tokenizer 是和 14B 版本共享的。也就是说，如果你只下载了 1.3B 目录就直接跑，会因为找不到 T5/VAE/tokenizer 而跑不起来。解决办法是额外下载一份 14B 权重（任意变体都行，因为共享件一致），然后在推理时用 --assets_dir 指向 14B 目录。run_fast.sh 的第三个参数就是干这个的。强烈建议小模型玩家把 14B 权重也下下来当"配件库"，磁盘换稳定性很划算。

四、跑通第一段视频

目标：不追求效果，先把一条官方示例视频完整生成出来，证明环境、权重、并行配置都对了。

最简单的方式是用官方一键脚本 run_fast.sh。脚本会从权重目录名推断任务类型和卡数：目录名含 1.3b 或 1p3b 就按 1.3B 处理、NPROC=2、GPU 0,1；否则按 14B 处理、NPROC=8、GPU 0-7。第三个参数是 assets_dir，1.3B 必须传：

bash run_fast.sh lingbot-world-v2-1.3b-causal-fast 361 lingbot-world-v2-14b-causal-fast

这条命令等价于下面的完整 torchrun 写法（README 里 1.3B 示例，4 卡）。注意它同时带了 --assets_dir 指向 14B 目录，否则会缺件：

torchrun --nproc_per_node=4 generate.py --task i2v-1.3B --size 480*832 --ckpt_dir lingbot-world-v2-1.3b-causal-fast --assets_dir lingbot-world-v2-14b-causal-fast --image examples/03/image.jpg --action_path examples/03 --dit_fsdp --t5_fsdp --ulysses_size 4 --frame_num 361 --local_attn_size 18 --sink_size 6 --prompt "A serene lakeside scene with a lone tree standing in calm water, surrounded by distant snow-capped mountains under a bright blue sky with drifting white clouds — gentle ripples reflect the tree and sky, creating a tranquil, meditative atmosphere."

如果你要跑 14B 的预训练因果模型（质量更高、每 chunk 40 步带 CFG），官方命令是：

torchrun --nproc_per_node=8 generate.py --task i2v-A14B --infer_mode causal_pretrain --size 480*832 --ckpt_dir lingbot-world-v2-14b-causal-pretrain --image examples/03/image.jpg --action_path examples/03 --dit_fsdp --t5_fsdp --ulysses_size 8 --frame_num 81 --prompt "A serene lakeside scene with a lone tree standing in calm water, surrounded by distant snow-capped mountains under a bright blue sky with drifting white clouds — gentle ripples reflect the tree and sky, creating a tranquil, meditative atmosphere."

跑通的标志是 output/ 目录下出现一个 .mp4 文件，文件名里带 causal_fast 或 causal_pretrain、尺寸和 ulysses_size，以及时间戳。如果卡在 import 或编译错误，回到第二节对照依赖版本；如果报注意力头数相关的 assert，跳到第五节看 ulysses_size。

五、参数调优：帧数、注意力窗口、chunk 与种子

跑通只是开始，要拿到你想要的效果得调参数。下面逐个说，默认值都来自 generate.py 的 argparse。

--frame_num：生成多少帧，必须是 4n+1（如 81、161、361）。帧数直接决定视频时长，配合 cfg.sample_fps 算出秒数。长视频就加大这个值，但要注意显存和生成时间线性增长。

--local_attn_size：KV cache 的局部注意力窗口大小，默认 -1（即用配置里的窗口）。官方示例用 18。它控制模型"回头看"多少历史帧，值太小长程一致性会崩，值太大显存和算力开销上去了。

--sink_size：KV cache 的 sink 大小，默认 0，官方示例用 6。和 local_attn_size 一起决定注意力窗口的形态，长视频建议保留官方示例里的组合。

--chunk_size：每个 chunk 的帧数，默认 4。模型是逐 chunk 推理的，chunk 是流式生成的基本单元。一般保持默认即可。

--base_seed：随机种子，默认 42。想复现某次结果就固定它；想换花样就改。多卡时 rank 0 会把种子广播给所有进程，所以你只设一个就行。

--save_dir：输出目录，默认 output。生成的 .mp4 落在这里。

--size：视频面积 宽*高，默认 1280*720，官方示例用 480*832。i2v 任务下输出宽高比会跟随输入图片，所以这个值主要影响总面积和算力。

最关键的并行参数是 --ulysses_size：Ulysses 并行度，默认 1，必须整除注意力头数。代码里 generate.py 有硬性断言：cfg.num_heads % ulysses_size == 0。1.3B 是 12 个头，所以可用 2 或 4；14B 是 40 个头，官方用 8。设错会直接报错 cannot be divided evenly，不是悄悄降级。而且 ulysses_size 必须等于 world_size（即 nproc_per_node），所以改卡数时这俩要一起改。

--infer_mode：选 causal_fast（默认，蒸馏少步，每 chunk 4 步、无 CFG，快）还是 causal_pretrain（预训练因果，每 chunk 40 步、带 CFG，更慢更重但质量更高）。这是速度和质量的取舍开关。--dit_fsdp 和 --t5_fsdp 是把 DiT 和 T5 用 FSDP 切分到多卡，多卡必开；--t5_cpu 是把 T5 放 CPU 省显存但更慢；--offload_model 是每步前向完把模型卸载到 CPU，进一步省显存。显存不够就依次上这些开关。

六、生产化与部署路径

必须泼一盆冷水：官方明确写"我们不计划发布部署代码"（We do NOT plan to release our deployment code）。所以你自己想把它接进服务、做高并发或低延迟推理，别等官方给方案，得自己搭。

官方给的两条参考路径：第一条是 SGLang 的 LingBot-World cookbook，地址 https://docs.sglang.io/cookbook/diffusion/LingBot-World/LingBot-World-2.0，它面向扩散类模型的部署，有现成的接入范式；第二条是 NVIDIA 的 flashdreams 仓库。这两条都是"参考"而非"开箱即用"，需要你自己把权重、前后处理和调度逻辑接进去。

多卡扩展的思路：ulysses_size 是序列并行，受头数整除约束，1.3B 最多 12、14B 最多 40。要进一步扩吞吐，得在 Ulysses 之外叠加 FSDP（--dit_fsdp/--t5_fsdp）和数据并行。但本仓库的推理入口 generate.py 是单机多卡范式，跨节点、动态 batch、流式服务化都不在它的设计范围内，这部分要你自己基于 SGLang/flashdreams 补。一句话：本地跑通用 generate.py，生产服务另起炉灶。

七、踩坑记录（八条）

下面八条是这篇 SOP 的价值所在，都是官方文件里能核实、或者官方与媒体口径冲突时必须并列的点。

1. 1.3B 权重包只含 DiT 权重。T5、VAE、tokenizer 与 14B 共享，必须用 --assets_dir（或 run_fast.sh 第三个参数）指向 14B 权重目录，否则直接跑不起来。这是新手第一个、也是最常见的坑。

2. 硬件门槛口径三重分歧，如实并列。README 的 1.3B 示例是 4 卡；run_fast.sh 注释明确 1.3B 参考设置是 2 卡（12 头、ulysses 整除 12，对应 1.3B causal-ODE CP=1 recipe）；媒体/官方 demo 宣称"1.3B Small 可在消费级单卡 GPU 实时运行"。结论：以官方代码仓为准，最低可复现参考是 2 卡；"消费级单卡实时"在代码仓中无复现路径，标注为官方未确认。

3. ulysses_size 必须整除注意力头数。1.3B 为 12 头（可用 2 或 4），14B 为 40 头（用 8）。设错直接触发 generate.py 里的 assert 报错，不是降速。

4. causal_fast 与 causal_pretrain 的取舍。前者是蒸馏少步模型，每 chunk 4 步、无 CFG，默认，快；后者是预训练因果模型，每 chunk 40 步、带 CFG，更慢更重但质量更高。别拿 fast 的速度去要求 pretrain 的质量，反之亦然。

5. 官方不开源部署代码。生产化要自行参考 SGLang cookbook 或 NVIDIA flashdreams，别等官方给方案，也别指望 generate.py 能直接当服务用。

6. 许可证 CC BY-NC-SA 4.0，非商用。任何商业产品化前必须先确认授权；衍生作品必须以相同协议分发。这是法律红线，不是技术细节。

7. 基于 Wan2.2。安装、环境、编译类问题，对照 Wan-Video 官方文档排障效率最高，因为代码同源。

8. 帧数与注意力窗口等参数对大时长生成影响显著。--frame_num 决定时长；--local_attn_size 18、--sink_size 6 是官方长视频组合，决定长程一致性；--chunk_size 是流式单元；--base_seed 控复现；--save_dir 控落盘。调长视频时这几项要一起看，单独改一个容易出时间跳变或一致性断裂。

八、上线前 Checklist（十项）

下面十项，是你在把这套东西交给同事、接进项目、或者对外展示之前，应该逐项打勾的清单。

1. 确认仓库已 git clone 且 cd 进入，路径无误。
2. 确认 pip install -r requirements.txt 与 flash-attn --no-build-isolation 都装成功，无编译报错。
3. 确认 transformers 版本落在 >=4.49.0,<=4.51.3，numpy 落在 >=1.23.5,<2，避免版本兼容坑。
4. 确认权重目录存在，且 1.3B 之外额外准备了 14B 目录作为 --assets_dir 配件库。
5. 确认 1.3B 推理命令带了 --assets_dir 指向 14B 目录，否则必败。
6. 确认 --ulysses_size 整除对应模型的头数（1.3B=12，14B=40），且与 nproc_per_node 相等。
7. 确认 --frame_num 是 4n+1，且与你要的时长匹配。
8. 确认输出 output/ 目录下生成了 .mp4，文件大小正常、能播放。
9. 确认你选择的 infer_mode 符合速度和质量预期（fast 快、pretrain 重）。
10. 确认许可证约束已评估：非商用场景才继续，商用先走授权确认。

九、姊妹篇与延伸阅读

同批姊妹篇，建议对照阅读，已经发布：

• 热点解读：/zh/posts/lingbot-world-2-0-hotspot
• 开源资源盘点：/zh/posts/gods-eye-view-resource
• 世界模型横评：/zh/posts/open-world-model-comparison-review

十、今天能用它做什么、不能用什么（诚实判断）

落到最后，给你一个不掺水的判断。

今天它能做的：在 2 卡及以上（1.3B）或 8 卡（14B）的机器上，稳定复现官方 demo 级别的交互式长视频生成；做世界模型、视频生成的研究复现和二次开发；把"首帧 + 相机轨迹 + 文字事件"驱动的长视频能力接进你自己的实验管线。质量上限在官方示例里已经看到了，14B causal_pretrain 是质量天花板。

今天它不能做的，或者说你不该指望的：第一，它不能在消费级单卡上实时跑——那是官方 demo/媒体口径，代码仓里没有复现路径，别拿这个去给老板立 flag。第二，它不能当现成服务用，官方不开源部署代码，生产化要靠 SGLang 或 flashdreams 自己搭。第三，也是最重要的，它不能商用。许可证是 CC BY-NC-SA 4.0，非商用。任何打算产品化、收费、或闭源分发的行为，第一步不是写代码，而是去确认授权，并准备好衍生作品同协议开源。把这条想清楚，再决定要不要在这套东西上投入工程资源。

常见问题

Q1：只有一张消费级显卡，能跑 1.3B 吗？ A1：以官方代码仓为准，最低可复现参考是 2 卡（ulysses_size=2）。README 示例是 4 卡，run_fast.sh 注释写 2 卡。"消费级单卡实时"是官方 demo/媒体口径，在代码仓中无复现路径，标注为官方未确认。单卡能不能跑，核不到，写未确认。

Q2：1.3B 下载完直接跑为什么报错找不到 T5/VAE？ A2：因为 1.3B 的 HuggingFace 权重包目前只包含 DiT 权重，T5、VAE、tokenizer 和 14B 共享。你需要额外下载一份 14B 权重，并用 --assets_dir 指向它（或 run_fast.sh 第三个参数）。这是官方 README 明确写的，不是环境坏了。

Q3：ulysses_size 设成 3 行不行？ A3：不行。代码里 generate.py 有硬性断言，ulysses_size 必须整除注意力头数。1.3B 是 12 头，可用 2 或 4；14B 是 40 头，官方用 8。设 3 会直接 assert 报错。而且它必须等于 nproc_per_node。

Q4：causal_fast 和 causal_pretrain 该选哪个？ A4：要快选 causal_fast，默认，每 chunk 4 步、无 CFG；要质量选 causal_pretrain，每 chunk 40 步、带 CFG，更慢更重。两者是速度和质量的取舍，没有谁"更好"，看你的场景。

Q5：想上线做产品，官方会给我部署代码吗？ A5：不会。官方明确不发布部署代码。生产化请参考 SGLang 的 LingBot-World cookbook 或 NVIDIA flashdreams 自己搭。另外，许可证是 CC BY-NC-SA 4.0 非商用，商用前必须先确认授权，衍生作品须同协议分发。