> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/ai_beginner_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/ai_beginner_guide/fu-lu/labs.md).

# 附录 E：工程师配套实验代码

本目录是 B 轨的可复现实验包。五个实验都使用固定输入、仅使用 CPU、无需在线 API 或密钥；Python 3.11+ 标准库即可运行。每个文件公开两个稳定入口：`run_experiment()` 返回可序列化结果，`evaluate(result)` 返回包含 `passed` 与逐项 `checks` 的验收报告。

## B 轨学习契约

**前置条件**

* 达到 A 轨验收标准或具备同等基础
* Python 3.11+
* 会在命令行运行 Python 文件
* 一台可进行 CPU 计算的电脑

**可交付物**

* 五份实验结果字典与自评记录
* 一份失败案例与排障记录
* 一份最小 AI 工作流设计

**验收标准**

* 能复现实验的固定输入与预期范围
* 能解释每项评估为何通过或失败
* 能在不使用在线 API 和密钥的情况下完成五个实验
* 能把评估结果映射回对应章节的核心概念

## 五个实验映射

| 实验                        | 对应章节     | 必交结果         | 机器验收                          |
| ------------------------- | -------- | ------------ | ----------------------------- |
| `01_ml_basics.py`         | 第 4 章    | 线性回归指标报告     | `evaluate()` 返回 `passed=True` |
| `02_structured_output.py` | 第 12.2 节 | 三个结构化输出校验结果  | `evaluate()` 返回 `passed=True` |
| `03_dl_overfitting.py`    | 第 5 章    | 训练/验证损失与早停点  | `evaluate()` 返回 `passed=True` |
| `04_rag_minimal.py`       | 第 12.5 节 | 检索命中、上下文与回答  | `evaluate()` 返回 `passed=True` |
| `05_agent_evals.py`       | 第 14 章   | 两个案例的智能体评估报告 | `evaluate()` 返回 `passed=True` |

## 固定输入、预期范围与排障

| 实验        | 固定输入                         | 预期范围                           | 常见失败与排障                 |
| --------- | ---------------------------- | ------------------------------ | ----------------------- |
| 01 线性回归   | 随机种子 42；100 条合成房价；80/20 拆分   | 斜率 4.5–5.5；RMSE 20–70；R² > 0.9 | 若结果变化，确认未改种子、样本数或拆分顺序   |
| 02 结构化输出  | 一个合法对象、一个多字段对象、一个破损 JSON     | 依次为 `true / false / false`     | 若多字段对象通过，检查是否仍拒绝额外字段    |
| 03 过拟合    | 随机种子 42；12 个带噪样本；4000 轮高容量拟合 | 最佳轮次 < 4000；最终验证损失高于最佳值        | 若没有反弹，检查噪声、学习率和验证集是否被改动 |
| 04 最小 RAG | 固定本地语料与问题“RAG 和上下文工程有什么关系？”  | 首条命中含 RAG；上下文与回答均引用命中证据        | 若无命中，检查分词规则与语料是否仍包含 RAG |
| 05 智能体评估  | 两个固定问题、答案和上下文                | 2 个案例；平均相关性 ≥ 0.8；一致性和忠实度均通过   | 若分数下降，检查输出是否引入上下文外内容    |

## 运行方式

在仓库根目录执行任一实验：

```bash
python3 labs/01_ml_basics.py
python3 labs/02_structured_output.py
python3 labs/03_dl_overfitting.py
python3 labs/04_rag_minimal.py
python3 labs/05_agent_evals.py
```

一次运行全部自动验收：

```bash
python3 -m unittest -v tests.test_labs
```

若脚本无法启动，先运行 `python3 --version`，确认版本为 3.11 或更高；再确认命令是在仓库根目录执行。实验不读取账号、网络或模型服务配置，因此不要把密钥写入代码或排障记录。

## 自评量表

每个实验按下列自评量表记 0–3 分，并附上一句证据：

* **0 分**：脚本未运行，且没有可复现的错误记录。
* **1 分**：能运行，但 `evaluate()` 未通过，已保存失败结果和排障假设。
* **2 分**：`evaluate()` 通过，能复述输入、指标和预期范围。
* **3 分**：在保持固定基线的前提下改变一个变量，能解释结果变化并恢复基线。

五个实验至少都达到 2 分，才算完成 B 轨实验验收。3 分探索必须另存记录，不得改写固定基线或放宽自动阈值。