用户指南 | API | 笔记本

---

Rust 中的机器学习 (Machine Learning)

---

为了开始熟悉新的 smartcore v0.4 API，现在有一个 Jupyter Notebook 环境仓库。请查看那里的说明，欢迎贡献，参见 CONTRIBUTING。

smartcore 是一个快速、易用的 Rust 机器学习库，涵盖经典的监督和无监督方法，具有模块化线性代数抽象和可选的 ndarray 支持。它旨在提供适合生产的 API、强类型和良好的默认值，同时保持对研究和实验的灵活性。

亮点

• 广泛的算法覆盖：线性模型、基于树的方法、集成学习、SVM（支持向量机）、邻居、聚类、分解和预处理。
• 强大的线性代数特质 (traits)，为偏好数组优先工作流的用户提供可选的 ndarray 集成。
• WASM 优先默认设置，注重可移植性；serde 和数据集等功能为可选开启。
• 实用的工具用于模型选择、评估、读取器（CSV）、数据集生成器和内置示例数据集。

安装

添加到 Cargo.toml：

[dependencies]
smartcore = "^0.4.3"

对于最新的开发分支：

[dependencies]
smartcore = { git = "https://github.com/smartcorelib/smartcore", branch = "development" }

可选功能（示例）：

• datasets
• serde
• ndarray-bindings（根据近期更改，已弃用以让位于仅 ndarray 支持）

请检查 Cargo.toml 以获取可用功能和兼容性说明。

快速开始

这里是一个使用 DenseMatrix 从原生 Rust 向量拟合 KNN（K-近邻）分类器的最小示例：

use smartcore::linalg::basic::matrix::DenseMatrix;
use smartcore::neighbors::knn_classifier::KNNClassifier;

// Turn vector slices into a matrix
let x = DenseMatrix::from_2d_array(&[
    &[1., 2.],
    &[3., 4.],
    &[5., 6.],
    &[7., 8.],
    &[9., 10.],
]).unwrap;

// Class labels
let y = vec![2, 2, 2, 3, 3];

// Train classifier
let knn = KNNClassifier::fit(&x, &y, Default::default()).unwrap();

// Predict
let yhat = knn.predict(&x).unwrap();

此示例对应于 crate 文档中的“第一个示例”部分，并展示了 smartcore 的易用 API 界面。

算法

smartcore 将算法组织成清晰的模块，具有统一的特质 (traits)：

• 聚类：K-Means, DBSCAN, 凝聚式（包括单链接），带有 K-Means++ 初始化和实用工具。
• 矩阵分解：SVD, EVD, Cholesky, LU, QR，以及相关的线性代数辅助函数。
• 线性模型：OLS, Ridge, Lasso, ElasticNet, Logistic Regression（逻辑回归）。
• 集成和基于树的方法：随机森林（分类器和回归器），Extra Trees，跨树和森林的共享可重用组件。
• SVM（支持向量机）：SVC/SVR 带内核枚举支持和多类扩展。
• 邻居：KNN 分类和回归，带距离度量和快速选择辅助函数。
• 朴素贝叶斯：高斯型、伯努利型、类别型、多项式型。
• 预处理：编码器、拆分工具和常见转换。
• 模型选择和指标：K-fold（K 折）、搜索参数和评估工具。

最近的强化强调树/森林中的可重用组件和扩展的多类 SVM 能力。添加了 XGBoost 风格回归和单链接聚类。参见 CHANGELOG 了解 API 变更和迁移说明。

数据访问和读取器

• CSV 读取器：从 CSV 读取矩阵，支持可配置的定界符和标题行，带有友好的错误消息和测试工具（包括非 IO 读取器抽象）。
• 数据集生成器：make_blobs, make_circles, make_moons 用于快速实验。
• 内置数据集（功能门控）：digits, diabetes, breast cancer, boston，带有序列化实用工具以持久化或刷新 .xy bundles。

WebAssembly 和可移植性

smartcore 在默认设置中采用 WASM/WASI 优先姿态，以简化浏览器和嵌入式部署。某些文件系统操作在 wasm 目标中受限；测试和 IO 工具的结构旨在尽可能避免不支持的调用。选择性启用 serde 等功能以最小化占用空间。查阅模块级文档和 CHANGELOG 以获取特定目标的注意事项。

笔记本

通过配套仓库提供一组精选的 Jupyter 笔记本，用于交互式探索 smartcore。要在本地运行，请使用 EVCXR 启用 Rust 笔记本。这是快速实验 v0.4 API 的推荐路径。

路线图和近期变更

• 特质系统重构，更少的结构体 (structs) 和更多的对象安全特质，大型代码库重组。
• 移至 Rust 2021 版本并清理重复代码路径。
• 使用 RNG（随机数生成器）机制在所有算法中使用种子和确定性控制。
• 搜索参数 API 用于 K-Means 和 SVM 家族中的超参数 (hyperparameter) 探索。
• 树和森林组件重构以实现重用；添加 Extra Trees。
• SVM 多类支持；SVR 内核枚举及相关改进。
• 引入 XGBoost 风格回归；实现单链接聚类。

参见 CHANGELOG.md 获取精确细节、弃用和破坏性变更。像 nalgebra-bindings 这样的功能已被放弃，转而采用仅 ndarray 路径。默认功能针对 WASM/WASI 构建进行了调整；根据需要启用 serde/datasets。

贡献

欢迎贡献：

• 打开一个描述变更的问题并在 PR 中链接它。
• 保持 PR 与开发分支同步，并确保测试在稳定版 Rust 上通过。
• 提供或更新测试；运行 clippy 并应用格式化。覆盖率和 linting 是工作流程的一部分。
• 使用提供的 PR 和问题模板来描述行为变更、新功能及预期。

如果添加 IO，首选使非 IO 测试直截了当的抽象（参见 readers/iotesting）。对于数据集，在测试中适当门控序列化辅助函数，以避免在 wasm 目标中意外写入文件。

许可证

smartcore 在宽松许可证 (license) 下开源；详情见 Cargo.toml 和 LICENSE。crate 元数据标识“smartcore Developers”为作者；社区贡献通过 Git 历史和发布记录致谢。

致谢

smartcore 的设计融合了众所周知的机器学习（ML）模式，同时保持地道的 Rust 风格。感谢所有贡献者，你们帮助扩展了算法、改进了文档、实现了 trait（特质）的现代化，并增强了代码库的健壮性以适用于生产环境。

smartcore 快速上手指南

smartcore 是一个面向 Rust 语言的高效、易用的机器学习库，涵盖经典监督与无监督学习方法，支持模块化线性代数抽象及可选的 ndarray 集成。

1. 环境准备

• 操作系统: Linux, macOS, Windows (支持跨平台部署)。
• 开发语言: Rust。
• 版本要求: 推荐使用 Rust 2021 Edition 或更高版本。
• 前置依赖: 确保已安装 Rust 工具链（包含 cargo 和 rustc）。

2. 安装步骤

在您的 Rust 项目根目录下的 Cargo.toml 文件中添加 smartcore 依赖：

[dependencies]
smartcore = "^0.4.3"

如需使用最新开发分支，可使用以下配置：

[dependencies]
smartcore = { git = "https://github.com/smartcorelib/smartcore", branch = "development" }

可选功能特性（按需启用）：

• datasets: 内置数据集支持
• serde: 序列化支持

3. 基本使用

以下示例演示了如何使用原生 Rust 向量配合 DenseMatrix 训练一个 KNN 分类器。

use smartcore::linalg::basic::matrix::DenseMatrix;
use smartcore::neighbors::knn_classifier::KNNClassifier;

// 将向量切片转换为矩阵
let x = DenseMatrix::from_2d_array(&[
    &[1., 2.],
    &[3., 4.],
    &[5., 6.],
    &[7., 8.],
    &[9., 10.],
]).unwrap();

// 类别标签
let y = vec![2, 2, 2, 3, 3];

// 训练分类器
let knn = KNNClassifier::fit(&x, &y, Default::default()).unwrap();

// 预测
let yhat = knn.predict(&x).unwrap();

运行上述代码即可体验 smartcore 简洁的 API 接口。更多算法（如聚类、回归、SVM 等）可参考官方文档。