AI 智能体开发 · Day 1 详细学习手册

主题：AI 全景认知 + 开发环境搭建 + 第一次 LLM 调用

总时长 ：2-2.5 小时（可分两次完成）

难度：零基础入门

产出：环境就绪 + 3 个可运行脚本 + 结构化笔记

前置条件：会 Python 基础语法（变量、函数、字典、import）、电脑能联网

学习目标与知识地图
[Part A：AI 全景认知（40 分钟）](#Part A：AI 全景认知（40 分钟）)
[Part B：开发环境搭建（30 分钟）](#Part B：开发环境搭建（30 分钟）)
[Part C：API Key 获取与项目初始化（20 分钟）](#Part C：API Key 获取与项目初始化（20 分钟）)
[Part D：第一次调用 LLM（30 分钟）](#Part D：第一次调用 LLM（30 分钟）)
[Part E：进阶练习------理解 API 响应结构（20 分钟）](#Part E：进阶练习——理解 API 响应结构（20 分钟）)
今日笔记模板
验收清单
[常见问题 FAQ](#常见问题 FAQ)
扩展资源
明日预告

1. 学习目标与知识地图

你今天要达成的目标

概念层面（能用自己话讲清楚）：

AI、ML、DL、NLP、LLM 之间的包含关系
预训练、微调、RLHF 三个阶段分别做什么
GPT 从 1 到 4o 的演进脉络
LLM 的输入输出是什么（文本进、文本出）
Token 是什么，为什么它重要

操作层面（亲手做过）：

Python 虚拟环境创建和激活
pip 安装第三方库
获取至少一个 LLM API Key
用代码调用 LLM 并拿到回复
理解 API 响应中的每个字段

知识地图

复制代码

Part A: 概念认知
  ├── AI 全景：AI > ML > DL > NLP > LLM
  ├── 训练三阶段：预训练 → 微调 → RLHF
  ├── GPT 演进史：GPT-1 → 2 → 3 → ChatGPT → 4 → 4o → o1
  └── LLM 的工作方式：文本进 → Token 化 → 模型推理 → Token 出 → 文本

Part B: 环境搭建
  ├── Python 版本检查
  ├── 虚拟环境创建
  ├── pip 换源 + 安装依赖
  └── IDE/编辑器选择

Part C: API 准备
  ├── 平台对比（DeepSeek / OpenAI / 阿里百炼）
  ├── 注册并获取 API Key
  ├── .env 环境变量管理
  └── 项目目录结构

Part D: Hello World
  ├── 最简 API 调用代码
  ├── 逐行代码解析
  ├── 运行与验证
  └── 报错处理

Part E: 深入理解
  ├── API 响应对象结构
  ├── Token 用量分析
  └── 多次调用实验

2. Part A：AI 全景认知（40 分钟）

这部分不需要电脑，拿张纸和笔跟着画图就行。概念清楚是后面所有实操的基础。

2.1 AI 的层级关系（10 分钟）

你可能经常看到 AI、ML、DL、NLP、LLM 这些词混在一起用，它们其实是包含关系：

复制代码

AI（人工智能）------ 最外层概念
│
├── ML（机器学习）------ AI 的一个子领域
│   │   核心思想：不靠人写规则，让机器从数据中"学"规律
│   │   例子：垃圾邮件分类（给它几千封邮件，它自己学会判断）
│   │
│   ├── DL（深度学习）------ ML 的一个子领域
│   │   │   核心思想：用多层神经网络（模仿大脑神经元结构）
│   │   │   例子：人脸识别、语音转文字
│   │   │
│   │   ├── CV（计算机视觉）------ 处理图片/视频
│   │   │   例子：自动驾驶识别路标
│   │   │
│   │   ├── Speech（语音处理）------ 处理声音
│   │   │   例子：Siri 听懂你说话
│   │   │
│   │   └── NLP（自然语言处理）------ 处理文本/语言
│   │       │   例子：机器翻译、情感分析
│   │       │
│   │       └── LLM（大语言模型）------ NLP 的最新阶段
│   │               例子：ChatGPT、DeepSeek、文心一言
│   │
│   ├── 传统 ML（非深度学习）
│   │   例子：决策树、SVM、随机森林
│   │
│   └── 强化学习
│       例子：AlphaGo 下围棋
│
├── 符号 AI（专家系统）------ 早期 AI 方式
│   核心思想：人写规则（if-then），机器执行
│   问题：规则写不完，复杂场景失效
│
└── 其他 AI 分支...

一句话记忆：AI 是最大的圈，ML 是 AI 里的圈，DL 是 ML 里的圈，NLP 是 DL 里的圈，LLM 是 NLP 里的圈。一层套一层。

关键区分------传统 NLP vs LLM：

维度	传统 NLP（2018 以前）	LLM（2018 以后）
工作方式	人工设计特征 + 统计模型	预训练 + 海量参数自动学习
例子	分词 → 词性标注 → 句法分析 → 规则匹配	给一段话，直接预测下一个词
能力	单一任务（只能做被训练的那件事）	通用能力（一个模型做很多事）
开发成本	每个任务都要标注数据 + 训练	调 API 就行
局限	规则覆盖不全就出错	会"幻觉"（编造信息）

2.2 LLM 训练三阶段（15 分钟）

这是理解"为什么 ChatGPT 比单纯的 GPT-3 好用"的关键。

阶段 1：预训练（Pre-training）------ 学会"语言"

复制代码

做什么：
  从互联网上收集万亿级别的文本（网页、书籍、论文、代码...）
  让模型做"完形填空"：给前半句，预测下一个词

花了什么：
  - 几千张 GPU 跑几个月
  - 花费几百万到上千万美元
  - 电费用了几百万度

学会了什么：
  - 语法规则（什么句子通顺）
  - 世界知识（巴黎是法国首都）
  - 常识推理（冰会融化）
  - 多语言能力

类比：
  一个人把整个图书馆的书读了一遍
  他什么都"知道"一点，但你问他问题，他可能给你一段百科式的文字
  而不是像聊天一样回答你

阶段 2：监督微调（Supervised Fine-Tuning, SFT）------ 学会"对话"

复制代码

做什么：
  人工写几万条"问题-回答"对
  让模型学会：用户问问题 → 我应该给出有用的回答

类比：
  读完图书馆的人，现在去做模拟题
  学会"考试格式"------别人问你问题，你要直接回答，不是写百科全书

效果：
  模型从"续写文本"变成了"回答问题"
  但回答质量参差不齐，有时候好，有时候差

阶段 3：RLHF（人类反馈强化学习）------ 学会"说人话"

复制代码

做什么：
  1. 模型对同一个问题生成多个回答
  2. 人工标注员给回答排序（哪个好哪个差）
  3. 训练一个"奖励模型"学会人类的偏好
  4. 用强化学习让 LLM 优化自己的回答，追求更高"奖励"

学会了什么：
  - 回答要有礼貌、有帮助、不有害
  - 不知道就说不知道，不要编
  - 给出结构化的、易读的回答

类比：
  老师批改作文，打分 + 写评语
  学生根据反馈调整写作风格
  最终学会"怎么写才是好作文"

这就是 ChatGPT 中"Chat"的含义------它不是只会续写文本，
而是被训练成"会聊天的助手"

三阶段总结图：

复制代码

预训练                    微调                      RLHF
┌──────────┐          ┌──────────┐          ┌──────────┐
│ 海量文本  │    →     │ 问答数据  │    →     │ 人类偏好  │
│ 预测下一个│          │ 学会回答  │          │ 学会说好  │
│ 词        │          │ 问题      │          │          │
├──────────┤          ├──────────┤          ├──────────┤
│ 成本：极高│          │ 成本：中  │          │ 成本：高  │
│ 数据：万亿│          │ 数据：万级│          │ 数据：万级│
│ 谁能做：  │          │ 谁能做：  │          │ 谁能做：  │
│ 大厂      │          │ 中小公司  │          │ 大厂      │
└──────────┘          └──────────┘          └──────────┘
    GPT-3                  GPT-3.5               ChatGPT
  (会续写)               (会回答)              (会说人话)

自测：如果你能回答下面三个问题，这部分就过关了------

预训练和微调的区别是什么？

预训练用海量无标注文本学语言能力；微调用有标注的问答对学回答格式。
为什么 GPT-3 发布时没有"爆红"，而 ChatGPT 发布后炸了？

GPT-3 只有预训练，续写文本但不擅长对话；ChatGPT 加了 RLHF，回答质量好、会聊天。
如果你想让模型学会你们公司的知识，应该做哪个阶段？

微调（SFT），或者更实际的做法是 RAG（后面会学）。

2.3 GPT 演进时间线（10 分钟）

不用背年份，重点是理解每次突破解决了什么问题。

时间	模型	参数量	解决了什么问题	意义
2018.06	GPT-1	1.17 亿	证明"预训练+微调"可行	从此 NLP 进入预训练时代
2019.02	GPT-2	15 亿	零样本能力初现	不微调也能做任务（但效果一般）
2020.05	GPT-3	1750 亿	涌现能力（Few-shot）	参数量大到一定程度，突然"开窍"
2022.11	ChatGPT	（GPT-3.5）	RLHF 让模型说人话	AI 第一次"出圈"，用户破亿
2023.03	GPT-4	（未公开）	推理能力大幅提升	通过律师考试前 10%
2023.05	GPT-4	---	多模态（看图）	不只是文本，能理解图片
2024.05	GPT-4o	---	实时语音+视觉	延迟低到可以实时对话
2024.09	o1	---	"慢思考"推理	数学/编程能力跳升
2025-26	o3 等	---	推理进一步强化	复杂问题分步推理

三个关键转折点（划重点）：

GPT-3 的"涌现"：参数量从 15 亿到 1750 亿，模型突然学会了之前做不到的事（Few-shot learning）。这证明"大力出奇迹"------模型够大，能力就够强。
ChatGPT 的 RLHF：技术上不是革命（GPT-3.5 的模型早就有了），但 RLHF 让输出质量飞跃。这证明了"对齐"（让 AI 的行为符合人类期望）的重要性。
o1 的"慢思考"：之前的模型是"快思考"------看到问题立刻回答。o1 引入了"先想再答"的推理链（Chain-of-Thought），在数学、编程等需要推理的任务上大幅提升。

国内模型对应（你开发时可能用到）：

国内模型	对标	特点
DeepSeek-V3	GPT-4o 级别	性价比极高，开源
Qwen (通义千问)	GPT-4 级别	阿里出品，中文好
GLM-4 (智谱)	GPT-4 级别	清华系，中文理解强
文心一言 (百度)	GPT-3.5~4	百度出品，生态全

2.4 LLM 的输入输出（5 分钟）

理解 LLM 最根本的一件事：它的输入是文本，输出也是文本。

复制代码

你输入：
  "用一句话解释什么是大语言模型"
        │
        ▼
┌───────────────────┐
│   LLM 内部处理      │
│                    │
│  1. 文本 → Token   │  （把文字切成小块）
│  2. Token → 向量    │  （把小块变成数字）
│  3. 模型推理        │  （算出下一个最可能的 Token）
│  4. Token → 文本    │  （把数字变回文字）
│  5. 重复 3-4        │  （一个字一个字生成完整回答）
│                    │
└───────────────────┘
        │
        ▼
输出：
  "大语言模型是一种通过海量文本数据训练的AI模型，
   能够理解和生成人类语言。"

关键认知：LLM 本质上是在做"下一个词预测"（Next Token Prediction）。它不是在"思考"，而是在根据概率生成最可能出现的下一个词。这就是为什么它有时候会"一本正经地胡说八道"------因为概率上说得通，但事实上不对。这叫"幻觉"（Hallucination）。

3. Part B：开发环境搭建（30 分钟）

3.1 为什么需要虚拟环境

复制代码

你的电脑上可能有多个 Python 项目：
  - 项目 A 依赖 openai 1.0
  - 项目 B 依赖 openai 1.50
  - 如果都装在全局环境里 → 版本冲突

虚拟环境 = 每个项目一个独立的 Python 环境
  互不干扰，干净清爽

3.2 逐步搭建

Step 1：确认 Python 版本

打开终端（Windows 用 Git Bash 或 PowerShell，Mac 用 Terminal）：

bash 复制代码

python --version

预期输出：

复制代码

Python 3.10.x  或  Python 3.11.x  或  Python 3.12.x

要求：Python 3.10 以上。如果版本太低，去 python.org 下载安装最新版。

Windows 注意事项：

安装时勾选 "Add Python to PATH"

如果 python 命令找不到，试试 python3

推荐用 Git Bash 作为终端，和教程命令一致

Step 2：创建项目目录

bash 复制代码

# 选一个纯英文路径（避免中文和空格！）
mkdir ai-agent-learning
cd ai-agent-learning

为什么不能有中文路径：Python 的虚拟环境激活脚本、pip 安装路径都可能因为中文编码出错，后面调试起来非常痛苦。

Step 3：创建虚拟环境

bash 复制代码

python -m venv ai-agent-env

预期：命令执行完后，当前目录会多一个 ai-agent-env 文件夹。这个文件夹就是你的虚拟环境，里面包含独立的 Python 解释器和 pip。

Step 4：激活虚拟环境

bash 复制代码

# Windows (Git Bash):
source ai-agent-env/Scripts/activate

# Windows (PowerShell):
.\ai-agent-env\Scripts\Activate.ps1

# macOS / Linux:
source ai-agent-env/bin/activate

验证激活成功 ：命令行最前面出现 (ai-agent-env) 标识：

复制代码

(ai-agent-env) user@computer:~/ai-agent-learning$

Windows PowerShell 如果报 "执行策略" 错误：
powershell 复制代码
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
然后重新激活。

Step 5：配置 pip 国内源

不做这步也能用，但下载速度会慢 10-20 倍。

bash 复制代码

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

验证：

bash 复制代码

pip config list

应该看到 global.index-url='https://pypi.tuna.tsinghua.edu.cn/simple'

其他可选源：

阿里云：https://mirrors.aliyun.com/pypi/simple/

腾讯云：https://mirrors.cloud.tencent.com/pypi/simple/

Step 6：安装依赖

bash 复制代码

pip install openai python-dotenv tiktoken numpy

各包用途说明：

包名	用途	你后面什么时候用到
`openai`	调用 LLM API 的 SDK（DeepSeek/OpenAI/阿里都兼容）	每次调 LLM
`python-dotenv`	从 .env 文件读取环境变量（保护 API Key）	每次加载配置
`tiktoken`	OpenAI 的 Token 分词器，本地数 Token	Day 3 Token 实验
`numpy`	数值计算，算向量相似度	Day 3 Embedding 实验

预期输出：

复制代码

Successfully installed openai-1.x.x python-dotenv-1.x.x tiktoken-0.x.x numpy-1.x.x

Step 7：安装代码编辑器（如果还没装）

编辑器	推荐度	说明
VS Code	首推	免费、轻量、Python 插件好
PyCharm Community	推荐	功能全，但偏重
Cursor	推荐	AI 辅助编程，和你的学习方向契合

VS Code 必装插件：

Python（微软官方）
Pylance（类型提示）
Markdown All in One（写笔记用）

3.3 环境搭建排错表

问题	原因	解决
`python: command not found`	Python 没加入 PATH	Windows 重装勾选 "Add to PATH"；Mac 用 `brew install python`
`python -m venv` 报错	缺少 venv 模块	Ubuntu: `sudo apt install python3-venv`
激活脚本找不到	路径有中文或空格	移到纯英文路径
PowerShell 执行策略报错	默认禁止运行脚本	`Set-ExecutionPolicy RemoteSigned -Scope CurrentUser`
`pip install` 卡住	默认用国外 PyPI 源	换清华源（见 Step 5）
安装报 `SSL: CERTIFICATE_VERIFY_FAILED`	Mac 上 Python 3.6+ 的 SSL 证书问题	运行 `/Applications/Python\ 3.x/Install\ Certificates.command`
`tiktoken` 安装失败	需要 C 编译器	Windows 装 Visual C++ Build Tools；Mac 装 Xcode Command Line Tools

4. Part C：API Key 获取与项目初始化（20 分钟）

4.1 平台选择

推荐方案：DeepSeek（便宜、国内直连、不需要梯子）

平台	注册地址	特点	价格（输入/输出每百万 Token）	是否需梯子
DeepSeek	https://platform.deepseek.com/	国内直连，性价比极高，API 兼容 OpenAI 格式	¥1 / ¥2	否
OpenAI	https://platform.openai.com/	最全最强，多模态	~¥18 / ~¥72	是
阿里百炼	https://bailian.console.aliyun.com/	国内直连，中文好，支持 Embedding	~¥0.8 / ~¥2	否
智谱 GLM	https://open.bigmodel.cn/	国内直连，清华系	~¥5 / ~¥5	否

建议：至少注册 DeepSeek（聊天模型）+ 阿里百炼（Embedding 模型，Day 3 要用）。

4.2 DeepSeek 注册流程（详细）

打开 https://platform.deepseek.com/
手机号注册 / 登录
左侧菜单 → "API Keys"
点击 "创建 API Key"
给 Key 起个名字（如 "learning"）
复制生成的 Key （格式：sk-xxxxxxxxxxxx）
立刻保存到安全的地方（Key 只显示一次，关掉就看不到了）

DeepSeek 新用户会送一些免费额度，够你学习用很久。

充值的话，10 块钱够你跑完整个月的学习实验。

4.3 阿里百炼注册流程（Day 3 要用，提前注册）

打开 https://bailian.console.aliyun.com/
阿里云账号登录
开通"百炼大模型服务"（新用户有免费额度）
左侧 → "API-KEY 管理" → 创建
复制保存

4.4 创建项目结构

在 ai-agent-learning 目录下创建以下文件：

复制代码

ai-agent-learning/
├── .env                 # API Key（绝对不能传 GitHub！）
├── .gitignore           # 告诉 Git 忽略哪些文件
├── notes/               # 每日笔记
│   └── day1.md
├── code/                # 代码练习
│   ├── hello_llm.py     # 今天的主代码
│   ├── api_response.py  # 理解 API 响应
│   └── multi_call.py    # 多次调用实验
└── README.md            # 项目说明

创建目录和文件：

bash 复制代码

mkdir notes code
touch .env .gitignore README.md
touch notes/day1.md code/hello_llm.py

4.5 配置 .env 文件

用编辑器打开 .env，写入：

env 复制代码

# DeepSeek API Key（你注册后复制的那个）
DEEPSEEK_API_KEY=sk-你复制的那串key

# 阿里百炼 API Key（Day 3 会用到，先填上）
DASHSCOPE_API_KEY=sk-你的阿里百炼key

# 如果你有 OpenAI 的 Key（可选）
# OPENAI_API_KEY=sk-你的openai-key

安全警告：.env 文件包含你的 API Key，等同于密码。绝对不要：

把 .env 上传到 GitHub

把 Key 直接写在代码里

把 Key 发到群里或截图给别人

4.6 配置 .gitignore

打开 .gitignore，写入：

gitignore 复制代码

# API Keys - 绝对不能提交
.env

# 虚拟环境
ai-agent-env/

# Python 缓存
__pycache__/
*.pyc
*.pyo

# IDE
.vscode/
.idea/

# 系统
.DS_Store
Thumbs.db

4.7 初始化 Git 仓库

bash 复制代码

git init
git add .
git status

检查：git status 的输出中不能出现 .env。如果出现了，说明 .gitignore 没配对。

bash 复制代码

git commit -m "init: project structure for AI agent learning"

5. Part D：第一次调用 LLM（30 分钟）

5.1 写代码

在 code/hello_llm.py 中写入以下代码：

python 复制代码

"""
Day 1: 第一个 LLM 程序
目标：验证 API 可用，理解调用流程
"""
import os
from dotenv import load_dotenv
from openai import OpenAI

# ============================================
# Step 1: 加载环境变量
# ============================================
# load_dotenv() 会读取项目根目录下的 .env 文件
# 把里面的 KEY=VALUE 加载到环境变量中
# 这样代码里不需要硬编码 API Key
load_dotenv()

# ============================================
# Step 2: 创建 API 客户端
# ============================================
# OpenAI 这个类是官方 SDK 提供的
# DeepSeek 的 API 兼容 OpenAI 格式，所以用同一个类
# 只需要改 base_url 指向 DeepSeek 的服务器

# --- 如果你用 DeepSeek ---
client = OpenAI(
    api_key=os.getenv("DEEPSEEK_API_KEY"),  # 从环境变量读取 Key
    base_url="https://api.deepseek.com"      # DeepSeek 的 API 地址
)
MODEL = "deepseek-chat"  # 模型名称

# --- 如果你用 OpenAI（需要梯子），注释掉上面，取消下面注释 ---
# client = OpenAI(
#     api_key=os.getenv("OPENAI_API_KEY")
#     # OpenAI 不需要 base_url，SDK 默认指向官方地址
# )
# MODEL = "gpt-4o"

# --- 如果你用阿里百炼 ---
# client = OpenAI(
#     api_key=os.getenv("DASHSCOPE_API_KEY"),
#     base_url="https://dashscope.aliyuncs.com/compatible-mode/v1"
# )
# MODEL = "qwen-plus"

# ============================================
# Step 3: 构造对话消息
# ============================================
# messages 是一个列表，每个元素是一条消息
# 每条消息有两个字段：
#   - role: 角色（"system" / "user" / "assistant"）
#   - content: 消息内容

messages = [
    # system 消息：设定 AI 的角色和行为（可选但推荐）
    {
        "role": "system",
        "content": "你是一个简洁的技术助手，回答要准确、精炼。"
    },
    # user 消息：用户的提问
    {
        "role": "user",
        "content": "用一句话解释什么是大语言模型"
    }
]

# ============================================
# Step 4: 调用 API
# ============================================
print("正在调用 LLM，请稍候...")

response = client.chat.completions.create(
    model=MODEL,           # 使用哪个模型
    messages=messages,     # 对话历史
    temperature=0.7,       # 随机性（0=确定性，1=高随机，后面会详细学）
    max_tokens=200,        # 最多生成多少 Token（限制成本）
)

# ============================================
# Step 5: 解析并打印结果
# ============================================
# response 是一个对象，结构如下：
# response
#   ├── choices            （列表，通常只有一个）
#   │   └── [0]
#   │       ├── finish_reason  （为什么停了：stop=正常结束，length=达到max_tokens）
#   │       └── message
#   │           ├── role        （"assistant"）
#   │           └── content     （模型生成的文本 ← 这是你最关心的）
#   └── usage              （Token 用量统计）
#       ├── prompt_tokens      （输入消耗的 Token）
#       ├── completion_tokens  （输出消耗的 Token）
#       └── total_tokens       （总计）

answer = response.choices[0].message.content
print(f"\n{'='*50}")
print(f"回答：")
print(f"{'='*50}")
print(answer)

print(f"\n{'='*50}")
print(f"Token 用量统计：")
print(f"{'='*50}")
print(f"  输入 (prompt):     {response.usage.prompt_tokens} tokens")
print(f"  输出 (completion): {response.usage.completion_tokens} tokens")
print(f"  总计 (total):      {response.usage.total_tokens} tokens")

print(f"\n{'='*50}")
print(f"其他信息：")
print(f"{'='*50}")
print(f"  模型: {response.model}")
print(f"  停止原因: {response.choices[0].finish_reason}")
print(f"  响应ID: {response.id}")

5.2 运行代码

确保虚拟环境已激活（命令行前面有 (ai-agent-env)），然后：

bash 复制代码

python code/hello_llm.py

5.3 预期输出

复制代码

正在调用 LLM，请稍候...

==================================================
回答：
==================================================
大语言模型是一种通过在海量文本数据上训练，从而具备理解和生成人类语言能力的超大规模AI模型。

==================================================
Token 用量统计：
==================================================
  输入 (prompt):     28 tokens
  输出 (completion): 45 tokens
  总计 (total):      73 tokens

==================================================
其他信息：
==================================================
  模型: deepseek-chat
  停止原因: stop
  响应ID: 8a7b3c2d-xxxx-xxxx-xxxx-xxxxxxxxxxxx

回答内容每次可能不同（因为 temperature=0.7 有随机性），但格式应该一样。

5.4 逐行代码解析

如果你对代码有疑问，这里是逐行解释：

代码	解释
`import os`	Python 标准库，用于读取环境变量
`from dotenv import load_dotenv`	第三方库，从 .env 文件加载变量
`from openai import OpenAI`	OpenAI 官方 SDK，DeepSeek 兼容这个接口
`load_dotenv()`	执行！把 .env 文件中的 KEY=VALUE 加载到 `os.environ`
`os.getenv("DEEPSEEK_API_KEY")`	从环境变量读取 Key，返回字符串
`OpenAI(api_key=..., base_url=...)`	创建客户端对象，后续所有 API 调用都通过它
`client.chat.completions.create(...)`	调用聊天补全接口（最常用的接口）
`model=MODEL`	指定用哪个模型
`messages=messages`	传入对话历史
`temperature=0.7`	控制随机性（Day 5 会深入学）
`max_tokens=200`	限制输出长度，防止费用超预期
`response.choices[0].message.content`	从响应对象中取出生成的文本
`response.usage`	Token 用量信息

5.5 运行报错处理

报错信息	原因	解决方案
`AuthenticationError: Invalid API key`	API Key 不对	检查 .env 文件中的 Key 是否完整复制，没有多余空格
`APIConnectionError: Connection error`	网络问题	DeepSeek 检查能否 ping 通；OpenAI 需要梯子
`RateLimitError`	调用太频繁或额度用完	等一会再试；或去平台充值/查看余额
`ModuleNotFoundError: No module named 'openai'`	包没装或虚拟环境没激活	确认命令行有 `(ai-agent-env)` 前缀，重新 `pip install openai`
`ModuleNotFoundError: No module named 'dotenv'`	包名搞混了	安装命令是 `pip install python-dotenv`（不是 `dotenv`）
`openai.BadRequestError: context_length_exceeded`	输入太长超过模型上下文	减少 messages 内容
`AttributeError: 'NoneType' object has no attribute`	响应解析问题	检查 response 是否正常返回，打印 `response` 看结构
`.env` 中的 Key 读不到	文件位置不对或格式不对	.env 必须在项目根目录；等号两边不能有空格

6. Part E：进阶练习------理解 API 响应结构（20 分钟）

6.1 打印完整响应对象

创建 code/api_response.py：

python 复制代码

"""
Day 1 进阶：深入理解 API 响应结构
"""
import os
import json
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

client = OpenAI(
    api_key=os.getenv("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com"
)

response = client.chat.completions.create(
    model="deepseek-chat",
    messages=[
        {"role": "user", "content": "什么是 Python？30 字以内回答。"}
    ],
    temperature=0,
    max_tokens=100,
)

# ============================================
# 实验 1: 打印完整响应对象
# ============================================
print("=" * 60)
print("实验 1: 完整响应对象（model_dump）")
print("=" * 60)

# response 是一个 Pydantic 对象，用 model_dump() 转成字典
response_dict = response.model_dump()
print(json.dumps(response_dict, indent=2, ensure_ascii=False))

# ============================================
# 实验 2: 逐层解析响应
# ============================================
print("\n" + "=" * 60)
print("实验 2: 逐层解析响应")
print("=" * 60)

print(f"\n第一层 - response 的类型: {type(response)}")
print(f"  response.id = {response.id}")
print(f"  response.model = {response.model}")
print(f"  response.created = {response.created} (Unix 时间戳)")

print(f"\n第二层 - response.choices (列表，长度={len(response.choices)})")
choice = response.choices[0]
print(f"  choice.index = {choice.index}")
print(f"  choice.finish_reason = {choice.finish_reason}")
print(f"  choice.message.role = {choice.message.role}")
print(f"  choice.message.content = {choice.message.content}")

print(f"\n第二层 - response.usage")
print(f"  usage.prompt_tokens = {response.usage.prompt_tokens}")
print(f"  usage.completion_tokens = {response.usage.completion_tokens}")
print(f"  usage.total_tokens = {response.usage.total_tokens}")

# ============================================
# 实验 3: finish_reason 的含义
# ============================================
print("\n" + "=" * 60)
print("实验 3: finish_reason 的含义")
print("=" * 60)

# 正常结束
print("\n--- 场景 A: 正常结束 (max_tokens=200) ---")
r1 = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "说一个笑话"}],
    max_tokens=200,
)
print(f"  finish_reason: {r1.choices[0].finish_reason}")
print(f"  输出: {r1.choices[0].message.content[:50]}...")

# 被 max_tokens 截断
print("\n--- 场景 B: 被截断 (max_tokens=5) ---")
r2 = client.chat.completions.create(
    model="deepseek-chat",
    messages=[{"role": "user", "content": "写一篇 500 字的文章"}],
    max_tokens=5,
)
print(f"  finish_reason: {r2.choices[0].finish_reason}")
print(f"  输出: {r2.choices[0].message.content}")
print(f"  注意：输出不完整，因为 max_tokens=5 太小了")

运行：

bash 复制代码

python code/api_response.py

实验 3 的预期输出对比：

复制代码

--- 场景 A: 正常结束 (max_tokens=200) ---
  finish_reason: stop
  输出: 为什么程序员不喜欢户外？因为有太多 bug...

--- 场景 B: 被截断 (max_tokens=5) ---
  finish_reason: length
  输出: 从前有
  注意：输出不完整，因为 max_tokens=5 太小了

结论：

finish_reason = "stop"：模型自然结束了回答（遇到了 <|end|> 结束符）
finish_reason = "length"：输出被 max_tokens 截断了，回答不完整
开发时一定要检查 finish_reason，如果被截断需要处理

6.2 多次调用实验

创建 code/multi_call.py：

python 复制代码

"""
Day 1 进阶：多次调用，观察输出的随机性
"""
import os
from dotenv import load_dotenv
from openai import OpenAI

load_dotenv()

client = OpenAI(
    api_key=os.getenv("DEEPSEEK_API_KEY"),
    base_url="https://api.deepseek.com"
)

prompt = "用一个比喻解释什么是 API（10 字以内）"

# ============================================
# 实验: 同一 Prompt 调用 5 次
# ============================================
print("=" * 60)
print(f"同一 Prompt 调用 5 次")
print(f"Prompt: {prompt}")
print("=" * 60)

results = []
for i in range(5):
    response = client.chat.completions.create(
        model="deepseek-chat",
        messages=[{"role": "user", "content": prompt}],
        temperature=0.7,  # 默认随机性
        max_tokens=50,
    )
    answer = response.choices[0].message.content.strip()
    tokens = response.usage.total_tokens
    results.append(answer)
    print(f"\n第 {i+1} 次: {answer}  [{tokens} tokens]")

# 分析
print("\n" + "=" * 60)
print("分析")
print("=" * 60)
unique = len(set(results))
print(f"5 次调用中，{unique} 个不同的回答")
if unique == 1:
    print("→ 所有回答完全相同（temperature 可能太低）")
elif unique == 5:
    print("→ 每次回答都不同（temperature=0.7 的正常表现）")
else:
    print(f"→ 有 {unique} 个不同回答，{5-unique} 个重复")

# ============================================
# 对比: temperature=0 的确定性输出
# ============================================
print("\n" + "=" * 60)
print("对比: temperature=0 (完全确定性)")
print("=" * 60)

results_t0 = []
for i in range(3):
    response = client.chat.completions.create(
        model="deepseek-chat",
        messages=[{"role": "user", "content": prompt}],
        temperature=0,  # 完全确定性
        max_tokens=50,
    )
    answer = response.choices[0].message.content.strip()
    results_t0.append(answer)
    print(f"第 {i+1} 次: {answer}")

if len(set(results_t0)) == 1:
    print("\n→ temperature=0 时，3 次输出完全相同（确定性）")
else:
    print("\n→ temperature=0 时仍有微小差异（API 实现层面可能有微小随机性）")

运行：

bash 复制代码

python code/multi_call.py

这个实验让你理解：

temperature=0.7（默认）时，同一个问题每次回答可能不同
temperature=0 时，同一个问题每次回答几乎相同
这就是 Day 5 要深入学习的"采样参数"

7. 今日笔记模板

在 notes/day1.md 中写以下内容：

markdown 复制代码

# Day 1 笔记 --- AI 全景认知 + 环境搭建 + 第一次调用

## 日期：2026-07-XX
## 学习时长：X 小时 X 分钟

## 一、今天学到的 5 件事

1. 
2. 
3. 
4. 
5. 

## 二、AI 全景理解（200 字内）

（用你自己的话写，不要复制教程。想象你在给同事讲这个概念。）

## 三、训练三阶段（填表）

| 阶段 | 做什么 | 类比 |
|------|--------|------|
| 预训练 | | |
| 微调 | | |
| RLHF | | |

## 四、API 调用流程（按顺序写）

1. 
2. 
3. 
4. 
5. 

## 五、API 响应结构（画出树状图）

response
├── ______
├── ______
│   └── [0]
│       ├── ______
│       └── ______
│           ├── ______
│           └── ______
└── ______
    ├── ______
    ├── ______
    └── ______

## 六、Token 用量记录

| 调用 | 输入 Token | 输出 Token | 总 Token |
|------|-----------|-----------|---------|
| hello_llm.py | | | |
| api_response.py 实验2 | | | |
| multi_call.py (5次) | | | |

## 七、踩的坑和解决方案

（记录今天遇到的报错和怎么解决的，以后会反复用到）

| 报错/问题 | 原因 | 解决方案 |
|----------|------|---------|
| | | |
| | | |

## 八、还不清楚的问题（明天查）

- 
- 

## 九、今日代码清单

- [ ] code/hello_llm.py 运行成功
- [ ] code/api_response.py 运行成功
- [ ] code/multi_call.py 运行成功
- [ ] git commit 了今天的代码

8. 验收清单

概念验收（能用自己的话讲）

能说出 AI > ML > DL > NLP > LLM 的包含关系
能解释预训练、微调、RLHF 三个阶段分别做什么
知道 ChatGPT 和 GPT-3 的区别（RLHF）
知道 LLM 的本质是"预测下一个 Token"
知道什么是"幻觉"（Hallucination）

操作验收（亲手做过）

Python 虚拟环境创建并激活成功
pip 换源，依赖安装成功
获取至少一个 API Key（推荐 DeepSeek）
.env 文件配置正确，.gitignore 包含 .env
Git 仓库初始化，确认 .env 不在跟踪范围内

代码验收（运行成功）

hello_llm.py 运行成功，看到 LLM 的回答
api_response.py 运行成功，看到了完整响应结构
理解 finish_reason 的两个值（stop / length）
multi_call.py 运行成功，看到了 temperature 的效果

笔记验收

notes/day1.md 按模板写完
至少记录了 5 件学到的事
记录了今天踩的坑

9. 常见问题 FAQ

Q1：DeepSeek 和 OpenAI 的 API 有什么区别？

A：API 格式完全兼容。你用 openai 这个 SDK，改一下 base_url 和 api_key 就能调用 DeepSeek。模型名称不同（deepseek-chat vs gpt-4o），但调用方式一模一样。这也是为什么 OpenAI SDK 成了行业事实标准。

Q2：为什么我每次运行 hello_llm.py 的回答都不一样？

A：因为 temperature=0.7 引入了随机性。Day 5 会详细学这个参数。如果你想每次输出一样，改成 temperature=0。

Q3：max_tokens 设多少合适？

A：看任务。简单问答 100-200 够了；写代码 500-1000；写长文 2000+。建议先设小一点（省 Token = 省钱），不够再加大。

Q4：API 调用很慢怎么办？

A：几个可能的原因：

网络问题（OpenAI 需要梯子，DeepSeek 国内直连较快）
输入太长（Token 越多推理越慢）
模型选择（大模型慢但好，小模型快但差）
用了推理模型（如 o1/deepseek-reasoner，会"思考"所以慢）

Q5：API Key 泄露了怎么办？

A：立刻去平台后台删除/禁用这个 Key，然后创建新的。不要试图"以后再处理"------泄露的 Key 可能被滥用产生费用。

Q6：为什么 .env 读不到 API Key？

A：检查以下几点：

.env 文件在项目根目录（不是 code/ 目录里）
.env 文件格式：KEY=value，等号两边不能有空格
Key 值不要加引号（KEY=sk-xxx 而不是 KEY="sk-xxx"）
代码里 load_dotenv() 在 os.getenv() 之前调用

Q7：虚拟环境每次都要激活吗？

A：是的。每次打开新终端都要重新激活。VS Code 可以设置默认使用虚拟环境的解释器，就不用每次手动激活了（Ctrl+Shift+P → "Python: Select Interpreter" → 选 ai-agent-env 里的 Python）。

Q8：我要不要充钱？

A：DeepSeek 新用户有免费额度，够你学习用。Day 1 的所有实验花费不会超过 0.01 元。如果要充值，10 元够你跑完整个月的学习。

10. 扩展资源

必看（今天或明天补看）

资源	类型	时长	价值
3Blue1Brown「But what is a GPT?」	YouTube 视频	15 分钟	Transformer 直觉理解，最好的入门视频
Jay Alammar「The Illustrated Transformer」	英文文章	20 分钟	图解 Attention 机制，最清晰的图文教程
OpenAI API 文档 - Quickstart	英文文档	10 分钟	官方 API 快速入门

选看（有余力再看）

资源	类型	说明
Andrej Karpathy「Let's build GPT from scratch」	YouTube 视频	2 小时，硬核，从零实现 GPT。可选看前 30 分钟建立感觉
DeepSeek API 文档	中文文档	DeepSeek 官方 API 文档
阿里百炼文档	中文文档	阿里大模型平台文档

工具

工具	用途
OpenAI Playground	在线测试 Prompt，不用写代码
DeepSeek 控制台	查看余额、用量、API Key
tiktoken 在线版	在线数 Token，直观感受

11. 明日预告

Day 2 主题：Transformer 架构直觉理解

明天你会学到：

为什么需要 Attention 机制（RNN 有什么问题）
Self-Attention 的 Q/K/V 三个概念
多头注意力（Multi-Head Attention）
Transformer 的整体结构
GPT 为什么是 Decoder-only
Encoder-only / Decoder-only / Encoder-Decoder 的区别

明天主要是概念理解，代码量少，但概念比较抽象。建议今晚或明天白天先看 3Blue1Brown 的视频预热。

附录：Day 1 完整文件清单

文件	说明
`code/hello_llm.py`	最简 LLM 调用，验证 API 可用
`code/api_response.py`	深入理解 API 响应结构
`code/multi_call.py`	多次调用，观察 temperature 效果
`notes/day1.md`	今日笔记
`.env`	API Key 配置（不提交 Git）
`.gitignore`	Git 忽略规则

附录：Day 1 时间分配建议

如果你一次性学完（约 2-2.5 小时）：

复制代码

00:00-00:40  Part A: 概念认知（边读边画图）
00:40-00:45  休息 5 分钟
00:45-01:15  Part B: 环境搭建（跟着敲命令）
01:15-01:35  Part C: API Key + 项目结构
01:35-02:05  Part D: Hello World（写代码 + 运行）
02:05-02:25  Part E: 进阶练习（理解响应结构）
02:25-02:35  写笔记

如果分两次（推荐）：

复制代码

第一次（1 小时）：
  Part A: 概念认知（40 分钟）
  Part B: 环境搭建（20 分钟）

第二次（1-1.5 小时）：
  Part C: API Key + 项目结构（20 分钟）
  Part D: Hello World（30 分钟）
  Part E: 进阶练习（20 分钟）
  写笔记（10 分钟）