rustyml 0.15.0

# 1.2. 安装与Feature配置

首先你需要在本地[安装Rust工具链](https://rust-lang.org/tools/install/)，确保Rust版本是1.89及以上，并且cargo已安装。运行以下命令以检查:

```bash
rustc --version
cargo --version
```

输出应该类似于:

```
rustc 1.96.0 (ac68faa20 2026-05-25)
cargo 1.96.0 (30a34c682 2026-05-25)

```

需要注意的是，RustyML默认开启全部功能，如果你希望精简内容，只开启部分，也可以在`Cargo.toml`中手动配置，这一点会在之后细讲，不用担心。

## 1.2.1. 将 RustyML 加入你的项目

如果还没有创建项目的话，使用`cargo`创建一个：

```bash
cargo new my_project # 将my_project替换成你想要的项目名
```

正确运行的输出应该类似于:

```
$ cargo new my_project
    Creating binary (application) `my_project` package
note: see more `Cargo.toml` keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
```

[RustyML](https://crates.io/crates/rustyml)在[crates.io](https://crates.io)上可以轻松被找到。

打开项目里的`Cargo.toml`，在`[dependencies]`部分写入:

```toml
[dependencies]
rustyml = "0.15"
ndarray = "0.17"
```
- 第一行依赖的意思是使用0.15版本的`rustyml` crate，使用默认feature(也就是开启全部的feature)，这样一来RustyML所有的功能你都可以使用了。
- 第二行依赖的意思是使用0.17版本的`ndarray` crate，你几乎总是还需要把 `ndarray` 作为*直接*依赖引入，因为这个crate是RustyML的依赖，RustyML需要它来处理数据。

有的使用你用不到RustyML的全部feature，你可以通过调整第一行依赖的`feature`字段来挑选feature组合。几种常见搭配：

```toml
# 不写`feature`字段代表使用默认feature(全部功能)
rustyml = "0.15"

# 仅神经网络框架 (需要关闭default feature)
rustyml = { version = "0.15", default-features = false, features = ["neural_network"] }

# 全量：machine_learning、neural_network、utils、metrics、math (等价于default)
rustyml = { version = "0.15", features = ["full"] }

# 全量，外加训练时的终端进度条
rustyml = { version = "0.15", features = ["full", "show_progress"] }
```

[7.4 按需裁剪与模块化集成](../Chapter-07/7.4._按需裁剪与模块化集成.md) 会深入讲解如何精简feature。

## 1.2.2. Feature 一览表

构建由八个 feature 控制。`default` 和 `full` 则是feature组合。

| Feature            | 对应模块                                                             | 内容                                                         |
|--------------------|----------------------------------------------------------------------|--------------------------------------------------------------|
| `machine_learning` | `rustyml::machine_learning`                                          | 回归、分类、聚类、降维、异常检测                             |
| `neural_network`   | `rustyml::neural_network`                                            | Keras 风格的神经网络架构：`Sequential`、层、优化器、损失函数 |
| `utils`            | `rustyml::utils`                                                     | 标准化、归一化、标签编码、训练/测试集划分                    |
| `metrics`          | `rustyml::metrics`                                                   | 回归、分类、聚类的评估指标                                   |
| `math`             | `rustyml::math`                                                      | 数学计算、使用`gemmkit`等矩阵乘积、确定性并行归约            |
| `default`          | `machine_learning` + `neural_network` + `utils` + `metrics` + `math` | 不指定任何 feature 时默认启用全部模块                        |
| `full`             | `machine_learning` + `neural_network` + `utils` + `metrics` + `math` | 全部模块                                                     |
| `show_progress`    | （无对应模块）                                                       | 提供终端进度条显示，详见 [1.2.6](#126-使用show_progress以显示训练进度条) |

一些表格看不出来的信息：
- `machine_learning`、`neural_network`、`utils`、`metrics`都会自动启用`math`。你从不需要在引入别的模块时再手动加上`math`，除非你只想要这个数学计算模块（详见 [6. 数学工具](../Chapter-06/6.0._数学工具.md)）。
- `rustyml::error`（统一的`Error`类型，详见[1.6 错误处理](./1.6._错误处理.md)）和`rustyml::random`（全局种子控制，见 [7.1 可复现性与随机种子](../Chapter-07/7.1._可复现性与随机种子.md)）只要`machine_learning`、`neural_network`或`utils`有一个开着就会出现。但`metrics` 单独构建或 `math` 单独构建时不会，因为这两个叶子模块既不返回 `RustymlResult`，也不消费随机性。
- `rustyml::tuning`（运行时并行度开关，见 [7.3 性能调优与并行](../Chapter-07/7.3._性能调优与并行.md)）无论开哪个feature都会出现。
- `rustyml::prelude` 模块总是会被编译，所以你一直可以从通过它导入内容，详见[1.5 Prelude与模块导入](./1.5._Prelude与模块导入.md)。

## 1.2.3. 每个 feature 引入哪些第三方 crate

下面这个表格展示了RustyML的每个feature都需要使用什么第三方库。就使用来说你完全不需要这些内容，不过这里还是列出来以方便你了解RustyML的依赖情况。

| Feature            | 它激活的第三方 crate                                                                                            |
|--------------------|-----------------------------------------------------------------------------------------------------------------|
| `math`             | `ndarray`、`ahash`、`rayon`、`gemmkit-ndarray`                                                       |
| `machine_learning` | `ndarray`、`rayon`、`ndarray-rand`、`ahash`、`serde`、`postcard`、`thiserror`、`gemmkit-ndarray`     |
| `neural_network`   | `ndarray`、`rayon`、`ndarray-rand`、`indicatif`、`serde`、`postcard`、`thiserror`、`gemmkit-ndarray` |
| `utils`            | `ndarray`、`rayon`、`ndarray-rand`、`ahash`、`serde`、`postcard`、`thiserror`、`gemmkit-ndarray`     |
| `metrics`          | `ndarray`、`ahash`、`rayon`、`gemmkit-ndarray`                                                       |
| `show_progress`    | `indicatif`                                                                                                     |

| 第三方库        | 版本                                     | 作用                                                                                         |
|-----------------|------------------------------------------|----------------------------------------------------------------------------------------------|
| ndarray         | 0.17 + `rayon` feature + `serde` feature | 提供数组类型及相关方法                                                                       |
| rayon           | 1.12                                     | 并行计算                                                                                     |
| ndarray-rand    | 0.16                                     | 为随机初始化提供种子                                                                         |
| ahash           | 0.8 + `serde` feature                    | 提供标签编码和高速哈希表                                                                     |
| serde           | 1.0 + `derive` feature                   | 提供模型权重的序列化和反序列化                                                               |
| postcard        | 1.1 + `use-std` feature                  | 提供模型权重的存储和读取                                                                     |
| thiserror       | 2.0                                      | 派生`Error`枚举                                                                              |
| indicatif       | 0.18                                     | 画进度条                                                                                     |
| gemmkit         | 0.1（默认开启 rayon 并行）               | 纯 Rust 的高性能矩阵乘法引擎，自行决定串行还是并行、用几个线程；经适配器间接引入，不作为直接依赖 |
| gemmkit-ndarray | 0.1 + `epilogue` feature                 | 零拷贝的`ndarray`适配器（转置、跨步切片都不用拷贝），`epilogue`让bias/激活函数融合进矩阵乘法 |

矩阵乘法的后端在gemmkit而不是RustyML里，它提供`GEMMKIT_*`环境变量用于针对机器的调优而非通用调度，详见 [7.3 性能调优与并行](../Chapter-07/7.3._性能调优与并行.md)。

`serde`、`postcard`、`thiserror`是比较重的依赖。把它们去掉（只留`metrics`和/或`math`）可以压缩构建时间并且减少依赖数量，例如：

```toml
rustyml = { version = "0.15", default-features = false, features = ["metrics"] }
```

## 1.2.4. 一个最小的端到端验证

在`Cargo.toml`里面写好依赖之后，在`src/main.rs`里面写代码：

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

fn main() {
    // 3 个样本，2 个特征
    let x = array![[1.0, 2.0], [2.0, 3.0], [3.0, 4.0]];
    let y = array![6.0, 9.0, 12.0];

    // new(fit_intercept) -> Self；默认求解器是精确的闭式解
    // 使用线性回归模型
    let mut model = LinearRegression::new(true);
    model.fit(&x, &y).unwrap(); // 训练模型
    
    // 使用训练好的模型进行预测
    let predictions = model.predict(&x).unwrap();
    println!("predicted {} values", predictions.len());
}
```

使用命令`cargo run`，正常输出：

```
predicted 3 values
```

## 1.2.5. 搭配ndarray

RustyML使用`ndarray`提供的数组类型，不论输入还是输出。经典机器学习模块接收`Array2<f64>`特征矩阵和`Array1<f64>`目标向量，神经网络则使用`Tensor`，也就是`ArrayD<f32>`别名（注意机器学习和工具模块用 `f64`，神经网络用`f32`）。RustyML 0.15基于`ndarray` 0.17构建，确保你的`Cargo.toml`文件里`ndarray`的版本号是`0.17`。

RustyML不会重新导出`ndarray`的构造函数，所以要构造你喂进去的那些数组（比如`array!`、`Array2::from_shape_vec`、`Array::ones`）得从`ndarray` crate里面调用。这就是为什么它必须是`Cargo.toml`里的依赖。[1.3 使用ndarray准备数据](./1.3._使用ndarray准备数据.md)讲了估计器期望的那些数组构造写法。

## 1.2.6. 使用`show_progress`以显示训练进度条

`show_progress`不添加任何类型，也不解锁任何模块。启用后，终端会有进度条显示已用时间、进度位置和当前损失，结束时打印“Training completed”；小批量循环（`fit_with_batches`）显示的是当前 epoch 里已跑过那些 batch 的平均损失。但进度条并不是你取回损失的途径——无论这个 feature 开没开，`fit` 和 `fit_with_batches` 都会返回一个每个 epoch 一条损失的 `History`。它买到的是：一次长时间的训练还在跑的时候你就能看着这个数字变，而不用等调用返回之后才读到。

在`Cargo.toml`中的给`rustyml`的`features`加上`"show_progress"`：

```toml
rustyml = { version = "0.15", features = ["full", "show_progress"] }
```

再次使用命令`cargo run`，你就能看到进度条（由于这个代码里数据比较少，所以你可能观察不到进度条的变化），输出：

```
[00:00:00] ######################################## 1000/1000 | Cost: 0.001324 | Max iterations | Iterations: 1000
predicted 3 values
```

建议只在交互式使用时再打开它。

## 1.2.7. MSRV

RustyML最低支持Rust版本是1.89。在更旧的工具链上，解析器会拒绝这个crate。使用`rustup update stable`就可以更新工具链。

除此之外没有任何需要配置的东西，这就是RustyML的优势。