LazyLLM黑科技 | 不装全家桶也能跑？LazyLLM 的按需动态加载方案

关注

原创 2026-03-10 17:35:19 339 阅读 AI 写同款· GEO 优化 ›

低代码Agent工厂：用LazyLLM快速克隆行业专属智能体本文介绍了LazyLLM低代码框架如何帮助企业快速构建行业专属智能体，解决传统AI开发的技术门槛高、周期长和成本昂贵问题。通过模块化设计和RAG技术，LazyLLM支持教育培训、电商客服等场景的智能体快速克隆与定制，显著提升开发效率和应用效果。阅读详情

背景｜依赖增多导致环境复杂度上升

如何才能在真正使用到某个依赖时动态加载该依赖呢？

import lazyllm
# 只用核心能力时，我们不希望触发 tools/rag 依赖检查
chat = lazyllm.OnlineChatModule(source="openai")
print("core ok")
# 一旦访问 Document，才会触发懒加载链路：
# lazyllm.Document
# -> import lazyllm.tools
# -> import lazyllm.tools.rag
# -> check_dependency_by_group('rag')
from lazyllm import Document  # 若缺少 rag 依赖，会在这里抛 ImportError

在较为复杂的 Python 项目中，常见问题是：代码尚未进入核心逻辑，运行环境会因为依赖冲突、缺失或版本不兼容而失败；不同模块往往依赖不同的第三方库。若将所有依赖统一安装，环境会迅速膨胀；若仅安装部分依赖，又容易在执行过程中因缺少依赖而中断。更进一步，即使框架自身依赖关系已经梳理清楚，也仍可能与用户本地环境产生版本或分发差异。这是 Python 生态中常见的依赖管理上的典型挑战。

难点｜依赖库难以管理，且相关报错不友好

业界常见的解决方案以及难点：

1️⃣全量安装依赖

import lazyllm
# 如果此句直接加载全量依赖会耗时很长，且会导致环境臃肿。用户不会用到的依赖白白占用空间。

2️⃣在用到某依赖时动态import

def func():
  from lazyllm import OnlineChatModule
  pass
# 调用到func时再加载某些依赖会过晚暴露问题，增加开发难度，降低开发者的用户体验

3️⃣缺少依赖或依赖冲突的导致的问题直接打印在海量日志中：关键依赖缺失信息会淹没在其他日志中，增加用户修复环境的成本。

解决方案｜按需加载与集中检查相结合

LazyLLM 采用按需加载策略：未使用的功能不预先要求安装 ；当用户首次调用相关能力时，框架对该功能组的依赖进行集中校验。

以 rag 为例，当用户首次使用相关能力时，LazyLLM 会：

1.一次性检查该功能组所需的全部依赖

2.明确列出缺失的包列表

3.给出统一的安装指令：lazyllm install rag

依赖组的版本约束由 LazyLLM 的预置逻辑管理，用户无需手动查阅兼容矩阵或推断版本组合。总体体验可以概括为：未使用的能力不引入依赖；使用时一次性补齐依赖并可直接继续运行。

下文进入实现细节👇

机制总览

LazyLLM 的延迟加载三层模型：

接下来依次揭开他们的神秘面纱👇

1️⃣顶层懒加载：lazyllm.getattr

解决的问题：

加载顶层模块时直接加载所有依赖。

lazy的方法：

通过__getattr__ 实现动态加载用户想要加载的子模块，在模块名合法的情况下动态调用该子模块内部的依赖加载流程，能让用户省略子模块路径。

getattr 的作用：当用户访问不存在的属性时，python会调用 obj.getattr(name) 以动态实现属性加载逻辑。

关键代码：

# 文件：lazyllm/__init__.py
def __getattr__(name: str):
    if name == 'tools': # 调用中间模块的加载逻辑
        return importlib.import_module('lazyllm.tools')
    elif name in __all__:
        tools = importlib.import_module('lazyllm.tools')
        builtins.globals()[name] = value = getattr(tools, name)  # 导入后会缓存导入结果以避免后续重复导入
        return value
    raise AttributeError(f"module 'lazyllm' has no attribute '{name}'") # 保证加载在顶层init中声明/暴露出来的子模块

效果：

👉顶层 API 暴露完整，但实际导入延后到首次访问

👉导入后写入 globals()，后续访问几乎无额外开销

2️⃣工具子模块懒加载：lazyllm.tools.getattr

解决的问题：

加载子模块时直接加载所有依赖。

lazy的方法：

与顶层__init_.py 类似，lazyllm.tools 也不会一次性导入所有子模块，而是根据名称映射到具体模块并按需加载。

关键代码：

# lazyllm/tools/__init__.py
def __getattr__(name: str):
    if name == 'fc_register':
        agent = import_module('.agent', package=__package__)
        globals()['fc_register'] = value = agent.register
    elif name in _SUBMOD_MAP:
        return import_module(f'.{name}', package=__package__)
    elif name in _SUBMOD_MAP_REVERSE:
        module = import_module(f'.{_SUBMOD_MAP_REVERSE[name]}', package=__package__)
        globals()[name] = value = getattr(module, name)
    return value

其中_SUBMOD_MAP, _SUBMOD_MAP_REVERSE 用于指定"类名 → 子模块"之间的映射。


_SUBMOD_MAP = {
    'rag': ['Document', 'Reranker', 'Retriever', 'SentenceSplitter', 'LLMParser'],
    'agent': ['ToolManager', 'FunctionCall', 'ReactAgent', 'PlanAndSolveAgent', 'ReWOOAgent'],
    'sql': ['SqlManager', 'MongoDBManager', 'DBManager', 'DBResult', 'DBStatus'],
    # 其他模块略
}

效果：

当用户编写 from lazyllm.tools import Document 时，才会实际导入 lazyllm.tools.rag。

3️⃣依赖集中检查：子模块导入时统一检测

解决的问题：

👉实际使用依赖时才暴露缺少依赖。

👉多个同时需要的依赖出现异常时，提示分散在不同的场景、log、时间等维度。

lazy的方法：

在子模块被导入时触发整个依赖组的检查。

关键代码：

# lazyllm/tools/rag/__init__.py
from lazyllm.thirdparty import check_dependency_by_group
check_dependency_by_group('rag') # 模块init中指定该子模块隶属于哪个依赖组
# lazyllm/thirdparty/__init__.py
def check_dependency_by_group(group_name: str):
    missing_pack = []
    for name in load_toml_dep_group(group_name): # 依赖分组信息直接从整个工程的配置toml文件中获取
        real_name = package_name_map_reverse.get(name, name)
        if not (config['init_doc'] and real_name in module_names or check_package_installed(real_name)):
            missing_pack.append(name)
    if len(missing_pack) > 0:
        msg = f'Missing package(s): {missing_pack}\nYou can install them by:\n    lazyllm install {group_name}'
        LOG.error(msg) # 提示安装依赖组的命令
        raise ImportError(msg)

效果：

👉对功能组进行整体校验

👉一次性列出缺失依赖

LazyLLM 将功能组（如 rag、rag-advanced、agent-advanced）的依赖声明在 pyproject.toml 的 extras 中，同时 lazyllm install 基于同一份配置解析并安装对应版本约束。因此，报错信息与安装命令在同一来源上生成：提示缺什么、安装什么、版本约束是什么保持一致。

👉提供明确的安装命令

4️⃣BONUS: 第三方包的延迟导入封装

当用户确实需要使用特定的三方依赖时也可以复用lazyllm中的延迟加载逻辑

lazy的方法：

LazyLLM 对第三方库（例如 torch、transformers）也提供了延迟加载封装。在lazyllm.thirdparty 中使用__getattribute__ 动态检查依赖的安装情况。

关键代码：

# lazyllm/thirdparty/__init__.py
class PackageWrapper(object):
    def __getattribute__(self, __name):
        if self._Wrapper__lib is None:
            try:
                self._Wrapper__lib = importlib.import_module(self._Wrapper__key, package=self._Wrapper__package)
            except ImportError:
                pip_cmd = get_pip_install_cmd([self._Wrapper__key])
                err_msg = f'Cannot import module `{self._Wrapper__key}`, please install it by `{pip_cmd}`'
                raise ImportError(err_msg) from None
        return getattr(self._Wrapper__lib, __name)

效果：

👉该机制将"运行到一半才报错"的问题前置到"首次使用即报错"，并提供可直接执行的安装建议（包含版本约束时亦可体现）。

👉这样导入时 from lazyllm.thirdparty import transformers，lazyllm并不会立即导入真实库；直到首次访问其属性时才进行导入，并在缺失时给出明确的安装建议。

使用方式（覆盖常见场景）

情况1️⃣：如果你想仅使用最简功能，可以仅加载顶层模块

import lazyllm
llm = lazyllm.OnlineChatModule(source="openai")

核心模块属于 lazyllm 的基础依赖，不需要额外安装。

情况2️⃣：如果你的开发涉及 RAG，可以通过顶层模块加载子模块（推荐方式

from lazyllm import Document, Retriever
docs = Document(dataset_path="/path/to/data", embed=lazyllm.OnlineEmbeddingModule())
retriever = Retriever(docs)

首次导入 Document 时会触发 rag 依赖检查。若缺少依赖，将提示：

Missing package(s): [...]
You can install them by:
    lazyllm install rag

然后用户可执行安装命令一次性补全依赖：

lazyllm install rag

情况3️⃣：如果你清楚的知道自己需要什么，可以直接使用子模块

from lazyllm.tools.rag import Document, SentenceSplitter

该方式会直接导入 lazyllm.tools.rag，因此依赖检查会立即触发。

情况4️⃣：如果你需要使用全部 RAG 或 Agent的能力，则需要手动安装相关依赖组

若使用向量数据库、Embedding 微调或 MCP 等高级能力，可安装对应扩展组：

lazyllm install rag-advanced
lazyllm install agent-advanced

这些扩展组来自 pyproject.toml 的 extras 配置，安装时会自动应用版本约束，通常无需人工拼装依赖版本。更多可安装的依赖场景见官网**安装引导文档（https://docs.lazyllm.ai/zh-cn/stable/）**或项目根目录中 pyproject.toml 的配置。

情况5️⃣：如果你想使用某个具体的第三方库，可以使用lazyllm.thirdparty 导入

from lazyllm.thirdparty import transformers
tokenizer = transformers.AutoTokenizer.from_pretrained("...")

若缺少依赖，会直接提示执行带版本约束的 pip install …。

小结

通过上面的介绍，相信你已经对 LazyLLM 这套"按需加载 + 集中检查"的依赖管理思路有了更直观的认识：不用的能力不必提前安装，真正用到时再一次性把依赖校验清楚，并给出可直接执行的安装指令。

简单回顾一下它解决的核心问题：

让环境更轻量：未使用的功能不引入额外依赖，避免安装集合不断膨胀。
让报错更友好： 缺失依赖在首次使用时就明确提示，并一次性列全，减少反复试错。
让安装更稳定： 依赖组与版本约束统一来源于同一份配置，提示与安装行为一致。

如果你也在维护一个功能模块多、依赖差异大的 Python 项目，这种设计思路通常会带来非常实际的收益：启动更快、环境更稳、问题暴露更早，用户使用门槛也更低。

欢迎升级体验 LazyLLM最新版本，请大家去github上点一个免费的star，支持一下～（也欢迎关注LazyLLM gzh哦！）

LazyLLM项目仓库链接🔗：

https://github.com/LazyAGI/LazyLLM
https://github.com/LazyAGI/LazyLLM/releases/tag/v0.7.1

标签

#科技 #人工智能 #编辑器

LazyLLM实战指南：基于RAG+Agent构建智能教学辅助系统本文详细介绍了如何利用LazyLLM框架结合RAG和Agent技术构建智能教学辅助系统。通过模块化设计和动态调整能力，系统能够快速生成个性化学习材料，显著提升教学效率。实战案例显示，AI辅助备课时间减少81.5%，学生满意度和通过率均有显著提升。阅读详情