# 04｜做一个可验证的技术项目

本仓库提供三个从零可运行的教学项目，全部使用小规模人工构造输入，不依赖付费 API。它们用于训练实验和工程判断，不证明你已经具备所有 AI 岗位要求，更不等于训练大模型或上线企业系统。

## 三个项目怎么选

| 项目 | 面向路线 | 核心验收 | 不能证明的能力 |
| --- | --- | --- | --- |
| 文本分类实验 | 算法 / 应用 ML | 独立分割、参数选择、对照、macro-F1、失败分析 | 深度学习研究、真实业务泛化 |
| 本地模型服务 | AI 工程 | HTTP 契约、错误输入、模型版本、延迟测量 | 云端高可用、真实生产容量 |
| 有引用与拒答的检索应用 | AI 应用 | 检索命中、回答覆盖、拒答与引用 | LLM 生成质量、完整防注入保障 |

先选一个与你的 JD 对应的项目，完成后再决定是否做第二个。具体目录、输入、命令、预期输出、验收与排错以 [examples/README.md](../examples/README.md) 及各子项目 README 为准。实测结果与案例解读见[技术案例](technical-case-studies.md)。

## 从干净目录开始

使用 Python 3.10 或更高版本。macOS/Linux 通常使用 `python3`；Windows 可使用 `py -3`，后续命令相应替换。进入仓库根目录，先检查版本，再运行总入口。

```bash
python3 --version
python3 examples/run_all.py
```

不要只保留终端里“成功”两个字。打开生成的 JSON 报告，检查样本数量、模型配置、失败样本和运行环境。复制一份到自己的项目记录，注明运行日期和代码版本。

## 数据先于模型

写出一行数据代表什么。是一个用户、一条文本、一次会话，还是一天的设备记录？如果同一对象的多条记录跨越训练和测试，模型可能记住对象特征。先确定分割单位，必要时按人、时间或组织分组，再做特征处理。

训练只用训练数据；验证集用于选择参数、阈值和方案；测试集用于最后评估。特征词表、标准化参数和缺失值规则也可能造成泄漏，不能只检查标签。官方 scikit-learn 文档强调在分割后学习预处理步骤，避免测试信息进入训练。[T01](../research/technical-sources.md)

本仓库小样例采用固定分割，方便验收。它不替代大型研究里的多个随机种子、时间外评估或跨域评估。改进样例时，先重新设计评测，再扩大模型。

## 指标必须写分母

准确率是正确预测数除以全部样本数；类别严重不均衡时，它可能掩盖少数类失败。Precision 关注“判为正的有多少是真的”，Recall 关注“真的为正的有多少被找出”。Macro-F1 先按类计算 F1，再对类别等权平均；它与先平均 precision/recall 再算 F1 不同。[T02](../research/technical-sources.md)

检索 Recall@k 必须说明相关文档集合。若每题恰好只有一个相关文档，“前 k 条是否命中”的平均值与单相关文档 Recall@k 一致；有多个相关文档时，hit rate 与 recall 不再相同。

拒答正确率和可回答覆盖率要一起看。全部拒答可能避免错误回答，却不能帮助用户完成可回答任务。不要只挑一个好看的数值。

## 失败分析按可修复原因分类

| 观察 | 可能原因 | 下一次最小实验 |
| --- | --- | --- |
| 某类频繁被误分 | 类别边界不清、样本少、词汇重叠 | 检查标签规则并补独立边界样本 |
| 训练很好，测试差 | 泄漏修复后的真实差距、过拟合、分布变化 | 固定数据，减少特征或正则化 |
| 文档检索没命中 | 同义词、分词、切块、查询不完整 | 仅改变一个检索组件 |
| 检索命中但回答错 | 答案提取、生成或上下文使用问题 | 单独验收答案步骤 |
| 本地接口延迟波动 | 预热、并发、输入大小或资源竞争 | 记录条件并重复同一测量 |
| 项目别人跑不通 | 依赖、路径、默认参数或缺少输入 | 从新目录照 README 重跑 |

“模型不好”不是能指导下一步的错误分类。记录输入、预期、实际、原因假设和验证动作，至少保留一条尚未解决的失败。

## 让项目有个人贡献

先原样跑通本仓库，标明复现。然后提出一个改进问题，例如“能否在不降低不可回答问题拒答率的前提下，提高可回答覆盖率？”固定测试集，建立开发集，调整检索或阈值，再报告收益与代价。

可选扩展包括真实许可数据、另一种基线、批处理、英文与中文分开评测、时间外样本、监控指标。只有你实际实现并验收的扩展才能写进简历。接入 LLM 时需另外记录供应商、模型版本、费用、数据去向、重复运行和生成评测；本版没有对任何在线模型进行这些实验。

## 研究岗的额外要求

三个轻量样例只能建立实验习惯。若目标 JD 要求深度学习研究，应再做匹配方向的论文复现：固定论文版本和数据许可；写清硬件预算；复现一个核心结论；记录多次运行；分析与原文的差异；在许可范围内发布代码。没有算力时缩小研究问题，不能伪造实验。

PyTorch 官方文档指出，不同版本、平台和 CPU/GPU 之间不能保证完全一致的可复现结果。记录环境、随机性控制和算子选择，比只写一个随机种子更完整。[T03](../research/technical-sources.md)

## 项目完成检查

- 输入完整、来源和许可明确，未包含个人信息或机构秘密。
- 一条命令可以生成结果，异常时给出可理解的错误。
- 基线、改动、指标、失败样本、限制都能找到。
- 只用开发集调参，保留测试用途；发现污染后重新建评测。
- 个人、第三方、同伴和 AI 辅助贡献已经声明。
- 未把教学指标写成客户收益、就业结果或生产性能。

通过这些检查后，才进入简历和面试表达。
