模型与 runner
公开模型 metadata、构建配置、执行协议和共享 pipeline 接口。
WorldFoundry 有两个相关但职责不同的扩展边界。WorldModelRunner 面向评测：接收归一化 request，返回归一化 result。PipelineABC 面向模型：负责加载和原生推理行为。一个 integration 可以同时实现两者，也可以用 adapter 把二者连接起来。
WorldModelManifest
公开 manifest 是模型身份与能力的紧凑 DTO。它不是完整 catalog YAML，也不是 runtime 证据；它保存的是 catalog 加载后 runner resolution 与评测真正需要的字段。
class WorldModelManifest(model_id: str,name: str = '',aliases: tuple[str, ...] = (),version: str = '',provider: str = '',capabilities: tuple[str, ...] = (),supported_tasks: tuple[str, ...] = (),required_artifacts: tuple[str, ...] = (),output_artifacts: tuple[str, ...] = (),tags: tuple[str, ...] = (),metadata: Mapping[str, Any] = <dict factory>,schema_version: str = WORLD_MODEL_MANIFEST_SCHEMA_VERSION)worldfoundry.evaluation.api.WorldModelManifestfrom worldfoundry.evaluation.api import WorldModelManifest简介
目录解析后的精简公开 DTO，描述模型身份与能力。不是完整 YAML，也不能证明 checkpoint 已加载。
属性
model_idstrnamestr- 默认值:
'' aliasestuple[str, ...]- 默认值:
() versionstr- 默认值:
'' providerstr- 默认值:
'' capabilitiestuple[str, ...]- 默认值:
() supported_taskstuple[str, ...]- 默认值:
() required_artifactstuple[str, ...]- 默认值:
() output_artifactstuple[str, ...]- 默认值:
() tagstuple[str, ...]- 默认值:
() metadataMapping[str, Any]- 默认值:
<dict factory> schema_versionstr- 默认值:
WORLD_MODEL_MANIFEST_SCHEMA_VERSION
方法
WorldModelConfig
WorldModelConfig 是传给 runner 的构建 payload。模型原生参数放入 parameters，设备、endpoint 等执行设置放入 runtime；如果已经解析出公开 manifest，也应一并保留。
from worldfoundry.evaluation.api import WorldModelConfig
config = WorldModelConfig(
model_id="matrix-game-2",
runner="worldfoundry.evaluation.models.runners.pipeline:WorldFoundryPipelineRunner",
variant="matrix-game-2-universal-action-validation",
parameters={"num_output_frames": 15, "fps": 12},
runtime={"device": "cuda:0"},
seed=42,
)上面是当前 Matrix-Game 2 catalog 使用的 binding。Runtime binding 会演进，生产代码仍应解析当前模型 manifest，而不是把文档示例硬编码进去。
class WorldModelConfig(model_id: str,runner: str,variant: str = '',parameters: Mapping[str, Any] = <dict factory>,runtime: Mapping[str, Any] = <dict factory>,seed: int | None = None,manifest: WorldModelManifest | None = None,metadata: Mapping[str, Any] = <dict factory>,schema_version: str = WORLD_MODEL_CONFIG_SCHEMA_VERSION)worldfoundry.evaluation.api.WorldModelConfigfrom worldfoundry.evaluation.api import WorldModelConfig简介
交给 runner 的构造载荷：model id、runner 目标、variant、parameters 与 runtime 放置。模型私有旋钮放在 parameters 中。
属性
model_idstrrunnerstrvariantstr- 默认值:
'' parametersMapping[str, Any]- 默认值:
<dict factory> runtimeMapping[str, Any]- 默认值:
<dict factory> seedint | None- 默认值:
None manifestWorldModelManifest | None- 默认值:
None metadataMapping[str, Any]- 默认值:
<dict factory> schema_versionstr- 默认值:
WORLD_MODEL_CONFIG_SCHEMA_VERSION
方法
WorldModelRunner
这个 runtime-checkable protocol 刻意保持很小。本地 checkpoint、托管 API、simulator policy 或 subprocess bridge 都可以满足它，不需要继承同一个基类。
from worldfoundry.evaluation.api import GenerationResult, WorldModelRunner
class ExistingArtifactRunner:
model_id = "existing-artifact"
capabilities = {"video_generation"}
@classmethod
def from_config(cls, config):
return cls()
def generate(self, requests):
return [
GenerationResult(
sample_id=request.sample_id,
model_id=self.model_id,
status="failed",
error="No generation implementation was configured.",
)
for request in requests
]
def cleanup(self):
pass
assert isinstance(ExistingArtifactRunner(), WorldModelRunner)这个例子故意返回显式失败，用来展示契约；真实 runner 必须物化输出，并把每个成功 artifact 写入对应 result。
class WorldModelRunner(Protocol)worldfoundry.evaluation.api.WorldModelRunnerfrom worldfoundry.evaluation.api import WorldModelRunner简介
最小可运行时检查的协议：接受 GenerationRequest，返回 GenerationResult。本地 checkpoint、远程 API、仿真器都可实现。
属性
model_idstrcapabilitiesCollection[str]
方法
PipelineABC
PipelineABC 给模型 integration 提供共同的加载与调用形态，同时保留原生行为。from_pretrained 构建组件，process 归一化输入，__call__ 执行一次推理，stream 把相同操作暴露给交互界面。生产 pipeline 可以按需要覆盖这些方法。
class PipelineABC(model_id: str | None = None,operators: Any = None,operator: Any = None,synthesis_model: Any = None,memory_module: Any = None,device: str = 'cuda',**kwargs: Any)worldfoundry.pipelines.pipeline_utils.PipelineABCfrom worldfoundry.pipelines.pipeline_utils import PipelineABC简介
面向模型的 pipeline 基类，负责加载与原生推理辅助。需要规范化评测边界时再与 WorldModelRunner 组合。
源码 docstring
Shared, non-strict base for WorldFoundry pipelines.
The class intentionally avoids abstract methods because many existing pipelines predate this contract. Subclasses can override any method while still sharing a stable framework surface.
参数
model_idstr | None- 默认值:
None operatorsAny- 默认值:
None operatorAny- 默认值:
None synthesis_modelAny- 默认值:
None memory_moduleAny- 默认值:
None devicestr- 默认值:
'cuda' kwargsAny
方法
from_pretrained(model_path: Any = None,required_components: dict[str, Any] | None = None,device: str = 'cuda',model_id: str | None = None,**kwargs: Any) -> 'PipelineABC'源码简介
from_pretrained — Create a pipeline with the unified loading signature.
源码 docstring
Create a pipeline with the unified loading signature.
This default is a compatibility implementation for lightweight or test pipelines. Production pipelines are expected to override it when they need to load model components.
参数
model_pathAny- 默认值:
None required_componentsdict[str, Any] | None- 默认值:
None devicestr- 默认值:
'cuda' model_idstr | None- 默认值:
None kwargsAny
返回值: 'PipelineABC'
简介
process — Normalize inputs before inference.
源码 docstring
Normalize inputs before inference.
Pipelines with operators should override this. The fallback preserves all caller data in a predictable shape for simple passthrough pipelines.
参数
argsAnykwargsAny
返回值: Any
简介
__call__ — Run the pipeline by delegating to :meth:process by default.
参数
argsAnykwargsAny
返回值: Any
简介
stream — Yield pipeline outputs using the same call semantics as `__call__`.
参数
argsAnykwargsAny
返回值: Any
简介
get_synthesis_model — Get synthesis model for PipelineABC.
返回值: Any
应该实现哪一个边界
如果目标是 benchmark 执行、批量处理归一化 sample、缓存或生成评测 ledger，应实现 WorldModelRunner。如果目标是为脚本或 Studio 提供可复用的模型原生推理对象，应使用 PipelineABC。两者都需要时，把 checkpoint 加载与原生调用留在 pipeline，再由 runner/operator 把 GenerationRequest 转成 pipeline 输入，并把原生输出转回 GenerationResult。
完整模型接入不只要求 API 形态正确。添加模型指南还会处理 catalog identity、资产、runtime binding、bounded validation 与文档。