【导航台账】老蒋的技术博客全系列文章汇总持续更新99%的Python开发者都踩过的坑__init__.py导入链污染而在LangChain、PyTorch等重型依赖项目中尤为常见。文章摘要在Python项目中运行仅依赖pandas和random的轻量脚本时因common/__init__.py错误地全局导入langchain.agents相关模块导致不必要的重型依赖链加载即使脚本未使用LangChain。问题根源在于__init__.py设计违反了最小导出原则主动导入了含LangChain依赖的子模块。解决方案是将__init__.py改为轻量级入口仅导出基础工具函数如setup_logger其他依赖改为按需导入。此原则适用于所有含重型依赖的Python项目可显著提升脚本启动效率。如果你在构建Agent项目时遇到了奇怪的ImportError本文就是为你准备的。问题现象在《智联工坊实战制造知识库工具调用Agent从零搭建OEE手册排班》项目工程化过程中运行01_generate_mock_data.py时明明只是一个生成CSV的轻量级脚本却报出ImportError: cannot import name AgentExecutor from langchain.agents检查发现整个脚本只用了pandas和random根本没有用到LangChain为什么会被强制加载根因分析Python在导入包时会先执行__init__.py这是语言机制决定的。【为什么Python会这样设计】这是Python的包导入机制所致并非Bug您可以这样理解“这不是LangChain的问题而是Python的底层设计”大家对框架是真心误解了。本案例问题出在common/__init__.py的设计上# ❌ 错误写法 from .base_agent_builder import BaseAgentBuilder from .llm_client import get_llm from .chroma_client import get_chroma_client当01_generate_mock_data.py执行from common.utils import setup_logger时Python 会先加载common/__init__.py而该文件中导入了base_agent_builder后者又导入了langchain.agents。导入链01_generate_mock_data.py → from common.utils import setup_logger → common/__init__.py 被执行 → from .base_agent_builder import BaseAgentBuilder → base_agent_builder.py → from langchain.agents import AgentExecutor, create_react_agent → 触发LangChain全量加载即使脚本根本不需要这就是“导入链污染”——轻量级脚本被迫加载了重型依赖。解决方案将__init__.py改为“轻量级网关”# ✅ 正确写法 from .utils import setup_logger, load_env # 以下为延迟导入不在此处主动加载 # 需要 LangChain 的场景请直接导入具体模块 # from common.llm_client import get_llm # from common.base_agent_builder import BaseAgentBuilder __all__ [setup_logger, load_env]修改后01_generate_mock_data.py只加载了utils.py中的纯函数完全避开了LangChain依赖链脚本秒级启动。修改之后运行成功实例效果如下修改后重新运行 ✅ 模拟数据生成成功: 21 条记录 - data/processed/production_records.csv经验总结__init__.py应遵循“最小导出原则”只导出绝对必要的纯工具函数避免在顶层导入重型依赖LangChain、Torch等。让业务代码按需导入而不是在__init__.py中集中导出所有模块。如果某个模块确实需要在多处使用让调用方直接from common.llm_client import get_llm而不是通过__init__.py中转。这个原则不仅适用于LangChain也适用于任何有重型依赖的Python项目。互动与交流您在Python项目中是否也遇到过类似的导入链污染问题欢迎在评论区分享你的踩坑经历我会逐一回复。 **建议收藏**下次遇到类似的ImportError可以快速对照本文排查。本文问题源自智联工坊实战制造知识库工具调用Agent从零搭建OEE手册排班-CSDN博客 完整源码及深度教程见该文详细内容。本文归属专栏《数据与AI工程排坑笔记》核心专栏地址制造业数据与AI落地实战下一篇《LangChain版本碎片化langchain-core 0.3 vs 1.4的生死冲突》即将发布本文的关键字和关键标签#排坑笔记#LangChain#Python#踩坑实录