Python 环境与项目脚手架

AI Agent（智能体）不是神秘的黑盒：剥开外壳，它就是一个「循环调用大模型 + 工具」的程序。本系列用 8 章手把手从 0 搭出一个可运行的智能体，全部代码放进同一个项目文件夹、逐章叠加。本章先把地基打好：装好 Python、建好项目目录、配好密钥环境变量，并让第一个「模型回复」程序跑通。

1. 安装 Python（3.10 以上）

本系列使用 OpenAI 官方 SDK v1.x，需要 Python 3.10+。打开终端确认版本：

python --version
# 输出示例：Python 3.11.9（版本号视安装而定，不低于 3.10 即可）

没有 Python 就去官网下载安装，Windows 安装时务必勾选 Add Python to PATH。喜欢新工具的读者也可以装 uv（一个用 Rust 写的 Python 包管理器），后面第 2 步给 uv 方案。

2. 创建项目与虚拟环境

先在任意位置新建项目文件夹 agent_demo，并在其中创建虚拟环境（venv），把依赖与系统隔离：

mkdir agent_demo
cd agent_demo
python -m venv .venv

激活虚拟环境（Windows 与 macOS/Linux 命令不同）：

.venv\Scripts\activate      # Windows PowerShell / CMD
source .venv/bin/activate   # macOS / Linux

激活后命令行提示符会出现 (.venv)，说明当前用的就是环境里的 Python。使用 uv 只需一条命令，效果等价：

uv init agent_demo && cd agent_demo
uv venv .venv              # 创建 .venv；uv run 会自动用它

3. 安装依赖

本系列只需要两个包：openai（SDK v1.x，统一调用 OpenAI 兼容接口）和 python-dotenv（读取 .env 配置）：

pip install openai python-dotenv
# 输出示例：Successfully installed openai-1.x.x python-dotenv-1.x.x ...

后续章节不再新增第三方依赖——循环、工具、结构化输出全部手写，这正是本系列的目的。

4. 项目目录结构

最终的项目结构如下（随章节推进逐步补齐，斜体注释说明用途）：

agent_demo/
├── .env              # 密钥与配置，不入库
├── .gitignore        # 忽略 .env / .venv 等
├── hello.py          # 第 1 章：第一个可运行脚本
├── llm_client.py     # 第 2 章：统一模型客户端
├── extract.py        # 第 4 章：结构化输出封装
├── tools.py          # 第 5 章：工具注册表
├── main.py           # 第 3/6/7 章：对话与智能体主程序
└── agent.py          # 第 8 章：可控的智能体运行器

代码文件都放在项目根目录、与 .env 同级，这样 python-dotenv 才能自动找到配置文件。

5. 配置 .env：密钥与模型

新建 .env，把密钥写进去（千万不要提交到代码仓库）。三行配置对应三种可切换的 OpenAI 兼容服务，以各家官方文档为准：

# 必填：任选一家的 API Key，如 OpenAI / DeepSeek / 通义千问
LLM_API_KEY=sk-你的密钥

# 接口地址（三选一，默认 OpenAI）
LLM_BASE_URL=https://api.openai.com/v1
# LLM_BASE_URL=https://api.deepseek.com
# LLM_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

# 模型名：默认 deepseek-chat；换服务商时同步修改（如 gpt-4o-mini、qwen-plus）
LLM_MODEL=deepseek-chat

# 单次请求超时（秒），可选
LLM_TIMEOUT=60

要点：换服务商 = 换密钥 + 换 LLM_BASE_URL + 换 LLM_MODEL，代码一行都不用改；接口地址与模型名请以各家官方文档为准（例如通义千问的兼容模式地址写法随时间可能调整）。

6. 配置 .gitignore

再建一个 .gitignore，防止密钥和虚拟环境被 git 跟踪：

.env
.venv/
__pycache__/
*.pyc

.env 一旦被提交到公开仓库，密钥就泄露了，务必先加忽略再提交。

7. 第一个程序 hello.py

新建 hello.py，用 openai SDK 发一条消息、打印模型回复：

"""第一个程序：调用模型并打印回复。"""
import os

from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()  # 读取项目根目录的 .env（需在 agent_demo 下运行）

client = OpenAI(
    api_key=os.getenv("LLM_API_KEY"),                          # 读 .env
    base_url=os.getenv("LLM_BASE_URL", "https://api.openai.com/v1"),
)

resp = client.chat.completions.create(
    model=os.getenv("LLM_MODEL", "deepseek-chat"),
    messages=[{"role": "user", "content": "你好，请用一句话介绍你自己"}],
)
print(resp.choices[0].message.content)

8. 运行

在 agent_demo 目录下运行：

python hello.py
# 输出示例（随模型与时间变化）：
# 你好！我是 DeepSeek，一个由深度求索公司开发的 AI 助手，擅长回答问题、辅助创作与编程……

看到类似输出，说明 SDK、密钥、网络、模型名全部打通——之后的章节都在这套地基上盖楼。

9. hello.py 逐行拆解

• from dotenv import load_dotenv：第三方库函数，把 .env 里的 LLM_API_KEY 等读进 os.environ，供下面 os.getenv 取用；.env 不写进代码，密钥才不会泄露。
• OpenAI(api_key=..., base_url=...)：构造 SDK 客户端。api_key 与 base_url 都从 .env 读，没读到时 base_url 用默认值兜底。
• client.chat.completions.create(...)：真正发起请求。model 指定模型名，messages 是对话消息列表——现在只有一条 user 消息（用户角色），多轮对话就是把更多消息塞进这个列表（第 3 章重点）。
• resp.choices[0].message.content：从响应里逐层取出助手文本：choices（候选回复，取第 0 个）→ message（消息对象）→ content（文本）。

10. 常见问题速查

• AuthenticationError：密钥无效或未填 LLM_API_KEY，检查 .env。
• NotFoundError / BadRequest：模型名不存在或该服务不支持，核对 LLM_MODEL 与 LLM_BASE_URL 的组合。
• APIConnectionError：网络不通。国内读者建议直接切 DeepSeek 或通义，无需代理。
• 提示找不到 .env：确认在 agent_demo 目录下运行，或改用绝对路径 load_dotenv("D:/xxx/.env")。
• 返回空内容：少数服务对纯问候类消息会过滤，属正常现象；正式场景按第 2 章封装统一处理。 小结：本章完成了环境安装、venv 隔离、openai+python-dotenv 安装、.env 密钥配置和 hello.py 首跑。密钥、地址、模型三件套集中放 .env，是后续所有章节「换服务商不改代码」的基础。