用 Python 与 Docker 给 AI 小工具做一个可复现的本地运行环境

很多 AI 小工具在作者自己的电脑上跑得好好的，换一台机器就报错：依赖装不上、模型路径找不到、端口被占用、结果忽好忽坏。问题往往不在模型本身，而在运行环境没有被完整记录下来。本文介绍一套轻量做法：先用 Python 虚拟环境把依赖说清楚，再用 Docker 把系统环境固定下来，最后用 Compose 把本地开发流程串起来，让同一个小工具在不同机器上得到尽量一致的结果。

第一步，先把依赖说清楚。新建项目时先固定 Python 版本，例如写明使用 Python 3.11，再创建虚拟环境并生成锁定文件。不要长期依赖 latest 这类浮动版本，因为一次重新安装就可能悄悄升级某个库，导致行为变化。建议把 requirements.txt 提交进仓库，同时记录关键库的大致版本范围；本地调试通过后，再用 pip freeze 输出一份完整清单，方便出问题时对照。模型文件、数据文件和大体积缓存不要放进依赖清单，要单独说明下载方式和存放路径。

第二步，用虚拟环境做第一层隔离。虚拟环境的好处是简单、启动快，适合快速验证想法：创建环境、激活、安装依赖、运行脚本，整个过程几分钟就能完成。但它只能隔离 Python 包，隔离不了系统库、系统工具版本和操作系统差异。同一份代码在 Windows、macOS 和 Linux 上仍可能因为换行、路径分隔符、缺失系统库而表现不同。所以虚拟环境适合开发初期的快速迭代，不适合作为交付的唯一依据。

第三步，用 Docker 做第二层固定。写 Dockerfile 时有几个实用原则：基础镜像尽量选体积小、版本明确的 slim 镜像；先复制依赖文件并安装，再复制业务代码，这样可以利用镜像分层缓存，改代码时不用每次重装依赖；设置合理的工作目录；尽量用非 root 用户运行，避免容器内生成的文件在宿主机上权限混乱；用 .dockerignore 排除虚拟环境、缓存、模型大文件和本地配置文件，防止镜像变得臃肿。还可以给服务加一个简单的健康检查，让启动失败时更容易定位。

一个最小示例可以这样组织：Dockerfile 负责安装依赖并设置启动命令；docker-compose.yml 负责把本地代码目录、数据目录和模型缓存目录挂载进容器，并声明端口映射和环境变量。这样改代码不用重建镜像，换机器时只要重新拉取镜像并挂载本地目录即可。环境变量不要写死在镜像里，本地开发用的配置可以放在 .env 文件中，并且把真实密钥排除在版本控制之外，用占位符和说明文档代替。

第四步，建立一份简短的调试清单。环境出问题时按顺序排查，往往比反复重装更快：先确认 Python 版本和依赖清单是否一致；再看端口是否被占用、数据目录是否挂载成功；然后检查文件权限和换行问题；最后看模型缓存路径和网络访问是否符合预期。把每次踩过的坑写进项目 README 的一小节，下一个接手的人就不用重复踩坑。这一步看起来琐碎，却是可复现性里最容易被忽视的部分。

最后提醒三点。第一，不要为了可复现而把环境做得过于复杂，能用一个容器讲清楚的，就不要拆成一堆服务。第二，镜像和依赖要定期更新，但更新要单独做一次验证，而不是在赶进度时顺手升级。第三，文档和环境要一起维护：依赖变了，文档里的版本说明也要跟着变。把环境当作产品的一部分来对待，AI 小工具才能从能跑一次，变成在任何一台机器上都能稳定跑起来。