# 01｜把一个小模型做成可信的实验

作者：AI酋长Andy · 星觉科技 · 北京 · 微信号：AIPMAndy  
版本：2026-11-13。教学模拟；没有真实客户、公司 KPI 或就业结果。

## 要解决的问题

把英文工单分到 `access`（账号访问）、`billing`（账单）、`technical`（技术故障）。这里的目标是展示实验判断力：如何不泄漏数据，如何选择方法，如何发现模型只记住了关键词。

该样例适合 ML/MLE 入门者练习评测。它不能替代研究论文、真实数据上的研究贡献，也不是训练大语言模型。

## 完整输入

`data/tickets.jsonl` 含 51 条手工编排的英文合成工单：训练 30 条、开发集 9 条、测试集 12 条。三种标签在每一份数据中都有样本；没有姓名、邮箱、真实工单或商业数据。

```json
{"id":"tr01","split":"train","label":"access","text":"I forgot my password and cannot sign in"}
```

`id` 是唯一键，`split` 固定用途，`label` 是人工预设类别，`text` 是输入。数据是为教学设计的，并非从总体随机抽样，因此结果不代表现实工单的表现。

## 运行步骤

在仓库根目录运行，Python 3.10+，无需安装包：

```bash
python3 examples/01_ml_experiment/run.py
python3 -m unittest discover -s examples/tests -v
```

第二条测试命令也检查其他项目的输入与评测逻辑，不启动外网连接。单独运行实验后，打开 `reports/evaluation.json` 与 `reports/failures.json`。

## 方法与选择过程

实现从零写的多项式朴素贝叶斯。将文本转小写，按英文字母/数字分词；词表只从 train 建立。对每个类别，累加类别先验的对数和各词的平滑条件概率对数。`alpha` 控制加法平滑，防止未见词令概率为零。输出中的概率仅是模型归一化分数，没有经过校准。

实验遍历 `alpha ∈ {0.25, 1, 2}`，并比较 unigram 与 unigram+bigram。只根据 dev 的 macro-F1 选参数；同分时保留先出现的较简单配置。test 不参与选择。每种配置的 dev 结果都在报告里。

对照有两项：始终预测训练集中最多的类，以及删除全部词特征、只保留类先验。训练集三类数量相等，固定顺序使基线预测 `access`。后者是一个强消融：说明文本特征提供了多少信息，不等于已解释每个特征的因果贡献。

数据读取器拦截重复 ID 和规范化后相同的文本，训练函数拒绝混入 dev/test。但这只能阻止明显重复。近义改写、同一用户的多条记录、同一时间事件和模板来源仍可能泄漏；真实任务应按用户/文档/时间分组划分，并检查采集过程。

## 预期输出与验收

```json
{"project":"01_ml_experiment","selected":{"alpha":0.25,"bigrams":false},"test":{"n":12,"accuracy":0.833333,"macro_f1":0.832011},"majority_macro_f1":0.166667,"failures":2}
```

| 验收项 | 固定样例结果 |
|---|---|
| 训练 / dev / test | 30 / 9 / 12 |
| 选择的参数 | alpha 0.25，unigram |
| test 正确数 | 10 / 12 |
| accuracy | 0.833333 |
| macro-F1 | 0.832011 |
| majority macro-F1 | 0.166667 |
| 失败数 | 2 |

accuracy 是正确题数 / 总题数。每类 F1 由 precision、recall 计算，macro-F1 对预定义的三类等权平均。没有分母时该类 precision/recall 记 0，并保留该类；测试中验证了这个约定。具体混淆矩阵见报告，不用单个总体数字掩盖类别差异。

`model.json` 可以序列化和重新载入。报告记录输入 SHA-256、Python 版本、划分大小、dev 各配置、test 逐题预测。统一验收运行 `python3 examples/run_all.py`。

## 两个失败怎么讲

| 样本 | 标注 → 预测 | 可观察现象 | 下一步验证 |
|---|---|---|---|
| `te08`: I cannot access my refund receipt | billing → access | “access” 与退款语境冲突；单一标签定义也可能有歧义 | 写清路由标注规则，另采集“访问失败＋账单对象”的边界样本 |
| `te11`: The invoice page spins forever | technical → billing | 模型被 invoice 带偏，没有充分理解页面卡死 | 增补多对象故障描述，比较词组/字符特征；使用新 dev，保留旧结果 |

这些是对错误的解释假设，不是已经证明的因果结论。不能先看 test 再定向补训练样本，随后把同一份 test 上的提升当作泛化提升。若为了学习这么做，明确标“针对已知错误的回归修复”，另建独立测试集。

## 错误排查

| 现象 | 检查 | 处理 |
|---|---|---|
| `duplicate normalized text / leakage risk` | 是否复制了不同 split 的文本 | 恢复原始输入；真实数据按来源去重并重新划分 |
| `train() accepts the training split only` | 传入列表是否包含 dev/test | 只把 `split == train` 的记录交给训练函数 |
| 指标与预期不同 | 数据哈希、代码 diff、Python 版本 | 先还原基线，再单因素实验；不直接改验收值 |
| 全是同一类 | 输入是否全是训练词表外词，或中文 | 本例只支持小英文词表；先记录 OOV，不能当正常置信度 |
| 觉得分数高所以“可上线” | 只有 12 条测试，且为合成数据 | 收集有许可的独立数据、评估标签质量与错误成本 |

## 形成自己的项目

先选一个具有真实边界的问题，比如公开可用文本的多类分类。核对许可，写数据卡，设计人群/时间划分，比较一个简单基线与一个改进。加入不平衡类、分布变化、置信度校准和人工复核策略。记录失败，不只记录最优分数。

如果申请研究岗，需要提出可被推翻的研究假设，复现论文基线，控制变量，并用足够数据和多次实验支持结论。这个小练习只是实验结构的底稿。

## 简历与面试（教学模拟，按实际完成内容修改）

可写：“复现并审查一个 51 条合成工单的文本分类基线，按 train/dev/test 隔离选参；记录 12 条测试上的 macro-F1 0.832 和 2 个边界错误，并新增【自己完成的具体改动】。”

不能写：“为大型企业搭建智能客服，分类准确率 83%，提升业务效率 50%。”本例没有这类证据。

准备回答：为什么用 macro-F1？重复样本检查漏掉什么？概率为什么不等于可信程度？如果拒答会怎样改变覆盖率？两个错误分别是模型问题还是标签定义问题？你写了哪些行、AI 辅助了哪些部分、你用什么测试验收？

## 许可与个人贡献

代码 MIT；数据 CC0，见 [数据说明](../DATA-LICENSE.md)。本基线由 AI 辅助新写并实际执行。读者在自己的贡献记录中把“原仓库基线”“本人新增实验”“AI 提供的草稿”“人工核验”分开。仅运行已有脚本不能描述为独立从零开发。
