←AI 实践笔记

第 1 课 · 约 10 分钟

为什么导入一个文件
会拖进 33 个

收件箱只用得上 4 个模块,启动时却加载了 33 个。这不是谁写错了,是 Python 包的一条规则决定的。学完这一课,你能自己验证这句话,也能判断一次改动会不会让收件箱起不来。

先看现象

你的收件箱启动时执行的是这一句:

import digital_avatar.geweapi.inbox_service

就这一句。但加载完之后,内存里躺着 33 个模块,其中包括 vision(看图)、firecrawl(爬网页)、memory(记忆)、application(分身主逻辑)——收件箱一个都用不上。

这个数字是实测的,不是估的。你自己也能测:
PYTHONPATH=src python3 -c "import sys,importlib; b=set(sys.modules); importlib.import_module('digital_avatar.geweapi.inbox_service'); print(len([m for m in set(sys.modules)-b if m.startswith('digital_avatar')]))"

规则只有一条

导入 parent.one 时,会隐式执行 parent/__init__.py。

— Python 语言参考 · The import system,原文:“Importing parent.one will implicitly execute parent/__init__.py”

「隐式」是这条规则的全部重点:你没写这行代码,Python 替你执行了。

要理解它,先分清两个词:

词是什么你项目里的例子
模块一个 .py 文件vision.py、webhook.py
包一个装着 __init__.py 的目录geweapi/ 这个目录

inbox_service.py 住在 geweapi/ 这个包里面。所以要拿到它,Python 必须先把这个包打开——也就是先执行 geweapi/__init__.py。

那个文件里写了什么

它的第一行是:

from .deepseek_transport import DeepSeekTransport, ModelAnswerError

deepseek_transport 是调用大模型用的。收件箱根本不调模型。

但这一行在 __init__.py 里,而 __init__.py 会被隐式执行,所以它一定会跑。这个文件里一共有 16 行这样的 import,把包里 29 个模块几乎全拉了进来。

连锁就是这么发生的:

你写的:  import ...geweapi.inbox_service
             ↓
Python 先做: 执行 geweapi/__init__.py
             ↓
那里面有:   from .deepseek_transport import ...
             from .vision import ...
             from .media import ...      (共 16 行)
             ↓
结果:       33 个模块全部加载完毕

为什么这件事要紧

加载一个模块,意味着执行它顶部的 import。vision.py 顶上如果写着 import pillow,那么加载它就要求这台机器上装了 pillow。

装不了?整句 import 失败,收件箱起不来,群消息全部进不去——而它根本不看图。

你在自己电脑上不会发现,因为你电脑上装了那个库。

练一练

三道题,凭理解答,答错了看解释再来。

1 · 你在 vision.py 里加了一行 import pillow,代码同步到了预发布,但那台机器上没装 pillow。重启收件箱会怎样?

收件箱启动的第一件事就是加载整个包,vision 在其中。加载 vision.py 就要执行它顶部的 import pillow,这一步找不到库就抛 ModuleNotFoundError,整个启动中断。「用到才崩」的前提是它被延迟加载了,而 __init__.py 的导入没有延迟。

2 · 假设改掉 __init__.py,让 inbox_service 直接从它真正需要的那几个模块导入,不再经过包的集中导入。改完之后?

连锁的源头就是 __init__.py 里那 16 行。断掉它,Python 就只加载真正被 import 到的那条链,vision、firecrawl 这些再也不会被牵连——它们的文件可以完全不上传到那台机器。顺带一提,加载的东西少了,启动只会更快,不会更慢。

3 · 官方文档用哪个词描述「__init__.py 被自动跑了一遍」这个行为?

原文是 “this __init__.py file is implicitly executed”。记住 implicitly(隐式)这个词很有用——以后你在报错或文档里再看到它,就知道是「你没写,但它跑了」。lazily evaluated(延迟求值)恰好是相反的行为,也正是这个问题的解法方向。

拿回去用

下次看到一次改动,问自己一句:这次改动有没有引入新的第三方依赖?

那条自检命令在 术语表 底部,也在你项目的 docs/agents/runtime-configuration.md 里。

建议读的一手材料

Python 教程 · 6. Modules —— 比语言参考好读,十五分钟能过一遍。只读 6.4「Packages」那一节就够,前面讲的是模块基础,你已经会了。