SuperAPI AI 工具集

large-class-style

编程与开发

查看项目

更新于 10-16 06:56

技能介绍

该技能为 SGLang 项目的三个大型类定义代码风格约定:Scheduler(python/sglang/srt/managers/scheduler.py)、TokenizerManager(python/sglang/srt/managers/tokenizer_manager.py)、ModelRunner(python/sglang/srt/model_executor/model_runner.py)。

一、冻结代码

部分核心文件被冻结,仅作编排:作为薄组合根,构造协作者、接线、委托调用并协调调用顺序,必须保持这种形态。领域逻辑不属于冻结文件,应放在独立模块的协作者类中。

原因:文件是协作者类之上的薄编排器,冻结可防止其重新膨胀为上帝类;将领域逻辑保留在协作者(各自文件)中,才能实现按文件代码归属、单一职责与单元测试;编排器是组合根,可以了解每个协作者,因为接线与排序是其职责,协调留在此处,领域逻辑不留。

冻结文件:python/sglang/srt/model_executor/model_runner.py。

允许的编排:每条语句都引用协作者,且属于以下之一——构造(简短的 init_<thing> helper,主体基本是单次构造,遵循第 2 节;条件构造用 maybe_init_<thing> 加一行门控)、接线(在 init 中运行 helper 的简短调用)、委托(在必要调用点调用协作者方法,如 self.foo.run(...))、协调(选择或排序上述内容的最小控制流:决定是否/哪个协作者接线或调用的 if、调用顺序、将一次调用结果传入下一次)。启发式:语句仅当构造、接线、委托或选择/排序这些时才允许,绝不允许计算或转换超出传递参数与结果的值。

不允许的领域逻辑:配置构建、数据转换、算法主体、数学、后处理——任何计算而非协调的分支或循环,应放在协作者中。修复方式:将该主体移入 FooManager(其 init 或工厂)加一个 (maybe_)init_foo helper。

协调逻辑去向:默认提取,将内聚的协调拉入低耦合协作者(初始化器、前向流水线)并委托;残留可保留,但仅限上述最小协调形式,保持伪代码可读,这是显式例外而非回退,需注明保留原因;当残留超出伪代码规模,即应提取专用协调器,而非继续内联。

传递协作者所需而非上帝对象:提取领域逻辑到协作者(工厂、初始化器、流水线)时,给它具体所需值——model_config、device、尺寸——而非整个冻结对象(ModelRunner、Scheduler)。传回上帝对象会重建拆分本要消除的耦合:模块仍读取其数十个属性,无法在不构建整个类的情况下单元测试,字段重命名会波及回来。默认使用窄关键字参数,参考形态:layer_setup.resolve_layer_indices(*, model, model_config, is_draft_worker, spec_algorithm)。返回小型冻结结构体,让编排器赋值到自身字段;协作者不应回写并修改上帝对象。若叶子确实需要活对象——其构造函数契约已接收 runner,或读取 init 后变化的状态——将该依赖限制在最小叶子,并在其上层全部传递窄参数,注明无法收窄的原因。

若确实传递上帝对象,保持只读:真正接收活对象的被调用方应读取其字段并返回结果,仅当确实无其他方式时才写回字段;编排器拥有对自身字段的赋值。原因:修改上帝对象的被调用方将其写入分散到其他模块,无法再通过阅读 model_runner.py 看出 ModelRunner 拥有什么,隐藏写入与编排器自身顺序竞争,被调用方静默依赖在恰好正确时机被调用。

二、init 风格

适用于修改上述三个类的 init 时。原因:下游 fork 会覆写某一部分(tokenizer、KV cache、IPC 等),内联逻辑迫使它们复制整个 init,会随上游腐化;拆分为 init_* helper 可让它们精确覆写所需部分。参考形态:python/sglang/srt/managers/tokenizer_manager.py 中的 TokenizerManager.init。

规则:init 是编排器,由一系列 self.init_(...) 调用加最小粘合组成,不内联非平凡构造;每个可覆写单元一个 helper,每个 init_ 对应子类可能替换的一个关注点,不要混在一起;命名 init_<thing>(snake_case,命名组件),条件构造用 maybe_init_<thing>,门控放在 helper 内;无静默状态耦合,helper 只读取先前 helper 设置的 self.,顺序放在 init 中,共享中间值作为参数传递而非通过 self.;新逻辑即新 helper,默认添加 init_<thing> 而非另一个内联块,一行 self.foo = server_args.foo 可以,结构化逻辑不行;保留覆写点,优先对现有 init_* 签名做增量修改,破坏性变更需在 PR 中说明。

范围:仅上述三个类,不包括其他 manager 风格类,也不包括小型 dataclass/工具构造函数。