---
title: 模型运行时
description: Pipeline、operator、synthesis、representation、memory 和 hosted API 文件如何协作。
---

## 运行形状

一次模型调用通常沿这条链展开：Pipeline 是可复现的公开入口，Operator 在执行前处理输入与媒体，Synthesis 持有 checkpoint 或 API 调用，Representation 和 Memory 只在需要几何产物或多轮状态时介入。所有路径都收敛到同一种 `GenerationResult`，Studio、CLI 和 benchmark 才能共用同一套 artifact contract。

<ArchDiagram id="model-runtime" locale="zh" />

模型特定的公开 wrapper 应当保持轻薄，但 inference implementation 不能散落复制在各个模型目录中。本地 diffusion 模型族应组合 `worldfoundry/base_models/diffusion_model` 中的 canonical components；family package 只保留真正属于该模型的 network block 和 adapter。职责与依赖规则见[原生 Diffusion](/zh/docs/maintainers/architecture/native-diffusion)。

所有 model runtime 都必须是仓内实现，不能依赖机器本地的外部 checkout。DiffSynth、Diffusers、LightX2V 和各模型官方仓库只作为迁移参考，而不是 runtime backend。外部仓库和 checkpoint 在所需推理代码进入 WorldFoundry canonical components 之前，只能作为 provenance 或 acquisition metadata 存在。

公开支持声明看 `integration_status`，实现深度看 `backend_stage`。只有 `integrated` 且 `in_tree_runtime` 同时成立，才代表完整 runnable integration。`metadata_only`、`profile_only` 和 `official_client_bridge_only` 对规划很有用，但不等于已经可运行。

## 当前运行时契约

每个 runnable method 都必须同时具备 Pipeline 和 Operator。Pipeline 是从 catalog `pipeline_target` 或 canonical binding resolver 可达的具体类，负责模型加载、归一化执行，以及 `GenerationResult` 的 artifact 语义。Operator 是 Pipeline 在输入侧的搭档，负责 validation、image/video loading、camera/action parsing、interaction shaping 和 perception preprocessing。Operator 可以很薄，但不能缺失。

Binding 解析应统一走 `worldfoundry/evaluation/models/pipelines/bindings.py`。Catalog loading、pipeline loading、runner resolution 和 validation 都应调用这里的 helpers，而不是各自重新解析 route string。Runtime profile 可以携带 execution metadata、环境预期、checkpoint path 和 command hints，但它不能替代 pipeline/operator pair；`metadata_only` 或 `profile_only` 的条目不应被宣传成 runnable support。

`worldfoundry/base_models/diffusion_model` 是本地 diffusion 的 canonical runtime，也是唯一 diffusion package boundary。根部 contract 与按职责组织的 `models/`、`recipes/`、`loaders/`、`runners/`、`schedulers/`、`optimizations/`、`extensions/` 共同构成架构。旧 `diffsynth/`、`image/`、`video/` 与兜底式 `common/` 子目录已经删除，不再是受支持的 ownership layer。产品模块可以单向 import 或 re-export canonical component，但 canonical component 永远不能反向 import。通用 checkpoint materialization、state-dict loading、placement/offload、distributed execution、kernel、configuration 与 IO 全部来自 `worldfoundry/core`，family package 不能重新实现一套。`worldfoundry/base_models/perception_core` 和 `worldfoundry/base_models/three_dimensions` 仍是 inference/runtime package。这里只保留推理必需的 transforms 和 geometry helpers，不保留 training datasets、dataloaders、callbacks、losses、augmentation-only modules 或 experiment scripts。

内置 `wan2.1-t2v-1.3b` recipe 是这条边界的第一个完整实例；其他 diffusion family（Matrix Game 3.5、Echo Memory、LTX、Cosmos Predict/Transfer、HunyuanVideo、Sana、FLUX.2）复用同一套 role 装配，不持有自己的 pipeline、loader、scheduler 或 runner。各 family 的迁移状态——复用了哪些 role、删除了什么、以及支撑 recipe 的结构/tensor 验证证据——记录在 [原生 Diffusion 整合](/zh/docs/maintainers/native-diffusion-consolidation)。checkpoint 结构验证与 CUDA artifact parity 是两回事，后者按 family 仍是独立 release gate。

## 基础抽象

四个基类定义组装面：`PipelineABC`（load/process/stream 入口）、`BaseOperator`（仅输入与交互整形）、`BaseSynthesis`（本地 native runtime 或 hosted API）、`BaseMemory`（为流式或多轮控制保留前序状态）。`NativeDiffusionPipeline` 和 `NativeDiffusionRunner` 在 `BaseSynthesis` 边界下承担本地 diffusion 执行。各基类定义在哪个文件、各自拥有什么，见 [Runtime 组装](/zh/docs/maintainers/architecture/runtime-assembly) 的基类表；它们依赖的共享原语见 [核心基础设施](/zh/docs/maintainers/architecture/core-infrastructure)。

## 目录职责

判断一个模型修复应该落在哪一层时，可以先问“这次失败发生在输入、推理、几何后处理，还是状态管理”，再映射到归属包：输入 → `operators/`，原生推理与 hosted API → `synthesis/`，3D/4D 推理与 artifact → `base_models/three_dimensions/`，流式或多轮状态 → `core/memory` 加 `synthesis/*/memory`。这些包的目录级布局（含各 family 的 `synthesis.py` 以及 CameraCtrl/MotionCtrl 的位置）见 [Runtime 组装](/zh/docs/maintainers/architecture/runtime-assembly)。仅有 profile shell 的类不算集成完成。

静态推理预设在 `worldfoundry/data/models/`：`catalog/` 是元数据，`bindings/` 是 pipeline 入口，`runtime/profiles/` 是执行要求，`runtime/environments/` 是依赖规格，`runtime/configs/<model>/` 是 YAML/JSON 预设和示例输入。不要依赖工作目录，用包数据路径解析：

```python
from worldfoundry.core.io.paths import package_data_path

config = package_data_path(
    "models", "runtime", "configs", "wonderworld", "inference.yaml"
)
```

Runtime manifest 可以用 `${WORLDFOUNDRY_DATA_ROOT}/models/runtime/configs/<model>/<file>`；WorldFoundry 启动前会展开这个 token。相对继承只放在各模型目录内。配置类留在 Python 模块。训练配方、checkpoint、数据集和生成的 job config 不属于打包数据。

## 参考实现：OpenVLA

`openvla` 是当前树里第一个完整跑通的 VLA 集成，也是理解 embodied-action runtime 的最好例子。它的设计目标很简单：同一份 checkpoint loader 同时服务 Studio 的一次性 action trace 和 benchmark 的闭环 rollout，而不需要用户再 clone 上游 GitHub 仓库。

Embodied 闭环路径从 runtime config 开始。`data/models/runtime/configs/vla_va_wam/openvla.yaml` 声明 `backend: callable_entrypoint`，并把 `policy_target` 指向 `worldfoundry.synthesis.action_generation.openvla.runtime:predict_action`。Embodied eval 在 `evaluation/tasks/embodied/policy_adapter.py` 里通过 `build_policy_adapter()` 读取这份 config，再由 `evaluation/tasks/embodied/adapters/runtime_policy_adapters.py` 中的 `CallableRuntimePolicyAdapter` 把该 callable 包装成统一的 policy protocol。这样 simulator rollout 只需要语言指令和 RGB observation，就能拿到一步 robot action，而不必经过完整 pipeline lifecycle。

Studio 和一次性 action trace 仍走 pipeline 路径。`OpenVLAPipeline` 绑定 `OpenVLASynthesis`；`OpenVLASynthesis.predict()` 会先解析 runtime profile、选择 checkpoint、写出 plan JSON，然后在未设置 `plan_only` 时派发真实推理。这条路径更适合需要 artifact 文件、run directory 和 profile metadata 的单次 job，而不是逐步 simulator 交互。

两条入口最终都会落到 `synthesis/action_generation/openvla/openvla_runtime/inference.py`。这里的 `select_openvla_checkpoint()` 根据 `unnorm_key` 在 base checkpoint 和 LIBERO fine-tuned checkpoint 之间选择本地 staged 权重；`OpenVLARuntime` 再加载 processor/model，构造官方 OpenVLA prompt，执行 `predict_action`，并写出归一化的 action trace metadata。Prismatic/OpenVLA 的 HF config、model 和 processor 代码 vendored 在 `openvla_runtime/configuration_prismatic.py`、`modeling_prismatic.py` 和 `processing_prismatic.py` 中，因此 runtime 不依赖外部 repo checkout，也不依赖 Hugging Face remote-code cache。

如果你要新增一个类似的 VLA policy，通常只需要三件事：在 `data/models/runtime/configs/vla_va_wam/` 增加 callable config，在 `synthesis/action_generation/<model>/runtime.py` 暴露 `predict_action()`，并确保 embodied adapter 能从 observation 中解析出 image 和 instruction。Pipeline/synthesis 层可以后补，用于 Studio 和 model-zoo one-shot 运行，但不应成为闭环 eval 的前置条件。

## Pipeline 编写约定

一个典型 pipeline 文件会在 constructor 中保存 synthesis、operator、representation 和 runtime config；`from_pretrained()` 负责 checkpoint staging 或 API client 初始化；`process()` / `__call__()` 把用户输入转成 artifact；`stream()` 只在 Studio live control 或增量输出场景需要时实现。Helper 函数应只保留会影响 reproducibility、credential handling 或 artifact semantics 的部分，不要把训练脚本式的实验逻辑带进公开 pipeline。

## 托管 API 路径

Wan hosted family、Kling、Runway、Luma Ray、Hailuo hosted、Sora/Veo API 和 World Labs 等 provider 路径都保留在 `pipelines/` 下的独立 wrapper 中，与本地 checkpoint runtime 分开维护。Hosted wrapper 往往只需要 staging 本地图像、构造 provider payload，或等待 remote job 完成；它们不应偷偷复用本地 diffusion runtime 的 checkpoint loader。所有 provider credential 只通过环境变量注入，manifest、docs、tests 和 generated reports 中都不应出现 API key。

## 与 Evaluation 的衔接

Evaluation runner 不会直接 import pipeline 文件，除非 catalog 中的 model runner 明确解析到那条 route。

<ArchDiagram id="model-runtime-bridge" locale="zh" />

`resolve_pipeline_route()`（`evaluation/models/pipelines/bindings.py:359`）与 `resolve_model_zoo_runner()`（`evaluation/models/runners/resolver.py:386`）把这条链路解析成可运行 runner。其背后的 catalog 解析、spec 合成与 runner 解析机制见 [评测核心 — 模型解析](/zh/docs/maintainers/architecture/evaluation-core)。Planned 或 profile-only 条目可以保留 `runtime_profile`，但不应暴露 runner target；薄 planning wrapper 也不应把 `pipeline_target` 误报成已验证支持。

## 模型族索引

各类模型修复应落在哪个包（`pipelines/`、`operators/`、`synthesis/`、`base_models/three_dimensions/`、`core/memory`）的目录级指引见 [Runtime 组装](/zh/docs/maintainers/architecture/runtime-assembly)。对声明了可运行 runner 的模型，记录 public class 行为与 public 方法；未声明或已归档的 wrapper 只保留简短索引，不展开实现细节。