rustyml 0.15.0

# 简介

RustyML 是一个完全用 Rust 编写的机器学习与深度学习库。它不需要链接任何外部库，不需要 Python 解释器，也不需要跨越 FFI 边界搬运数组。本指南是这个库的实战伴侣，带你从一个全新的 `cargo new` 项目走到训练神经网络。它还讲解如何调整热点内核里并行与串行的切换阈值，以及序列化一个模型时磁盘上究竟落下了哪些字节。本指南对应 RustyML **0.15**：书中每个完整示例都在这个版本下、开启 `full` 和 `show_progress` feature 编译通过，所以你读到的就是编译器认可的内容。

## 本指南是什么

[docs.rs 上的 API 文档](https://docs.rs/rustyml)是每一个函数签名、每一条 trait 约束、每一个枚举变体的唯一权威来源。本指南不重复那份文档，而是解释签名本身没有说出口的那些取舍。docs.rs 列出了 `Adam::new` 的参数。本指南则说明该选哪个优化器。它说明为什么单次调用的 `random_state` 会压过全局种子，而不是反过来。它还说明把一份保存的网络加载进层形状已经对不上的模型时会发生什么。本指南力求具体，在证据支持的地方直接给出判断，并指出具体估计器中的已知陷阱。

crate 里经典机器学习那一半的代码，几乎都遵循同一个套路：构造、`fit`、`predict`。这正是你在 scikit-learn 里熟悉的先 `(&x, &y)` 再 `&x` 的节奏。

```rust
use rustyml::prelude::machine_learning::*;
use ndarray::array;

fn main() {
    // 一个极小的线性关系：y = 3 * x
    let x = array![[1.0], [2.0], [3.0], [4.0]];
    let y = array![3.0, 6.0, 9.0, 12.0];

    // new(fit_intercept)；默认求解器就是精确的闭式解
    let mut model = LinearRegression::new(true);
    model.fit(&x, &y).unwrap();

    let predictions = model.predict(&x).unwrap();
    println!("predictions: {:?}", predictions);
}
```

本指南后面的内容会逐个模块拆开讲这个套路。模型共享 `Fit` 和 `Predict` trait。指标始终按 `(y_true, y_pred)` 这个顺序取参。一句 `set_global_seed` 就能让整个 crate 变得确定。

## 面向谁

本指南面向两类读者。第一类是想做机器学习、又不愿离开 Rust 生态的 **Rust 开发者**。这类读者不需要 `pip`，不需要链接 BLAS，也没有需要审计的 unsafe FFI。一条 `cargo add` 命令就能引入一个遵守 Rust 所有权、`Send`/`Sync` 和错误处理规则的 crate。第二类是**从 Python 转过来的机器学习从业者**，熟悉 scikit-learn 和 Keras。这类读者想在 Rust 里用上同一套心智模型。RustyML 提供的正是这些：`fit`/`predict` 方法，以及用 `.add(...)` 和 `.compile(...)` 搭起来的 Keras 风格 `Sequential` 模型。它的混淆矩阵和轮廓系数，在 scikit-learn 里是什么意思，在这里就是什么意思。RustyML 把这些概念都用编译型、静态类型、默认并行的 Rust 表达出来。凡是 RustyML 有意与 scikit-learn 或 Keras 不同的地方，本指南都会说明差异以及原因。

你不需要有 Rust 数值代码的经验，但应该能顺畅地读 Rust、会跑 `cargo`。数据自始至终都在 [`ndarray`](https://docs.rs/ndarray) 数组里流动，所以在你随处撞见它之前，[使用 ndarray 准备数据](./Chapter-01/1.3._使用ndarray准备数据.md)会先讲这个库。

## 本书如何组织

整个 crate 拆成五个由 feature 控制的模块：`machine_learning`、`neural_network`、`utils`、`metrics`、`math`。此外还有一个按领域拆分的 `prelude`。章节编排沿着这个结构展开。第 1 章要从头读到尾，之后的章节当作参考资料来用。

| 章节 | 覆盖内容 | 对应模块 |
|---|---|---|
| [1. 快速上手](./Chapter-01/1.0._快速上手.md) | 安装、feature 配置、ndarray、第一个端到端模型、prelude、错误处理 | 入门通道 |
| [2. 经典机器学习](./Chapter-02/2.0._经典机器学习.md) | 回归、分类、聚类、降维、异常检测 | `machine_learning` |
| [3. 神经网络](./Chapter-03/3.0._神经网络.md) | `Sequential` 模型，全连接/卷积/循环层，损失函数，优化器，保存权重 | `neural_network` |
| [4. 数据预处理](./Chapter-04/4.0._数据预处理.md) | 训练集/测试集划分，标准化与归一化，标签编码 | `utils` |
| [5. 模型评估](./Chapter-05/5.0._模型评估.md) | 回归、分类、聚类指标 | `metrics` |
| [6. 数学工具](./Chapter-06/6.0._数学工具.md) | 距离度量、矩阵乘法、确定性的并行归约 | `math` |
| [7. 进阶主题](./Chapter-07/7.0._进阶主题.md) | 可复现性与随机种子，模型持久化内部机制，性能调优，最小化构建 | 横向贯通 |

第 2、3 章覆盖两大算法家族，占了 crate 大部分的表面积。第 4 到 6 章为这两大家族提供支撑：预处理跑在模型之前，指标跑在模型之后，二者都建立在同一套数值原语之上。第 7 章覆盖横向贯通的进阶主题：`random_state` 如何相对全局种子解析、一份保存的模型经 postcard 序列化后的字节里装了什么、运行时可调的并行开关怎么工作。它还展示了如何编译出只拉入 `metrics` 或只拉入 `math` 的构建。

## 怎么读这本书

[快速上手](./Chapter-01/1.0._快速上手.md)要按顺序、从头到尾读一遍，且只需读这一次。它是唯一一章假设你已经读过前面内容的章节。它装好 crate、搭起 ndarray、搭出一个完整模型，好让后面每一章都能踩在这块共同的地基上。第 1 章之后的每一章都是参考资料，可以按任意顺序阅读。手头的问题需要什么，就直接翻到[支持向量机](./Chapter-02/2.5._支持向量机.md)、[优化器](./Chapter-03/3.4._优化器.md)或[聚类指标](./Chapter-05/5.3._聚类指标.md)。遇到某一页依赖另一页讲过的概念时，就顺着正文里的交叉链接跳过去。如果 RustyML 已经能为你编译、模型也已经能训练，那第 1 章的任务就算完成了。把本书剩下的部分当成一本手册：需要哪一页就翻哪一页。

## 版本、反馈与约定

本版对应当前的 crate 版本 **0.15**。RustyML 尚在 1.0 之前，处于活跃开发中。API 正在趋于稳定，但次要版本更新中仍可能出现破坏性更改。如果本指南里的某个签名与编译器实际认可的不一致，请以[对应确切版本的 docs.rs](https://docs.rs/rustyml) 为准。bug 反馈、功能需求，以及对本指南的勘误，都请提交到 [GitHub 仓库](https://github.com/SomeB1oody/RustyML)，那里欢迎 issue 和 pull request。

本指南遵循两条约定。其一，完整示例都是自带 `main` 函数、内嵌极小数据集、只跑几轮迭代的独立程序。把任意一个完整示例粘进一个开了 `full` feature 的项目里，原样运行即可。代码片段和函数签名则会明确标注出来。其二，在 `metrics` 和 `math` 这两个叶子模块之外，所有可能失败的调用都返回 `RustymlResult<T>`，它是 `Result<T, rustyml::error::Error>` 的别名，背后是一个结构化、可 match 的错误枚举。示例里用 `.unwrap()` 只是为了保持简短。[错误处理](./Chapter-01/1.6._错误处理.md)会告诉你在真实代码里该写什么。