Studio 内部

Studio 是覆盖同一套 pipeline 与 artifact 契约的目录驱动 shell，供 CLI 推理与评测共用。它不拥有模型权重、打分逻辑或 benchmark manifest；职责是发现可运行条目、准备输入、调用正确的 runtime driver、写出 RunRecord，并为 UI 挑选 preview assets。同一套执行核心服务 world 实时交互页面、Workspace job、conda 子进程与 torchrun worker。

调用图

Studio 执行路径

启动

启动启动参数ui/launch_config.py

parse_launch_config()

前端前端路由ui/launcher.py

discover_catalog()

运行时

发现Cataloginference/catalog.py

StudioManager()

编排StudioManagerinference/execution.py

prepare_inputs()

准备已落盘输入inference/execution.py

runtime_driver_for()

调度Driverinference/execution.py

run()

产出

执行RunRecordinference/execution.py

materialize_run()

预览预览资源inference/execution.py

推理语义放在 studio/inference/execution.py，catalog 发现放在 studio/inference/catalog.py。studio/ui/launcher.py 负责独立前端路由，启动参数由 studio/ui/launch_config.py 解析。页面、全屏与键盘交互位于 studio/visualization/backends/world.py 和 world_realtime_client.py；推理语义应由共享 execution 核心处理。

文件

Catalog discovery

Catalog 构建刻意做成静态过程。discover_catalog() 用 AST helpers 扫描 pipeline 模块，从而在不 import 重型 CUDA 栈或可选依赖的情况下列出模型。它合并三路来源：pipeline_*.py 类、component-pipeline 工厂、action-synthesis 类，再叠加 curated overrides 与 canonical runtime entries（aliases、默认 kwargs、checkpoint、runtime_kind）。去重键是 (module_path, class_name)；隐藏或抽象 id 不会进入 UI 列表。

真正的 import 发生在更晚：只有某次 run 需要具体类时，StudioManager.import_pipeline_class() 才按 CatalogEntry 的 module_path / class_name 加载。因此模型可以出现在 catalog 里，却在 LOAD 时因当前环境缺少 runtime import 或本地 checkpoint 而失败。

• 找 project root (_project_root() / _project_root_candidates()) — 允许 Studio 从 repo root 或 package context 运行。
• 检查 pipelines（_AstPipelineInfo 周边 AST helpers）— 不 import 重型模型依赖，直接读取 pipeline modules。
• 归一化 ids (_normalize_model_id()) — UI、CLI launch args 和 recent runs 共用的稳定 lookup key。
• 构建 entries (discover_catalog()) — 产出 CatalogEntry[]，包含 family、class path、category、backend、aliases、examples。
• 过滤 entries (filter_catalog()) — 对 UI 列表应用 search 和 category filters。

Execution core

StudioManager 是编排中枢。典型的 run / stream / init / reset 路径会准备 request、把输入落到 run 目录、按 entry.runtime_kind 选择 driver、加载 pipeline（LRU 缓存）、调用 driver，再物化为 RunRecord。Driver 存在是因为并非每个家族都是一次 __call__：two-stage 3DGS 先重建再 orbit，point-cloud nav 先重建再渲染视角，WorldFM 需要自定义相机与 panorama 处理；其余走 BaseRuntimeDriver。

PreparedInputs 是 staging 后的归一化载荷（prompt、图像、视频、interactions、runtime kwargs）。PipelineContext 保存已加载类、device、variant 与 output root。RunRecord 是 UI 可重载的持久单元：ids、inputs、outputs、artifact 路径、preview 选择、status 与 manifest JSON。Workspace 推理还可传入 infer_metadata 契约，让物化阶段校验必需的输出类型（video、image、splat 等）。

• PreparedInputs — 保存 staged prompt、images、videos、interactions、runtime kwargs 和 metadata。
• RunRecord — 保存 run ID、model ID、inputs、outputs、artifacts、preview paths、status 和 manifest export。
• PipelineContext — 保存 imported pipeline class、model ref、device、variant、load kwargs、output root。
• BaseRuntimeDriver — 默认 driver：load pipeline、run fresh request、可选 initialize/continue streaming、reset state。
• TwoStage3DGSRuntimeDriver — Two-stage 3DGS flows 的专用 driver。
• PointCloudNavRuntimeDriver — Point-cloud/navigation previews 的专用 driver。
• WorldFMRuntimeDriver — WorldFM camera pose 和 panorama workflow 的专用 driver。
• StudioManager — 编排 import、driver selection、input preparation、run execution、recent-run storage、unload/reset。

Preview 和 Artifact Helpers

Driver 返回后，materialize_run() 把异构 result 落成 run 目录下的文件：metadata JSON、已知 artifact key、可选的 frame→video 导出、mesh 转换，以及可选的 Rerun recording。若 preview 仍为空，Studio 可能按 WORLDFOUNDRY_STUDIO_ARTIFACT_SCAN_MODE 扫描输出目录。随后 pick_preview_assets() 为 UI 排序产物——优先生成视频与命名 preview，而不是 staged inputs——并返回主视频、图像、splat/model、gallery 与可选 .rrd。

Preview 空白通常意味着 pipeline 把文件写到了预期 key 之外、返回了没有 save() 的内存对象，或产出了解码器拒绝的视频。应先修 pipeline 契约，再考虑放宽 scan mode 或转换 helpers。

• export_frames_to_video() — 把 frame sequences 转成 preview video。
• collect_artifact_paths() — 在 output directory 下发现生成文件。
• pick_preview_assets() — 为 UI preview 选择 primary video/image/model/json assets。
• maybe_extract_video_preview_image() — 从 video preview 保存代表性图片。
• convert_model_for_preview() — Browser preview 需要别的格式时转换 3D assets。
• maybe_build_rerun_rrd() — 可用时构建 Rerun recording。
• write_json() — 写 run manifests 和 input/output records。

UI 文件边界

启动与展示通过独立浏览器前端提供。模型加载、输入归一化、runtime driver 与 artifact 契约由共享推理模块负责，页面与传输层调用 StudioManager。

• 启动参数 — ui/launch_config.py 解析 CLI flags 与环境默认值，返回 StudioLaunchConfig。
• 前端路由 — ui/launcher.py 与 visualization/backends/frontends.py 根据模型或 artifact 启动 world、Viser、Spark 等前端。
• 浏览器交互 — visualization/backends/world.py 与 world_realtime_client.py 负责页面、全屏、键盘和摇杆。
• 实时传输 — visualization/backends/world_realtime.py 维护常驻会话，调用 StudioManager.run_realtime() 并通过 WebRTC/WebSocket 传输帧和控制。
• 共享推理 — inference/execution.py 负责模型与 driver；实时交互直接传输内存中的帧，每次按键无需导出 MP4。

实时服务边界

实时路径刻意把模型状态与展示状态分开：

调用图

实时服务

输入浏览器按键边沿

重采样控制边沿

控制RealtimeControlResampler

步进驻留 runtime

模型ResidentWorldRuntime

提取realtime_frames_from_result()

会话后处理链

后处理VideoPostprocessStream

编码以便传输

传输分辨率 / JPEG 处理

按策略入队

队列latest-interactive / ordered-quality

线路WebRTC / WebSocket

模型通过 RealtimeSpec 拥有因果时序；transport 不应猜测 latent stride，也不能 静默改变严格 segment 帧数。latest-interactive 会在有界 backpressure 后丢弃旧帧， 保护控制延迟；ordered-quality 从不丢帧，凡是 chunk_done 帧数属于播放契约的 prompt-scheduled 或 queued segment 都必须使用它。

Postprocessor 位于解码 RGB 提取之后，持有隔离的会话状态，可以暂存一个 chunk， 并按 chain 顺序 flush 尾帧。默认 identity processor 也走同一条生产边界但不改变 输出，因此未来接 VSR、去噪或插帧时不需要侵入模型专属推理循环。RTX adapter 保持 layout/container/dtype/range，每条 stream 独占一个 VFX effect，复用前先 clone 借用的 DLPack 输出，并由单独授权的 rtx_postprocess extra 控制。每个完成的 chunk 都会记录归一化阶段 timing；用 runtime/realtime_regression.py 可以对 trace 中的 p50/p90、吞吐、队列深度和掉帧做门禁。

调试路径

多数 Studio bug 来自 catalog、输入、runtime 或 artifact 契约错位。缺模型几乎总是 catalog discovery、aliases 或隐藏 id。device / variant 错通常来自 launch config 与 PipelineContext overrides。输入到不了模型，问题在 prepare_inputs() 或 driver kwargs 绑定。Streaming 失败常见于没有 memory state 就调用 init/stream，或 two-stage driver 尚无先验重建。Recent run 无法 reload，说明 materialize_run() 之后 manifest 或 artifact 路径漂移了。

• UI 里缺模型 — discover_catalog() output、CatalogEntry.aliases、category filter、pipeline file naming。
• Variant/device 错 — StudioLaunchConfig、resolve_cli_variant_id()、PipelineContext。
• 输入没到模型 — prepare_inputs()、PreparedInputs、driver run_fresh() kwargs。
• Preview 空白 — collect_artifact_paths()、pick_preview_assets()、conversion helpers、generated file extension。
• Streaming 坏了 — BaseRuntimeDriver.run_init()、BaseRuntimeDriver.run_continue()、pipeline stream()、memory state。
• Recent run 无法 reload — RunRecord.to_manifest()、materialize_run()、load_run()、artifact paths。

面向用户的启动与 frontend 路由见 Studio。Studio 作为使用界面如何把用户意图编译为与 CLI、MCP 相同的 request，见 使用界面与编排。Studio 所依赖的 pipeline / operator / GenerationResult 契约见 模型运行时。