V3 Real World Tests 规格

1. 目标

V3 Real World Tests 是进入 1.x 稳定版本之前的真实世界验收门。MPSBoost 在完成 0.x 预发布、功能扩展和工程优化后，必须在公开、可复现、具备实际表格学习难度的 数据集上证明正确性、稳定性、安装体验和端到端性能，才能发布任何 1.x 版本。

在本阶段完成之前，公开 PyPI 版本只能使用 0.x 版本号。1.0.0 代表真实用户可以 依赖的稳定承诺，不允许仅因为功能数量多、CI 通过或 synthetic benchmark 通过就升级。

2. 版本纪律

• 0.x：允许快速迭代、预发布和能力扩展，但必须诚实标注限制。
• 0.x alpha/beta/rc：用于模块里程碑、性能门和稳定性候选。
• 1.x：只能在 V3 真实世界数据集验收全部通过后发布。
• 已发布版本不可覆盖；任何修复必须递增新版本。
• synthetic benchmark 只能证明局部能力，不能单独作为 1.x 发布依据。

3. 数据集要求

真实世界测试集必须满足：

• 来源合法、许可证清楚、可被用户复现；
• 覆盖回归、二分类、多分类、异常检测和排序中已经实现的模型族；
• 包含不同规模：小数据、中等数据、大行数、宽表、高基数类别、缺失值、偏斜标签；
• 明确 train/validation/test 切分；
• 记录数据下载、校验、预处理和缓存策略；
• 不把原始数据、私有数据或许可证不清的数据打包进 wheel。

3.1 数据集验收矩阵

V3 必须建立 tests/real_world/ 测试套件。该套件用于回答“这个库在真实用户会遇到的 数据形态上是否可靠”，而不是替代 unit test、integration test 或 synthetic benchmark。

第一批数据集应优先选择来源稳定、许可证清楚、可缓存、可离线复跑的数据：

数据集	任务类型	主要目的	获取策略
Iris	多分类	最小多分类 sanity test，验证 sklearn 工作流、类别概率和保存加载。	优先使用 sklearn.datasets.load_iris 内置数据。
Breast Cancer Wisconsin	二分类	验证二分类概率、阈值、AUC/accuracy 和小中型数值表格表现。	优先使用 sklearn.datasets.load_breast_cancer 内置数据。
Diabetes	回归	小型回归 sanity test，验证回归指标、模型 I/O 和可复现性。	优先使用 sklearn.datasets.load_diabetes 内置数据。
California Housing	回归	中等规模回归 baseline，覆盖真实数值表格和性能边界。	使用 sklearn.datasets.fetch_california_housing，必须缓存并允许离线复跑。
Digits	多分类	图像 flatten 后的轻量多分类树模型压力测试。	优先使用 sklearn.datasets.load_digits 内置数据。
MNIST subset	多分类	更接近真实图像分类规模的 flatten 特征压力测试，限制样本数避免 CI 失控。	外部下载必须锁版本、缓存、校验 hash；默认不阻塞普通测试。
Titanic	二分类 + 缺失值 + 类别特征	验证真实清洗流程、缺失值策略、类别编码和 pipeline 兼容。	使用稳定镜像或项目下载脚本；禁止把原始数据打包进 wheel。
Adult Income	二分类 + 高类别特征	验证类别特征、较大行数、类别基数和公平记录指标。	外部下载必须缓存、校验 hash，并支持手动预下载路径。
Covertype subset	多分类 + 大行数	验证较大行数、多分类和训练吞吐边界。	外部下载或 OpenML 获取必须 opt-in，默认使用固定子集。
Higgs subset	二分类 + 性能边界	验证大规模数值表格吞吐、内存峰值和 CPU/MPS 退化边界。	只作为 opt-in 长测试；必须限制子集大小并记录机器信息。

3.2 数据与缓存纪律

• tests/real_world/ 不允许 mock 后端，也不允许把合成数据标记为真实数据验收。
• 普通 CI 默认只运行无需网络、无需外部下载、耗时可控的内置数据集测试。
• 外部数据集必须通过项目脚本下载到分层缓存目录，缓存命中时不得重新下载。
• 下载脚本必须记录数据来源、许可证、版本、文件大小、hash 和本地缓存路径。
• 数据预处理必须可复现；随机切分必须固定 seed，并记录 train/validation/test 比例。
• 如果数据下载失败，测试应明确 skip 并说明缺少哪个数据文件，不得静默降级为 mock。
• 真实世界性能测试必须记录设备、系统版本、Python 版本、包版本、数据规模和参数配置。

4. 对照基线

每个已实现模型族必须至少有一个强 CPU 基线和一个项目 CPU oracle 对照：

• CPU oracle 用于数值语义和边界验证；
• 强 CPU 基线用于性能和模型质量参考；
• GPU 结果必须记录训练时间、预测时间、指标、模型大小和内存峰值；
• 小数据退化必须公开，不得只展示赢的场景。

5. 质量门

进入 1.x 前必须全部满足：

• 干净环境安装成功，无本地编译要求；
• 真实数据集训练、预测、保存、加载、复现全部通过；
• 端到端性能报告覆盖预处理、分箱、训练、同步、预测和模型 I/O；
• 模型质量不明显劣于 CPU 基线，差异必须解释；
• 缓存删除、损坏、禁用均不影响结果；
• 长时间重复训练无内存增长、资源泄漏或 GPU command 失败；
• 文档清楚列出支持范围、不支持范围和退化区间。

6. 1.x 发布门

只有以下条件全部完成，tasks.md 才能允许 1.0.0：

1. V1 MPS histogram engine 已稳定；
2. V2 arboretum implementation 中计划进入 1.0 的模型族全部完成；
3. V3 真实世界测试矩阵全部通过；
4. CI、PyPI、wheel、许可证、体积和权限审计全部通过；
5. 用户最终确认公开承诺范围、版本号和 artifact 哈希。