WorldFoundry
English中文

模型与 runner

公开模型 metadata、构建配置、执行协议和共享 pipeline 接口。

编辑此页GitHubMarkdown

本页内容
WorldModelManifestWorldModelConfigWorldModelRunnerPipelineABC应该实现哪一个边界

WorldFoundry 有两个相关但职责不同的扩展边界。WorldModelRunner 面向评测：接收归一化 request，返回归一化 result。PipelineABC 面向模型：负责加载和原生推理行为。一个 integration 可以同时实现两者，也可以用 adapter 把二者连接起来。

WorldModelManifest

公开 manifest 是模型身份与能力的紧凑 DTO。它不是完整 catalog YAML，也不是 runtime 证据；它保存的是 catalog 加载后 runner resolution 与评测真正需要的字段。

类

WorldModelManifest

源码
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.apifrom worldfoundry.evaluation.api import WorldModelManifest

目录解析后的精简公开 DTO，描述模型身份与能力。不是完整 YAML，也不能证明 checkpoint 已加载。

属性

model_idstr
namestr默认值 ''
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

方法

cmethfrom_dict(data: Mapping[str, Any]) -> 'WorldModelManifest'源码

该类型上的公开 classmethod。

参数

dataMapping[str, Any]

返回值

'WorldModelManifest'

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，而不是把文档示例硬编码进去。

类

WorldModelConfig

源码
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.apifrom worldfoundry.evaluation.api import WorldModelConfig

交给 runner 的构造载荷：model id、runner 目标、variant、parameters 与 runtime 放置。模型私有旋钮放在 parameters 中。

属性

model_idstr
runnerstr
variantstr默认值 ''
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

方法

cmethfrom_dict(data: Mapping[str, Any]) -> 'WorldModelConfig'源码

该类型上的公开 classmethod。

参数

dataMapping[str, Any]

返回值

'WorldModelConfig'

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。

协议

WorldModelRunner

源码
class WorldModelRunner(model_id: str,capabilities: Collection[str])
worldfoundry.evaluation.apifrom worldfoundry.evaluation.api import WorldModelRunner

最小可运行时检查的协议：接受 GenerationRequest，返回 GenerationResult。本地 checkpoint、远程 API、仿真器都可实现。

属性

model_idstr
capabilitiesCollection[str]

方法

cmethfrom_config(config: WorldModelConfig) -> 'WorldModelRunner'源码

该类型上的公开 classmethod。

参数

返回值

'WorldModelRunner'
methgenerate(requests: Sequence[GenerationRequest]) -> Sequence[GenerationResult]源码

该类型上的公开 method。

参数

requestsSequence[GenerationRequest]

返回值

Sequence[GenerationResult]
methcleanup() -> None源码

该类型上的公开 method。

返回值

None

PipelineABC

PipelineABC 给模型 integration 提供共同的加载与调用形态，同时保留原生行为。from_pretrained 构建组件，process 归一化输入，__call__ 执行一次推理，stream 把相同操作暴露给交互界面。生产 pipeline 可以按需要覆盖这些方法。

类

PipelineABC

源码
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_utilsfrom 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

方法

cmethfrom_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'
methprocess(*args: Any,**kwargs: Any) -> Any源码

简介

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.

参数

argsAny
kwargsAny

返回值

Any
meth__call__(*args: Any,**kwargs: Any) -> Any源码

__call__ — Run the pipeline by delegating to :meth:process by default.

参数

argsAny
kwargsAny

返回值

Any
methstream(*args: Any,**kwargs: Any) -> Any源码

stream — Yield pipeline outputs using the same call semantics as `__call__`.

参数

argsAny
kwargsAny

返回值

Any
methget_operator() -> Any源码

get_operator — Get operator for PipelineABC.

返回值

Any
methget_synthesis_model() -> 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 与文档。