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

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

import lazyllm# 只用核心能力时，我们不希望触发 tools/rag 依赖检查ch@t = 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 的预置逻辑管理，用户无需手动查阅兼容矩阵或推断版本组合。总体体验可以概括为：未使用的能力不引入依赖；使用时一次性补齐依赖并可直接继续运行。

下文进入实现细节\uD83D\uDC47

机制总览

LazyLLM 的延迟加载三层模型：

接下来依次揭开他们的神秘面纱\uD83D\uDC47

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

• 解决的问题：

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

• lazy的方法：

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

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

• 关键代码：

# 文件：lazyllm/__init__.pydef __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中声明/暴露出来的子模块

• 效果：

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

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

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

• 解决的问题：

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

• lazy的方法：

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

• 关键代码：

  # lazyllm/tools/__init__.pydef __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️⃣依赖集中检查：子模块导入时统一检测

• 解决的问题：

\uD83D\uDC49实际使用依赖时才暴露缺少依赖。

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

• lazy的方法：

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

• **关键代码：**

  # lazyllm/tools/rag/__init__.pyfrom lazyllm.thirdparty import check_dependency_by_groupcheck_dependency_by_group('rag') # 模块init中指定该子模块隶属于哪个依赖组# lazyllm/thirdparty/__init__.pydef 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}\You can install them by:\    lazyllm install {group_name}'        LOG.error(msg) # 提示安装依赖组的命令        raise ImportError(msg)

• 效果：

\uD83D\uDC49对功能组进行整体校验

\uD83D\uDC49一次性列出缺失依赖

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

\uD83D\uDC49提供明确的安装命令

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

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

• lazy的方法：

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

• **关键代码：**

  # lazyllm/thirdparty/__init__.pyclass 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)

• 效果：

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

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

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

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

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

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

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

from lazyllm import Document, Retrieverdocs = 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-advancedlazyllm install agent-advanced

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

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

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

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

小结

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

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

• 让环境更轻量： 未使用的功能不引入额外依赖，避免安装集合不断膨胀。

• 让报错更友好： 缺失依赖在首次使用时就明确提示，并一次性列全，减少反复试错。

• 让安装更稳定： 依赖组与版本约束统一来源于同一份配置，提示与安装行为一致。

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

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

LazyLLM项目仓库链接\uD83D\uDD17：

• https://github.com/LazyAGI/LazyLLM

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