AI Agent / 系统课时
配置 Python 项目环境
配置 Python 项目环境
本课用 Python 3.11 或更高版本创建虚拟环境,安装后续示例的直接依赖,并记录当前环境实际解析出的版本。
学习目标
- 检查 Python 与 pip 是否满足项目要求
- 使用虚拟环境隔离项目依赖
- 用依赖文件复现并验证开发环境
前置检查
先确认当前终端可以调用 Python 3.11 或更高版本。macOS 和 Linux 通常使用 python3;Windows 可使用 py -3.11,后续命令中的解释器名称按本机实际情况替换。
python3 --version
python3 -m pip --version预期输出
Python 3.11.<PATCH>
pip <VERSION> from <PATH> (python 3.11)<PATCH>、<VERSION> 和 <PATH> 会随安装版本与系统路径变化。若 Python 版本低于 3.11,应先升级解释器;系统 Python 的 pip 缺失时,仍可尝试创建带 pip 的虚拟环境。若发行版未提供 venv 或 ensurepip 组件,先按该发行版的说明安装 Python 虚拟环境支持。
初始化虚拟环境
在项目根目录创建 .venv,再激活它。虚拟环境会为当前项目提供独立解释器和依赖目录,避免与系统 Python 或其他项目互相污染。
mkdir agent-project
cd agent-project
python3 -m venv .venv
source .venv/bin/activate
python -c "import sys; print(sys.prefix != sys.base_prefix)"预期输出
TrueWindows PowerShell 可以直接运行虚拟环境内的解释器,不依赖激活脚本。
New-Item -ItemType Directory -Path agent-project
Set-Location agent-project
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -c "import sys; print(sys.prefix != sys.base_prefix)"若使用的是更高版本的 Python Launcher,将 -3.11 换成已安装版本。以下各处的 python -m pip 可换成 .\.venv\Scripts\python.exe -m pip。
固化并安装依赖
把项目允许的直接依赖范围保存为 requirements.txt。用任意编辑器都可以创建这个文件,下面的写入命令适用于 Bash。下面选择 HTTP 客户端和环境变量加载库,足以支撑后续 Agent 接口调用与密钥配置。
cat > requirements.txt <<'EOF'
httpx>=0.27,<1.0
python-dotenv>=1.0,<2.0
EOF
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -c "import httpx, dotenv; print('environment ready')"预期输出
<INSTALL_LOG>
environment ready<INSTALL_LOG> 代表 pip 根据本机缓存、平台和已安装版本产生的动态日志;最终出现 environment ready 才说明两个依赖都能被当前虚拟环境导入。requirements.txt 中的范围允许不同日期解析出不同版本。在干净的项目环境验证后,可以执行 python -m pip freeze > requirements-resolved.txt 保存实际解析快照,随后用 python -m pip install -r requirements-resolved.txt 在相同平台和 Python 版本下复装,再执行 python -m pip check。快照不包含解释器、平台或软件包哈希,跨平台部署仍需分别校验。
建立最小项目结构
环境就绪后,可采用下面的最小结构,把业务代码、测试和环境变量示例分开管理。
agent-project/
├── .venv/
├── src/
│ └── __init__.py
├── tests/
├── .env.example
├── .gitignore
└── requirements.txt.gitignore 至少应忽略 .venv/、.env、__pycache__/ 和 .pytest_cache/。真实密钥只放在本地 .env 或密钥管理服务中,仓库只提交不含敏感值的 .env.example。
验证与典型失败
环境验收应同时确认解释器路径、虚拟环境状态和依赖导入结果。若安装后仍提示模块不存在,最常见原因不是依赖没装,而是 IDE 或终端使用了另一个 Python 解释器。
| 现象 | 常见原因 | 处理方式 |
|---|---|---|
python 版本仍然过低 |
虚拟环境由旧解释器创建 | 删除 .venv,用 Python 3.11+ 重新创建 |
| 安装成功但导入失败 | pip 与运行程序不属于同一解释器 | 始终使用 python -m pip 安装 |
| PowerShell 禁止执行激活脚本 | 当前会话执行策略受限 | 直接运行 .\.venv\Scripts\python.exe |
| 团队成员安装结果不同 | 依赖范围过宽或文件未同步 | 收紧版本范围,并统一更新依赖文件 |
不要通过全局安装来“临时解决”模块缺失,否则问题会在其他机器或部署环境重新出现。修复后应重新执行导入验证命令,确认输出仍为 environment ready。
本课总结
- Python 3.11+ 和独立虚拟环境是项目可复现的基础
- 使用
python -m pip可以避免解释器与 pip 指向不同环境 - 依赖文件、导入验证和敏感信息隔离共同构成完整的环境验收
下一课预告
下一课创建配置模块,随后两课直接导入该模块发起调用。