2026/9/10 3:11:07
FEATURED · 精选文章 
SGLang 大型类代码风格规范Scheduler / TokenizerManager / ModelRunner 的 Frozen-Code 与__init__编排约定【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang本指南以 SGLang 仓库内.claude/skills/large-class-style/SKILL.md技能文档为骨架系统讲解 SGLang 三个大型核心类——Scheduler、TokenizerManager、ModelRunner——的代码组织约定model_runner.py的 frozen-code仅编排、不含领域逻辑约束以及三个类__init__的init_*编排风格。读完本文你将掌握 SGLang 核心运行时文件的演进红线能够判断一段新增逻辑该放在编排者orchestrator还是协作类collaborator中并为下游 fork 的定点覆写tokenizer、KV cache、IPC 等提供正确的扩写姿势。适用范围SGLang 的三棵“巨树”该代码风格约定只针对 SGLang 中三个体量最大、被下游 fork 覆写最多的类全部位于python/sglang/srt下类文件Schedulerpython/sglang/srt/managers/scheduler.pyTokenizerManagerpython/sglang/srt/managers/tokenizer_manager.pyModelRunnerpython/sglang/srt/model_executor/model_runner.py这不是对 SGLang 全部代码的要求其他 manager 风格类、小的 dataclass / 工具构造函数不受本节约束见原文档 §2.3 Scope。约定的核心目标是防止这三个文件重新长成上帝类god class并让每个子模块保持单一职责、可独立单元测试。从源码结构看SGLang 已经把大量领域逻辑从这三个文件抽离到了独立的协作类模块中例如ModelRunner的领域逻辑集中在python/sglang/srt/model_executor/model_runner_components/目录下attention_backend_setup.py、cuda_graph_setup.py、kv_pool_runtime.py、layer_setup.py、load_model_utils.py、moe_ep_setup.py、weight_exporter.py、weight_updater.py 等 14 个模块Scheduler的协作类则分布在python/sglang/srt/managers/scheduler_components/等目录。本约定正是这套拆分结构的宪法。1. Frozen Codemodel_runner.py只做编排1.1 什么是 frozen codepython/sglang/srt/model_executor/model_runner.py是 SGLang 中被标记为frozen的核心文件它必须是orchestration-only——一个薄的组合根composition root负责构造协作类、把它们接线wire、把调用委托delegate出去、并协调coordinate调用顺序。它必须一直保持这样。原文档明确给出了原因链该文件本质是对协作类的一层薄编排冻结它是为了防止它重新膨胀成上帝类领域逻辑放在协作类自己的文件里才能实现按文件划分代码所有权、单一职责与单元测试编排者是组合根它可以认识每一个协作类因为接线和排序本来就是它的职责。协调coordination留在这里领域逻辑domain logic不在这里。1.2 被冻结的文件python/sglang/srt/model_executor/model_runner.py注意被明确冻结的文件目前只有model_runner.py一个原文档 §1.2。Scheduler与TokenizerManager遵循的是__init__编排风格第 2 节而非 frozen 约束。1.3 允许出现在冻结文件中的语句四类编排动作原文档规定冻结文件中的每一条语句都必须指向某个协作类并且属于以下四类之一Construct构造——一个短的init_thing辅助方法其函数体本质上是单次构造遵循 §2 的命名与形态条件构造时使用maybe_init_thing并在方法内写一行 gate 判断Wire接线——在编排点例如__init__调用上面的辅助方法Delegate委托——在必要的调用点调用协作类的方法self.foo.run(...)Coordinate协调——选择或排序上述动作的最小控制流一个if决定接哪个协作类、调用哪个决定调用顺序把一个调用的结果串给下一个调用。启发式判断标准一条语句只有当它构造、接线、委托、或选择/排序这些动作时才被允许——永远不允许计算或转换一个值除了透传参数和结果。原文档给出的正例骨架frozen 文件中允许的形态# model_runner.py — orchestration only. def init_foo(self): # construct self.foo FooManager(server_argsself.server_args, deviceself.device) self.init_foo() # wire (in __init__) if self.server_args.enable_bar: # coordinate: select self.bar.prepare(forward_batch) # delegate out self.foo.run(forward_batch) # delegate self.baz.consume(out) # coordinate: thread result into next delegate这条约定在真实源码中大量可见。例如ModelRunner.__init__中构造与接线被拆成清晰的一次一个init_*调用__init__主体只负责排序与最小粘合见 model_runner.pyself.init_startup_observability() self.init_remote_instance_weight_transporter() self.init_msprobe() # auxiliary hidden capture mode. TODO: expose this to server args? self.init_spec_aux_hidden_state() ... # Initialize MooncakeTransferEngine BEFORE init_torch_distributed so # that the shared TE can be passed to the Mooncake PG backend self.init_shared_mooncake_transfer_engine() # Get available memory before model loading. self.init_torch_distributed() ... self.init_mindspore_runner()对应的辅助方法都保持单次构造的薄形态例如def init_msprobe(self): self.msprobe_debugger misc_utils.create_msprobe_debugger() def init_weight_updater(self): self.weight_updater WeightUpdater( tp_rankself.ps.tp_rank, deviceself.device, gpu_idself.gpu_id, model_configself.model_config, custom_weight_loadersget_model().custom_weight_loader, get_modellambda: self.model, update_model_fieldsself.update_model_fields, recapture_cuda_graphself.init_decode_cuda_graph, get_model_runnerlambda: self, )见 model_runner.py。类似的init_weight_exporter、init_remote_instance_weight_transporter、init_ngram_embedding_manager等全部保持同一形态——方法体即一次构造把领域细节下沉到被构造的类里。1.4 不允许出现在冻结文件中的语句领域逻辑原文档明确列出禁区配置构建、数据转换、算法主体、数学计算、后处理——任何计算而非协调的分支或循环。# NOT allowed in a frozen file: domain logic inlined. self.foo None if self.server_args.enable_foo: config build_foo_config(self.model_config, self.device) # config logic in frozen file self.foo FooManager(config) # inline construction, not via (maybe_)init_foo out [step(x) for x in batch] # computation, not coordination修复方法把上面的函数体移进FooManager放到它的__init__或工厂方法里并配套一个(maybe_)init_foo辅助方法。从源码看这条规则正是model_runner_components/目录存在的理由build_load_config、compute_attention_and_moe_layers、resolve_sliding_window_size、maybe_downgrade_dtype_for_legacy_gpu等函数全部位于 load_model_utils.py 与 layer_setup.py 等协作模块中model_runner.py只是 import 并委托它们。1.5 协调逻辑该放哪里原文档给出两级策略默认抽离extract。把内聚的协调逻辑抽成低耦合的协作类一个初始化器、一个前向管线然后委托给它残留保留residue stays。无法内聚抽取的协调逻辑可以留在编排者里——但只允许上文最简Coordinate形态且要保持伪代码可读pseudocode-readable。这是显式例外而非兜底需要注明它为什么留下来。关键信号当残留逻辑膨胀到超过伪代码的规模时说明该抽取一个专门的协调者dedicated coordinator了而不是继续内联。这条规则在Scheduler中体现为大量init_*与显式排序注释。例如Scheduler.__init__中通过self.init_ipc_channels(port_args)、self.init_tokenizer()、self.init_model_config()、self.init_metrics_collector(...)、self.init_request_dispatcher()等见 scheduler.py 附近各辅助方法内部保留最小 gate 逻辑例如def maybe_init_hccl_dp_prewarm(self) - None: if not ( _is_npu and is_deepseek_v4(self.tp_worker.model_runner.model_config.hf_config) ): return ...见 scheduler.py——maybe_前缀 方法内部一行 gate 的形态与约定完全吻合。1.6 传协作类需要的东西不要传上帝对象抽离领域逻辑到协作类工厂、初始化器、管线时原文档要求只给它需要的具体值——model_config、device、尺寸——而不是整个冻结对象ModelRunner、Scheduler。原因把上帝对象传回去等于重新制造拆分之前试图消除的耦合——模块仍然要读它几十个属性、不构建整个类就无法单元测试、任何字段重命名都会反向传播到这个模块。具体默认约定默认使用窄的关键字参数narrow, keyword args。原文档给出的参照形态正是仓库中的真实签名layer_setup.resolve_layer_indices(*, model, model_config, is_draft_worker, spec_algorithm)该函数真实存在于 layer_setup.py返回一个小的ModelLayerInfo冻结结构体正是窄参数 返回小结构体的标准范例。返回小的冻结结构体frozen struct由编排者把结果赋到自己的字段上协作类不应回头改写上帝对象。如果某个叶子节点确实需要存活对象——它的构造函数契约本来就接收 runner或者它要读取 init 之后会变化的状态——就把这个依赖限制在最小的叶子上其上所有层都传窄参数并注明为什么无法进一步收窄。1.7 如果确实要传上帝对象保持只读对于真正需要活对象的被调用方原文档要求读取字段并返回结果只有在确实没有其他办法时才写回字段。字段赋值由编排者拥有。# Good — callee reads the runner and returns a small frozen struct; the orchestrator # owns the writes. # model_runner.py class ModelRunner: def bar(self): self.foo_result foo(self) # another_file.py def foo(model_runner) - FooResult: return FooResult(axx, byy, czz) # Avoid — callee reaches back in and writes the runners fields. # model_runner.py class ModelRunner: def bar(self): foo(self) # another_file.py def foo(model_runner): model_runner.a xx model_runner.b yy model_runner.c zz为什么禁止反向写回原文档的论证一个会改写上帝对象的被调用方会把它的写操作散布到其他模块——你只读model_runner.py再也无法看清ModelRunner到底拥有哪些字段隐藏的写操作会与编排者自身的顺序竞争hidden writes race with the orchestrators own ordering被调用方会静默地依赖自己在恰好正确的时机被调用。源码中一个符合读 runner、返回结果的例子是WeightChecker(get_modellambda: self.model, psself.ps)它通过 lambda 拿到模型引用而并非改写 runner 字段见 model_runner.py。2.__init__编排风格可覆写单元化本节约定适用于上述三个类Scheduler、TokenizerManager、ModelRunner的__init__修改。2.1 为什么需要这套风格下游 fork 会覆写其中一个部件tokenizer、KV cache、IPC……如果逻辑内联fork 只能整体复制__init__而复制件会随上游演进逐渐腐烂rots against upstream拆成init_*辅助方法后fork 只需覆写它真正需要的那个。原文档指定的参照形态正是TokenizerManager.__init__python/sglang/srt/managers/tokenizer_manager.py。2.2 六条规则__init__是编排者。它是一串self.init_*(...)调用加上最少的粘合代码不内联任何非平凡构造一个可覆写单元对应一个辅助方法。每个init_*只封装子类可能替换的一个关注点不要混装Dont lump命名init_thingsnake_case命名组件本身条件构造用maybe_init_thinggate 放在辅助方法内部无隐式状态耦合辅助方法只读取更早的辅助方法设置的self.*顺序由__init__掌控共享的中间结果用参数传递而不是通过self.*传递新逻辑 新辅助方法默认新增init_thing而不是再堆一个内联块。一行self.foo server_args.foo没问题结构化逻辑不行保留覆写点优先对既有init_*的签名做**增量式additive**修改破坏性变更要在 PR 中显式声明。2.3 真实源码对照TokenizerManager与SchedulerTokenizerManager的__init__编排序列与辅助方法见 tokenizer_manager.pyinit_model_config # L473 init_tokenizer_and_processor # L490 init_ipc_channels # L558 init_running_status # L590 init_request_logging_and_dumping # L608 init_weight_update # L635 init_lora # L652 init_disaggregation # L671 init_metric_collector_watchdog # L705 init_request_dispatcher # L753Scheduler的辅助方法更密集见 scheduler.py覆盖启动计时、模型配置、指标收集、IPC、空闲休眠、tokenizer、Mamba 后端、MoE GEMM 配置、TP 模型 worker、draft worker、内存池、attention 后端、CUDA graph、模型 worker、hisparse 协调器、运行状态、chunked prefill、动态 chunk 尺寸、调度策略、软看门狗、disaggregation、overlap、n-gram embedding、确定性推理、请求分发、profiler、权重更新、LoRA drainer/loader、grammar manager、请求接收、DP-Attention 适配器、池统计观察者、不变量检查器、rank 一致性检查器、KV 事件发布者、负载发布/询问者、输出流、beam 协调器、批结果处理器等。ModelRunner同样全面遵循见 model_runner.pyinit_startup_observability、init_msprobe、init_weight_updater、init_spec_aux_hidden_state、init_weight_exporter、init_remote_instance_weight_transporter、init_ngram_embedding_manager、init_kv_cache_configurator、init_mindspore_runner、init_memory_saver_adapter、maybe_init_remote_instance_transfer_engine、maybe_init_expert_location_metadata、maybe_init_lplb_solvers、maybe_init_eplb_manager、maybe_init_elastic_ep、init_token_oracle、maybe_init_expert_backup_client、maybe_init_lora_manager、init_kv_index_translator、maybe_init_hisparse_coordinator、init_attention_backends、init_cuda_graphs、init_routed_experts_capturer、init_indexer_capturer、init_torch_distributed、init_shared_mooncake_transfer_engine、maybe_init_dwdp、init_lora_manager、init_decode_cuda_graph、init_prefill_cuda_graph、init_threads_binding等。注意其中init_decode_cuda_graph/init_prefill_cuda_graph与recapture_cuda_graphself.init_decode_cuda_graph的用法见 model_runner.py辅助方法本身可以成为下游协作类的回调参数这是保留覆写点的延伸——fork 覆写了init_decode_cuda_graphWeightUpdater拿到的重捕获回调也随之替换。2.4 范围限制只约束上面列出的三个类不适用于其他 manager 风格类也不适用于小型 dataclass / 工具类构造函数。3. 一套可用于 Code Review 的检查清单综合原文档约定在为这三个类做代码评审或动手修改时可以对照以下问题这条逻辑是协调还是计算如果是配置构建、数据变换、算法主体、数学计算、后处理——它应该进入协作类而不是model_runner.pyfrozen 文件新功能是否拆成了独立的init_thing结构化逻辑不允许以内联块形式进入__init__一行简单赋值self.foo server_args.foo除外条件构造是否用了maybe_init_thinggate 应放在辅助方法内部而不是在__init__里展开if内联构造协作类拿到的是窄参数还是上帝对象默认传model_config、device等具体值参照resolve_layer_indices(*, model, model_config, is_draft_worker, spec_algorithm)形态上帝对象是否只读被调用方读取字段并返回冻结结构体写回由编排者完成确有例外要注明原因覆写点是否被保留对既有init_*签名做增量修改破坏性变更必须在 PR 中声明顺序是否清晰辅助方法只读更早设置好的self.*共享中间结果走参数传递顺序编排留在__init__。4. 关键文件索引技能文档原文.claude/skills/large-class-style/SKILL.md冻结文件orchestration-onlypython/sglang/srt/model_executor/model_runner.py__init__编排参照形态python/sglang/srt/managers/tokenizer_manager.py大型编排类python/sglang/srt/managers/scheduler.pyModelRunner协作类目录python/sglang/srt/model_executor/model_runner_components/窄参数 冻结结构体返回范例layer_setup.pyScheduler协作类目录python/sglang/srt/managers/scheduler_components/本文所有结论均以当前仓库为准frozen 文件目前仅model_runner.py一个Scheduler与TokenizerManager适用__init__编排风格§2而不受 frozen 约束。若后续版本调整文件边界请以仓库最新代码为准。【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
SGLang 大型类代码风格规范：Scheduler / TokenizerManager / ModelRunner 的 Frozen-Code 与 `__init__` 编排约定
SGLang 大型类代码风格规范Scheduler / TokenizerManager / ModelRunner 的 Frozen-Code 与__init__编排约定【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang本指南以 SGLang 仓库内.claude/skills/large-class-style/SKILL.md技能文档为骨架系统讲解 SGLang 三个大型核心类——Scheduler、TokenizerManager、ModelRunner——的代码组织约定model_runner.py的 frozen-code仅编排、不含领域逻辑约束以及三个类__init__的init_*编排风格。读完本文你将掌握 SGLang 核心运行时文件的演进红线能够判断一段新增逻辑该放在编排者orchestrator还是协作类collaborator中并为下游 fork 的定点覆写tokenizer、KV cache、IPC 等提供正确的扩写姿势。适用范围SGLang 的三棵“巨树”该代码风格约定只针对 SGLang 中三个体量最大、被下游 fork 覆写最多的类全部位于python/sglang/srt下类文件Schedulerpython/sglang/srt/managers/scheduler.pyTokenizerManagerpython/sglang/srt/managers/tokenizer_manager.pyModelRunnerpython/sglang/srt/model_executor/model_runner.py这不是对 SGLang 全部代码的要求其他 manager 风格类、小的 dataclass / 工具构造函数不受本节约束见原文档 §2.3 Scope。约定的核心目标是防止这三个文件重新长成上帝类god class并让每个子模块保持单一职责、可独立单元测试。从源码结构看SGLang 已经把大量领域逻辑从这三个文件抽离到了独立的协作类模块中例如ModelRunner的领域逻辑集中在python/sglang/srt/model_executor/model_runner_components/目录下attention_backend_setup.py、cuda_graph_setup.py、kv_pool_runtime.py、layer_setup.py、load_model_utils.py、moe_ep_setup.py、weight_exporter.py、weight_updater.py 等 14 个模块Scheduler的协作类则分布在python/sglang/srt/managers/scheduler_components/等目录。本约定正是这套拆分结构的宪法。1. Frozen Codemodel_runner.py只做编排1.1 什么是 frozen codepython/sglang/srt/model_executor/model_runner.py是 SGLang 中被标记为frozen的核心文件它必须是orchestration-only——一个薄的组合根composition root负责构造协作类、把它们接线wire、把调用委托delegate出去、并协调coordinate调用顺序。它必须一直保持这样。原文档明确给出了原因链该文件本质是对协作类的一层薄编排冻结它是为了防止它重新膨胀成上帝类领域逻辑放在协作类自己的文件里才能实现按文件划分代码所有权、单一职责与单元测试编排者是组合根它可以认识每一个协作类因为接线和排序本来就是它的职责。协调coordination留在这里领域逻辑domain logic不在这里。1.2 被冻结的文件python/sglang/srt/model_executor/model_runner.py注意被明确冻结的文件目前只有model_runner.py一个原文档 §1.2。Scheduler与TokenizerManager遵循的是__init__编排风格第 2 节而非 frozen 约束。1.3 允许出现在冻结文件中的语句四类编排动作原文档规定冻结文件中的每一条语句都必须指向某个协作类并且属于以下四类之一Construct构造——一个短的init_thing辅助方法其函数体本质上是单次构造遵循 §2 的命名与形态条件构造时使用maybe_init_thing并在方法内写一行 gate 判断Wire接线——在编排点例如__init__调用上面的辅助方法Delegate委托——在必要的调用点调用协作类的方法self.foo.run(...)Coordinate协调——选择或排序上述动作的最小控制流一个if决定接哪个协作类、调用哪个决定调用顺序把一个调用的结果串给下一个调用。启发式判断标准一条语句只有当它构造、接线、委托、或选择/排序这些动作时才被允许——永远不允许计算或转换一个值除了透传参数和结果。原文档给出的正例骨架frozen 文件中允许的形态# model_runner.py — orchestration only. def init_foo(self): # construct self.foo FooManager(server_argsself.server_args, deviceself.device) self.init_foo() # wire (in __init__) if self.server_args.enable_bar: # coordinate: select self.bar.prepare(forward_batch) # delegate out self.foo.run(forward_batch) # delegate self.baz.consume(out) # coordinate: thread result into next delegate这条约定在真实源码中大量可见。例如ModelRunner.__init__中构造与接线被拆成清晰的一次一个init_*调用__init__主体只负责排序与最小粘合见 model_runner.pyself.init_startup_observability() self.init_remote_instance_weight_transporter() self.init_msprobe() # auxiliary hidden capture mode. TODO: expose this to server args? self.init_spec_aux_hidden_state() ... # Initialize MooncakeTransferEngine BEFORE init_torch_distributed so # that the shared TE can be passed to the Mooncake PG backend self.init_shared_mooncake_transfer_engine() # Get available memory before model loading. self.init_torch_distributed() ... self.init_mindspore_runner()对应的辅助方法都保持单次构造的薄形态例如def init_msprobe(self): self.msprobe_debugger misc_utils.create_msprobe_debugger() def init_weight_updater(self): self.weight_updater WeightUpdater( tp_rankself.ps.tp_rank, deviceself.device, gpu_idself.gpu_id, model_configself.model_config, custom_weight_loadersget_model().custom_weight_loader, get_modellambda: self.model, update_model_fieldsself.update_model_fields, recapture_cuda_graphself.init_decode_cuda_graph, get_model_runnerlambda: self, )见 model_runner.py。类似的init_weight_exporter、init_remote_instance_weight_transporter、init_ngram_embedding_manager等全部保持同一形态——方法体即一次构造把领域细节下沉到被构造的类里。1.4 不允许出现在冻结文件中的语句领域逻辑原文档明确列出禁区配置构建、数据转换、算法主体、数学计算、后处理——任何计算而非协调的分支或循环。# NOT allowed in a frozen file: domain logic inlined. self.foo None if self.server_args.enable_foo: config build_foo_config(self.model_config, self.device) # config logic in frozen file self.foo FooManager(config) # inline construction, not via (maybe_)init_foo out [step(x) for x in batch] # computation, not coordination修复方法把上面的函数体移进FooManager放到它的__init__或工厂方法里并配套一个(maybe_)init_foo辅助方法。从源码看这条规则正是model_runner_components/目录存在的理由build_load_config、compute_attention_and_moe_layers、resolve_sliding_window_size、maybe_downgrade_dtype_for_legacy_gpu等函数全部位于 load_model_utils.py 与 layer_setup.py 等协作模块中model_runner.py只是 import 并委托它们。1.5 协调逻辑该放哪里原文档给出两级策略默认抽离extract。把内聚的协调逻辑抽成低耦合的协作类一个初始化器、一个前向管线然后委托给它残留保留residue stays。无法内聚抽取的协调逻辑可以留在编排者里——但只允许上文最简Coordinate形态且要保持伪代码可读pseudocode-readable。这是显式例外而非兜底需要注明它为什么留下来。关键信号当残留逻辑膨胀到超过伪代码的规模时说明该抽取一个专门的协调者dedicated coordinator了而不是继续内联。这条规则在Scheduler中体现为大量init_*与显式排序注释。例如Scheduler.__init__中通过self.init_ipc_channels(port_args)、self.init_tokenizer()、self.init_model_config()、self.init_metrics_collector(...)、self.init_request_dispatcher()等见 scheduler.py 附近各辅助方法内部保留最小 gate 逻辑例如def maybe_init_hccl_dp_prewarm(self) - None: if not ( _is_npu and is_deepseek_v4(self.tp_worker.model_runner.model_config.hf_config) ): return ...见 scheduler.py——maybe_前缀 方法内部一行 gate 的形态与约定完全吻合。1.6 传协作类需要的东西不要传上帝对象抽离领域逻辑到协作类工厂、初始化器、管线时原文档要求只给它需要的具体值——model_config、device、尺寸——而不是整个冻结对象ModelRunner、Scheduler。原因把上帝对象传回去等于重新制造拆分之前试图消除的耦合——模块仍然要读它几十个属性、不构建整个类就无法单元测试、任何字段重命名都会反向传播到这个模块。具体默认约定默认使用窄的关键字参数narrow, keyword args。原文档给出的参照形态正是仓库中的真实签名layer_setup.resolve_layer_indices(*, model, model_config, is_draft_worker, spec_algorithm)该函数真实存在于 layer_setup.py返回一个小的ModelLayerInfo冻结结构体正是窄参数 返回小结构体的标准范例。返回小的冻结结构体frozen struct由编排者把结果赋到自己的字段上协作类不应回头改写上帝对象。如果某个叶子节点确实需要存活对象——它的构造函数契约本来就接收 runner或者它要读取 init 之后会变化的状态——就把这个依赖限制在最小的叶子上其上所有层都传窄参数并注明为什么无法进一步收窄。1.7 如果确实要传上帝对象保持只读对于真正需要活对象的被调用方原文档要求读取字段并返回结果只有在确实没有其他办法时才写回字段。字段赋值由编排者拥有。# Good — callee reads the runner and returns a small frozen struct; the orchestrator # owns the writes. # model_runner.py class ModelRunner: def bar(self): self.foo_result foo(self) # another_file.py def foo(model_runner) - FooResult: return FooResult(axx, byy, czz) # Avoid — callee reaches back in and writes the runners fields. # model_runner.py class ModelRunner: def bar(self): foo(self) # another_file.py def foo(model_runner): model_runner.a xx model_runner.b yy model_runner.c zz为什么禁止反向写回原文档的论证一个会改写上帝对象的被调用方会把它的写操作散布到其他模块——你只读model_runner.py再也无法看清ModelRunner到底拥有哪些字段隐藏的写操作会与编排者自身的顺序竞争hidden writes race with the orchestrators own ordering被调用方会静默地依赖自己在恰好正确的时机被调用。源码中一个符合读 runner、返回结果的例子是WeightChecker(get_modellambda: self.model, psself.ps)它通过 lambda 拿到模型引用而并非改写 runner 字段见 model_runner.py。2.__init__编排风格可覆写单元化本节约定适用于上述三个类Scheduler、TokenizerManager、ModelRunner的__init__修改。2.1 为什么需要这套风格下游 fork 会覆写其中一个部件tokenizer、KV cache、IPC……如果逻辑内联fork 只能整体复制__init__而复制件会随上游演进逐渐腐烂rots against upstream拆成init_*辅助方法后fork 只需覆写它真正需要的那个。原文档指定的参照形态正是TokenizerManager.__init__python/sglang/srt/managers/tokenizer_manager.py。2.2 六条规则__init__是编排者。它是一串self.init_*(...)调用加上最少的粘合代码不内联任何非平凡构造一个可覆写单元对应一个辅助方法。每个init_*只封装子类可能替换的一个关注点不要混装Dont lump命名init_thingsnake_case命名组件本身条件构造用maybe_init_thinggate 放在辅助方法内部无隐式状态耦合辅助方法只读取更早的辅助方法设置的self.*顺序由__init__掌控共享的中间结果用参数传递而不是通过self.*传递新逻辑 新辅助方法默认新增init_thing而不是再堆一个内联块。一行self.foo server_args.foo没问题结构化逻辑不行保留覆写点优先对既有init_*的签名做**增量式additive**修改破坏性变更要在 PR 中显式声明。2.3 真实源码对照TokenizerManager与SchedulerTokenizerManager的__init__编排序列与辅助方法见 tokenizer_manager.pyinit_model_config # L473 init_tokenizer_and_processor # L490 init_ipc_channels # L558 init_running_status # L590 init_request_logging_and_dumping # L608 init_weight_update # L635 init_lora # L652 init_disaggregation # L671 init_metric_collector_watchdog # L705 init_request_dispatcher # L753Scheduler的辅助方法更密集见 scheduler.py覆盖启动计时、模型配置、指标收集、IPC、空闲休眠、tokenizer、Mamba 后端、MoE GEMM 配置、TP 模型 worker、draft worker、内存池、attention 后端、CUDA graph、模型 worker、hisparse 协调器、运行状态、chunked prefill、动态 chunk 尺寸、调度策略、软看门狗、disaggregation、overlap、n-gram embedding、确定性推理、请求分发、profiler、权重更新、LoRA drainer/loader、grammar manager、请求接收、DP-Attention 适配器、池统计观察者、不变量检查器、rank 一致性检查器、KV 事件发布者、负载发布/询问者、输出流、beam 协调器、批结果处理器等。ModelRunner同样全面遵循见 model_runner.pyinit_startup_observability、init_msprobe、init_weight_updater、init_spec_aux_hidden_state、init_weight_exporter、init_remote_instance_weight_transporter、init_ngram_embedding_manager、init_kv_cache_configurator、init_mindspore_runner、init_memory_saver_adapter、maybe_init_remote_instance_transfer_engine、maybe_init_expert_location_metadata、maybe_init_lplb_solvers、maybe_init_eplb_manager、maybe_init_elastic_ep、init_token_oracle、maybe_init_expert_backup_client、maybe_init_lora_manager、init_kv_index_translator、maybe_init_hisparse_coordinator、init_attention_backends、init_cuda_graphs、init_routed_experts_capturer、init_indexer_capturer、init_torch_distributed、init_shared_mooncake_transfer_engine、maybe_init_dwdp、init_lora_manager、init_decode_cuda_graph、init_prefill_cuda_graph、init_threads_binding等。注意其中init_decode_cuda_graph/init_prefill_cuda_graph与recapture_cuda_graphself.init_decode_cuda_graph的用法见 model_runner.py辅助方法本身可以成为下游协作类的回调参数这是保留覆写点的延伸——fork 覆写了init_decode_cuda_graphWeightUpdater拿到的重捕获回调也随之替换。2.4 范围限制只约束上面列出的三个类不适用于其他 manager 风格类也不适用于小型 dataclass / 工具类构造函数。3. 一套可用于 Code Review 的检查清单综合原文档约定在为这三个类做代码评审或动手修改时可以对照以下问题这条逻辑是协调还是计算如果是配置构建、数据变换、算法主体、数学计算、后处理——它应该进入协作类而不是model_runner.pyfrozen 文件新功能是否拆成了独立的init_thing结构化逻辑不允许以内联块形式进入__init__一行简单赋值self.foo server_args.foo除外条件构造是否用了maybe_init_thinggate 应放在辅助方法内部而不是在__init__里展开if内联构造协作类拿到的是窄参数还是上帝对象默认传model_config、device等具体值参照resolve_layer_indices(*, model, model_config, is_draft_worker, spec_algorithm)形态上帝对象是否只读被调用方读取字段并返回冻结结构体写回由编排者完成确有例外要注明原因覆写点是否被保留对既有init_*签名做增量修改破坏性变更必须在 PR 中声明顺序是否清晰辅助方法只读更早设置好的self.*共享中间结果走参数传递顺序编排留在__init__。4. 关键文件索引技能文档原文.claude/skills/large-class-style/SKILL.md冻结文件orchestration-onlypython/sglang/srt/model_executor/model_runner.py__init__编排参照形态python/sglang/srt/managers/tokenizer_manager.py大型编排类python/sglang/srt/managers/scheduler.pyModelRunner协作类目录python/sglang/srt/model_executor/model_runner_components/窄参数 冻结结构体返回范例layer_setup.pyScheduler协作类目录python/sglang/srt/managers/scheduler_components/本文所有结论均以当前仓库为准frozen 文件目前仅model_runner.py一个Scheduler与TokenizerManager适用__init__编排风格§2而不受 frozen 约束。若后续版本调整文件边界请以仓库最新代码为准。【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
