Studio

介绍

WorldFoundry Studio 是围绕仓库 pipelines 的薄可视化入口。模型在启动时固定；切换模型族时启动新进程。

Studio 现在有多前端入口：

可视化内容

默认情况下，Studio 会隐藏大多数高级面板。使用 --show-aux-panels 显示 history、notes、catalog、3DGS import 和低层 runtime controls。

Workspace 模式

多模型验证和发布 QA 推荐启动 workspace app，而不是单模型 Studio 进程：

source tmp/worldfoundry_unified_env.sh
conda activate "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}"

bash scripts/workspace/run_workspace.sh \
  --host 127.0.0.1 \
  --port 7870 \
  --max-jobs 8

如果 checkpoint 或 benchmark 数据不在默认 cache 中，显式传入根目录：

bash scripts/workspace/run_workspace.sh \
  --ckpt-dir /path/to/checkpoints \
  --data-dir /path/to/benchmark-data

launcher 不依赖任何机器专有路径。资产解析顺序是：命令行参数、已经导出的 环境变量、repo 同级存在的 ckpt/ 或 data/ 目录、tmp/worldfoundry_unified_env.sh 中的 env-file 值，最后回退到 ~/.cache/worldfoundry/...。

Workspace 必须从模型推理使用的统一 runtime 环境启动，不能从只装了 UI 依赖的轻量环境启动。CUDA 12.8 机器通常对应 worldfoundry-unified-cu128，先执行 source tmp/worldfoundry_unified_env.sh 再启动 7870。如果 LOAD 或 START 报 cv2 等模块缺失，说明当前 7870 进程不是统一 runtime 环境，先重启 workspace，再排查模型代码。

不要在机器之间复制或搬迁已经创建好的 conda 环境。Python、OpenSSL 等原生 链接可能仍指向旧 prefix，导致浏览器服务能启动，但 resident inference worker 一运行模型就报缺少 python3.x、cv2、libssl 或 libcrypto。遇到这类 问题，按公开 setup 路径验证或重建统一环境：

bash scripts/setup/bootstrap_worldfoundry.sh --verify-only
source tmp/worldfoundry_unified_env.sh
bash scripts/workspace/run_workspace.sh

打开：

http://127.0.0.1:7870/

workspace 是发布验证时推荐使用的 UI。 它适合提交 inference job、检查不同模型的输入表单、查看生成产物， 以及在同一个界面里对比多次 run。

Workspace 也支持 evaluation job。以 VBench 为例：选择 Evaluation， benchmark 选 vbench，把生成视频目录填到 Dataset Root（或把官方 VBench results JSON 填到 Results Path），Metrics 填一个或多个 dimension，例如 aesthetic_quality、motion_smoothness，也可以填 preset custom_supported。VBench 专用 runtime 参数，例如 {"mode":"custom_input","load_ckpt_from_local":true}，写到 Eval Runtime JSON。

Create Job 配置

Workspace UI 没有单独的 Settings 页。每次提交前在 Create Job 对话框里 定制参数即可。

打开 Create Job 或切换 task profile 时，表单会先用 Workspace 启动时加载 的默认值预填。catalog 和 task profile 中的模型专用官方 demo 值仍优先于这些 共享默认值。

未配置 settings 文件时的默认值：

可选的持久化默认值

若希望在 Workspace 重启后仍复用同一套默认值，可指定 JSON settings 文件：

export WORLDFOUNDRY_STUDIO_SETTINGS_FILE=/path/to/studio-settings.json

启动时 Workspace 会把该文件加载到 /api/settings，Create Job 表单通过 GET /api/settings 读取。运维脚本也可以用 POST /api/settings 更新：

curl -sS -X POST http://127.0.0.1:7870/api/settings \
  -H 'Content-Type: application/json' \
  -d '{"values":{"fps":12,"num_frames":49,"attention_backend":"torch"}}'

未设置 WORLDFOUNDRY_STUDIO_SETTINGS_FILE 时，默认值只存在于当前 Workspace 进程内存中，重启后会恢复为内置默认。

快速 job 与 preflight 检查

Workspace inference 默认走快速 job 路径：默认认为 conda 环境、checkpoint 根目录和 viewer 依赖已经在启动 server 前配置好。正常反复推理时建议保持默认。

只有在环境排障或发布前 preflight 时，再显式打开检查：

为了让 job 完成路径最快，模型 runtime 应该在 run record 中显式返回 preview_image、preview_video、artifact_paths、rrd_path 和 output_dir。 只有旧 runtime 只写文件、不返回路径时，才建议把 artifact scan mode 切到 always。

Resident worker 会让 conda 子进程在多个 job 之间保持存活，因此子进程里的 StudioManager 可以复用 pipeline cache。排查进程启动问题，或希望每个 job 结束后立刻释放 GPU 显存时，设置 WORLDFOUNDRY_STUDIO_RESIDENT_WORKERS=0。

Visualizers、Gallery 和 Artifacts 适合快速视觉 QA。 这些视图会展示最近生成的视频、图片、manifest 和直接 artifact 链接。 真正对外声明验证通过前，还需要把对应 run 记录到模型推理验证页。

Workspace 可视化入口

7870 Workspace 是整套可视化服务的统一浏览器入口。打开 Visualizers 页面后，每张卡片都有 Launch、Open 和 Stop 按钮。卡片下方会 嵌入正在运行的 viewer iframe，普通 QA 流程里不需要手动复制 URL。具身仿真器 Bridge 卡片标记为 计划中：与 Viser、Spark、Rerun、World Rollout 不同，目前还不会启动仓内 embodied viewer。

世界模型分段 Rollout

• 端口7868
• Aliasinteractive-world, world-model, world-rollout

面向实时漫游的缓冲式动作条件 rollout。前端持续采样控制输入并预取生成片段。

产物image, video, action_trace

启动入口python -m worldfoundry.studio.app matrix-game-2 --frontend world --port 7868

Viser Geometry Viewer

• 端口18590
• Aliasviser, geometry, pointcloud

点云、depth 转 point set、mesh、camera pose 和 trajectory。

产物ply, pcd, xyz, glb, gltf, obj, npz

启动入口python -m worldfoundry.studio.app pi3 --frontend points --asset /path/to/scene.ply

Rerun Timeline Viewer

• 端口9876
• Aliasrrd

`.rrd` timeline / recording，同步 camera、frame、track 与 3D entity。

产物rrd

启动入口python -m worldfoundry.studio.app vggt --frontend rerun --asset /path/to/recording.rrd

Spark Gaussian Splat Viewer

• 端口8765
• Alias3dgs, splat

通过仓内 Spark frontend 查看 3D Gaussian splat。实时预览来自 Spark.js Hello World butterfly demo。

产物splat, spz, ksplat, sog, splat-ply

启动入口python -m worldfoundry.studio.app vggt --frontend spark --asset /path/to/scene.splat

具身仿真器 Bridge

计划中

• 端口18610
• Aliassim, simulator

仍处于计划/早期集成阶段。当前 Studio 只会登记外部 simulator URL 并给出 tunnel 提示，还没有仓内 embodied viewer。请先单独启动 simulator，再把 URL 填到 Visualizers。

产物action_trace, trajectory, simulator_url

启动入口python -m worldfoundry.studio.app openvla --frontend embodied --simulator-url http://127.0.0.1:18610

world 默认使用 7868。只有部署环境要求固定代理路由时，才需要手动指定端口。

实时前端需要 worldfoundry[studio_realtime]（worldfoundry[ui] 已包含）。 服务启动时会后台加载模型；一次会话固定复用同一个 pipeline context 和执行线程。 WASD/IJKL 只发送按下/释放边沿，服务端按生成 chunk 重采样；RGB 帧直接进入 WebRTC 视频轨。控制到画面的热路径不会扫描 artifact、写 manifest 或编码 MP4。

远程机器上使用时，需要暴露 7870 和实际启动的 viewer 端口。例如：

ssh -L 7870:127.0.0.1:7870 \
    -L 18590:127.0.0.1:18590 \
    -L 8765:127.0.0.1:8765 \
    -L 9876:127.0.0.1:9876 \
    user@host

产物可视化路由

inference job 完成后，Workspace 会扫描 run record 和输出目录里的可视化产物。 Artifacts 页会为支持的文件显示 Open 和 Open in ... 操作。 Job Detail 只保留内嵌 preview video/image，不再重复 viewer 快捷入口。

Base model 感知结果

WorldFoundry 为仓内 3D 和 perception model 维护一份统一的可视化能力注册表。 编写 model-specific viewer 前先查询注册表：

worldfoundry-eval models visualizations
worldfoundry-eval models visualizations --family perception_core
worldfoundry-eval models visualizations --model raft --json

结构化 2D 结果复用同一个转换命令。当前支持 detection、mask、flow、 tracks、feature-pca、depth、normal、keypoints 和 text：

worldfoundry-eval models visualize \
  --kind flow \
  --artifact outputs/flow.npz \
  --output outputs/flow.png

worldfoundry-eval models visualize \
  --kind detection \
  --artifact outputs/detections.json \
  --media inputs/frame.png \
  --output outputs/detections.png

这条共享路径覆盖 Depth Anything、SAM、RAFT、DINO、GroundingDINO、 YOLO World、CoTracker 等仓内 family 的官方输出 schema。原生图像/视频进入 media viewer，点云和 mesh 进入 Viser，Gaussian splat 进入 Spark，同步场景记录 进入 Rerun。每个模型的权威映射以 registry 命令输出为准。

对磁盘上已有的 run，直接在 Workspace 打开该 run，用 Artifacts 标签页确认 viewer 路由。上表是路由参考；具体 run 以 Artifacts 里的 Open / Open in ... 按钮为准。

对模型作者来说，最容易复现的方式是把输出写到 Studio run 的输出目录，并在 run record 中保留稳定路径：

• preview_image 或 preview_video：用于快速媒体预览。
• artifact_paths：用于原始生成产物。
• rrd_path：用于 Rerun recording。
• output_dir：用于让 Workspace 继续发现目录里的其他文件。

3D reconstruction 模型应该导出浏览器可读的 .ply、.glb、.gltf、.obj、 .pcd、.xyz 或紧凑点云/depth .npz。3DGS 模型应该导出原生 splat 文件，或者 header 中包含 scale、rotation、opacity、spherical-harmonic color 等 splat 属性的 binary little-endian Gaussian-splat PLY。Workspace 会在选择 Viser 或 Spark 前区分普通 PLY geometry 和 Gaussian-splat PLY。

坐标系契约

启动 viewer 是 geometry contract 的一部分。points、mesh、camera-to-world、frustum 和 trajectory 必须处于同一个已声明坐标系，不能只翻转点云：

• 已完成 OpenCV-to-OpenGL 对齐的官方 GLB 使用 asset-native 和 exporter 声明的 up axis；VGGT/VGGT-Omega 官方 GLB 使用 +Y up、alignment=none。
• VGGT/VGGT-Omega、UniDepth V2 与 UniK3D 的原始 model-point NPZ 保留 OpenCV camera frame，Viser 只应用一次 opencv-to-opengl 并使用 +Y up。
• UniDepth V2/UniK3D 的 Workspace PLY 已写成 x-right/y-up/z-forward，因此使用 asset-native、+Y up、alignment=none，不能再次翻转。
• DUSt3R、LoGeR 与 Pi3 的 PLY 保留预测 camera-to-world sidecar；Viser 对 points 与 cameras 一起应用 first-camera-opengl，使用 +Y up，并按中心 5-95% geometry 取景，避免少量离群点把有效场景缩得过小。
• Rerun recording 必须声明 world ViewCoordinates，并让每个 Pinhole 使用同一 camera convention；Cut3R 与 MonST3R 的 world/camera 都使用 RDF。

Workspace 会自动解析 VGGT、DUSt3R、LoGeR、Pi3、UniDepth V2 与 UniK3D 的上述已验证默认值。其他 exporter 可用 Visualizer Params JSON 显式覆盖。请求端口被占用时，Viser 会显示实际绑定端口。Rerun 默认使用 WebGPU； 只有目标浏览器需要时才设置 WORLDFOUNDRY_STUDIO_RERUN_RENDERER=webgl。

选择 3D viewer

默认按产物语义路由，避免每个模型重复实现 viewer：

viewer 进程能启动不等于 inference 已完成视觉验证。3D/4D 方法的 release evidence 应先确认 geometry 与 camera data 有限，再在真实浏览器中打开实际产物，检查 canvas 非空且构图可读，执行 reset/orbit 或 timeline 交互，并检查 console error。官方 viewer 应作为小型 visualization plugin 保留；共享 Viser/Rerun scene layer 足够时， 不要复制其 inference runtime，也不要为单个模型另写 frontend。

Studio 截图

这些截图来自当前用于模型发布验证的 7870 workspace。

Inference Jobs

队列会展示已提交 run、最终状态，以及 run record 提供的内嵌 preview video 或 image。

Create Job

表单应该展示模型真实的输入 contract。 下面的截图只展示 UI 结构；真正的 release demo 声明应以验证记录和对应 run manifest 为准。

Catalog

Catalog 过滤可以用来确认 workspace 提交 job 前能看到哪些 world-model entries。

Gallery

Gallery 提供最近 inference outputs 和 preview artifacts 的紧凑视觉检查入口。

模型推理 Demo 结果

下面的 gallery 只做视觉参考，展示来自仓内 Studio 或 Studio-compatible API run 的 代表性产物。这里不是 release claim 表；精确参数、环境说明、run id 和剩余风险 记录在验证 reference 中。本页只嵌入经过筛选的非短测示例。

启动矩阵

推荐本地启动：

cd /path/to/WorldFoundry
PYTHONPATH=. WORLDFOUNDRY_STUDIO_PORT=7868 conda run -p "${WORLDFOUNDRY_UNIFIED_ENV_PREFIX}" python -m worldfoundry.studio.app \
  lingbot-world \
  --variant fast \
  --model-ref /path/to/checkpoints/lingbot-world-fast \
  --device cuda:1

如果当前 checkout 没有安装到环境里，请保留 PYTHONPATH=.。

Studio 启动时会打印解析到的 workspace、model、cache 和 Hugging Face cache 根目录，方便在真正运行前发现路径配置问题。

打开：

http://127.0.0.1:7868

远程 GPU 节点推荐用 SSH tunnel。

world 进程通过配置的 HTTP 端口提供页面和 WebRTC signaling；视频与控制随后 走 ICE 选出的 WebRTC 链路。普通 SSH 端口转发只会承载 signaling，无法单独转发 WebRTC 媒体。浏览器不能直连 GPU 主机时，请通过 WORLDFOUNDRY_REALTIME_ICE_SERVERS_JSON 配置 TURN relay。

ssh -N -L 7868:127.0.0.1:7868 user@gpu-host
# local browser:
# http://127.0.0.1:7868

页面状态条会显示 RTC 播放 FPS、生成耗时、控制延迟、队列深度和丢弃的旧帧。 ICE 超时会明确报错，不会让页面永久停留在连接中。

交互模式

键盘/实时控制：

WASD = move
Arrow keys / IJKL = look

键盘和摇杆的按下/释放边沿会立即通过当前实时通道发送。常驻 runtime 在模型 chunk 边界采样最新的有效控制状态；输入不会创建第二个 inference request，也 不会重新加载 pipeline。

沉浸式全屏与实时运行日志

全屏视图属于共享的 world 前端，因此所有路由到该前端的交互模型都可以使用。 它会复用当前 peer 或 socket、帧缓冲和常驻模型会话。进入或退出全屏不会让 浏览器重连，也不会重启生成。

1. 按正常流程准备模型输入并启动会话。
2. 点击 viewport 左上角的 FULLSCREEN，或按 F。
3. 画面会铺满屏幕，并自动打开实时运行日志。
4. 点击 LIVE LOG 或按 Shift+L，可以在不退出全屏的情况下隐藏或显示日志。
5. 按 Esc 或点击 EXIT，返回标准 Studio 布局和同一个活动会话。

日志会展示 client/model 就绪状态、实时传输状态、segment 排队/生成/播放阶段、 错误和每个 chunk 的性能数据。chunk 完成后会记录帧数、生成耗时 (gen)、播放 队列深度 (queue) 和丢弃的旧帧数 (dropped)。这些内容用于当前交互会话排障； 它们不是持久化 run artifact，也不是服务端完整 stdout/stderr 的副本。

实时日志复用现有实时连接。浏览器按 animation frame 批量更新 DOM，并且最多 保留最近 120 条记录，因此长时间游玩不会无限扩大日志树，也不会在帧传输热路径 增加轮询。浏览器允许 Fullscreen API 时，点击按钮或使用快捷键会进入原生全屏； 如果原生全屏不可用或被浏览器策略阻止，Studio 会保持当前会话，并回退到铺满 浏览器视口的布局。 Workspace 的 visualizer iframe 已经授予 fullscreen 权限。

启动 flags

环境变量

Studio 只支持 WORLDFOUNDRY_* 环境变量。

发布证据

只有当对应官方配置已经通过仓内 Studio 或 Studio-compatible API 路径运行后， 才把 demo media 放到公开文档中。保留对应 run manifest、解码后的视频元数据和 视觉 QA 记录，确保页面中嵌入的视频可以追溯到实际 release candidate run。