From 3d53563e3e17dac2cb67cd36e5c73fd0a435e60e Mon Sep 17 00:00:00 2001 From: tzhouam Date: Fri, 9 Oct 2026 11:25:58 +0800 Subject: [PATCH] knowledge: backfill LingBot World model contracts and usage --- .../vllm-omni/models/lingbot-world/_index.md | 21 ++-- .../models/lingbot-world/architecture.md | 82 ++++++++++++ .../lingbot-world/execution-validation.md | 119 ++++++++++++++++++ .../vllm-omni/models/lingbot-world/rules.md | 67 +++++++++- 4 files changed, 277 insertions(+), 12 deletions(-) create mode 100644 knowledge/repos/vllm-omni/models/lingbot-world/architecture.md create mode 100644 knowledge/repos/vllm-omni/models/lingbot-world/execution-validation.md diff --git a/knowledge/repos/vllm-omni/models/lingbot-world/_index.md b/knowledge/repos/vllm-omni/models/lingbot-world/_index.md index a48335f5..7fd6765f 100644 --- a/knowledge/repos/vllm-omni/models/lingbot-world/_index.md +++ b/knowledge/repos/vllm-omni/models/lingbot-world/_index.md @@ -1,7 +1,7 @@ --- title: "LingBot World" created: 2026-09-04 -updated: 2026-09-22 +updated: 2026-10-09 type: index tags: [vllm-omni, models, diffusion] sources: [vllm_omni/diffusion/models/lingbot_world/] @@ -17,13 +17,13 @@ confidence: high ## 源码路径 -共 5 个文件： - -- `vllm_omni/diffusion/models/lingbot_world/` +固定源码版本的模型目录有 7 个文件：`__init__.py`、`pipeline.py`、 +`transformer.py`、`dmd_block.py`、`camera.py`、`actions.py` 与 `utils.py`。 +分别从 pipeline 的请求/stepwise 入口、DMD block runner 和 camera/action 解析开始核对。 ## 依赖的共享代码模块 -- `vllm_omni/experimental/ar_diffusion/` → 无对应 component owner +- `vllm_omni/experimental/ar_diffusion/` → [AR 分页几何](../../components/diffusion/rules-ar-paging-geometry.md)、[系统运行时](../../components/diffusion/rules-system-runtime.md) 与 [tick/事件提交](../../components/model-executor/rules-bridge-batch.md) - `vllm_omni/diffusion/models/` → [diffusion](../../components/diffusion/_index.md) - `vllm_omni/diffusion/distributed/` → [diffusion](../../components/diffusion/_index.md) - `vllm_omni/diffusion/model_loader/` → [diffusion](../../components/diffusion/_index.md) @@ -34,7 +34,9 @@ confidence: high ## checkpoint、尺寸与量化 -- 上游没有 deploy 预设。pipeline 模块自述：Request-scoped LingBot-World v2 causal DMD pipeline. +- checkpoint：`robbyant/lingbot-world-v2-14b-causal-fast-diffusers`；registry key 为 `LingBotWorldCausalDMDPipeline`。 +- stepwise serving 显式选择 `vllm_omni/deploy/lingbot_world_v2_stepwise.yaml`；模型没有自动选用的默认 deploy config。 +- 新补内容按 [固定源码版本 9cf443a7bb24d6b8007981311466d769ec13b3d8](https://github.com/vllm-project/vllm-omni/tree/9cf443a7bb24d6b8007981311466d769ec13b3d8/vllm_omni/diffusion/models/lingbot_world) 核对；不改变仓库级 release baseline。 ## 什么时候查这里 @@ -50,4 +52,9 @@ confidence: high | 遇到什么 | 查看哪里 | |---|---| -| 该模型的硬门禁规则 | [session lifecycle 规则](rules.md)：`LBW-1a`、`LBW-1b` 新增核对：LBW-1a、LBW-1b。 | +| checkpoint 固定形状、首图/文本/camera 数据流、DMD 与模型/共享 owner 边界 | [架构](architecture.md) | +| offline、stepwise/WebSocket、SE3 controls、配置、FP8 与 realtime 验证口径 | [运行与验证](execution-validation.md) | +| 该模型的硬门禁规则 | [模型规则](rules.md)：session VAE decode、condition history 与模型专有合同 | +| paged KV 容量、K/V 独立存储、单 request stepwise rollout 与 warmup | [系统运行时](../../components/diffusion/rules-system-runtime.md)：`DIFF-4o`、`DIFF-4aa`、`DIFF-4ab`、`DIFF-4ad` | +| kernel 合法 page、ragged sink/recent window、scratch 与固定 block-table width | [AR 分页几何](../../components/diffusion/rules-ar-paging-geometry.md)：`DIFF-15a`–`DIFF-15c` | +| deprecated tick 的 session/event/request identity、失败与提交 | [跨 stage bridge](../../components/model-executor/rules-bridge-batch.md)：`EXEC-1l` | diff --git a/knowledge/repos/vllm-omni/models/lingbot-world/architecture.md b/knowledge/repos/vllm-omni/models/lingbot-world/architecture.md new file mode 100644 index 00000000..8bf1824f --- /dev/null +++ b/knowledge/repos/vllm-omni/models/lingbot-world/architecture.md @@ -0,0 +1,82 @@ +--- +title: "LingBot World 2.0 架构与模型边界" +created: 2026-10-09 +updated: 2026-10-09 +type: architecture +tags: [vllm-omni, models, diffusion] +sources: + - vllm-project/vllm-omni@9cf443a7bb24d6b8007981311466d769ec13b3d8:vllm_omni/diffusion/models/lingbot_world/pipeline.py + - vllm-project/vllm-omni@9cf443a7bb24d6b8007981311466d769ec13b3d8:vllm_omni/diffusion/models/lingbot_world/transformer.py + - vllm-project/vllm-omni@9cf443a7bb24d6b8007981311466d769ec13b3d8:vllm_omni/diffusion/models/lingbot_world/camera.py + - vllm-project/vllm-omni@9cf443a7bb24d6b8007981311466d769ec13b3d8:vllm_omni/diffusion/models/lingbot_world/dmd_block.py +confidence: high +--- + +# LingBot World 2.0 架构与模型边界 + +本页解释 image-conditioned causal world generation；执行硬约束见 [模型规则](rules.md)，入口、配置与验证方法见 [运行与验证](execution-validation.md)。 +内容核对到固定源码 `9cf443a7bb24d6b8007981311466d769ec13b3d8`；该模型页的补充不推进仓库级 release baseline，也不代表已运行真实权重验证。 + +## 模型专有部分与共享模块的边界 + +registry key 为 `LingBotWorldCausalDMDPipeline`，实现目录是 `diffusion/models/lingbot_world/`。pipeline 拥有首图条件、camera/action 解释、四步 DMD block、流式 VAE state 和模型自有状态显存声明；transformer 拥有 causal video attention、camera injection 与 C2WS 投影。 + +| 边界 | 模型侧职责 | 共享 owner | +|---|---|---| +| 请求与控制 | materialize image/trajectory，解释 camera script 和 SE3 interaction，校验模型几何 | HTTP/WebSocket transport、事件排队和输出生命周期属于 serving/diffusion | +| AR 执行 | block 数学、条件编码、模型状态 bind/reset/close | runner 的 paged KV、容量、scratch/commit 和 stepwise 调度见 [系统运行时](../../components/diffusion/rules-system-runtime.md) | +| attention | 模型 Q/K/V、sink/recent window 与 camera token | page 选择、ragged block 与固定 table 宽度见 [AR 分页几何](../../components/diffusion/rules-ar-paging-geometry.md) | +| 旧 tick 协议 | 解释 LingBot camera controls | typed tick 身份、快照和失败提交见 [EXEC-1l](../../components/model-executor/rules-bridge-batch.md#exec-1l-typed-ar-diffusion-tick-必须隔离协议身份并以完整-metadata-提交) | + +这些共享合同只保留一份正文；具体模型规则不能替代共享 runner/transport 的验收。 + +## 配置、checkpoint 和兼容范围 + +当前实现按 `robbyant/lingbot-world-v2-14b-causal-fast-diffusers` 的固定结构构建。`from_config` 校验配置值，不能把该入口当作任意 Wan 或其他 LingBot 尺寸的通用加载器。 + +| 配置 | 固定合同 | +|---|---| +| transformer | 40 层，40 attention heads，head dim 128，hidden size 5120，FFN 13824 | +| 输入/输出 | 36 input channels，16 output channels；patch `(1, 2, 2)` | +| 文本/时间 | UMT5 text dim 4096，freq dim 256，文本长度 512 | +| AR 几何 | 每 block 3 latent frames；sink 9，完整滑窗 18 latent frames | +| 时间压缩 | Wan VAE temporal factor 4；合法像素帧数 `9 + 12k` | +| 采样 | causal-fast 固定四步 DMD；flow shift 默认来自 scheduler，配置/请求可显式指定正有限值 | +| RoPE | 预计算长度 1024；temporal 绝对位置越界时即时计算，不能据此断言所有运行时状态都无限长 | + +标准组件分别从 `tokenizer/`、`text_encoder/`、`vae/` 加载；custom transformer 经 `DiffusersPipelineLoader` 的 `transformer.` 权重前缀装载。在线 FP8 只接入 transformer 内已有 vLLM parallel linears；普通 `nn.Linear`、VAE、text encoder 与 AR KV 不因此量化。 +来源：[配置校验](https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/vllm_omni/diffusion/models/lingbot_world/transformer.py#L992)、[组件加载](https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/vllm_omni/diffusion/models/lingbot_world/pipeline.py#L623)。 + +## 从输入到输出的主要流程 + +1. preprocess materialize 首图与 camera 输入；`_parse_request` 校验单请求、单输出、runner 提供的 generator、分辨率与完整 block 数。 +2. tokenizer/UMT5 生成文本条件；首图填入条件视频首帧，其余帧为零，经 Wan VAE encode 后取确定性 latent。16 个条件 latent channels 与 4 个 mask channels 组成 20-channel condition；再与 16-channel noisy latent 拼成 transformer 的 36-channel 输入。 +3. camera 模块把 pose/intrinsics 转成逐像素 ray embedding。当前六个通道实际为 **origin xyz + direction xyz**；不要根据 `build_plucker_embedding` 的名字误写为 moment/direction。像素 unshuffle 把 `6 × 8²` 折成 384 channels，再与视频 patch 网格对齐。 +4. 同一 `LingBotDMDBlockRunner` 推进四个 denoising probes，默认额外执行 clean-x0 KV writeback；每 block 提交 3 latent frames。可选最后一步 KV reuse 改变写回语义，详见 [模型规则](rules.md)。 +5. stepwise `post_decode` 按 session 复用 causal VAE temporal cache，产出像素 chunk 与 AR metadata；完成、reset、close 和失败边界释放模型状态。 + +来源：[条件编码](https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/vllm_omni/diffusion/models/lingbot_world/pipeline.py#L1106)、[camera embedding](https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/vllm_omni/diffusion/models/lingbot_world/camera.py#L425)、[DMD block](https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/vllm_omni/diffusion/models/lingbot_world/dmd_block.py)。 + +## 三种执行入口 + +| 入口 | 请求边界与输出 | 适用问题 | +|---|---|---| +| offline trajectory replay | 一个 request 重放预定 pose/intrinsics 路径，输出完整视频 | 已知 camera trajectory、整片比较 | +| stepwise streaming | 一次 `generate()` 是整个 rollout；prepare 一次，每 AR block 输出一个 chunk | `WS /v1/realtime/video`、request-scoped script 与 mid-session interaction | +| deprecated in-process tick | 每 request 只生成一个 block，session state 跨 request 保留 | 旧内部控制面与兼容性调查；不能套用 stepwise 的 request identity | + +stepwise 配置显式启用 `ARDiffusionEngine`、`step_execution` 与 `streaming_output`，固定 `max_num_seqs=1`；多副本 session affinity 尚未实现。模型不自动选择默认 deploy YAML，需由调用方选择执行模式。 + +## 设计取舍与实现边界 + +- **滑窗与持久状态**：sink/recent window 约束 attention residency；condition encoder、streaming decoder、cross attention 与 in-flight scratch 仍各有状态。滑窗不能单独证明显存上界。 +- **流式 VAE**：带 session 且 shape 不走 tiled decode 时复用 temporal cache，首 chunk 9 像素帧、后续每 chunk 12 帧。decoder 不支持流式或当前 shape 需 tiling 时走独立 decode，会损失跨 block 连续性；不能把 fallback 的输出当作同一时间线。 +- **纯 Ulysses 与 VAE 宽度分片**：当前代码支持 strict Ulysses，默认在多 rank 上复用同一 group 做 VAE width sharding；每 rank 通过 all-gather 得到完整输出。可用 `lingbot_vae_spatial_sharding=False` 保留 DiT SP 而关闭 VAE 分片。边界卷积的累加顺序不同，不能承诺 bitwise 等价。 +- **KV reuse 与精度**：`lingbot_reuse_last_step_kv=True` 省去 clean-latent writeback，但存储的是最后 noisy probe 的 KV；它与 online FP8 都需要 scene/seed/trajectory/长 session 的独立质量对照。 +- **文档漂移**：该 pin 的 recipe 尾部仍有“无 stateful streaming VAE / SP 未支持”的旧说明；能力边界按 pinned pipeline、deploy 与测试核对，不合并相互矛盾的声明。 + +来源：[decode 与 fallback](https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/vllm_omni/diffusion/models/lingbot_world/pipeline.py#L1762)、[parallel validator](https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/vllm_omni/diffusion/models/lingbot_world/pipeline.py#L249)。 + +## 怎样验证功能、精度和性能 + +按 [运行与验证](execution-validation.md) 的分层入口验证 request/control、DMD math、session cleanup、真实 checkpoint parity 和持续输出 cadence。结构 fixture 与 CPU mock 只验证对应合同；本页的源码核对不替代 GPU、真实权重、长 session 或端到端性能验证。 diff --git a/knowledge/repos/vllm-omni/models/lingbot-world/execution-validation.md b/knowledge/repos/vllm-omni/models/lingbot-world/execution-validation.md new file mode 100644 index 00000000..f3c8712c --- /dev/null +++ b/knowledge/repos/vllm-omni/models/lingbot-world/execution-validation.md @@ -0,0 +1,119 @@ +--- +title: "LingBot World 运行入口、配置与验证" +created: 2026-10-09 +updated: 2026-10-09 +type: guide +tags: [vllm-omni, models, diffusion, benchmark] +sources: + - vllm-project/vllm-omni@9cf443a7bb24d6b8007981311466d769ec13b3d8:vllm_omni/diffusion/models/lingbot_world/pipeline.py + - vllm-project/vllm-omni@9cf443a7bb24d6b8007981311466d769ec13b3d8:recipes/Robbyant/LingBot-World-2.0.md + - vllm-project/vllm-omni@9cf443a7bb24d6b8007981311466d769ec13b3d8:vllm_omni/deploy/lingbot_world_v2_stepwise.yaml + - vllm-project/vllm-omni@9cf443a7bb24d6b8007981311466d769ec13b3d8:benchmarks/lingbot_world/README.md + - vllm-project/vllm-omni@9cf443a7bb24d6b8007981311466d769ec13b3d8:benchmarks/lingbot_world/workload.py +confidence: high +--- + +# LingBot World 运行入口、配置与验证 + +源码核对版本：`9cf443a7bb24d6b8007981311466d769ec13b3d8`。模型数据流见 [架构](architecture.md)，开发/审查必须执行的模型约束见 [规则](rules.md)。以下命令是该版本的上游运行入口；本次知识补充没有启动模型或测量 GPU 性能。 + +## 请求与配置速查 + +| 字段或入口 | 当前行为 | +|---|---| +| checkpoint | `robbyant/lingbot-world-v2-14b-causal-fast-diffusers`，固定 causal-fast 14B 配置 | +| prompt/image | 非空文本、恰好一张图；路径图像先由 preprocess materialize；tensor 为 `[3,H,W]` 或 `[1,3,H,W]` | +| outputs / RNG | 一次请求、一个输出；使用 runner 提供的单个 `torch.Generator`；不接收 caller-provided latents | +| width/height | 同时给出或同时省略；输出正整数且按 VAE×patch 的 16 对齐，面积不超过 `480×832`；省略时由图像比例推导 | +| frames / steps | `num_frames = 9 + 12k`，每 block 3 latent frames；`num_inference_steps=4`；文本 max sequence length 固定 512 | +| flow shift | 正有限值；模型配置决定 scheduler 默认，请求 `extra_args.flow_shift` 可覆盖 | +| stepwise cache geometry | 请求 H/W 与加载时 `model_config.ar_diffusion_height/width` 一致；默认 480/832 | +| camera_action_script | stepwise 专用，每 chunk 恰好三项 latent-frame action；与 `action_path` 互斥 | +| action_path | 服务端轨迹文件需配置 trusted root：`model_config.lingbot_action_root` 或 `VLLM_OMNI_LINGBOT_ACTION_ROOT` | +| KV reuse | `model_config.lingbot_reuse_last_step_kv`，严格 boolean，默认 false，实例构造时固定；旧环境变量已不读取 | +| VAE width sharding | `model_config.lingbot_vae_spatial_sharding`，boolean，默认 true；多 Ulysses rank 生效 | +| online FP8 | `quantization_config={"method":"fp8"}`；可用完整 layer prefix 配置 `ignored_layers` | + +来源：[request parser](https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/vllm_omni/diffusion/models/lingbot_world/pipeline.py#L898)、[stepwise deploy](https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/vllm_omni/deploy/lingbot_world_v2_stepwise.yaml)。 + +## 离线 trajectory replay + +运行上游 example；首图与动作目录使用已验证的本地文件： + +```bash +python examples/offline_inference/diffusion/lingbot_world_v2.py \ + --prompt "The camera moves slowly forward through the scene." \ + --image first_frame.png --action-dir actions/forward \ + --num-frames 81 --output lingbot_world_v2.mp4 +``` + +目录内 `poses.npy` 是 `[frames,4,4]`，`intrinsics.npy` 是 `[frames,4]`；两者长度一致且有限，覆盖请求所需帧数，source trajectory 上限为 4096 帧。runtime 只消费请求前缀。request-mode 不接受 stepwise `camera_action_script`；固定轨迹与 deprecated tick controls 也有不同边界。 + +## 单 request stepwise serving + +```bash +vllm serve robbyant/lingbot-world-v2-14b-causal-fast-diffusers \ + --omni --deploy-config vllm_omni/deploy/lingbot_world_v2_stepwise.yaml \ + --port 8000 +``` + +deploy 明确设置 `ARDiffusionEngine`、`step_execution: true`、`streaming_output: true` 与 `max_num_seqs: 1`。这是单 GPU eager smoke 入口；单凭启动或输出成功不能说明达到 realtime。 +客户端用 `WS /v1/realtime/video` 的 `session.start` 开始整个 rollout；首图通过 `image_reference.image_url` 的 `http(s)` 或 `data:` URL 传入。完整公共 envelope 见固定版本 [streaming API](https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/docs/serving/streaming_video_output_api.md)。 + +`extra_params.camera_action_script` 是 request-scoped WASD script。mid-session camera 更新则通过 `session.interaction.interaction.event.multi_modal_data.camera` 提交结构化 SE3，Unity 坐标为 `+X` 右、`+Y` 上、`+Z` 前；velocity 示例： + +```json +{"mode":"velocity","data":{"translation":[0.0,0.0,0.05],"rotation":[0.0,0.0,0.0,1.0]}} +``` + +这只是 camera 对象，不是完整 WebSocket message。key tokens 由客户端转为 SE3，不能直接塞进公共 interaction。上游客户端提供转换入口： + +```bash +python examples/online_serving/streaming_video_generation/streaming_video_client.py \ + --model robbyant/lingbot-world-v2-14b-causal-fast-diffusers \ + --prompt "The camera moves slowly forward through the scene." \ + --image-reference first_frame.png --width 832 --height 480 \ + --num-frames 33 --fps 16 --seed 42 \ + --camera-updates '[{"at":1.0,"actions":["w"]}]' \ + --output lingbot_world_v2_stream.mp4 +``` + +单次 stepwise request 的 `session_id == request_id`，`chunk_index` 从零连续增长。deprecated tick example 每次 `generate()` 只有一个 chunk，具有独立 event/request identity；其生命周期合同见 [EXEC-1l](../../components/model-executor/rules-bridge-batch.md#exec-1l-typed-ar-diffusion-tick-必须隔离协议身份并以完整-metadata-提交)，不要把两种控制面混用。 + +## 并行、量化与质量开关 + +当前 pipeline 校验纯 Ulysses：`sequence_parallel_size == ulysses_degree`，`ring_degree == allgather_degree == 1`，strict mode，禁用 `ulysses_a2a_permute`。PP/CFG/VAE-patch parallel size 大于 1、HSDP 和 expert parallel 均拒绝；不能把同 group 的 VAE width sharding 描述成支持 `vae_patch_parallel_size`。 +四 GPU compiled 示例在 `benchmarks/lingbot_world/configs/usp4_compiled.yaml`；其 TP=1 是该配置的选择，不是 pipeline validator 对所有 TP 的限制。 + +在线 FP8 通过通用 quantization 配置传到 transformer 的 vLLM parallel linears，可按完整 prefix 保留敏感层为 BF16。camera/C2WS exclusion 是质量实验的配置选择，不是所有场景默认正确的策略。KV reuse 省去一次 writeback，VAE width sharding 改变边界数值顺序；每个开关都应与匹配的 BF16/默认 commit/full-frame decode 对照，不能从单个 kernel speedup 推断 E2E 或长 session 质量。 + +## 验证入口与证明边界 + +| 检查层 | 固定版本的测试入口 | 能证明的范围 | +|---|---|---| +| 模型合同 | `tests/diffusion/models/lingbot_world/test_pipeline_lingbot_world.py`、`test_lingbot_world_transformer.py` | request 几何、checkpoint fixture、DMD/quantization 传播、decode 生命周期与并行拒绝等定向合同 | +| camera/action | 同目录 `test_lingbot_world_camera.py`、`test_lingbot_world_actions.py` | trajectory、ray/control 形状与数值约束；不能代替可视运动质量 | +| 流式状态/内存 | `tests/diffusion/ar_diffusion/test_streaming_decode.py` 与 pipeline session tests | session 隔离、frame timeline、cleanup、预算公式；不能单独证明真实峰值显存 | +| benchmark client | `tests/benchmarks/test_lingbot_world_realtime.py` | scripted WebSocket、chunk arithmetic、RTF/SLO 指标；不能证明真实服务延迟 | +| 真实 checkpoint | `tests/e2e/offline_inference/test_lingbot_world_v2.py`、`test_lingbot_world_v2_stepwise.py` 与 `tests/e2e/online_serving/test_lingbot_world_v2_stepwise.py` | 需要相匹配的权重、GPU、依赖与拓扑；应另外记录 head、revision、实际命令、视频/latent 与指标 | + +这些是可用验证入口，未声称本次已执行 upstream 测试。先做当前环境的 import/version preflight，再选择对应测试；真实精度还需固定 seed、首图、prompt、camera trajectory、尺寸、帧数、dtype 和 attention backend，对照官方/既有 BF16 输出，覆盖跨窗口、prompt/control 切换、失败、reset/close 和长 session。 + +## Realtime benchmark 的指标口径 + +上游 [benchmark](https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/benchmarks/lingbot_world/README.md) 连接已经启动的服务，测量单 session 的持续输出 cadence；先启动匹配 topology，再运行： + +```bash +python benchmarks/lingbot_world/benchmark_lingbot_world_realtime.py \ + --port 8000 --num-chunks 40 --warmup-sessions 1 --sessions 3 \ + --target-fps 12 --output-json lingbot_world_repeated.json +``` + +- `ttfc_ms` 包含首次 prepare/encode 及可能的 compile/capture；后续 inter-arrival 衡量持续 cadence，不等于每个组件的执行时间。 +- 流式 decoder 正常工作时，首 chunk 9 帧，后续 12 帧；N chunks 总帧数为 `12N-3`。`video_rtf = wall_seconds / (frames / target_fps)`，小于 1 才达到该播放帧率的 realtime；`video_rtfx` 是倒数。 +- `--fps` 标记 mux，`--target-fps` 决定播放期限与 RTF。checkpoint 未声明原生 fps；报告两者，不能换 fps 后仍宣称同一性能结论。 +- session warmup 支付编译成本；默认 6 个 chunk warmup 排除 attention window ramp，二者不同。terminal chunk 不再准备下一 block，排除于 steady metrics，但保留于整体 RTF、all intervals 和 playback simulation。 +- 40 chunks 在默认 warmup 下每 session 33 个 steady intervals，三次合计 99；插值 p99 仍是稀疏样本摘要。报告每 session 的 spread、SLO attainment、模拟 playback stalls，不用短 rollout 均值代替持续性能。 +- 客户端没有 server-side timestamps 或显存指标；组件归因需服务端 profiler，真实显存需服务端测量。client/server inter-arrival 接近不能分离固定编码/传输延迟。 + +通用性能证据合同见 [benchmark scope](../../benchmark/guides/benchmark-scope.md)；本页只解释 LingBot 的 chunk 与播放时间口径，不保存一次性跑分。 diff --git a/knowledge/repos/vllm-omni/models/lingbot-world/rules.md b/knowledge/repos/vllm-omni/models/lingbot-world/rules.md index 7e0e1399..c46c50c2 100644 --- a/knowledge/repos/vllm-omni/models/lingbot-world/rules.md +++ b/knowledge/repos/vllm-omni/models/lingbot-world/rules.md @@ -1,13 +1,24 @@ --- -title: "LingBot World session lifecycle 规则" +title: "LingBot World 模型规则" created: 2026-09-22 -updated: 2026-09-22 +updated: 2026-10-09 type: rule tags: [vllm-omni, models, diffusion] -sources: ["PR #6533", "PR #6838", vllm_omni/diffusion/models/lingbot_world/pipeline.py] +sources: + - "PR #6533" + - "PR #6838" + - vllm_omni/diffusion/models/lingbot_world/pipeline.py + - "PR #7816" + - "PR #7651" + - "PR #7549" + - "https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/vllm_omni/diffusion/models/lingbot_world/pipeline.py" + - "https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/vllm_omni/diffusion/models/lingbot_world/dmd_block.py" + - "https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/vllm_omni/diffusion/models/lingbot_world/transformer.py" + - "https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/tests/diffusion/models/lingbot_world/test_pipeline_lingbot_world.py" + - "https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/tests/diffusion/models/lingbot_world/test_lingbot_world_transformer.py" --- -# LingBot World session lifecycle 规则 +# LingBot World 模型规则 ## Direct 代码快速入口 @@ -15,11 +26,15 @@ sources: ["PR #6533", "PR #6838", vllm_omni/diffusion/models/lingbot_world/pipel |---|---|---| | streaming VAE、session reset/close、admission bytes | `session-decode`：`LBW-1a` | `lingbot_world/pipeline.py` session hooks → `experimental/ar_diffusion/streaming_decode.py` | | condition block、encoder history、temporal RoPE | `condition-history`：`LBW-1b` | `lingbot_world/pipeline.py` condition state → `lingbot_world/transformer.py` RoPE → model admission | +| 四步 DMD、clean KV、last-step reuse | `kv-writeback`：`LBW-2a` | `pipeline.py` model config → `dmd_block.py` probe / transition / commit | +| Ulysses、VAE width shard、每 rank admission | `vae-sharding`：`LBW-2b`、`LBW-2e`、`LBW-2f` | `pipeline.py` parallel validation → `_install_sharded_vae_decode` → `_streaming_decode_bytes_per_session` | +| online FP8、ignored_layers、projection prefix | `quantization`：`LBW-2c` | `pipeline.py` transformer factory → `transformer.py` parallel linears / prefixes | +| 在线 SE(3)、WASD script、camera pose 对齐 | `camera-input`：`LBW-2d` | `pipeline.py` `_prepare_next_chunk` → `_prepare_camera`；共享 camera interaction handler | ## LBW-1a — AR 流式 VAE decode 状态必须按 session 持有并计入 admission - 触发：修改 LingBot/Wan 系 AR-Diffusion `post_decode`、streaming VAE decode、`SupportsStreamingDecode`，或 `model_owned_state_bytes_per_session`。 -- 强制：每个 `session_id`（与 `request_id` 同键）持有独立 `StreamingDecodeState`；chunk 间复用同一 temporal cache；`reset_ar_diffusion_session`/`close_ar_diffusion_session` 一并释放。`model_owned_state_bytes_per_session` 必须计入 decoder 按分辨率声明的常驻字节，不能只算 image condition。会走 VAE tiled decode 的 shape 不得冒充可跨 chunk 线程 cache。 +- 强制：每个 `session_id` 持有独立 `StreamingDecodeState`；stepwise 中 `session_id == request_id`，不能把此等式推广到具有独立 chunk request identity 的 deprecated tick。chunk 间复用同一 temporal cache；`reset_ar_diffusion_session`/`close_ar_diffusion_session` 一并释放。`model_owned_state_bytes_per_session` 必须计入 decoder 按分辨率声明的常驻字节，不能只算 image condition。会走 VAE tiled decode 的 shape 不得冒充可跨 chunk 线程 cache。 - 禁止：把 temporal cache 留在共享 VAE 模块上跨 session 覆写；块级独立 decode 却声称 timeline 连续；漏报 decode state 导致 admission 低估显存。 - 验收：覆盖跨 chunk 连续性、session 隔离、release、非流式/tiling fallback，以及 admission 字节随 H×W 缩放不随 session 长度增长。^[PR #6533] @@ -29,3 +44,45 @@ sources: ["PR #6533", "PR #6838", vllm_omni/diffusion/models/lingbot_world/pipel - 强制：跨 block 推进时保留 causal encoder history（committed + in-flight），每 session 只驻留当前 condition block 与有界 cache；admission 必须计入两份 encoder history 与 streaming-decode 字节。reset/close 必须释放 encoder cache。超出预计算 RoPE 表的 temporal 位置按绝对位置即时算 cos/sin，不得扩张常驻表。条件编码要求 unpatched、非 tiled Wan encoder。 - 禁止：用固定像素/latent 帧上限冒充无界 realtime；只预算 self-KV 而漏算 encoder cache；在失败 block 后提交 pending history；把本变更写成已解决共享 paged-KV 长度上限。 - 验收：因果条件递进、session 隔离/清理、失败不提交、内存会计、tick/stepwise 一致，以及 RoPE 越界且 cache 尺寸固定。^[PR #6838] + +## LBW-2a — KV 写回策略必须由实例配置固定并在所有 DMD 入口保持一致 + +- 触发：修改四步 causal DMD、KV 写回、`lingbot_reuse_last_step_kv`，或拆分 request / stepwise 执行路径。 +- 强制：`model_config.lingbot_reuse_last_step_kv` 只接受布尔值，加载组件前验证并固定到 pipeline 实例，默认 `False`。默认模式四次 denoise probe 不提交 KV，再用最终 clean `x0`、`t=0` 做一次写回；显式启用 reuse 时只在第四次 probe 写入其 noisy 输入的 KV，并省去 clean forward。两种模式都必须完成 paged context finalization；request 与 stepwise 共用 `LingBotDMDBlockRunner` 的 transition / commit 合同。 +- 禁止：重新读取旧环境开关或逐请求改策略；把 reuse 写成数值等价优化；把 clean-KV forward 算成第五次 denoise；省去 clean forward 时同时漏掉 pages 提交。 +- 验收：非法配置拒绝、默认值与实例隔离；两种模式逐次核对 timestep、`update_cache`、实际写回 latent、`start_frame` 和每块一次 paged commit；request / stepwise 的四次或五次 transformer 调用与输出一致性分别验证。[配置与调用轨迹测试](https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/tests/diffusion/models/lingbot_world/test_pipeline_lingbot_world.py#L1456)、[stepwise 提交测试](https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/tests/diffusion/models/lingbot_world/test_pipeline_lingbot_world.py#L2515)。^[PR #7816] + +## LBW-2b — 并行配置必须在组件加载前满足 pure Ulysses 合同 + +- 触发：修改 LingBot parallel config 或并行能力验证。 +- 强制：sequence parallel 仅接受 `sequence_parallel_size == ulysses_degree` 的 pure strict Ulysses，`ring_degree == allgather_degree == 1` 且禁用 `ulysses_a2a_permute`；在加载组件前拒绝不支持的模式。 +- 禁止：设置 `pipeline_parallel_size > 1`、`cfg_parallel_size > 1` 或 `vae_patch_parallel_size > 1`，或启用 HSDP / expert parallel；不能把 VAE width sharding 解释为支持 tiled VAE executor。 +- 验收：合法 pure Ulysses 通过；非法并行组合在 tokenizer、encoder、VAE 加载前失败。实际 process group 的检查属于 `LBW-2e`。[并行验证源码](https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/vllm_omni/diffusion/models/lingbot_world/pipeline.py#L249)。 + +## LBW-2c — Online FP8 配置必须贯通 eligible linears 与稳定的完整层名 + +- 触发：修改 LingBot transformer 构造、parallel linear、权重前缀，或 `quantization_config` / `ignored_layers`。 +- 强制：沿 pipeline factory、transformer、block 到每个 eligible vLLM parallel linear 传递同一 `quant_config` 与完整 prefix；覆盖 self/cross attention、FFN、camera injectors 和 C2WS。以 `transformer.blocks....` 等完整层名匹配 exclusions；fused `self_attn.qkv` 按一个投影排除。默认保留 BF16，online FP8 使用现有 `quantization_config={"method": "fp8"}` 入口，不内置模型专属 exclusion 策略。 +- 禁止：声称此选项同时量化普通 `nn.Linear`（含 output/time/text embedding）、norm、convolution、text encoder、VAE 或 AR KV cache；改变 prefix 导致调用者的 `ignored_layers` 静默失效；把某个 camera/C2WS exclusion 示例当成普遍质量保证，或将 FP8 plumbing 推广成已验证其他量化方法。 +- 验收：factory 接收原 quant config；有/无 quant、空/完整 prefix 的构造测试逐层核对 config 对象与层名，保留 checkpoint loader 测试。需要选择 exclusion 策略时核实真实加载后的 FP8/BF16 层分布，并按目标场景、seed、camera 和 session 长度对照 BF16。[构造与 prefix 测试](https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/tests/diffusion/models/lingbot_world/test_lingbot_world_transformer.py#L492)、[量化边界与 exclusions](https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/recipes/Robbyant/LingBot-World-2.0.md#L218)。^[PR #7549] + +## LBW-2d — 每个 block 的 camera condition 必须来自唯一且 latent 对齐的输入 + +- 触发：修改 LingBot 在线 camera interaction、request-scoped camera script / trajectory，或 Plücker camera embedding。 +- 强制：在线入口使用共享 camera handler 的结构化 SE(3) `translation` / `rotation`，先完成 chunk-boundary apply，再消费 session 的 `last_absolute_poses`；每块必须恰好有一个 pose 对应一个 latent frame（当前为三帧）。调用 `_prepare_camera(..., latent_aligned=True)`，保持前一块尾 pose（首块 identity）的 anchor，按 controller translation unit 归一化在线运动。`camera_action_script` 是 step execution 的 request-scoped WASD 输入；预设 script / cached trajectory 与已收到的在线 camera event 必须互斥，不能静默忽略后者。兼容 typed tick 时仍验证唯一 camera control 及其 trajectory / 三帧 action schema。 +- 禁止：把 WASD `data.actions` 作为在线 engine SE(3) payload；在 model prepare 中再次 apply 事件；用 media-frame 数替代 latent-frame 数；对已对齐的在线 poses 再做整段轨迹重采样；复用当前块首 pose 代替 pre-action anchor 而丢掉第一步动作。 +- 验收：覆盖无输入时 identity/hold、边界 apply 缺失、pose 数量错误、首动作 anchor、跨块连续动作和非匀速 trajectory；script / trajectory 收到在线事件必须报错。模型侧核对 folded camera 与 condition 的 frame / height / width 一致；共享事件排序与 target/velocity 时间线由共享 handler 测试负责。[模型 camera 分支与对齐](https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/vllm_omni/diffusion/models/lingbot_world/pipeline.py#L1959)、[输入互斥测试](https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/tests/diffusion/models/lingbot_world/test_pipeline_lingbot_world.py#L2734)、[共享 SE(3) handler](https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/vllm_omni/diffusion/interaction/modality_handlers/camera.py#L104)。 + +## LBW-2e — VAE width sharding 必须匹配实际 Ulysses group 并向每 rank 返回完整帧 + +- 触发：修改 LingBot VAE shard 安装、输出 gather 或 `lingbot_vae_spatial_sharding`。 +- 强制：多 Ulysses rank 默认沿 width 安装 Wan spatial shard decode；安装前核对实际 group 大小与配置一致，用 `dst=None` 让每 rank 获得组装帧。开关只接受布尔值；显式 `False` 保留整帧 decode 与原 DiT SP。 +- 禁止：group 不匹配时继续安装/使用分片；只让一个 rank 获得下游每 rank 都要消费的帧；关闭时仍访问 shard group。 +- 验收：单 rank 不安装、多 rank 默认安装、显式关闭不访问 group、非法开关与 group mismatch 拒绝；保留 `LBW-1a` 的 session 隔离、连续 decode 和释放测试。[分片安装测试](https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/tests/diffusion/models/lingbot_world/test_pipeline_lingbot_world.py#L760)。^[PR #7651] + +## LBW-2f — Streaming VAE admission 必须按实际 padded shard 尺寸估算 + +- 触发：修改 sharded decoder 每 session 常驻字节估算或 latent/pixel width 换算。 +- 强制：先将像素 width 向上换算为 latent extent，再按实际 rank 数向上分片，最后乘 VAE spatial scale，以此 local width 预算 temporal cache；未分片时仍报整帧。 +- 禁止：用未取整的 `width / ranks` 低报 cache；把 halo 接收 buffer 重复计作每 session temporal state。 +- 验收：覆盖不能整除的宽度和开关两种状态；例如 SP4 的 840 像素 width 应按 216 像素 local width 预算，关闭 sharding 则按完整 840。[预算测试](https://github.com/vllm-project/vllm-omni/blob/9cf443a7bb24d6b8007981311466d769ec13b3d8/tests/diffusion/models/lingbot_world/test_pipeline_lingbot_world.py#L783)。^[PR #7651]