Basalt 3.4.0 文档

欢迎！这里是 Basalt 3.4.0 的官方文档。Basalt 是一个 Java 调度、Rust 托管底层的机器学习运行时，覆盖 eager 张量、自动求导、原生 CNN/Transformer 算子与 scikit-learn 风格的经典估计器。

文档章节：

API 参考按模块组织的完整 API：类型、方法、参数、返回值与抛出条件
快速开始十行代码完成一次前向与反向传播
安装Maven 坐标、运行参数与原生库加载顺序
经典机器学习估计器、指标、数据切分与交叉验证
神经网络手写层、序列模型、注意力与序列训练
eager 张量PyTorch 风格动态张量、Module 组合与自动求导
原生内核指令队列、计算图、内存所有权与失败回退
持久化.bsl v2 容器格式、CRC32C 校验与往返一致性

其他资源：

Basalt 开发者指南构建、验证与基准脚本
架构与基准报告原生 GEMM、自动求导与实测数据
与 scikit-learn 对比同一份 BasaltD 数据下的十项对比
GitHub 仓库源码、发布产物与问题追踪

安装

<dependency>
    <groupId>io.github.9178nekomc</groupId>
    <artifactId>basalt</artifactId>
    <version>3.4.0</version>
</dependency>

运行期需要开启 Vector API 孵化模块：--add-modules jdk.incubator.vector。原生库已随 basalt-3.4.0-all.jar 打包；加载失败时经典模型自动回退纯 Java 路径。

快速开始

try (Basalt jsl = Basalt.create()) {
    Tensor x = basalt.randn(32, 8);
    Tensor y = basalt.randn(32, 1);
    Linear hidden = basalt.linear(8, 16);
    Linear output = basalt.linear(16, 1);
    Tensor loss = output.forward(hidden.forward(x).relu()).mse(y);
    loss.backward();
}

三层 API 边界

层级	入口	适用场景
整体	`Basalt` 门面、`Estimator.fit/predict`	一行完成训练、预测、交叉验证
模块	`RandomForest.builder()`、`HistogramGradientBoosting.builder()`	按模块调参、替换求解器、控制线程
原子	`NativeContext` + `CommandQueueBuilder`	手写算子序列、自定义损失与优化器

模块索引

模块	公开类型	职责
`basalt`	11	统一门面：一次创建上下文，取张量、模块、优化器，并转发经典模型入口。
`basalt.core`	16	基础数据层：行主序矩阵、布局标记、原生经典核、模型容器读写原语。
`basalt.data`	6	BasaltD 数据管线：流式与内存映射两条读取路径、标准化参数。
`basalt.io`	7	模型持久化：.bsl v2 容器（magic + kind + 长度 + CRC32C）。
`basalt.ml`	102	经典机器学习：线性模型、近邻、SVM、树、梯度提升、聚类、降维、朴素贝叶斯、指标与切分。
`basalt.nn`	36	手写神经网络层：Dense / Conv2D / RNN / LSTM / GRU / 注意力、序列训练与序列化。
`basalt.nativebridge`	8	原生桥接专家层：上下文、张量句柄、128 字节指令队列、自动求导入口。
`basalt.torch`	39	PyTorch 风格 eager API：动态张量、Module 组合、原生 autograd、优化器与损失。
`basalt.concurrent`	1	批量推理编排：虚拟线程 + 信号量限流。

文档约定

签名：由 tools/api_dump.py 扫描源码生成，与编译产物一一对应； → 之后是返回类型。
参数：逐个列出名称、类型与语义。标注"默认值"的，取自字段初始值而非推测。
抛出：只列出源码中真实存在的 throw 或显式校验分支。
包内可见类型：没有 public 修饰符但出现在公开签名中的类型，归入各模块页末尾，不作为稳定 API 承诺。
精度分层：原生张量引擎为 f32，经典估计器保持 f64。
规模：226 个公开类型、1463 个公开成员，其中 1463 个成员附有逐参数说明。

构建与验证

mvn clean install        # 编译 + JUnit 5 + 标准 jar + Fat Jar + 源码包
./verify.sh              # 编译期拒绝用例 + legacy 套件 + Rust 单元测试
./benchmark.sh           # 基准，输出 build/bench/*.csv
./native-build.sh        # 只构建 Rust 内核到 build/native/

API 参考