# CoT 思维链演示项目 — 学生阅读指南
## 一、这个项目是做什么的？
这是一个**真实调用阿里云百炼大模型**的教学演示项目，不是写死的假答案，也不是本地模拟。
程序会对**同一道题**分别用三种提示词策略去问 `qwen-plus`，让你亲眼看到：
| 对比维度 | 无 CoT | 有 CoT |
|----------|--------|--------|
| 输出形式 | 往往只有一行答案 | 有「第一步 / 第二步…」推理链 |
| 复杂题准确率 | 容易跳步、答错 | 分步计算，更不容易错 |
| 过程是否可检查 | 看不到推理过程 | 每一步都能审查、纠错 |
**课堂推荐先看第 1 题**（`9.9 和 9.10 谁大？`），无 CoT 容易答错，有 CoT 容易答对，对比最明显。
---
## 二、是不是真实运行？
**是的，100% 真实运行。**
每次你看到的「模型回复」，都是程序通过网络请求阿里云百炼接口得到的实时结果：
```
你的电脑 → dashscope SDK → 百炼云端 qwen-plus → 返回真实生成文本
```
证据：
1. 需要有效的 `DASHSCOPE_API_KEY`，否则会报错，无法运行
2. 每次调用都会消耗百炼账号的 Token（可在百炼控制台查看用量）
3. 同一道题多次运行，措辞可能略有不同（但 `temperature=0` 已尽量保持稳定）
4. 断网或 Key 无效时，程序会抛出 API 错误，不会假装成功
本项目**没有**以下东西：
- 没有写死的「假回复」
- 没有 `if question == xxx: return "4"` 这类硬编码
- 没有用本地规则引擎代替大模型
---
## 三、项目是怎么构建的？
### 3.1 目录结构
```
cot_demo/
├── main.py # 【入口】解析命令行、组织演示流程、打印对比小结
├── demo.py # 【核心】三种 CoT 模式的 messages 组装与调用
├── prompts.py # 【提示词】无CoT / 零样本CoT / 少样本CoT 的 system 和 user 模板
├── questions.py # 【题库】3 道经典演示题及参考答案
├── llm_client.py # 【API层】封装 dashscope.Generation.call，真正发网络请求
├── config.py # 【配置】模型名、温度、种子、API Key 读取
├── display.py # 【展示】终端输出格式化、项目说明打印
├── run.bat # 双击运行（默认第 1 题）
├── run_all.bat # 双击运行全部 3 题
├── requirements.txt # 依赖：dashscope
└── docs/
└── 项目说明.md # 本文件
```
### 3.2 模块分工（谁负责什么）
| 文件 | 职责 | 学生应关注什么 |
|------|------|----------------|
| `config.py` | 读取系统环境变量 `DASHSCOPE_API_KEY`，设置模型参数 | API Key 从哪来、为什么用 `qwen-plus` |
| `llm_client.py` | 调用 `dashscope.Generation.call()` 发请求 | **真正联网的地方**，所有模式最终都走这里 |
| `prompts.py` | 存放三种模式的提示词文本 | **改提示词就在这里**，对比实验的核心 |
| `questions.py` | 存放演示题目 | 可换成自己的题做实验 |
| `demo.py` | 把 prompts + question 拼成 messages 列表 | 理解 system/user/assistant 怎么组 |
| `main.py` | 控制运行顺序、提取答案、判断对错 | 理解一整道题的演示流程 |
| `display.py` | 美化终端输出 | 可忽略，不影响核心逻辑 |
### 3.3 设计原则
1. **提示词与代码分离**：改 CoT 效果主要改 `prompts.py`，不用动 API 调用逻辑
2. **一种 API 封装**：三种模式共用 `llm_client.call_llm()`，保证对比公平（同一模型、同一参数）
3. **参数稳定**：`temperature=0`、`seed=42`，课堂演示尽量可复现
---
## 四、程序运行流程（一步一步）
以 `python main.py`（默认第 1 题）为例，完整执行顺序如下：
```
第 0 步：启动 main.py
↓
第 1 步：check_env()
读取 os.getenv("DASHSCOPE_API_KEY")
确认系统环境变量里已配置百炼密钥
↓
第 2 步：print_intro()
打印 CoT 概念说明、三种模式介绍、项目是否真实运行
↓
第 3 步：run_one_question(1)
从 questions.py 取出第 1 道题
↓
第 4 步：依次执行三种模式（每种模式 = 1 次真实 API 调用）
│
├─ 模式 A：demo.run_direct()
│ prompts.py 取 SYSTEM_DIRECT + 题目
│ 组装 messages → **先打印【发送给模型的提示词】**
│ → llm_client.call_llm() → 百炼 API
│ 打印【模型回复】→ 提取最终答案 → 判断对错/是否有分步
│
├─ 模式 B：demo.run_zero_shot_cot()
│ prompts.py 取 SYSTEM_ZERO_SHOT_COT + 题目 +「请一步一步思考」
│ 组装 messages → llm_client.call_llm() → 百炼 API
│ 打印回复 → 提取最终答案 → 判断对错/是否有分步
│
└─ 模式 C：demo.run_few_shot_cot()
prompts.py 取 SYSTEM_FEW_SHOT_COT
+ 示例 user（罗杰网球题）
+ 示例 assistant（带推理链的标准答案）
+ 真正要答的新题目
组装 messages → llm_client.call_llm() → 百炼 API
打印回复 → 提取最终答案 → 判断对错/是否有分步
↓
第 5 步：打印「本题对比小结」
汇总 A/B/C 的提示词结构差异 + 最终答案、正确性、是否有分步推理
↓
第 6 步：演示结束
```
**跑 1 道题 = 3 次 API 调用；跑全部 3 题 = 9 次 API 调用。**
---
## 五、三种模式分别怎么工作？
### 模式 A：无 CoT（直接要答案）
**messages 结构：**
```python
[
{"role": "system", "content": "只输出一行最终答案，禁止写推理过程..."},
{"role": "user", "content": "9.9 和 9.10 谁大？"},
]
```
**作用：** 模拟「只要结果、不要过程」的提问方式。复杂题容易跳步出错。
---
### 模式 B：零样本 CoT（Zero-shot CoT）
**messages 结构：**
```python
[
{"role": "system", "content": "必须先写推理过程，按第一步/第二步组织..."},
{"role": "user", "content": "9.9 和 9.10 谁大？\n\n请一步一步思考..."},
]
```
**作用：** 不给示例，只靠提示词要求模型自己展开推理链。对应课程里的「给模型思考时间」。
---
### 模式 C：少样本 CoT（Few-shot CoT）
**messages 结构：**
```python
[
{"role": "system", "content": "请模仿示例的推理格式..."},
{"role": "user", "content": "罗杰有 5 个网球..."}, # 示例题
{"role": "assistant", "content": "第一步：...\n最终答案：11"}, # 示例推理链
{"role": "user", "content": "9.9 和 9.10 谁大？"}, # 真正要答的题
]
```
**作用：** 用「示例问题 + 示例推理」教会模型输出格式，再让它答新题。对应课程的「文本参考 / Few-shot」。
---
## 六、API 调用层详解（llm_client.py）
这是**唯一真正联网**的函数：
```python
response = dashscope.Generation.call(
api_key=API_KEY, # 从 os.getenv("DASHSCOPE_API_KEY") 读取
model="qwen-plus", # 百炼上的通义千问 Plus
messages=messages, # 上面三种模式拼好的对话列表
temperature=0, # 低随机性，结果更稳定
seed=42, # 固定种子，尽量可复现
result_format="message", # 返回标准 message 格式
)
return response.output.choices[0].message.content
```
如果 `status_code != 200`，程序会报错退出，不会返回假数据。
---
## 七、怎么运行？
### 前置条件
1. 已安装 Python 3.8+
2. 已执行 `pip install -r requirements.txt`
3. Windows 系统环境变量中已配置 `DASHSCOPE_API_KEY`（无需每次在终端手动设置）
### 网页版（推荐课堂演示）
```powershell
python web_app.py
# 或双击 run_web.bat
```
浏览器打开：**http://127.0.0.1:8765**
页面会实时展示：
1. 运行环境（模型、API Key 状态、是否真实调用）
2. 运行过程三步进度（模式 A → B → C）
3. 三列卡片：每列显示完整提示词 + 模型回复
4. 底部对比小结表（提示词差异 + 结果差异）
技术说明：前端通过 **SSE（Server-Sent Events）** 订阅 `/api/stream/<题号>`，
后端每完成一种模式就推送一次事件，学生能清楚看到「正在调用 API → 返回结果」的全过程。
### 终端版
```powershell
python main.py # 默认第 1 题
python main.py --all # 全部 3 题
python main.py --only 2 # 指定第 2 题
```
或直接双击 `run.bat` / `run_all.bat`。
---
## 八、建议的学习顺序
1. **先运行**：`python main.py`，看终端输出的 A/B/C 对比
2. **再读** `prompts.py`：对比三种提示词差在哪
3. **然后读** `demo.py`：看 messages 是怎么拼的
4. **最后读** `llm_client.py`：确认是真实 API 调用
5. **动手改**：试着改 `SYSTEM_ZERO_SHOT_COT` 里的措辞，重新运行看效果变化
---
## 九、常见问题
**Q：为什么模式 A 有时也写了很多字？**
A：早期版本提示词不够严格，模型会「偷偷推理」。当前版已要求「只输出一行」，模式 A 应只有一行答案。
**Q：为什么有时无 CoT 也答对了？**
A：简单题（如第 2、3 题）模型直接心算也能对。CoT 的价值在复杂题（如第 1 题）更明显。
**Q：运行报错「未读取到 DASHSCOPE_API_KEY」？**
A：检查 Windows 系统环境变量是否配置，配置后需**重新打开终端**。
**Q：和课程里的 OpenAI 库写法一样吗？**
A：思路一样（都是 `messages` 列表 + `system/user/assistant`），只是本项目按课堂要求改用 **DashScope 官方 SDK** 调用百炼。