产品需求文档（PRD）¶

1. 产品愿景¶

MPSBoost 为 Apple Silicon 本地表格学习提供高效、稳定、易安装的梯度提升决策树训练与推理能力。用户通过熟悉的 estimator 风格 Python API 选择 device="mps"，无需理解底层哪些操作使用优化原语、哪些操作使用自定义 GPU kernel。

2. 用户痛点¶

本地设备具有强 GPU 和统一内存，但传统树训练通常无法使用这些资源。
依赖远端 GPU 会增加费用、环境差异、数据传输和隐私风险。
现有通用张量接口不适合直方图聚合、离散切分和动态样本分区。
源码编译、复杂工具链和重量级依赖阻碍普通 Python 用户安装。
只展示 kernel 加速而忽略预处理与同步，会产生错误性能预期。

3. 目标用户¶

在 Apple Silicon Mac 上进行表格回归和分类的数据开发者；
需要本地、离线或隐私友好训练的团队；
需要 estimator 风格接口并希望接入现有 Python 工作流的用户；
研究统一内存与不规则 GPU 算法的系统开发者。

4. 产品原则¶

正确、稳定、容易安装优先于功能数量。
用户入口统一为 mps，内部实现细节不泄露到公共参数。
不静默回退、不接受未知参数、不伪造功能或性能。
小数据可能由 CPU 更快，产品必须公开适用边界。
缓存只提升速度，不改变训练结果。

5. 版本范围¶

0.2.0 必须交付¶

Apple Silicon arm64 macOS 预编译 wheel；
MPSBoostRegressor estimator；
数值稠密二维输入；
平方误差目标；
确定性分箱；
深度受限 histogram GBDT；
MPS 后端真实执行梯度与直方图热路径；
CPU oracle 用于测试，不作为 device="mps" 的静默回退；
fit、predict、get_params、set_params；
模型保存与加载；
is_available() 和 system_info()；
明确错误、中文代码注释、完整测试与可复现 benchmark。

后续版本候选¶

二分类、概率预测和 early stopping；
缺失值默认方向；
行/列采样和更多正则化；
GPU split scan、partition 和训练预测全热路径；
类别特征、多分类、排序与解释能力。

候选能力未进入对应已批准任务前，不得提前暴露为可用 API。

6. 核心用户流程¶

import mpsboost as mb

model = mb.GradientBoostingRegressor(
    n_estimators=200,
    learning_rate=0.05,
    max_depth=6,
    max_bins=256,
    reg_lambda=1.0,
    device="mps",
    random_state=42,
)
model.fit(X_train, y_train)
prediction = model.predict(X_test)
model.save_model("model.mb")

7. 功能需求¶

FR-01 输入¶

接受二维、有限数值的稠密数组和一维标签。
检查形状、dtype、连续性、溢出和生命周期。
输入转换是否复制必须可诊断。

FR-02 参数¶

构造参数采用 estimator 常见命名。
未知参数立即报错；冲突参数列出冲突原因。
构造函数无昂贵副作用，设备初始化发生在 fit()。

FR-03 训练¶

使用统一分箱数据和二阶梯度统计。
树结构、叶值和预测与 CPU oracle 在规定容差内一致。
设备失败不得返回半成品模型。

FR-04 预测¶

训练完成后支持批量预测。
加载模型后的预测与保存前一致。
未拟合调用必须明确报错。

FR-05 设备¶

device="mps" 要求真实 Apple GPU 后端可用，否则早失败。
device="cpu" 仅用于参考和诊断。
device="auto" 已具备初始选择规则和可观察性：小任务或 MPS 不可用时选择 CPU，估计热路径足够大且 MPS 可用时选择 MPS。

FR-06 诊断¶

返回包版本、后端可用性、设备名称、运行模式和关键耗时。
不输出用户名、主目录、训练数据或凭据。

FR-07 缓存¶

L1 进程缓存、L2 用户可重建缓存、L3 构建缓存严格分离。
缓存有版本 key、校验、原子写入和安全失效。
导入包和查询路径不创建缓存目录。

FR-08 模型¶

模型格式版本化、长度可验证、无原始训练数据。
CPU 与 MPS 推理读取同一格式。
未知新版本默认拒绝，不猜测解析。

8. 非功能需求¶

NFR-01 安装¶

支持平台使用 python -m pip install mpsboost 安装。
wheel 自带 native extension 与 shader 资源。
不要求用户安装重量级运行时、包管理器或编译器。

NFR-02 性能¶

大型预登记数据上，GPU histogram 相对项目 CPU oracle 目标至少 2 倍。
至少一个预登记端到端场景优于强 CPU 基线，目标至少 1.3 倍。
所有性能声明必须包含预处理、同步、设备、数据和模型质量。

NFR-03 内存¶

max_bins <= 256 默认使用 uint8。
长生命周期 buffer 复用；禁止与 rows × features × bins 成比例的意外分配。
内存不足前进行检查并给出估算和建议。

NFR-04 稳定¶

所有 GPU command 检查完成状态。
shader/native ABI 不匹配时早失败。
重复训练不发生线性内存增长。
缓存损坏只导致重建，不导致错误模型。

NFR-05 可维护¶

遵守 SOLID/DRY 和中文注释规范。
公共接口、模型格式和关键数据布局均有测试保护。
不允许两套参数语义或重复数学公式。

9. 明确非目标¶

0.2.0 不实现多机、多 GPU、其他操作系统或非 Apple Silicon。
不在 0.2.0 实现完整类别特征、多分类、排序和解释能力。
不以外部项目源码为起点，不复制第三方实现。
不开发图形界面或应用商店产品。

10. 0.2.0 完成定义¶

只有下列条件全部满足才可发布：

真实回归训练和预测完成，不存在 mock 或占位成功路径。
CPU/GPU 正确性、边界、稳定性和安装测试全部通过。
受支持环境的 wheel 在干净机器无需编译即可使用。
端到端基准诚实记录成功与退化区间。
模型保存/加载、缓存失效和错误诊断通过测试。
tasks.md 的 0.2.0 发布门全部打勾。