AlayaWorld空间记忆深度解析：DA3深度估计+前向投影如何让重访场景依然可辨认

AlayaWorld 空间记忆（spatial memory）是这款全开源、交互式长时程世界模型的"空间一致性"关键：当相机沿轨迹走远、再重访曾经看过的场景时，模型还能认出同一座建筑、同一片草地。答案藏在三个环节里——DA3（Depth Anything 3）深度估计、基于可见覆盖度的历史帧检索、把历史帧前向投影回当前视角的 forward warp。本文面向新手，不带公式地拆解这条流水线。

1️⃣ 问题背景：长视频为什么会"忘记"走过的路

AlayaWorld 基于 LTX 2.3 视频 DiT，以自回归分块方式生成视频：

如果生成第 40 个 chunk 时只盯着"最近几帧"做上下文，早期见过的场景就彻底失忆，重访时建筑会漂移、颜色会变脸。项目文档将其概括为：explicit 3D cache reprojected to the queried view for spatial recall, so revisited places stay recognizable（见 README.md）。

下图是仓库内置 demo（playground/case1）的首帧——一段日落时分的雅典卫城长镜头，正是"沿路走、再回头"这类场景的典型测试素材：

2️⃣ 空间记忆三步流水线：测景深 → 找参照 → 贴回画面

推理侧的整套逻辑集中在 alaya/inference/spatial.py 的SpatialMemory类中，它维护一个SpatialBank（空间银行），按三个阶段运转：

阶段①测景深：init_bank/append_prediction为新入库的每一帧调用 DA3 估计深度 阶段②找参照：_select_bank_sources用Sparse3DCache做覆盖度检索，挑出对目标视角"可见面积最大"的 10 帧历史帧 阶段③贴回画面：build_context把选中帧前向投影（forward warp）到目标相机位姿，VAE 编码后作为 DiT 的空间条件

2.1 测景深：DA3 深度估计器

深度由 alaya/memory/da3_depth.py 的DA3DepthEstimator提供，它是对 Depth Anything 3 的懒加载封装（缺依赖时普通训练路径依然可用）。几个工程细节值得注意：

• 相机条件推理：至少 2 帧时会把cam_c2w/intrinsic一并喂给 DA3（见 da3_depth.py 中_select_camera_arrays_for_frame_indices），让深度估计与相机标定对齐；若带相机条件推理失败，会自动降级为纯图像推理并重试；
• 数值防护：深度中的 NaN/Inf 被nan_to_num替换并裁剪到[0, 1e4]，保证后续反投影不出错；
• 兜底方案：配置里depth_backend可选da3/constant（见 alaya/config/schema.py），没有深度时就退回constant_depth: 1.0的平面假设。

深度估计结果与像素帧一起存入SpatialBank（pixels+depths+frame_indices，见 spatial.py）。每生成完一个新 chunk，append_prediction会把它解码回像素、再跑一遍 DA3测出新深度、追加进银行——空间记忆随视频滚动不断生长。

2.2 找参照：覆盖度检索（而不是"最近邻"）

检索核心是 alaya/memory/spatial_cache.py 的Sparse3DCache，思路非常直观：

1. 反投影：unproject_depth（spatial_cache.py）用深度图 + 相机外参 + 内参，把每个像素"抬"成世界坐标系下的 3D 点；默认downsample: 4，只保留 1/16 的点，计算量可控；
2. 前向投影：把所有历史帧的世界点批量投影进目标视角，对每个目标像素取"最近深度"（scatter_reduce_+amin），并用retrieval_depth_threshold: 0.1的容差判定该点是否真正可见；
3. 按可见面积打分：每张候选帧的分数 = 它在目标画面里实际覆盖的可见像素数；retrieval_max_coverage: true时采用贪心集合覆盖策略，逐帧挑选能补充最多新像素的帧，最终取num_context_frames: 10张。

也就是说：相机原地转身时，"离得远但正对着你"的老帧会优先被召回——这正是"重访可辨认"的直接来源。银行内每帧的世界点一旦入库就不会变，world_points缓存让每个 chunk 只需反投影新增帧（spatial.py 中的注释说明了这一优化）。

2.3 贴回画面：forward warp + 深度冲突消解

选中 10 帧后，build_context调用 alaya/inference/warp_da3.py 的forward_warp_indexed_pixel_sources_to_pixel_targets，底层实现_forward_warp_rgbd_with_depth（spatial_cache.py）做的是标准的前向投影融合：

• 源帧的每个像素：深度反投影 → 世界坐标 → 投到目标相机 → 得到目标像素坐标；
• 多个源帧的像素落到同一个目标像素时，按"谁离镜头近谁赢"（z-buffer 式最近深度）消解冲突，落空的像素留空（后由 VAE/模型补全）；
• 同时输出一张coverage 掩码，记录哪些像素是"真历史内容投影来的"、哪些是空洞。

一句话概括：先量深度，再挑帧，最后把旧画面按 3D 几何"糊"到新视角上——糊得准不准，取决于 DA3 深度准不准，这就是标题里两者的关系。

3️⃣ DiT 如何"阅读"空间记忆

前向投影的结果并不直接拼进视频，而是转成两种条件喂给 DiT（spatial.py）：

训练侧同样消费这套几何条件：stage2b 的 AR-SFT 使用 ViGeo pointmap 版本的空间条件（配置见 configs/stage2b_arsft_vigeo.yaml），推理侧则按配置切换depth_backend（da3或vigeo，字段定义见 alaya/config/schema.py）。下面是另一个内置 demo（playground/case2）的乡村风车首帧，展示同一套记忆机制在低多边形风格下的鲁棒性：

4️⃣ 关键配置速查（configs/infer.yaml）

da3 推理路径的完整配置在 configs/infer.yaml：

spatial_memory: enabled: true context_mode: target_prefix_pixels depth_backend: da3 # da3 / constant da3_process_res: 504 # DA3 处理分辨率 retrieval_max_coverage: true # 贪心集合覆盖检索 retrieval_depth_threshold: 0.1 # 可见性深度容差 num_context_frames: 10 # 召回的历史帧数 downsample: 4 # 世界点降采样倍率 constant_depth: 1.0 # 无深度时的平面兜底 skip_recent_latents: 1 # 检索时跳过最近 latent

调参直觉：num_context_frames越大记忆越丰富但编码开销越高；retrieval_depth_threshold放大会容忍更多"擦边可见"的像素，适合深度估计噪声较大的场景。

5️⃣ 一键跑起来

按照 inference/README.md 的说明准备好权重（merged_infer.safetensors权重包、Gemma 文本编码器、DA3 权重放入hf_cache）后，单卡即可运行内置 case1（约 1 分钟视频）：

pip install -r requirements.txt bash inference/run.sh

或多 GPU 上下文并行加速：

GPUS=4 bash inference/run.sh

等价于CONFIG_PATH=configs/infer.yaml bash scripts/finetune/train.sh，全部推理路径均由这一个入口按配置驱动。

小结

AlayaWorld 的空间记忆回答了一个朴素的问题："走远了回头看，世界还在原地吗？"它的工程答案不玄乎——DA3 把 2D 帧量成 3D，覆盖度检索决定"回忆哪几帧"，前向投影加最近深度融合把回忆贴回当前视角，最后经 VAE 与掩码变成 DiT 能消费的条件。理解这条深度 → 检索 → 投影的链路，也就理解了长时程世界模型里"一致性"二字的另一半来源（另一半是训练阶段的漂移历史与 error bank 机制，可继续翻阅 alaya/trainer/ 目录）。