# 1.2 环境配置

> **Week 1 | Lesson 1.2 | 30 分钟**

---

## 学习目标

完成本课后，你将能够：

- 安装 Python 3.10+ 和 uv 包管理器
- 使用 uv 创建项目并管理依赖
- 配置 OpenAI API Key 环境变量
- 安装并运行 Ollama 本地模型
- 正确管理 `.env` 文件中的敏感信息
- 运行测试脚本验证环境是否正常

---

## 1. 安装 Python 3.10+

### 为什么需要 Python 3.10+？

本课程使用的 Agent 框架（OpenAI Agents SDK、LangGraph 等）需要 Python 3.10 或更高版本。Python 3.10 引入了更好的类型提示语法（`str | None`）和更清晰的模式匹配（`match/case`），这些都被现代 AI 框架广泛使用。

### 检查是否已安装

打开终端（Windows: PowerShell / CMD, Mac/Linux: Terminal），运行：

```bash
python --version
# 或
python3 --version
```

如果输出版本号 >= 3.10，可以直接跳到下一步。

### 安装 Python

**Windows：**
1. 访问 https://www.python.org/downloads/
2. 下载最新稳定版（推荐 3.12+）
3. **重要**：安装时勾选 "Add Python to PATH"
4. 完成后运行 `python --version` 验证

**macOS：**
```bash
# 使用 Homebrew 安装（推荐）
brew install python@3.12

# 验证
python3 --version
```

**Linux (Ubuntu/Debian)：**
```bash
sudo apt update
sudo apt install python3.12 python3.12-venv python3.12-dev
python3.12 --version
```

---

## 2. 安装 uv 包管理器

### 为什么不用 pip？

| 对比项 | pip + venv | uv |
|--------|-----------|-----|
| 安装速度 | 慢，需要逐一下载 | 快，全局缓存 + 并行下载 |
| 依赖解析 | 可能冲突，慢 | 用 Rust 编写，极快 |
| 虚拟环境管理 | 需要手动创建 venv | 内置，一条命令 |
| 跨项目隔离 | 需手动管理 | 自动处理 |
| 可复现性 | 需要手动维护 requirements.txt | 自动锁定依赖版本 |

简单说：**uv = pip + venv + poetry 的功能，但快 10-100 倍。**

### 安装 uv

**Windows (PowerShell)：**
```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

**macOS / Linux：**
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**验证安装：**
```bash
uv --version
# 输出示例: uv 0.6.x
```

### 初始化项目

```bash
# 创建项目目录
mkdir agent-hello && cd agent-hello

# 用 uv 初始化项目（指定 Python 版本）
uv init --python 3.12

# 查看项目结构
# agent-hello/
# ├── .python-version    # Python 版本锁定
# ├── pyproject.toml     # 项目配置（替代 requirements.txt）
# └── hello.py           # 示例文件
```

### 安装依赖

```bash
# 安装 OpenAI SDK（后续课程需要）
uv add openai

# 安装 python-dotenv（用于读取 .env 文件）
uv add python-dotenv

# uv 会自动创建虚拟环境并安装依赖
# 依赖信息记录在 pyproject.toml 和 uv.lock 中
```

### 运行代码

```bash
# 方式 1：uv run 自动使用虚拟环境
uv run python hello.py

# 方式 2：先激活虚拟环境，再运行
uv venv  # 如果还没创建
source .venv/bin/activate   # Mac/Linux
.venv\Scripts\activate      # Windows
python hello.py
```

---

## 3. 配置 OpenAI API Key

### 如何获取 API Key

1. 访问 https://platform.openai.com/
2. 注册或登录账号
3. 进入 API Keys 页面：https://platform.openai.com/api-keys
4. 点击 "Create new secret key"
5. 复制并**妥善保存**（只显示一次！）

### 设置环境变量

**为什么用环境变量？**
- 不要把 API Key 硬编码到代码里
- 不要提交到 Git 仓库
- 不同环境可以配置不同的 Key

#### 方式 A：使用 .env 文件（推荐）

在项目根目录创建 `.env` 文件：

```bash
# .env 文件 — 存放环境变量
# 注意：这个文件绝不能提交到 Git！

# OpenAI API 配置
OPENAI_API_KEY=sk-proj-你的密钥在这里

# 可选：指定 API 基础 URL（国内用户可能需要代理）
# OPENAI_BASE_URL=https://api.openai.com/v1
```

然后在代码中读取：

```python
# main.py
from dotenv import load_dotenv
import os

# 加载 .env 文件中的环境变量
load_dotenv()

# 读取 API Key
api_key = os.getenv("OPENAI_API_KEY")

if not api_key:
    print("错误：未找到 OPENAI_API_KEY 环境变量")
    print("请创建 .env 文件并设置 API Key")
else:
    print("API Key 已加载！")
    # 注意：不要打印完整的 API Key，只显示前几位
    print(f"Key 前缀: {api_key[:10]}...")
```

#### 方式 B：直接在终端设置（临时）

```bash
# Mac/Linux
export OPENAI_API_KEY="sk-proj-你的密钥"

# Windows PowerShell
$env:OPENAI_API_KEY = "sk-proj-你的密钥"

# Windows CMD
set OPENAI_API_KEY=sk-proj-你的密钥
```

### 保护 .env 文件

```bash
# 创建 .gitignore 文件，确保 .env 不被提交
echo ".env" > .gitignore
echo ".venv" >> .gitignore
echo "__pycache__/" >> .gitignore
echo "*.pyc" >> .gitignore
```

---

## 4. Ollama：免费本地模型方案

如果你不想使用付费的 OpenAI API，或者想离线运行，Ollama 是一个完美的替代方案。

### 什么是 Ollama？

Ollama 是一个开源工具，让你**在本地运行大语言模型**。它支持多种模型，安装简单，跨平台。

### 安装 Ollama

**macOS / Windows：**
1. 访问 https://ollama.com
2. 下载安装包，双击安装

**Linux：**
```bash
curl -fsSL https://ollama.com/install.sh | sh
```

### 下载并运行模型

```bash
# 下载小型模型（约 4.7 GB，适合大多数电脑）
ollama pull qwen2.5:7b

# 或者更小的模型（约 2 GB，适合低配置电脑）
ollama pull qwen2.5:1.5b

# 或者使用 Google 的 Gemma 模型
ollama pull gemma2:2b

# 查看已下载的模型
ollama list
```

### 测试模型

```bash
# 直接在终端与模型对话
ollama run qwen2.5:7b

# 输入你的问题，模型会回复
# 按 Ctrl+D 退出
```

### 在 Python 中使用 Ollama

Ollama 启动后会在本地运行一个 API 服务（默认端口 11434）。我们可以用 OpenAI SDK 的兼容模式来调用它：

```python
# ollama_test.py
"""使用 Ollama 本地模型进行测试"""
from openai import OpenAI

# 创建指向 Ollama 的客户端
client = OpenAI(
    base_url="http://localhost:11434/v1",  # Ollama 的 API 地址
    api_key="ollama",  # Ollama 不需要 API Key，随便填一个就行
)

# 发起对话
response = client.chat.completions.create(
    model="qwen2.5:7b",  # 使用已下载的模型
    messages=[
        {"role": "system", "content": "你是一个友好的助手。"},
        {"role": "user", "content": "用一句话介绍 Python"},
    ],
)

print(response.choices[0].message.content)
# 输出示例: Python 是一种简洁易读的高级编程语言，
# 广泛用于 Web 开发、数据科学、人工智能等领域。
```

运行：
```bash
# 确保 Ollama 正在运行（在另一个终端窗口）
ollama serve

# 在终端运行脚本
uv run python ollama_test.py
```

---

## 5. 环境测试脚本

创建一个完整的测试脚本，验证所有组件是否正常工作：

```python
# test_env.py
"""
环境配置验证脚本
运行此脚本检查所有依赖是否正确安装
"""
from dotenv import load_dotenv
import os
import sys


def check_python_version():
    """检查 Python 版本"""
    version = sys.version_info
    print(f"Python 版本: {version.major}.{version.minor}.{version.micro}")
    if version.major == 3 and version.minor >= 10:
        print("  ✓ Python 版本符合要求 (>= 3.10)")
        return True
    else:
        print("  ✗ Python 版本过低，需要 3.10+")
        return False


def check_dotenv():
    """检查 .env 文件和 API Key"""
    load_dotenv()
    api_key = os.getenv("OPENAI_API_KEY")

    if api_key and api_key.startswith("sk-"):
        print(f"  ✓ OpenAI API Key 已配置 ({api_key[:10]}...)")
        return True
    elif api_key == "ollama":
        print("  ✓ 使用 Ollama 本地模式")
        return True
    else:
        print("  ✗ 未找到有效的 OPENAI_API_KEY")
        print("    提示：创建 .env 文件并设置 OPENAI_API_KEY=sk-...")
        return False


def check_openai_sdk():
    """检查 OpenAI SDK 是否可用"""
    try:
        from openai import OpenAI
        print("  ✓ OpenAI SDK 已安装")
        return True
    except ImportError:
        print("  ✗ OpenAI SDK 未安装")
        print("    运行: uv add openai")
        return False


def check_ollama():
    """检查 Ollama 是否可用"""
    import urllib.request
    try:
        response = urllib.request.urlopen("http://localhost:11434")
        if response.status == 200:
            print("  ✓ Ollama 服务正在运行 (localhost:11434)")
            return True
    except Exception:
        print("  ⚠ Ollama 服务未运行（如果使用本地模型，请启动它）")
        print("    运行: ollama serve")
        return False
    return False


def test_api_connection():
    """测试 API 连接"""
    from openai import OpenAI

    load_dotenv()
    api_key = os.getenv("OPENAI_API_KEY")

    # 判断使用 OpenAI 还是 Ollama
    if api_key == "ollama":
        client = OpenAI(
            base_url="http://localhost:11434/v1",
            api_key="ollama",
        )
        model = "qwen2.5:7b"
    else:
        client = OpenAI(api_key=api_key)
        model = "gpt-4o-mini"

    print(f"\n正在测试连接 (模型: {model})...")

    try:
        response = client.chat.completions.create(
            model=model,
            messages=[{"role": "user", "content": "你好，请回复'连接成功'"}],
            max_tokens=20,
        )
        reply = response.choices[0].message.content.strip()
        print(f"  ✓ 连接成功！模型回复: {reply}")
        return True
    except Exception as e:
        print(f"  ✗ 连接失败: {e}")
        return False


def main():
    print("=" * 50)
    print("AI Agent 实战营 — 环境配置验证")
    print("=" * 50)
    print()

    results = []

    print("[1/4] 检查 Python 版本")
    results.append(check_python_version())
    print()

    print("[2/4] 检查 .env 配置")
    results.append(check_dotenv())
    print()

    print("[3/4] 检查 OpenAI SDK")
    results.append(check_openai_sdk())
    print()

    print("[4/4] 检查 Ollama（可选）")
    check_ollama()  # 可选，不影响结果
    print()

    # 如果前面都通过了，测试 API 连接
    if all(results):
        print("[测试] API 连接测试")
        test_api_connection()
        print()

    # 总结
    print("=" * 50)
    if all(results):
        print("✓ 所有检查通过！环境配置完成！")
    else:
        print("✗ 部分检查未通过，请查看上面的提示并修复")
    print("=" * 50)


if __name__ == "__main__":
    main()
```

运行测试：

```bash
uv run python test_env.py
```

预期输出：

```
==================================================
AI Agent 实战营 — 环境配置验证
==================================================

[1/4] 检查 Python 版本
Python 版本: 3.12.x
  ✓ Python 版本符合要求 (>= 3.10)

[2/4] 检查 .env 配置
  ✓ OpenAI API Key 已配置 (sk-proj-xxx...)

[3/4] 检查 OpenAI SDK
  ✓ OpenAI SDK 已安装

[4/4] 检查 Ollama（可选）
  ⚠ Ollama 服务未运行（如果使用本地模型，请启动它）
    运行: ollama serve

[测试] API 连接测试
正在测试连接 (模型: gpt-4o-mini)...
  ✓ 连接成功！模型回复: 连接成功

==================================================
✓ 所有检查通过！环境配置完成！
==================================================
```

---

## 6. 跨平台注意事项

### Windows

- 使用 **PowerShell** 而非 CMD（更好的兼容性）
- 虚拟环境激活路径：`.venv\Scripts\activate`
- 如果遇到编码问题，在文件开头添加：`# -*- coding: utf-8 -*-`
- 推荐安装 **Windows Terminal**（微软商店免费）

### macOS

- 虚拟环境激活路径：`source .venv/bin/activate`
- 如果遇到权限问题，检查 Gatekeeper 设置
- Apple Silicon (M1/M2/M3) 用户运行 Ollama 性能优秀

### Linux

- 包管理器因发行版而异（apt / yum / pacman）
- 确保安装了 `python3-venv` 包
- Ollama 在 Linux 上支持 GPU 加速（NVIDIA CUDA）

---

## 动手练习

### 练习 1：创建你的第一个 Agent 项目

```bash
# 1. 创建项目目录
mkdir ~/agent-projects/week1 && cd ~/agent-projects/week1

# 2. 初始化项目
uv init --python 3.12

# 3. 安装依赖
uv add openai python-dotenv

# 4. 创建 .env 文件（填入你的 API Key）
echo "OPENAI_API_KEY=sk-proj-你的密钥" > .env

# 5. 创建 .gitignore
echo ".env" > .gitignore
echo ".venv" >> .gitignore
```

### 练习 2：运行环境测试脚本

将上面 `test_env.py` 的内容复制到项目中并运行：

```bash
uv run python test_env.py
```

如果全部通过，说明环境配置成功。

---

## 本节总结

- **Python 3.10+** 是运行 AI Agent 框架的最低要求
- **uv** 是现代 Python 包管理工具，比 pip 快 10-100 倍，推荐替代 pip/venv/poetry
- **OpenAI API Key** 通过 `.env` 文件管理，绝不硬编码或提交到 Git
- **Ollama** 提供免费的本地模型方案，无需 API Key，适合学习和低使用量场景
- 使用 **测试脚本** 验证环境，确保所有组件正常工作
- 不同操作系统有细微差异，注意路径和命令的区别

下一课，我们将用配置好的环境，构建第一个真正的 AI Agent。