# 机器学习开发规范 - CODING-STANDARDS-ML

**版本**: 2.0.0
**适用范围**: 机器学习开发岗位（监督/无监督/强化学习/深度学习，框架无关）
**最后更新**: 2025-12-25

---

## 🚨 核心铁律（继承自 common.md）

> **必须遵循 common.md 的四大核心铁律**

```
铁律1: SPEC 是唯一真源（SSOT）
       - 模型需求必须符合 SPEC 定义
       - 指标、数据、部署以 SPEC 为准

铁律2: 智能复用与销毁重建
       - 现有模型完全匹配 → 直接复用
       - 部分匹配 → 重新训练

铁律3: 禁止渐进式开发
       - 禁止在旧模型上微调新功能
       - 禁止保留兼容性特征

铁律4: Context7 调研先行
       - 使用成熟的 ML 框架和工具
       - 禁止自己实现常见算法
```

---

## 📊 数据管理

### 数据质量
- ✅ 数据探索性分析（EDA）
- ✅ 缺失值检测和处理
- ✅ 异常值识别和处理
- ✅ 数据一致性验证
- ✅ 数据分布检查
- ❌ 不要盲目使用原始数据

### 数据预处理
- ✅ 数据清洗流程标准化
- ✅ 特征缩放（归一化/标准化）
- ✅ 类别编码（One-Hot/Label/Target）
- ✅ 文本预处理（分词/去停用词/词干化）
- ✅ 图像预处理（缩放/增强/归一化）
- ❌ 避免数据泄漏（训练集信息进入测试集）

### 数据划分
- ✅ 训练集/验证集/测试集分离
- ✅ 时间序列数据按时间划分
- ✅ 分层采样（保持类别分布）
- ✅ 交叉验证（K-Fold/Stratified）
- ❌ 禁止测试集用于模型选择

---

## 🔧 特征工程

### 特征构建
- ✅ 领域知识驱动特征
- ✅ 特征交互（组合特征）
- ✅ 多项式特征
- ✅ 时间特征提取（日/周/月/季节）
- ✅ 聚合特征（统计量）
- ❌ 避免特征爆炸（维度灾难）

### 特征选择
- ✅ 相关性分析
- ✅ 特征重要性排序
- ✅ 递归特征消除（RFE）
- ✅ 正则化（L1/L2）
- ✅ 方差阈值过滤
- ❌ 避免保留冗余特征

### 特征存储
- ✅ 特征版本控制
- ✅ 特征复用（特征商店）
- ✅ 特征文档化
- ✅ 特征管道自动化
- ❌ 避免特征不一致（训练vs推理）

---

## 🤖 模型开发

### 模型选择
- ✅ 基线模型先行（简单模型）
- ✅ 根据问题选择模型类型
- ✅ 对比多种模型
- ✅ 集成学习（Ensemble）
- ❌ 不要过早使用复杂模型

### 训练流程
- ✅ 设置随机种子（可复现）
- ✅ 早停（Early Stopping）
- ✅ 学习率调度
- ✅ 梯度裁剪（防止梯度爆炸）
- ✅ 批次大小合理设置
- ❌ 避免训练集过拟合

### 超参数调优
- ✅ 网格搜索（Grid Search）
- ✅ 随机搜索（Random Search）
- ✅ 贝叶斯优化
- ✅ 超参数重要性分析
- ✅ 验证集选择最优超参数
- ❌ 不要在测试集上调参

---

## 📈 模型评估

### 评估指标
- ✅ 根据业务目标选择指标
- ✅ 分类：Accuracy/Precision/Recall/F1/AUC
- ✅ 回归：MAE/MSE/RMSE/R²
- ✅ 排序：NDCG/MAP
- ✅ 多指标综合评估
- ❌ 单一指标可能误导

### 模型诊断
- ✅ 学习曲线分析
- ✅ 混淆矩阵（分类）
- ✅ 残差分析（回归）
- ✅ 特征重要性
- ✅ 错误样本分析
- ❌ 不要忽略模型偏差

### 过拟合防止
- ✅ 正则化（L1/L2/Dropout）
- ✅ 数据增强
- ✅ 早停
- ✅ 交叉验证
- ✅ 简化模型复杂度
- ❌ 避免训练集性能完美但泛化差

---

## 🔬 实验管理

### 实验追踪
- ✅ 记录超参数配置
- ✅ 记录训练指标
- ✅ 记录模型版本
- ✅ 记录数据版本
- ✅ 使用实验追踪工具（MLflow/Weights & Biases）
- ❌ 不要手动记录实验

### 可复现性
- ✅ 固定随机种子
- ✅ 环境配置版本化（requirements.txt）
- ✅ 代码版本控制（Git）
- ✅ 数据版本控制（DVC）
- ✅ 训练脚本参数化
- ❌ 避免环境依赖不明确

---

## 🚀 模型部署

### 模型序列化
- ✅ 标准格式保存（ONNX/SavedModel）
- ✅ 模型版本化
- ✅ 模型元数据记录
- ✅ 模型压缩（量化/剪枝）
- ❌ 避免使用不兼容格式

### 推理优化
- ✅ 批量推理
- ✅ 模型量化（INT8/FP16）
- ✅ 模型蒸馏（Teacher-Student）
- ✅ 推理加速（TensorRT/ONNX Runtime）
- ✅ 缓存热点预测
- ❌ 避免推理延迟超标

### 在线服务
- ✅ API接口标准化
- ✅ 输入验证
- ✅ 超时和重试机制
- ✅ 负载均衡
- ✅ A/B测试
- ❌ 不要直接返回模型输出（需后处理）

---

## 📊 监控和维护

### 性能监控
- ✅ 监控推理延迟
- ✅ 监控预测准确率
- ✅ 监控资源使用（CPU/GPU/内存）
- ✅ 监控吞吐量
- ❌ 不要部署后不监控

### 数据漂移检测
- ✅ 输入分布监控
- ✅ 特征漂移检测
- ✅ 概念漂移检测
- ✅ 自动告警
- ✅ 触发模型重训练
- ❌ 避免模型过期

### 模型更新
- ✅ 持续训练（Incremental Learning）
- ✅ 定期重训练
- ✅ 新版本灰度发布
- ✅ 回滚机制
- ❌ 不要中断线上服务

---

## 🔒 安全和隐私

### 数据隐私
- ✅ 数据脱敏
- ✅ 差分隐私
- ✅ 联邦学习（分布式训练）
- ✅ 访问控制
- ❌ 禁止泄露训练数据

### 模型安全
- ✅ 对抗样本检测
- ✅ 模型水印
- ✅ 输入验证（防注入）
- ✅ 输出过滤
- ❌ 避免模型被逆向

### 公平性
- ✅ 检测模型偏见
- ✅ 公平性指标评估
- ✅ 数据平衡
- ✅ 偏见缓解技术
- ❌ 不要忽视伦理问题

---

## 🧪 测试

### 单元测试
- ✅ 数据预处理函数测试
- ✅ 特征工程函数测试
- ✅ 模型推理函数测试
- ✅ 边界条件测试
- ❌ 避免测试覆盖不足

### 集成测试
- ✅ 端到端管道测试
- ✅ 数据验证测试
- ✅ 模型加载测试
- ✅ API接口测试
- ❌ 不要跳过集成测试

### 模型测试
- ✅ 不变性测试（输入变化，输出不变）
- ✅ 定向期望测试（特定输入，预期输出）
- ✅ 性能基准测试
- ✅ 对抗样本测试
- ❌ 避免只测试快乐路径

---

## 📋 机器学习开发检查清单

- [ ] 数据质量验证和预处理
- [ ] 训练/验证/测试集正确划分
- [ ] 特征工程和选择
- [ ] 基线模型建立
- [ ] 超参数调优（验证集）
- [ ] 模型评估（多指标）
- [ ] 过拟合检查
- [ ] 实验可复现（种子/环境/版本）
- [ ] 模型部署和推理优化
- [ ] 监控和数据漂移检测

---

---

## 🏛️ 高级 ML 架构（20+年经验）

### MLOps 成熟度模型
```
Level 0 - 手动过程：
- 手动训练和部署
- 无版本控制
- 无监控

Level 1 - ML 管道自动化：
- 自动化训练管道
- 特征工程自动化
- 实验追踪

Level 2 - CI/CD 管道：
- 模型 CI/CD
- 自动化测试
- 自动化部署

Level 3 - 完整 MLOps：
- 持续训练（CT）
- 持续监控（CM）
- 自动重训练
- 特征商店
```

### 特征商店架构
```
核心组件：
- 特征注册：元数据、血缘、版本
- 离线存储：批量特征（Data Lake）
- 在线存储：实时特征（Redis/DynamoDB）
- 特征服务：低延迟 API

关键能力：
- 训练-推理一致性
- 时间旅行（Point-in-Time）
- 特征复用
- 数据质量验证

技术选型：
- Feast：开源、轻量
- Tecton：企业级
- SageMaker Feature Store：AWS 集成
```

### 大规模训练架构
```
分布式训练：
- 数据并行（Data Parallelism）
- 模型并行（Model Parallelism）
- 流水线并行（Pipeline Parallelism）
- 混合并行（Hybrid Parallelism）

大模型训练：
- DeepSpeed ZeRO
- Megatron-LM
- FSDP（Fully Sharded Data Parallel）
- 梯度检查点（Gradient Checkpointing）

硬件加速：
- GPU 集群（NVIDIA A100/H100）
- TPU Pods（Google Cloud）
- 混合精度训练（AMP）
- 编译优化（TorchScript/XLA）
```

### LLM/生成式 AI 架构
```
RAG（检索增强生成）：
- 向量数据库：Pinecone/Milvus/pgvector
- 嵌入模型：OpenAI/Cohere/本地
- 检索策略：语义/混合
- 生成模型：GPT/Claude/开源

微调策略：
- 全量微调（Full Fine-tuning）
- LoRA/QLoRA（参数高效）
- Prompt Tuning
- RLHF/DPO

生产部署：
- vLLM/TGI（推理优化）
- 量化（INT4/INT8/AWQ/GPTQ）
- 缓存（KV Cache/Prompt Cache）
- 负载均衡
```

---

## 🔧 资深 ML 专家必备技巧

### 深度学习调优
```
超参数策略：
- 学习率：Warmup + Cosine Decay
- Batch Size：渐进增大
- 正则化：Dropout + Weight Decay
- 数据增强：自动化（AutoAugment）

训练稳定性：
- 梯度裁剪（Gradient Clipping）
- 梯度累积（Gradient Accumulation）
- 混合精度（FP16/BF16）
- 初始化策略（Xavier/He/Orthogonal）

调试技巧：
- 过拟合单批次验证
- 学习率范围测试
- 梯度分布监控
- 激活值可视化
```

### 模型评估深度
```
离线评估：
- 分层采样评估
- 时间切分评估
- 交叉验证策略
- 统计显著性检验

在线评估：
- A/B 测试设计
- 多臂老虎机
- 交叉效应检验
- 长期效果追踪

业务指标对齐：
- 模型指标 → 业务指标映射
- 成本敏感评估
- 收益曲线分析
- 阈值优化
```

### 推理优化深度
```
模型压缩：
- 量化：PTQ/QAT
- 剪枝：结构化/非结构化
- 蒸馏：Teacher-Student
- NAS：自动架构搜索

运行时优化：
- 算子融合
- 内存优化
- 批处理策略
- 缓存策略

硬件适配：
- TensorRT（NVIDIA）
- ONNX Runtime
- OpenVINO（Intel）
- CoreML/Metal（Apple）
```

### 生产级监控
```
数据监控：
- 特征分布漂移（KS/PSI）
- 缺失值监控
- 数据延迟监控
- 数据质量分数

模型监控：
- 预测分布变化
- 置信度分布
- 特征重要性变化
- 性能指标趋势

告警策略：
- 分级告警（P0-P3）
- 自动重训练触发
- 人工审核触发
- 回滚机制
```

---

## 🚨 资深 ML 专家常见陷阱

### 数据陷阱
```
❌ 数据泄漏：
- 未来信息进入训练
- 测试集污染
- 正确做法：严格时间切分，特征审查

❌ 采样偏差：
- 样本不代表真实分布
- 类别不平衡处理不当
- 正确做法：分层采样，加权损失

❌ 特征不一致：
- 训练和推理特征计算不同
- 特征版本不匹配
- 正确做法：特征商店，统一管道
```

### 模型陷阱
```
❌ 过度复杂：
- 一上来就用复杂模型
- 无基线对比
- 正确做法：简单基线先行

❌ 指标优化过度：
- 只盯着单一指标
- 忽视业务影响
- 正确做法：多指标平衡，业务对齐

❌ 验证方式不当：
- 随机划分时间序列
- 未考虑数据分布
- 正确做法：按业务场景设计验证
```

### 生产陷阱
```
❌ 模型老化：
- 部署后不监控
- 数据漂移不处理
- 正确做法：持续监控，定期重训

❌ 推理性能忽视：
- 只关注模型精度
- 延迟无法满足 SLA
- 正确做法：性能和精度平衡

❌ 回滚机制缺失：
- 新模型上线出问题
- 无法快速回滚
- 正确做法：蓝绿部署，快速回滚
```

---

## 📊 性能监控指标

| 指标 | 目标值 | 告警阈值 | 测量工具 |
|------|--------|----------|----------|
| 模型准确率 | 根据业务 | 下降 5% | 评估管道 |
| 推理延迟（P99） | < 100ms | > 500ms | APM |
| 特征漂移（PSI） | < 0.1 | > 0.25 | 监控系统 |
| 预测分布偏移 | < 0.1 | > 0.2 | 监控系统 |
| 模型训练时间 | 根据场景 | > 2x 基线 | MLflow |
| GPU 利用率 | > 80% | < 50% | 硬件监控 |
| 特征新鲜度 | < 1小时 | > 24小时 | 特征商店 |
| 数据质量分数 | > 99% | < 95% | 质量平台 |
| 实验成功率 | 根据团队 | 异常下降 | 实验平台 |
| 模型更新频率 | 根据业务 | 超过阈值 | 部署系统 |

---

## 📋 机器学习开发检查清单（完整版）

### 数据管道
- [ ] 数据质量验证
- [ ] 训练/验证/测试正确划分
- [ ] 无数据泄漏
- [ ] 特征工程版本化

### 模型开发
- [ ] 基线模型建立
- [ ] 超参数调优（验证集）
- [ ] 多指标评估
- [ ] 可复现性保证

### 生产部署
- [ ] 推理性能优化
- [ ] 模型版本管理
- [ ] 蓝绿/金丝雀部署
- [ ] 回滚机制

### 持续运营
- [ ] 数据漂移监控
- [ ] 模型性能监控
- [ ] 自动重训练触发
- [ ] 告警和 On-call

---

**机器学习开发原则总结**：
数据质量、特征工程、模型评估、可复现性、实验追踪、部署优化、监控漂移、安全隐私、公平性、持续改进
