Part 1 — hyper_parallel/protocols/ 协议层

整个工程的基石。完成后整套抽象类可独立 import、独立单测，但不接入任何已有路径。纯新增、零侵入。

1. 目标

实现 torchtitan 的 Configurable / Module / BaseModel / ShardingConfig / MeshAxisName / ModelSpec 一整套协议，作为后续 M2–M9 共同的基础抽象层。

2. 任务边界（新增文件）

新增包目录 hyper_parallel/protocols/：

3. 核心设计点

3.1 Configurable.__init_subclass__

class Configurable:
    Config: type["Configurable.Config"]

    @dataclass(kw_only=True, slots=True)
    class Config:
        _owner: ClassVar[type["Configurable"]] = None

        def build(self, **runtime_kwargs) -> "Configurable":
            return self._owner(self, **runtime_kwargs)

    def __init_subclass__(cls, **kw):
        super().__init_subclass__(**kw)
        if "Config" in cls.__dict__:
            cls.Config._owner = cls

3.2 Module.parallelize(tp_mesh) 流程

def parallelize(self, tp_mesh):
    sc = self.sharding_config
    if sc is None:
        # 递归 children
        for child in self.children():
            if isinstance(child, Module):
                child.parallelize(tp_mesh)
        return

    if sc.local_map is not None:
        raise NotImplementedError("local_map will be added in M9")

    # 1. 分布参数 / buffer
    for path, named_p in sc.state_shardings.items():
        param = _get_attr_by_path(self, path)
        placements = resolve_placements(named_p, tp_mesh.mesh_dim_names)
        new_local = distribute_tensor(param.data, tp_mesh, placements)
        _set_param_by_path(self, path, platform.Parameter(new_local))

    # 2. 包 forward 做 in/out reshard
    self._wrap_forward_with_reshard(tp_mesh)

    # 3. 递归子模块
    for child in self.children():
        if isinstance(child, Module):
            child.parallelize(tp_mesh)

注意 distribute_tensor 来自 hyper_parallel.core.dtensor.dtensor:409，签名 (tensor, device_mesh, placements)，与 torch 版兼容。

3.3 resolve_placements

def resolve_placements(
    named: NamedPlacement,                    # dict[MeshAxisName, Placement]
    mesh_axis_names: tuple[str, ...],         # 实际 mesh 的维度名
) -> list[Placement]:
    out = []
    for axis_name in mesh_axis_names:
        if axis_name in named:
            out.append(named[axis_name])
        else:
            out.append(Replicate())            # 未声明的轴默认 Replicate
    # 缺主轴报错
    declared = set(named.keys())
    extra = declared - set(mesh_axis_names)
    if extra:
        raise ValueError(f"NamedPlacement has axes not in mesh: {extra}")
    return out

4. 与 torchtitan 接口差异说明

5. 开发步骤

1. Step 1（0.5 d）：建包 + types.py + __init__.py。
2. Step 2（1 d）：configurable.py。
   • __init_subclass__ 自动绑 owner。
   • Config.build() 调 cls(self, **runtime_kwargs)。
   • Configurable.Config.replace(**kw) 用 dataclasses.replace 实现。
3. Step 3（0.5 d）：sharding.py。resolve_placements 是核心。
4. Step 4（1 d）：module.py 的 Module 基类 + ModuleList / ModuleDict / Sequential。
5. Step 5（0.5 d）：model.py 的 BaseModel。update_from_config 默认空实现，由子类重写。
6. Step 6（0.5 d）：state_dict_adapter.py + model_spec.py。

6. 验证标准

新建 tests/torch/ut/protocols/：

通过门槛：

• 5 个 UT 全绿。
• import hyper_parallel.protocols 不引入循环依赖。
• 现存 tests/torch/st/qwen3_5/ 等存量测试 0 受影响。
• hyper_parallel/__init__.py 不暴露新符号。

7. 工期 & 依赖