AI Agent / 系统课时

开发环境与工具链搭建

开发环境与工具链搭建

本课使用 Python 3.11 或更高版本、Git 和独立虚拟环境。环境检查会验证两个 Python 包可导入,并报告密钥变量的本地配置状态。完成这些步骤后,可以先运行第一节的离线示例。

创建独立环境

在 macOS 或 Linux 终端运行以下命令。python3 -m venv 若提示缺少 venv 支持,先安装系统对应的 Python 虚拟环境组件。

bash
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。

powershell
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。

text
.venv/
.env
__pycache__/
*.pyc

需要配置模型 API 时,可在同一目录创建 .env。示例中的值是占位符。

dotenv
OPENAI_API_KEY=replace-with-your-key

真实密钥可由运行环境注入,或者保存在本机的 .env 中。可以用 git check-ignore .env 检查忽略规则。如果文件已被 Git 跟踪,新增忽略规则不会停止跟踪。若真实密钥已提交,应撤销并替换该密钥。

运行本地自检

在项目根目录保存为 check_env.py。脚本始终从自身所在目录读取 .env。已有同名环境变量优先,输出只包括版本号和状态。

python
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 快速入门。

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

目录与阅读设置

记录一个想法

开发环境与工具链搭建

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

登录哪都通