应使用 omegaconf.structured() 包装带 @dataclass 装饰、字段全有类型注解、默认值用 field(default_factory=...) 的类；yaml 合并需先转原生结构再重建或启用严格模式；必填字段不可用 missing，须显式赋默认值；传入 lightningmodule 前需 to_container(resolve=true, throw_on_missing=true)。
OmegaConf 里怎么定义带类型提示的配置类
直接用 DictConfig 或 ListConfig 手动拼结构，后期维护和 IDE 支持会越来越糟。正确做法是用 OmegaConf.structured() 包装一个数据类（dataclass），类型信息就能透传到配置实例里。
常见错误是把普通字典传给 structured()，它会静默失败——只接受带 @dataclass 装饰的类或已注册的类型。另外，字段默认值必须是不可变对象（比如用 field(default_factory=list) 而不是 default=[]）。
-
@dataclass类中所有字段都需有类型注解，否则OmegaConf不识别为结构化字段 - 嵌套结构要逐层用
@dataclass，不能只在顶层用 - 如果字段可选，用
Optional[Type]+field(default=None)，别用None作默认值（会触发类型校验失败）
@dataclass
class ModelConfig:
name: str = "resnet50"
num_classes: int = 1000
@dataclass
class TrainConfig:
lr: float = 1e-3
model: ModelConfig = field(default_factory=ModelConfig)
cfg = OmegaConf.structured(TrainConfig)
加载 YAML 后怎么安全地合并进结构化配置
直接 OmegaConf.merge(cfg, loaded_yaml) 很危险：如果 loaded_yaml 里有新字段，OmegaConf 默认允许，但结构化配置本意是“封闭 schema”。结果就是运行时才发现字段没类型、IDE 不提示、序列化出错。
真正安全的做法是先用 OmegaConf.to_container() 把 YAML 转成原生 Python 结构，再用 OmegaConf.structured() 重建一次；或者更稳妥地，用 OmegaConf.create(loaded_yaml) 加上 OmegaConf.merge(structured_cfg, loaded_cfg)，并启用严格模式。
立即学习“Python免费学习笔记（深入）”；
- 合并前确保
loaded_yaml不含结构化配置不支持的类型（如datetime、自定义对象） - 避免用
cfg.xxx = yyy动态赋值新增字段，这会绕过类型检查 - 调试时用
OmegaConf.is_missing(cfg, "field")判断字段是否存在，而不是hasattr或in操作符
为什么 cfg.model.name 有时返回 MISSING 而不是报错
这是 OmegaConf 的“懒校验”机制在起作用：字段声明为 name: str = MISSING 时，访问它不会立刻崩溃，而是返回 MISSING 对象。表面看是容错，实则是埋雷——后续传给函数可能触发 TypeError，堆栈还指向下游代码，不是配置层。
根本原因常是：YAML 文件漏写了该字段，或字段名拼写错误（比如写成 modle），而结构化配置又没设默认值。更隐蔽的是，父类继承了字段但子类没显式覆盖，导致初始化时未注入值。
- 所有必填字段必须显式赋默认值，哪怕只是空字符串或 0，别依赖
MISSING - 用
OmegaConf.resolve(cfg)强制展开插值（如${train.lr}），否则MISSING可能被掩盖在引用链里 - CI 中加一行
OmegaConf.to_object(cfg)测试，它会在缺失字段时立即抛ValidationError
在 PyTorch Lightning 中怎么把 OmegaConf 配置传进 LightningModule
直接把 cfg 当参数传进去没问题，但容易踩两个坑：一是没冻结配置，训练中途意外修改了 cfg.optimizer.lr；二是把整个 cfg 存成 self.hparams，导致 checkpoint 体积暴增（DictConfig 序列化后比原生 dict 大 3–5 倍）。
Lightning 官方推荐路径是调用 self.save_hyperparameters(hparams)，但注意它只接受原始 Python 类型。所以得先用 OmegaConf.to_container(cfg, resolve=True) 转一下，且设 throw_on_missing=True 避免漏掉 MISSING 字段。
- 别在
__init__里对cfg做深层 copy（如copy.deepcopy(cfg)），OmegaConf自带深拷贝语义，用OmegaConf.copy(cfg) - 如果要用插值（如
${model.name}），务必在传入 Lightning 前调用OmegaConf.resolve(cfg)，否则插值留在 checkpoint 里会失效 - 调试时打印
type(cfg.model)，如果是DictConfig说明没走结构化流程，类型提示和 IDE 补全就全丢了
结构化配置真正的复杂点不在定义，而在边界——YAML 和代码之间的映射是否全程受控。最容易被忽略的是 resolve 和 to_container 的调用时机，差一行，就从强类型退化成弱字典。
