搭建 Python AI 开发环境：虚拟环境、依赖与密钥管理

上一篇介绍了模型、提示词、上下文与 API 的关系。真正调用 API 之前，还需要一套隔离、可复现且不会泄露密钥的 Python 环境。本篇从创建项目目录开始，完成虚拟环境、依赖安装、环境变量和最小配置检查，为后续接入任意模型服务打好基础。

为什么每个项目都需要独立环境

Python 项目会依赖不同版本的软件包。项目甲可能需要某个 SDK 的新版本，项目乙却仍依赖旧接口；如果都安装到系统 Python，升级一个包就可能让另一个项目无法运行。

虚拟环境会为项目准备独立的 Python 可执行文件和包目录。它不是虚拟机，不会复制完整操作系统，因此创建很快、占用空间也较小。Python 标准库自带的 venv 已能满足入门项目需要，Python 官方文档也把它定义为创建轻量隔离环境的工具。

先确认 Python 可用：

1	python3 --version

然后创建项目和虚拟环境：

1
2
3

mkdir ai-demo
cd ai-demo
python3 -m venv .venv

.venv 是常见目录名。它只属于当前项目，不应该复制给别人或提交到 Git；其他人应根据依赖清单重新创建自己的环境。

激活并验证虚拟环境

在 Linux 或 macOS 中执行：

1	source .venv/bin/activate

Windows PowerShell 对应的命令是：

1	.venv\Scripts\Activate.ps1

激活后，终端提示符通常会出现 (.venv)。不要只依赖这个标记，可以直接验证解释器路径：

1 2	python -c "import sys; print(sys.executable)" python -m pip --version

两条输出的路径都应指向当前项目的 .venv。相比直接运行 pip，使用 python -m pip 能更明确地保证安装命令属于当前解释器。PyPA 的虚拟环境与 pip 指南也采用这种方式。

离开项目时运行 deactivate。下次回来只需重新激活，不必再次创建环境。

安装并记录项目依赖

本篇用 python-dotenv 从本地 .env 文件读取开发配置：

1 2	python -m pip install --upgrade pip python -m pip install python-dotenv

安装完成后，把精确版本写入依赖清单：

1	python -m pip freeze > requirements.txt

其他环境可以这样恢复：

1	python -m pip install -r requirements.txt

requirements.txt 应提交到 Git，.venv 则不提交。前者是“需要哪些材料”的清单，后者只是本机按照清单生成的成品。入门阶段使用精确版本有助于复现；将来维护正式项目时，还要定期评估安全更新，而不是永远锁住旧版本。

用环境变量保存 API 密钥

API 密钥相当于服务账号的密码。最危险的做法是把真实密钥直接写进 Python 文件：代码一旦进入 Git 历史，即使后来删掉，那段历史仍可能被看到。

在项目根目录新建 .env，内容使用服务商文档规定的变量名。这里用通用占位名演示：

1 2	MODEL_API_KEY=替换为你的真实密钥 MODEL_NAME=替换为服务商提供的模型名称

同时建立 .gitignore：

.venv/
.env
__pycache__/
*.pyc

为了让团队知道需要哪些配置，可以提交一份不含秘密的 .env.example：

1 2	MODEL_API_KEY= MODEL_NAME=

安装的 python-dotenv 会读取 .env 并写入进程环境。它默认不会覆盖操作系统中已经存在的同名变量，相关行为可在其 PyPI 项目说明中核对。

编写最小配置检查程序

创建 check_config.py：

import os

from dotenv import load_dotenv


load_dotenv()

api_key = os.getenv("MODEL_API_KEY")
model_name = os.getenv("MODEL_NAME")

if not api_key:
    raise RuntimeError("缺少 MODEL_API_KEY，请检查 .env 或系统环境变量")

if not model_name:
    raise RuntimeError("缺少 MODEL_NAME，请检查 .env 或系统环境变量")

print(f"配置检查通过，准备使用模型：{model_name}")
print(f"密钥已读取，长度为：{len(api_key)}")

运行程序：

1	python check_config.py

示例只输出密钥长度，不输出密钥本身。日志、异常信息和调试截图同样可能造成泄露，因此真实项目中也应避免打印完整密钥。若密钥曾出现在公开仓库、聊天记录或终端共享画面中，应立即在服务商后台撤销并重新生成，而不是只删除本地文件。

提交代码前做一次泄露检查

初始化 Git 后，先看将要提交哪些文件：

1
2
3

git init
git status --short
git check-ignore -v .env .venv/

最后一条命令应显示它们由 .gitignore 中的规则排除。还可以检查暂存区：

1	git diff --cached --name-only

如果列表中出现 .env、私钥文件、下载的凭据或虚拟环境目录，应在提交前移出暂存区并修正忽略规则。不要把“仓库是私有的”当作密钥管理方案；私有仓库也可能因权限配置、日志或依赖服务而扩大可见范围。

常见问题

安装成功但程序仍提示找不到包。 通常是安装和运行使用了不同解释器。重新激活环境，并分别检查 python -m pip --version 与 python -c "import sys; print(sys.executable)"。

换电脑后复制 .venv 能否直接用。 不建议。虚拟环境中可能包含绝对路径和平台相关文件，应复制代码与依赖清单，再重新运行 python3 -m venv .venv 和安装命令。

生产环境也使用 .env 吗。 .env 适合本地开发。部署时优先使用运行平台提供的密钥管理或环境变量注入能力，避免把秘密放进镜像、部署脚本和配置仓库。

小结

一套可靠的入门环境应满足四点：每个项目使用独立虚拟环境；依赖版本有清单可恢复；密钥只通过环境变量或密钥系统注入；提交前能确认秘密和生成目录未进入 Git。完成这些准备后，下一步就可以选择模型服务，发出第一次真实 API 请求，并为超时、限流和无效响应增加错误处理。

搜索时光笔记