AI Agent / 系统课时

配置 Python 项目环境

配置 Python 项目环境

本课用 Python 3.11 或更高版本创建虚拟环境,安装后续示例的直接依赖,并记录当前环境实际解析出的版本。

学习目标

  • 检查 Python 与 pip 是否满足项目要求
  • 使用虚拟环境隔离项目依赖
  • 用依赖文件复现并验证开发环境

前置检查

先确认当前终端可以调用 Python 3.11 或更高版本。macOS 和 Linux 通常使用 python3;Windows 可使用 py -3.11,后续命令中的解释器名称按本机实际情况替换。

bash
python3 --version
python3 -m pip --version

预期输出

text
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 或其他项目互相污染。

bash
mkdir agent-project
cd agent-project
python3 -m venv .venv
source .venv/bin/activate
python -c "import sys; print(sys.prefix != sys.base_prefix)"

预期输出

text
True

Windows PowerShell 可以直接运行虚拟环境内的解释器,不依赖激活脚本。

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 接口调用与密钥配置。

bash
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')"

预期输出

text
<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。快照不包含解释器、平台或软件包哈希,跨平台部署仍需分别校验。

建立最小项目结构

环境就绪后,可采用下面的最小结构,把业务代码、测试和环境变量示例分开管理。

text
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 指向不同环境
  • 依赖文件、导入验证和敏感信息隔离共同构成完整的环境验收

下一课预告

下一课创建配置模块,随后两课直接导入该模块发起调用。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置 Python 项目环境

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通