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。只有部署环境要求固定代理路由时，才需要手动指定端口。

远程机器上使用时，需要暴露 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 快捷入口。

对磁盘上已有的 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。

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 前端会像 LagerNVS Browser Viewer 一样由远端进程同时 serve 页面和 WebSocket 控制/帧更新通道。本地浏览器只需要通过 tunnel 访问同一个端口。 启动日志会打印对应命令，形状如下：

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

这与 LagerNVS 的 browser viewer 思路一致：渲染/资产服务跑在远端 GPU 节点， 本地浏览器通过 tunnel 访问同一个 loopback 端口。

页面状态条会显示 WS VIEW ... / GPU ...，用于区分浏览器/网络瓶颈和模型端渲染瓶颈。 如果 WebSocket 不可用，会自动退回 HTTP API。

交互模式

键盘/实时控制：

WASD = move
Arrow keys / IJKL = look

拖动摇杆或按住键盘方向键时，会等待上一个 step 完成后再发送下一次请求。

启动 flags

环境变量

Studio 只支持 WORLDFOUNDRY_* 环境变量。

发布证据

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