一、问题：模块扩展与注册
在 LLM 工程里，功能一旦开始往上叠，模块数量几乎是不可避免地往上涨。这时候，真正摆在你面前的，不是“还能不能加功能”，而是——这些模块到底怎么统一管理。问题通常会从两个方向同时冒出来：
- 对内：框架内部的模块注册方式各不相同，前期还能忍，越往后越难维护、越难梳理
- 对外：外部模块没法直接接进来，往往还得额外写注册代码、维护注册表，注册成本越来越高
这两类问题看起来不一样，本质却是同一件事：框架缺少一套合理的注册机制，无法让模块在体系内自然扩展。
如果不早点把这件事想清楚，模块加得越多，系统就越容易失控。
二、难点：统一且易扩展
真要动手设计一套注册机制时，难点往往很快就会浮现出来：
- 很难用同一种方式去管理框架内部类型各不相同的模块，注册逻辑一多，就开始各走各的路
- 新模块一接进来，老模块却被迫“感知”到变化，甚至影响原有用法
- 注册成本始终降不下来：即便已经有了注册机制，仍然需要手写注册代码、维护注册表和扩展逻辑
这些问题叠加在一起，很容易把“扩展能力”变成系统长期演进中的负担。
三、LazyLLM 的注册机制
针对这些难点，LazyLLM 选择了一条更干脆的路：模块在定义时自动完成注册，不需要再做任何额外操作。
无论是类模块还是函数模块，底层都走同一套自动注册逻辑，所有模块统一纳入同一个命名空间进行管理。整体机制可以概括为两种模式：“继承即注册”和“注册即继承”。
定义类时，只要继承对应的能力基类，就会在定义阶段自动注册到全局注册表中。
同时，类会继承基类的命名分组，该分组下的所有模块都会自动获得基类提供的能力。
定义函数时，只需使用 @xxx_register 装饰器，就会被自动包装为类对象，并根据注册类型，继承相应基类的能力。
通过这种方式，你不需要手写任何注册逻辑，也不需要手动维护注册表，就能把模块自然地接入框架。在这种注册机制下，模块之间只共享上级命名空间（例如 lazyllm.launcher ），注册新模块，本质上只是往命名空间里新增一个 key-value，不会影响其他模块的感知和使用。
模块完成自动注册后，统一通过 lazyllm.xxx.yyy 的形式访问，接口保持一致，使用方式不变，用户体验也始终统一。
四、用户视角：如何使用注册机制
这一章将从用户视角出发，带你一步步了解 LazyLLM 的注册机制：从如何访问已经注册到框架中的模块，到如何基于现有机制扩展新的类模块和函数模块。通过这些具体用法，你会直观感受到什么是“ lazy 地注册”，以及 LazyLLM 注册机制在扩展性和使用体验上的优势。
4.1 访问已注册的模块
A. 访问方式
对于已经注册到框架中的模块，LazyLLM 提供了多种访问方式，让你在使用时既灵活又省心。
1️⃣基于属性的访问（dot access）
LazyLLM 支持使用属性访问代替字典索引，lazyllm.launchers.k8slauncher 和 lazyllm.launchers['k8slauncher'] 等价，这样可以保持访问形式的一致性。
2️⃣大小写不敏感的 key 匹配
访问模块时，key 对大小写不敏感。比如 lazyllm.launchers.k8s、lazyllm.launchers.K8s 和 lazyllm.launchers.K8S 在语义上完全一致，不再要求你精确记住注册时的大小写细节。需要注意的是，注册时使用的 key 仍然是机制内部的唯一标识，并不会因为访问方式不同而发生变化。
3️⃣允许省略能力后缀
对于某些类名以能力后缀结尾的类（比如前面提到的 lazyllm.launchers.k8slauncher），可以在访问时省略能力后缀，简写为 lazyllm.launchers.k8s，框架在查找时会自动补齐后缀，减少冗余输入。
4️⃣支持默认 key
可以显式地为某个注册分组设置默认 key，用来指定省略 key 时选择的实现类，示例如下。设置默认key只会影响访问时的 key 和解析结果，不会改变实际注册的 kv。
ld = LazyDict(name="ld", ALd=int, BLd=str)
ld.set_default("ALd")
ld.default # -> int（示意）
5️⃣函数式调用默认实现
当某个能力分组只有一个实现，或者已经设置了 default key 后，可以直接把分组当作函数来调用。
例如 lazyllm.launchers(**kwargs)，等价于调用该分组下的默认实现 lazyllm.launchers.k8s(**kwargs)（此处k8s仅为文档示例，并非框架中的真实默认实现）。
B. 目前支持的能力基类
除了 launchers 类型之外，LazyLLM 还支持多种能力类的继承，涵盖模型、调度器、调优、存储以及其他工具能力。
如图所示，你可以直接打印某个组名，快速查看该命名空间下当前已经注册的所有类及其子类结构。这在理解框架已有能力、或者确认某个模块是否已经被正确注册时，非常直观、也非常实用。
在能力组织上，LazyLLM 采用了两级能力体系：
- 一级能力：例如 online、launcher、deploy 等，用于描述能力的大类
- 二级能力：目前主要存在于 online 分组下，例如 chat、embed 等，用于进一步细分具体能力形态
通过 dot access，可以自然地访问这些多级注册的类结构，例如从一级能力一路定位到具体实现类。
在此基础上，LazyLLM 为不同能力类型提供了对应的基类，用户在扩展新模块时，只需继承相应基类即可自动完成注册。
目前支持的基类包括：
C. 目前支持的注册函数
除了能力基类之外，LazyLLM 目前还提供三个装饰器函数，用来把函数模块注册为类对象并加入注册机制，具体描述如下：
4.2 扩展新的类
A. 继承规则
如果要构造自己的类并注册到 LazyLLM 框架中，只需要继承4.1章节中提到的能力基类，就能够实现自动继承和统一访问。为了完成这个继承过程，需要遵守以下规则：
如果你要定义一个能力分组的基类，类名需要满足 LazyLLM+<GroupName>+Base 的命名约定。一旦满足这个约定，框架内部就会自动新增一个 <GroupName> 能力分组，并且可以通过 lazyllm.<GroupName> 直接访问。
在注册能力基类时，可以通过设置 \_\_lazyllm\_registry\_disable\_\_ ，主动跳过该类的注册流程。这样，这个类不会被写入注册表，也无法通过 lazyllm.<GroupName> 访问，但完全不影响它被继承、复用或作为能力基类存在。
除了依赖类名生成能力分组，还可以通过 \_\_lazyllm\_registry\_key\_\_ 显式指定注册 key。这样可以把“类叫什么”和“用户怎么访问”这两件事分开处理，同时不影响原有的继承关系。
下面的示例把这三条规则放在一起，展示了一个更真实的使用场景：
OnlineMultiModalBase 用来承载所有多模态相关的通用逻辑（例如 forward、_load\_images 等），但它本身并不希望成为一层可直接访问的能力分组，因此设置 \_\_lazyllm\_registry\_disable__=True，只作为抽象基类存在。
而 LazyLLMOnlineSTTModuleBase 在继承多模态基类通用能力的同时，需要作为独立的能力层级对外暴露，于是通过 \_\_lazyllm\_registry\_key\_\_ = LLMType.STT 指定注册 key。这样，它的所有子类都会被统一注册到 lazyllm.online.stt 命名空间下，并自动具备多模态基类提供的能力。
通过这种方式，你可以精确控制哪些类参与注册、注册到哪里、如何被访问，而继承关系和能力复用本身，始终保持清晰、干净。
B. 命名规则
在定义具体能力类时，除了完成继承之外，还需要遵守一套明确的命名约定，框架才能正确完成自动注册和解析。
具体能力类的类名需要满足 <Supplier> + <GroupName> 的命名规则。一旦满足该约定，类就会被自动注册到对应基类的命名空间下，并以类名作为注册 key。在实际访问时，可以直接使用 <Supplier> 作为 key，框架会在内部自动补齐 <GroupName> 后缀完成匹配。
为了与 Python 生态保持一致，也为了统一开发者的认知和习惯，所有能力类的类名都应采用驼峰命名法（CamelCase）。
通过这套命名规则，LazyLLM 可以在不引入额外配置的情况下，同时保证注册行为可预测、访问方式简洁，也让代码结构本身就“说明了一切”。
C. 代码示例
以下为能力类的定义样例，定义后可以通过 lazyllm.online.chat.qwen 或 lazyllm.online.chat.qwenchat 访问该类，访问方法和框架内置的模块完全相同，实现无感、无额外代码的统一注册。
4.3 扩展新的函数
A. 注册规则
如果要注册新的函数到框架里，需要执行以下两个步骤：
1️⃣创建新的能力分组
LazyLLM 里支持两种创建的方式：
a.定义类时继承 metaclass=LazyLLMRegisterMetaClass，该类的类名/显式设置的 registry key 就会被自动识别，并注册为新的能力分组；
b.使用 Register.new\_group('group\_name')，直接创建一个新的能力分组并注册到框架内。
2️⃣【可选】定义新的register对象
指定需要继承的能力基类，设置 rewrite 函数，用新的函数覆写基类的 rewrite 函数。比如，指定 rewrite 函数为 cmd，就可以使用 @register.cmd 对函数进行装饰，从而重写基类的 cmd 函数。
3️⃣根据能力选择注册器并注册到某个能力分组内
使用 @xxx\_register('group\_name') 装饰器把函数包装为类对象，并把函数名和函数体作为 key-value 对注册到 group\_name 能力分组下，这样就可以通过 lazyllm.group\_name.func_name 访问该函数。
B. 代码示例
如图所示，示例中首先构造了一个 register 实例，并指定 rewrite 函数为 apply 和 cmd 。随后，通过 component\_register.new\_group("testgroup") 创建了新的能力分组 testgroup。
使用 @component\_register 进行装饰，函数会被注册到 testgroup 命名空间下，继承 ComponentBase 类，默认覆写 apply 函数（未显式指定时，默认覆盖rewrite\_func[0]），并自动获得 launcher 提供的跨节点调度能力。
由于使用了 @component_register.cmd，会显式覆写基类中的 cmd 函数，实现不同的执行逻辑。
在使用时，可以直接通过：lazyllm.testgroup.myfunc()(*args) 来调用函数；同时也支持在括号中传入指定的 launcher，从而决定函数的运行位置，例如本地执行（empty）或提交到 Slurm 集群等。
五、技术剖析：架构与源码细节
最后，我们来一起深入 LazyLLM 注册机制的底层技术，了解它是如何设计和实现的。
5.1 架构设计
LazyLLM 的注册系统由三层组成，自下而上分别为：
1️⃣LazyDict：
注册结果的访问层，负责解决“注册之后，用户如何访问和调用”的问题。
2️⃣LazyLLMRegisterMetaClass：
注册逻辑的核心控制层，负责决定“类在定义时是否被注册、注册到哪里、以什么形式暴露”。
3️⃣Register 装饰器：
函数到类的适配层，负责将“函数形式的能力”统一纳入基于类的注册体系。
这三层各司其职、相互配合：前两层共同完成类模块的自动注册；在此基础上，Register 装饰器进一步解决了函数模块的接入问题，让函数也能够享有与类一致的注册能力。
最终效果是：不论能力最初以类还是函数的形式存在，都可以通过同一套注册与访问机制被框架统一管理和使用。
5.2 访问层：LazyDict
A. 职责边界
LazyDict 是注册机制中直接面向使用者的访问层。所有通过注册机制生成的分组与实现，最终都会以 LazyDict 的形式对外暴露。它不参与注册决策，也不决定实现类的归属关系，职责仅限于：
- 作为某个 Base 类对应的注册容器
- 维护注册结果与访问行为之间的映射关系
在系统内部，LazyDict 的结构可抽象表示为：
LazyDict(
impl_a -> ClassA,
impl_b -> ClassB,
)
该对象随后被直接绑定到 lazyllm.<group>，作为该分组的统一访问入口。
B. 核心代码
以下为 LazyDict 的部分核心代码，可以看到 _match 函数中允许通过 default 匹配默认 key，并通过拼接 key 和 group name 实现省略能力后缀访问的能力，同时兼容多种调用方式并且对大小写不敏感。
5.3 核心控制层：LazyLLMRegisterMetaClass
A. 职责边界
LazyLLM 的类注册行为由统一的 metaclass 控制。所有参与注册的类，都会在定义阶段经过该元类的处理，从而决定其是否被纳入注册体系、归属到哪个能力分组，以及是否对外暴露访问入口。
在整体架构中，LazyLLMRegisterMetaClass 的职责是：
- 解析类的继承结构以确定其对应的分组路径与访问入口
- 将可注册的实现类组织到对应的能力分组中
- 为后续的统一访问入口生成必要的注册信息
B. 核心代码
以下为 LazyLLMRegisterMetaClass 类的核心代码，处理逻辑主要分为三层，对应4.2章节中的继承规则：
1️⃣是否跳过注册
首先判断类是否定义了 \_\_lazyllm\_registry\_disable\_\_。如果该属性被设置为 True，当前类会被直接跳过注册流程：不会写入父类分组，也不会出现在访问入口中，但不影响该类被继承或作为能力基类复用。
2️⃣是否定义新的能力分组
接着判断类名是否符合 LazyLLM<xxx>Base 的命名规则。如果符合，框架会自动提取中间的 <xxx>，创建对应的能力分组，并绑定到 lazyllm.<group> 命名空间下。该基类的所有子类，都会被统一注册到同一个 LazyDict 中。
3️⃣是否进入已有分组并细分层级
最后判断类是否具有 \_lazy\_llm\_group 属性（即是否存在可注册的父类）。在此基础上，如果类中定义了 \_\_lazyllm\_registry\_key__，则会以该值作为新一层的 group name。同时，注册流程末尾还预留了一个后处理钩子，允许类在注册完成后执行自定义逻辑，用于补充通用行为。
5.4 适配层：Register
A. 职责边界
LazyLLM 的注册体系是以“类”为核心构建的，但在真实使用中，并不是所有能力都适合用类来表达。很多时候，一个能力本质上就是“一段可调用的逻辑”，用函数来写反而更自然。
为了不让这两种开发方式割裂开来，LazyLLM 提供了 Register 装饰器，专门用来把函数形式的能力统一纳入同一套基于类的注册机制中。
Register 装饰器的职责在于：
- 为函数构造一个等价的、可注册的类表示
- 使函数能力能够复用基于元类的注册流程
- 保证函数与类在注册结果和访问方式上的一致性
B. 核心代码
下面给出的 Register 类是函数注册机制的核心实现。
其中，new_group 函数在前文已经提到，用于创建新的能力分组。它在内部做的事情其实很直接：基于 python 的 type() 动态建类机制，动态创建一个继承自 baseclass 的能力基类，并命名为 LazyLLM{name}Base。由于该类满足注册规则，name 这个能力分组也会随之自动注册到框架中。
真正的关键逻辑集中在 _wrap 函数中，整体流程可以拆解为几个步骤：
1️⃣标准化类名
首先对传入的类名进行规范化处理，去掉 LazyLLM 和 Base 等前后缀，得到统一的分组标识。
2️⃣定位能力基类
接着调用 \_get\_base\_cls\_from_registry，找到当前能力分组对应的基类，用于后续继承。
3️⃣确定覆写目标函数
根据传入的 rewrite_func 参数，判断当前注册对象需要覆写基类中的哪个函数（例如 apply 或 cmd ）。
4️⃣动态生成注册类并完成绑定
最后，在 impl 函数中动态生成一个用于注册的“空壳类”，完成注册流程，并将当前函数绑定到指定的 rewrite_func 上。
通过这一适配层，LazyLLM 实现了“类与函数并行接入、统一管理”的注册模型。
前文提到的几种注册器，就是通过构造 Register 实例实现的：
component_register = lazyllm.Register(ComponentBase, ['apply', 'cmd'])
module_register = lazyllm.Register(ModuleRegistryBase, ['forward'])
fc_register = lazyllm.Register(ModuleTool, ['apply'], default_group='tool')
六、写在最后
最后，让我们来一起回顾一下 LazyLLM 的注册机制。
通过 LazyDict 与 LazyLLMRegisterMetaClass 的协同设计，无论注册对象最初是类还是函数，最终都会走同一套注册逻辑、进入同一个注册表，并统一纳入相同的命名空间进行管理。在注册的视角下，这个过程本质上只是向命名空间中新增一个新的 key–value 对——只要 key 不冲突，新增模块就不会影响任何已存在的模块，实现了完全独立、可叠加的扩展方式。
对使用者来说，所有模块的访问方式始终保持一致，大幅降低了理解和使用成本；
对开发者来说，注册一个自己的模块也变得非常轻量——不需要额外流程，不需要手动维护注册表，只要遵守约定，底层机制就会自动把事情处理好。
在后续的文章中，我们还会继续拆解 LazyLLM 里其他“lazy”的小设计。当系统规模真正开始扩展时，你会发现，这些看似不起眼的机制，往往才是最省时间、也最少踩坑的那一部分。
欢迎升级体验 LazyLLM 最新版本，请大家去github上点一个免费的star，支持一下～
LazyLLM项目仓库链接🔗：
更多技术内容，欢迎移步 gzh “LazyLLM" 讨论！
