Core 配置

延迟构造图、结构化推理配置、递归实例化与 freeze 行为。

最后更新: 2026年7月22日

本页内容

Core 配置把“描述对象图”和“构造昂贵模型对象”分开。LazyCall(target)(...) 会把 target 与命名参数记录成可编辑的 OmegaConf 节点；只有当 runtime 准备好以后，instantiate 才遍历对象图并真正创建对象。

这个 package 需要 attrs 和 omegaconf。它们由视频或模型 runtime 环境提供，不属于最小 CLI 安装。

延迟构造示例

from torch import nn

from worldfoundry.core.configuration import LazyCall, instantiate

Linear = LazyCall(nn.Linear)
layer_config = Linear(in_features=8, out_features=4, bias=False)

# 此时还没有真实 module，因此组合配置仍然可以修改对象图。
layer_config.out_features = 6
layer = instantiate(layer_config)

assert isinstance(layer, nn.Linear)
assert layer.in_features == 8
assert layer.out_features == 6

LazyCall 只接受关键字参数。它先记录 target 签名中的默认值，再用显式值覆盖。嵌套 list 和 mapping 默认递归实例化；设置 _recursive_=False 可以关闭递归；普通 mapping 和基础值会原样通过。

发布模型的结构化配置

Config 及其嵌套 attrs 类只保存发布推理共同需要的小部分配置：延迟模型图、checkpoint 来源、runtime/CuDNN 设置、模型并行设置和 job 身份。模型专属字段继续留在模型自己的 lazy graph 中。

make_freezable 会为采用 slots=False 的 attrs 类增加递归 freeze()。它用于防止配置完成组合后被意外改写，并不会让配置引用的 PyTorch module 也变成不可变对象。

完整参考

以下为该类别的生成签名。可用本页符号索引跳转；源码链接指向各惰性导出背后的具体实现。

9 个公开符号

`CheckpointConfig`

cls

class CheckpointConfig(load_path: str = '',load_from_object_store: ObjectStoreConfig = attrs.field(factory=ObjectStoreConfig),strict_resume: bool = True,dcp_allow_mismatched_size: bool = False,load_ema_to_reg: bool = False)

worldfoundry.core.configuration.CheckpointConfigfrom worldfoundry.core.configuration import CheckpointConfig

源码

简介

CheckpointConfig — Checkpoint source and strictness controls for inference construction. 属于 Core 配置（LazyConfig / 延迟对象图）。

属性

load_pathstr: 默认值: ''
load_from_object_storeObjectStoreConfig: 默认值: attrs.field(factory=ObjectStoreConfig)
strict_resumebool: 默认值: True
dcp_allow_mismatched_sizebool: 默认值: False
load_ema_to_regbool: 默认值: False

`Config`

cls

class Config(model: LazyDict | None,job: JobConfig = attrs.field(factory=JobConfig),trainer: InferenceRuntimeConfig = attrs.field(factory=InferenceRuntimeConfig),model_parallel: _ModelParallelConfig = attrs.field(factory=_ModelParallelConfig),checkpoint: CheckpointConfig = attrs.field(factory=CheckpointConfig))

worldfoundry.core.configuration.Configfrom worldfoundry.core.configuration import Config

源码

简介

Config — Fields used to compose and instantiate a released inference model. 属于 Core 配置（LazyConfig / 延迟对象图）。

属性

modelLazyDict | None
jobJobConfig: 默认值: attrs.field(factory=JobConfig)
trainerInferenceRuntimeConfig: 默认值: attrs.field(factory=InferenceRuntimeConfig)
model_parallel_ModelParallelConfig: 默认值: attrs.field(factory=_ModelParallelConfig)
checkpointCheckpointConfig: 默认值: attrs.field(factory=CheckpointConfig)

方法

methto_dict() -> dict[str, Any]源码

简介

该类型上的公开 method。

返回值: dict[str, Any]

methvalidate() -> None源码

简介

validate — Validate the small set of fields needed during inference.

返回值: None

`EMAConfig`

cls

class EMAConfig(enabled: bool = False,rate: float = 0.1,iteration_shift: int = 0)

worldfoundry.core.configuration.EMAConfigfrom worldfoundry.core.configuration import EMAConfig

源码

简介

EMAConfig — Exponential moving-average settings used while loading inference models. 属于 Core 配置（LazyConfig / 延迟对象图）。

属性

enabledbool: 默认值: False
ratefloat: 默认值: 0.1
iteration_shiftint: 默认值: 0

`instantiate`

func

def instantiate(cfg,*args,**kwargs)

worldfoundry.core.configuration.instantiatefrom worldfoundry.core.configuration import instantiate

源码

简介

把 LazyConfig / LazyCall 对象图实例化为具体 Python 对象。

参数

cfg: a dict-like object with "_target_" that defines the caller, and other keys that define the arguments
args: Optional positional parameters pass-through.
kwargs: Optional named parameters pass-through.

`LazyCall`

cls

class LazyCall(target)

worldfoundry.core.configuration.LazyCallfrom worldfoundry.core.configuration import LazyCall

源码

简介

LazyConfig 图中的延迟构造调用，对象只在 instantiate 时真正创建。

源码 docstring

Wrap a callable so that when it's called, the call will not be executed, but returns a dict that describes the call.

LazyCall object has to be called with only keyword arguments. Positional arguments are not yet supported.

Example:: from worldfoundry.core.configuration import LazyCall, instantiate

layer_cfg = LazyCall(nn.Conv2d)(in_channels=32, out_channels=32) layer_cfg.out_channels = 64 # can edit it afterwards layer = instantiate(layer_cfg)

参数

target: Callable to instantiate later, its importable string name, or an existing target mapping.

方法

meth__call__(**kwargs)源码

简介

__call__ — Return an editable config instead of invoking the target.

参数

kwargs: Named constructor arguments. Target defaults are copied first, then explicit values override them.

说明

Positional arguments are intentionally unsupported at this stage; they can be supplied later to `instantiate` when necessary.

`LazyConfig`

cls

class LazyConfig()

worldfoundry.core.configuration.LazyConfigfrom worldfoundry.core.configuration import LazyConfig

源码

简介

LazyConfig — Load local Python/YAML lazy configs and save resolved inference configs. 属于 Core 配置（LazyConfig / 延迟对象图）。

方法

smethload_rel(filename: str, keys: str | tuple[str, ] | None = None)源码

简介

该类型上的公开 staticmethod。

参数

filenamestr
keysstr | tuple[str, ...] | None: 默认值: None

smethload(filename: str, keys: str | tuple[str, ] | None = None)源码

简介

该类型上的公开 staticmethod。

参数

filenamestr
keysstr | tuple[str, ...] | None: 默认值: None

smethsave_yaml(config: Any, filename: str | Path) -> str源码

简介

该类型上的公开 staticmethod。

参数

configAny
filenamestr | Path

返回值: str

`LazyDict`

cls

class LazyDict(args, **kwargs)

worldfoundry.core.configuration.LazyDictfrom worldfoundry.core.configuration import LazyDict

源码

简介

LazyDict — Marker subclass for editable, lazily instantiated object graphs. 属于 Core 配置（LazyConfig / 延迟对象图）。

源码 docstring

Marker subclass for editable, lazily instantiated object graphs.

It behaves like OmegaConf `DictConfig but lets WorldFoundry distinguish a deferred constructor tree from an ordinary runtime mapping. Construct it through LazyCall` in normal code.

参数

args
kwargs

`make_freezable`

func

def make_freezable(cls: T) -> T

worldfoundry.core.configuration.make_freezablefrom worldfoundry.core.configuration import make_freezable

源码

简介

make_freezable — Add a recursive runtime `freeze operation to an attrs class. 属于 Core 配置（LazyConfig / 延迟对象图）。标注返回类型：T`。

参数

clsT

返回值: T

`ObjectStoreConfig`

cls

class ObjectStoreConfig(enabled: bool = False,credentials: str = '',bucket: str = '')

worldfoundry.core.configuration.ObjectStoreConfigfrom worldfoundry.core.configuration import ObjectStoreConfig

源码

简介

ObjectStoreConfig — Object-store location used to read inference checkpoints. 属于 Core 配置（LazyConfig / 延迟对象图）。

属性

enabledbool: 默认值: False
credentialsstr: 默认值: ''
bucketstr: 默认值: ''