04|做一个可验证的技术项目
本仓库提供三个从零可运行的教学项目,全部使用小规模人工构造输入,不依赖付费 API。它们用于训练实验和工程判断,不证明你已经具备所有 AI 岗位要求,更不等于训练大模型或上线企业系统。
三个项目怎么选
| 项目 | 面向路线 | 核心验收 | 不能证明的能力 |
|---|---|---|---|
| 文本分类实验 | 算法 / 应用 ML | 独立分割、参数选择、对照、macro-F1、失败分析 | 深度学习研究、真实业务泛化 |
| 本地模型服务 | AI 工程 | HTTP 契约、错误输入、模型版本、延迟测量 | 云端高可用、真实生产容量 |
| 有引用与拒答的检索应用 | AI 应用 | 检索命中、回答覆盖、拒答与引用 | LLM 生成质量、完整防注入保障 |
先选一个与你的 JD 对应的项目,完成后再决定是否做第二个。具体目录、输入、命令、预期输出、验收与排错以 examples/README.md 及各子项目 README 为准。实测结果与案例解读见技术案例。
从干净目录开始
使用 Python 3.10 或更高版本。macOS/Linux 通常使用 python3;Windows 可使用 py -3,后续命令相应替换。进入仓库根目录,先检查版本,再运行总入口。
bashpython3 --version
python3 examples/run_all.py
不要只保留终端里“成功”两个字。打开生成的 JSON 报告,检查样本数量、模型配置、失败样本和运行环境。复制一份到自己的项目记录,注明运行日期和代码版本。
数据先于模型
写出一行数据代表什么。是一个用户、一条文本、一次会话,还是一天的设备记录?如果同一对象的多条记录跨越训练和测试,模型可能记住对象特征。先确定分割单位,必要时按人、时间或组织分组,再做特征处理。
训练只用训练数据;验证集用于选择参数、阈值和方案;测试集用于最后评估。特征词表、标准化参数和缺失值规则也可能造成泄漏,不能只检查标签。官方 scikit-learn 文档强调在分割后学习预处理步骤,避免测试信息进入训练。T01
本仓库小样例采用固定分割,方便验收。它不替代大型研究里的多个随机种子、时间外评估或跨域评估。改进样例时,先重新设计评测,再扩大模型。
指标必须写分母
准确率是正确预测数除以全部样本数;类别严重不均衡时,它可能掩盖少数类失败。Precision 关注“判为正的有多少是真的”,Recall 关注“真的为正的有多少被找出”。Macro-F1 先按类计算 F1,再对类别等权平均;它与先平均 precision/recall 再算 F1 不同。T02
检索 Recall@k 必须说明相关文档集合。若每题恰好只有一个相关文档,“前 k 条是否命中”的平均值与单相关文档 Recall@k 一致;有多个相关文档时,hit rate 与 recall 不再相同。
拒答正确率和可回答覆盖率要一起看。全部拒答可能避免错误回答,却不能帮助用户完成可回答任务。不要只挑一个好看的数值。
失败分析按可修复原因分类
| 观察 | 可能原因 | 下一次最小实验 |
|---|---|---|
| 某类频繁被误分 | 类别边界不清、样本少、词汇重叠 | 检查标签规则并补独立边界样本 |
| 训练很好,测试差 | 泄漏修复后的真实差距、过拟合、分布变化 | 固定数据,减少特征或正则化 |
| 文档检索没命中 | 同义词、分词、切块、查询不完整 | 仅改变一个检索组件 |
| 检索命中但回答错 | 答案提取、生成或上下文使用问题 | 单独验收答案步骤 |
| 本地接口延迟波动 | 预热、并发、输入大小或资源竞争 | 记录条件并重复同一测量 |
| 项目别人跑不通 | 依赖、路径、默认参数或缺少输入 | 从新目录照 README 重跑 |
“模型不好”不是能指导下一步的错误分类。记录输入、预期、实际、原因假设和验证动作,至少保留一条尚未解决的失败。
让项目有个人贡献
先原样跑通本仓库,标明复现。然后提出一个改进问题,例如“能否在不降低不可回答问题拒答率的前提下,提高可回答覆盖率?”固定测试集,建立开发集,调整检索或阈值,再报告收益与代价。
可选扩展包括真实许可数据、另一种基线、批处理、英文与中文分开评测、时间外样本、监控指标。只有你实际实现并验收的扩展才能写进简历。接入 LLM 时需另外记录供应商、模型版本、费用、数据去向、重复运行和生成评测;本版没有对任何在线模型进行这些实验。
研究岗的额外要求
三个轻量样例只能建立实验习惯。若目标 JD 要求深度学习研究,应再做匹配方向的论文复现:固定论文版本和数据许可;写清硬件预算;复现一个核心结论;记录多次运行;分析与原文的差异;在许可范围内发布代码。没有算力时缩小研究问题,不能伪造实验。
PyTorch 官方文档指出,不同版本、平台和 CPU/GPU 之间不能保证完全一致的可复现结果。记录环境、随机性控制和算子选择,比只写一个随机种子更完整。T03
项目完成检查
- 输入完整、来源和许可明确,未包含个人信息或机构秘密。
- 一条命令可以生成结果,异常时给出可理解的错误。
- 基线、改动、指标、失败样本、限制都能找到。
- 只用开发集调参,保留测试用途;发现污染后重新建评测。
- 个人、第三方、同伴和 AI 辅助贡献已经声明。
- 未把教学指标写成客户收益、就业结果或生产性能。
通过这些检查后,才进入简历和面试表达。