AI Agent / 系统课时
开发环境与工具链搭建
开发环境与工具链搭建
本课使用 Python 3.11 或更高版本、Git 和独立虚拟环境。环境检查会验证两个 Python 包可导入,并报告密钥变量的本地配置状态。完成这些步骤后,可以先运行第一节的离线示例。
创建独立环境
在 macOS 或 Linux 终端运行以下命令。python3 -m venv 若提示缺少 venv 支持,先安装系统对应的 Python 虚拟环境组件。
python3 --version
git --version
mkdir ai-agent-demo
cd ai-agent-demo
python3 -m venv .venv
.venv/bin/python -m pip install openai python-dotenv在 Windows PowerShell 中,可以用 Python Launcher 创建虚拟环境。若安装方式只提供 python 命令,把两处 py -3 换成 python。
py -3 --version
git --version
New-Item -ItemType Directory -Path ai-agent-demo
Set-Location ai-agent-demo
py -3 -m venv .venv
.\.venv\Scripts\python.exe -m pip install openai python-dotenv两组命令都直接调用虚拟环境内的解释器来安装依赖。这样即使 PowerShell 的脚本执行策略限制激活脚本,也可以正常运行。Python 版本应为 3.11 或更高,Git 能输出版本号。若后续需要在另一台电脑复现相同依赖,可保存同一个解释器的 -m pip freeze 输出。
准备环境变量文件
在项目根目录先创建 .gitignore。
.venv/
.env
__pycache__/
*.pyc需要配置模型 API 时,可在同一目录创建 .env。示例中的值是占位符。
OPENAI_API_KEY=replace-with-your-key真实密钥可由运行环境注入,或者保存在本机的 .env 中。可以用 git check-ignore .env 检查忽略规则。如果文件已被 Git 跟踪,新增忽略规则不会停止跟踪。若真实密钥已提交,应撤销并替换该密钥。
运行本地自检
在项目根目录保存为 check_env.py。脚本始终从自身所在目录读取 .env。已有同名环境变量优先,输出只包括版本号和状态。
import os
from importlib.metadata import version
from pathlib import Path
from dotenv import load_dotenv
from openai import OpenAI
project_dir = Path(__file__).resolve().parent
load_dotenv(project_dir / ".env", override=False)
value = os.getenv("OPENAI_API_KEY", "").strip()
if not value:
status = "missing"
elif value == "replace-with-your-key":
status = "placeholder"
else:
status = "present"
print(f"Project: {project_dir.name}")
print(f"openai SDK: {version('openai')}")
print(f"python-dotenv: {version('python-dotenv')}")
print(f"API key configuration: {status}")macOS 或 Linux 使用 .venv/bin/python check_env.py,Windows 使用 .\.venv\Scripts\python.exe .\check_env.py。开头应显示项目目录和两个包的实际版本。没有配置时末行显示 missing,照抄示例值显示 placeholder,提供非空值时显示 present。present 只说明变量有值。鉴权、项目权限和模型可用性需要另行验证,本脚本不发起网络请求。
根据故障现象排查
- 找不到虚拟环境内的 Python 时,检查创建命令是否成功,以及当前目录是否正确。
- 导入失败时,用虚拟环境解释器运行
-m pip show openai python-dotenv,在同一环境中补装缺失依赖。 - 环境变量意外覆盖了文件值时,核对启动终端的环境设置。脚本使用
override=False保留进程已有配置。
官方安装和后续 API 调用方式见 OpenAI Python SDK 快速入门。