MMEngine Runner 与 XTuner 边界

XTuner 跑在 MMEngine 上。MMEngine 是 OpenMMLab 生态的"PyTorch Lightning 版"，提供 Runner / Hook / Registry 等抽象。本章把这些过一遍，让你看懂 XTuner config 在写什么。

4.1整体调用栈

4.2Registry：用字符串注册类

MMEngine 的核心机制是 Registry——把类按名字注册到一个全局表，配置里用 dict 指定 type：

# 注册（XTuner 内部）
from mmengine.registry import MODELS

@MODELS.register_module()
class SupervisedFinetune(nn.Module):
    def __init__(self, llm, lora=None, ...):
        ...

# 使用（config 里）
model = dict(
    type=SupervisedFinetune,        # 直接用类
    # 或：type="SupervisedFinetune"，字符串也行
    llm=dict(type=AutoModelForCausalLM.from_pretrained, ...),
    lora=dict(type=LoraConfig, r=64),
)

这种"dict 配置 + Registry 解析"是 OpenMMLab 全家桶共用的范式。

4.3Runner：训练循环包装

Runner 是 MMEngine 顶层：你给它 model / dataloader / optim / scheduler / hooks，它跑完整训练循环。

from mmengine.runner import Runner

runner = Runner(
    model=model,
    train_dataloader=train_dl,
    optim_wrapper=optim_cfg,
    param_scheduler=scheduler_cfg,
    train_cfg=dict(by_epoch=True, max_epochs=3),
    default_hooks=dict(
        timer=dict(type=IterTimerHook),
        logger=dict(type=LoggerHook, interval=10),
        param_scheduler=dict(type=ParamSchedulerHook),
        checkpoint=dict(type=CheckpointHook, interval=1),
    ),
    custom_hooks=[
        dict(type=EvaluateChatHook, ...),    # XTuner 自家 Hook
    ],
)
runner.train()

所有这些 dict 都来自 XTuner config，由 Runner 解析成实际对象。

4.4Hook：定时插入逻辑

Hook = "训练某阶段执行的回调"。MMEngine 自带 7 个默认 hook：

XTuner 自定义 hook：

• EvaluateChatHook：训练中定期跑几个 prompt 看输出；
• VarlenAttnArgsToMessageHubHook：传递 packing 参数；
• DatasetInfoHook：打印数据集信息。

4.5XTuner 与 MMEngine 的边界

4.6这种设计的优劣

4.7这章你需要带走的

• XTuner 跑在 MMEngine 上，配置是 Python 文件 + Registry；
• 核心抽象：Runner（顶层）+ Hook（插件）+ Registry（注册表）；
• 用 dict + type=Class 的方式写配置；
• XTuner 主要贡献：SFT/DPO/VL model wrapper + 数据 preprocessor + chat template。

4.8 CLI entry_point.py：13 个子命令

xtuner 命令的 dispatcher 在 xtuner/entry_point.py:12-253，cli() 函数（line 276-338）按 MODES 元组路由：

cli() 多卡逻辑：检测 NNODES / NPROC_PER_NODE 环境变量，决定用 torchrun 还是直接 subprocess.run；端口未指定时随机 20000-29999。

4.9 model wrapper 源码定位