# AI 算法研发工作流

`ml-development` 是随 pi-pstack-native 提供的 Pi Skill，用于组织机器学习、深度学习和大模型评测任务。它把数据、实验与证据串起来，适用于已有项目，也适用于从零搭建小型实验。它提供工作方法和记录模板；训练框架、数据、计算资源和评测命令仍由实际项目决定。

## 开源实践调研

下面是本流程参考的开源工具及其适用边界。它们解决的问题不同，**不需要全部安装**。

| 项目 | 适合解决的问题 | 本流程借鉴的做法 | 选择时考虑 |
| --- | --- | --- | --- |
| [DVC](https://doc.dvc.org/user-guide/pipelines/defining-pipelines) | 数据与模型产物版本、可复现的多阶段流水线 | 记录数据版本、参数、代码和阶段依赖 | 多人协作、大文件及复杂流水线时有价值；小项目可以先用现有脚本和清单。 |
| [MLflow Tracking](https://mlflow.org/docs/latest/ml/tracking/) | 记录实验参数、指标、代码版本和产物 | 用统一记录关联运行、配置、数据、指标和产物 | 适合实验数量较多时检索比较；单次实验也可先使用项目内记录。 |
| [Optuna](https://optuna.readthedocs.io/en/stable/tutorial/20_recipes/002_multi_objective.html) | 超参数搜索、多目标优化 | 先定义搜索空间、预算和评价方式，再比较试验 | 搜索本身消耗计算资源；种子不能保证所有场景可复现，参见其[复现说明](https://optuna.readthedocs.io/en/stable/faq.html)。 |
| [scikit-learn](https://scikit-learn.org/stable/common_pitfalls.html) | 传统机器学习的基线、预处理和评估 | 按任务选择切分单位，在训练集拟合预处理，防止数据泄漏 | 即使使用其他框架，也应检查数据、特征工程与评估之间是否泄漏。 |
| [PyTorch](https://docs.pytorch.org/docs/stable/notes/randomness.html) | 深度学习训练与计算 | 记录随机性、软件和硬件环境，区分固定种子与可复现性 | 不同平台、版本和算子可能产生差异；确定性设置可能影响性能或不可用。 |
| [lm-evaluation-harness](https://github.com/EleutherAI/lm-evaluation-harness) | 大模型任务评测与标准化比较 | 记录任务、模型、提示、生成设置和评测版本 | 公共 benchmark 不自动代表实际业务表现，还需检查数据污染、成本和任务适配性。 |

这些项目是可选工具和方法参考，当前 Skill 不会自动部署它们，也不会要求使用某家云服务或实验平台。

## 使用

在安装本扩展的 Pi 会话中显式调用：

```text
/skill:ml-development 为当前分类项目建立可复现的基线：检查数据切分，确定主指标，运行预算内的冒烟测试，并记录下一轮实验计划。
```

此 Skill 采用显式调用模式（`disable-model-invocation: true`），不会因为普通的 ML 自然语言请求自动触发。可以在 `/skill:ml-development` 后用自然语言描述任务。与 `/poteto-mode` 配合时需明确要求两者；Poteto 的上游路由不会自动选择本套流程。Skill 的调用依赖模型实际遵循指令，不保证自动启动子代理或训练任务。

建议在请求中提供数据位置与使用权限、任务目标、已有基线、评估指标、时间和计算预算；如果存在独立测试集，还应说明其使用规则。涉及长时间训练、付费服务或共享计算资源时，先明确预算及使用范围。Pi 子代理的 token、费用、运行时长预算不会自动约束外部训练进程、GPU 用量或云服务计费；没有能管理完整进程树并强制执行预算的授权执行环境时，应只准备命令与计划，不启动此类训练。未提供必要数据或设备时，流程会尽量完成独立的准备工作，并说明哪些步骤无法执行。

## 六个阶段

1. **定义问题**：明确预测对象、约束、指标方向、现有基线和预算。
2. **准备数据**：记录数据版本及切分方法，检查重复、时间和实体泄漏；只在训练集拟合预处理。
3. **建立基线**：复用现有实现或建立简单基线；先运行必要的低成本代码检查和冒烟测试。
4. **规划实验**：列出假设、对照、参数范围和资源上限；记录失败和中止的试验。
5. **评估比较**：在一致协议下报告指标、样本量及可行的误差或不确定性；保留最终测试集用于冻结方案后的评估。
6. **复现与交付**：记录代码、数据标识、依赖、硬件、配置、命令、随机性和产物位置，同时说明无法复现的部分。

可以按任务只执行相关阶段；例如已有模型的评估从第五阶段开始，但仍要检查数据切分和比较协议。随包提供的 [运行记录](../skills/ml-development/references/run-record.md) 和 [实验矩阵](../skills/ml-development/references/experiment-matrix.md) 是模板，不会自动覆盖项目文件。

## 示例与结果解读

- **监督学习**：用户提供已有数据集，要求按用户或时间分组切分，以指定指标比较简单基线与候选模型。实验应记录数据版本、训练集拟合的变换、样本数和验证结果；最终测试集不参与调参。
- **大模型或代理评测**：固定模型版本、提示词、采样参数、工具权限和用例集，分别记录任务本身是否成功、报告格式是否符合合同、评测是否运行以及验收结果。不能仅凭一个 `verified` 数字判断模型能力。
- **缺少 GPU 或数据权限**：可以检查仓库、设计实验和编写适当的离线测试；训练或真实模型评测应标记为未运行，不得把模拟结果当成真实性能。

Skill 及其六个阶段可以通过扩展的 `pstack_skill` 工具供子代理读取。复用已有的 `scout`、`architect`、`worker`、`reviewer`、`verifier` 角色，无须为六个阶段各建一个 Agent。`reviewer` 和 `verifier` 仅能只读检查证据，不能执行训练命令；并行任务仍由现有工作流权限、验证策略和实际模型调用决定。Git worktree 不是操作系统安全沙箱，不应在公开记录中包含凭证或敏感数据。