LazyLLM黑科技：谁调用决定结果截然不同

问题：调用主体不明

在工程实践中，有一类问题特别隐蔽，但几乎人人都遇到过：同一个方法，看起来一模一样，结果却完全不同。

为什么？因为方法的语义，不只取决于“做什么”，还取决于——谁在调用。

这就要说到一个关键区别：很多操作天生就是类级的，影响全局；有些则是实例级的，只对当前对象有效。

然而写法和调用方式通常完全一样，这就埋下了隐患——本想只改当前对象，结果动了全局；或者，某个实例悄悄改了全局状态，别的实例跟着遭殃。更麻烦的是，这类 bug 不会立刻崩溃，而是：行为依赖调用顺序、别人无法复现、定位极其困难。

你翻遍接口文档、检查所有参数，都看不出毛病。真正缺失的，只有一个关键信息——系统根本不知道究竟是谁在调用这个方法。

如果这种上下文只能靠约定或文档来保持，一旦系统规模上去，这些问题就会悄悄升级成结构性风险。

难点：主体感知

要解决它，真正的难点并不在于同时支持两种行为，而是如何在不动接口设计的前提下，让系统能够感知到调用者的身份。

常见的做法都有明显短板：

• 如果把全局操作和实例操作拆成两套方法，语义是清晰了，但接口会膨胀，命名负担变重，也更容易被误用。
• 如果通过参数区分作用范围，比如传入 scope 或 global=True，本质上是把语义暴露到接口层，不够直观，使用成本也高了。

更关键的是，这些方案都没有解决核心问题：调用主体并不是方法参数，而是调用方式本身所隐含的信息。

从系统设计的角度看，理想状态应该是：只暴露一个方法名，调用方式保持一致，行为分流由框架自动完成。

这意味着一个很关键的转向：主体识别必须发生在调用之前，而不是参数解析之后。

也就是说，框架需要在方法被访问的那一刻，就已经知道当前是谁在调用，并据此决定后续执行路径。

难点也正是在这里：如何在保持接口简洁的同时，让调用主体成为系统可感知的一等信息。

解决方案与代码示例

解决方案

为了解决调用主体不可感知的问题，LazyLLM 引入了 DynamicDescriptor，将调用主体识别前移到方法访问阶段，为方法注入了“调用者感知”的能力。

通过这一机制，同一个方法名在不同访问方式下，会自动绑定到不同的执行对象：

• 从类访问时，方法接收类本身，执行全局逻辑。
• 从实例访问时，方法接收实例对象，执行局部逻辑。

调用方式保持完全一致，区别只来自调用上下文本身。

下图展示的是 LazyLLM 中 Document 类的真实源代码：

以 create_node_group 函数为例，在这两次调用中，create_node_group 并未通过参数区分作用范围，而是由框架在访问阶段自动判断调用主体：

• 使用 Document.create_node_group() 类调用 → 全局注册路径，把 node group 注册到全局注册表。
• 使用 doc.create_node_group() 实例调用 → 实例内部路径，注册到当前 doc 实例内，不与其他实例共享。

这种设计带来的效果是：类级与实例级操作共享同一个接口，调用形式保持直觉一致，内部执行路径自动分流，无需额外参数或命名约定。

对使用者而言，方法名只描述“做什么”，而不需要关心“在哪个层级生效”，作用范围由调用主体自然决定。

总而言之，DynamicDescriptor 让 LazyLLM 在不增加 API 数量的前提下，将“调用主体”这一关键信息纳入系统语义之中。

代码示例

除了上述真实代码示例之外，以下是一个简单的使用示例。

例如，你可以用 @DynamicDescriptor 装饰自定义类的方法。在函数体内，根据第一个参数是类对象还是实例对象，返回不同的结果。调用 a.who() 时打印 instance 的结果，调用 A.who() 则打印 class。

通过这个例子，你能更直观地感受到 @DynamicDescriptor 在实际代码中能起到什么作用——充分利用它对调用者的感知能力，优化整体类和函数的设计。

技术剖析与源码细节

下图为 DynamicDescriptor 的类定义，接下来我们深入剖析源码细节。

访问阶段：捕获调用上下文

DynamicDescriptor 的第一步工作，发生在方法被访问时，而不是被调用时。

在 Python 中，当一个对象实现了 __get__，它就会参与属性访问过程。无论是通过类访问还是实例访问，只要读取这个属性，解释器都会先进入 __get__。

这里最关键的并不是返回了什么，而是 __get__ 捕获到了什么：

• instance：类访问时为 None，实例访问时为当前对象。
• owner：无论访问对象是谁，总是所属的类。

也就是说，在真正调用函数之前，框架已经准确知道：这次访问是来自类，还是来自某个实例。

DynamicDescriptor 并不急着执行逻辑，而是将以下三者封装成一个中间对象：原始函数、当前实例（如果存在）、所属类。

这一步的本质，是捕获调用上下文，并把它保存下来，为后续执行做准备。

调用阶段：延迟绑定执行对象

真正的语义分流，发生在第二阶段：这个中间对象被调用时。Impl 本身是一个可调用对象：

__call__ 函数里做了一件非常明确的事：

• 如果访问来自实例，就把实例作为第一个参数。
• 如果访问来自类，就把类作为第一个参数。

因此，被 DynamicDescriptor 修饰的方法，可以统一写成如下写法，而不需要提前决定它是实例方法还是类方法。

这种“延迟绑定”的设计有两个关键优势：

• 语义分流发生在系统内部，调用者不需要传额外参数，也不需要理解内部规则。
• 调用方式天然携带语义，类调用与实例调用，本身就是最可靠的上下文信息。

最终效果是：方法名只描述“做什么”，而“在哪个层级生效”，由调用主体自然决定。

总结

LazyLLM 这次的做法，就是把一个大家早就遇到过、但一直没能优雅处理的问题，给出了一个干净利落的解法：同一个操作，在不同层级下语义不一样，但接口层又很难自然表达。以前要么靠约定，要么拆两套接口，最终不是变复杂，就是容易被误用。

DynamicDescriptor 提供了一条更顺的路：不改接口，不加参数，而是直接让系统在执行前就知道“是谁在调用”。这样一来，类级和实例级的行为可以自然分开，但对使用者来说，写法完全不变。

更重要的是，这件事把一个原本需要人脑判断的东西，变成了系统自动处理的能力。接口依然简单，行为更可控，也更不容易出错。

本质上，这是在做一件很工程的事情：不让使用者去记规则，而是让系统把正确的行为变成默认。