Tribuo - 一个 Java 预测库（v4.3）

Tribuo 是一个基于 Java 的机器学习库，提供了多分类、回归、聚类、异常检测以及多标签分类等功能。Tribuo 不仅实现了多种流行的机器学习算法，还封装了其他库以提供统一的接口。Tribuo 包含加载、特征提取和数据转换所需的所有代码，并且为所有支持的预测类型提供了评估类。该项目由 Oracle Labs 的机器学习研究团队主导开发，我们欢迎社区贡献。

所有训练器都可以通过 OLCUT 配置系统进行配置。这使得用户能够在一个 XML 或 JSON 文件中定义训练器，并可重复地构建模型。每个包的 config 文件夹中都包含所提供训练器的示例配置文件。这些配置文件也可以使用相应的 OLCUT 配置依赖项以 JSON 或 EDN 格式编写。模型和数据集可以通过 Java 序列化进行序列化。

所有模型和评估都包含一个可序列化的溯源对象，该对象记录了模型或评估的创建时间、数据的身份及其所应用的任何转换，以及训练器的超参数。对于评估而言，此溯源信息还包括所使用的具体模型。溯源信息可以提取为 JSON，或者直接使用 Java 序列化进行序列化。在生产部署中，溯源信息可以被删除并替换为哈希值，以便通过外部系统跟踪模型。许多 Tribuo 模型可以导出为 ONNX 格式，以便在其他语言、平台或云服务中部署。

Tribuo 支持 Java 8 及以上版本，并且我们在 Java 的长期支持版本以及最新版本上进行测试。Tribuo 本身是一个纯 Java 库，支持所有 Java 平台；然而，我们的一些接口需要本地代码，因此仅在有本地库支持的情况下才受支持。我们主要在 Windows 10、macOS 和 Linux（RHEL/OL/CentOS 7+）的 x86_64 架构上进行测试，因为这些是与我们交互的本地库所支持的平台。如果您对其他平台感兴趣，并希望使用本地库接口（ONNX Runtime、TensorFlow 和 XGBoost），我们建议您联系这些库的开发者。请注意，模型卡片和可复现性包需要 Java 17，因此它们并不包含在 tribuo-all Maven Central 发布中。

文档

• 库架构
• 包概览
• Javadoc 4.3、4.2、4.1、4.0
• 辅助程序
• 开发者文档
• 路线图
• 常见问题解答

教程

教程笔记本包括分类、聚类、回归、异常检测、TensorFlow、文档分类、列式数据加载、使用外部训练模型以及配置系统的示例，可以在 tutorials 中找到。这些教程使用 IJava Jupyter 笔记本内核，并支持 Java 10 及以上版本，但模型卡片和可复现性教程需要 Java 17。要将教程中的代码转换回 Java 8，在大多数情况下只需将 var 关键字替换为相应类型即可。

算法

通用预测器

Tribuo 包含多个适用于广泛预测任务的算法实现：

算法	实现	备注
Bagging	Tribuo	可使用任何 Tribuo 训练器作为基学习器
随机森林	Tribuo	适用于分类和回归任务
Extra Trees	Tribuo	适用于分类和回归任务
K-NN	Tribuo	包含多种并行后端选项，以及单线程后端
神经网络	TensorFlow	通过 Tribuo 封装器在 TensorFlow 中训练神经网络。模型可以使用 ONNX 接口或 TF 接口进行部署

集成方法和 K-NN 使用组合函数来生成其输出。这些组合器针对特定的预测任务，但集成方法和 K-NN 的实现则与任务无关。我们为多分类、多标签分类和回归任务提供了投票和平均组合器。

分类

Tribuo 提供以下算法的实现或接口：

算法	实现	备注
线性模型	Tribuo	使用 SGD，并允许使用任何梯度优化器
因子分解机	Tribuo	使用 SGD，并允许使用任何梯度优化器
CART	Tribuo
SVM-SGD	Tribuo	Pegasos 算法的实现
Adaboost.SAMME	Tribuo	可使用任何 Tribuo 分类训练器作为基学习器
多项式朴素贝叶斯	Tribuo
正则化线性模型	LibLinear
SVM	LibSVM 或 LibLinear	LibLinear 仅支持线性 SVM
梯度提升决策树	XGBoost

Tribuo 还提供用于序列分类任务的线性链 CRF。该 CRF 使用 Tribuo 的任意梯度优化器通过 SGD 进行训练。

Tribuo 拥有一组信息论特征选择算法，可用于分类任务。特征输入会自动离散化为等宽区间。目前包括互信息最大化 (MIM)、条件互信息最大化 (CMIM)、最小冗余最大相关性 (mRMR) 和联合互信息 (JMI) 的实现。

为了解释分类器的预测结果，Tribuo 实现了 LIME 算法。该实现允许混合文本和表格数据，并可使用任何稀疏模型作为解释器（例如回归树、Lasso 等），但不支持图像。

回归

Tribuo 的回归算法默认是多维的。一维实现会被封装以产生多维输出。

算法	实现	备注
线性模型	Tribuo	使用 SGD，并允许使用任何梯度优化器
因子分解机	Tribuo	使用 SGD，并允许使用任何梯度优化器
CART	Tribuo
Lasso	Tribuo	使用 LARS 算法
弹性网	Tribuo	使用坐标下降算法
正则化线性模型	LibLinear
SVM	LibSVM 或 LibLinear	LibLinear 仅支持线性 SVM
梯度提升决策树	XGBoost

聚类

Tribuo 提供了聚类的基础设施，并内置了两种聚类算法实现。我们计划在未来逐步增加更多算法。

算法	实现	备注
HDBSCAN*	Tribuo	一种基于密度的算法，用于发现聚类和异常点
K-Means	Tribuo	包含顺序和并行后端，以及 K-Means++ 初始化算法

异常检测

Tribuo 提供了异常检测任务的基础设施。我们计划在未来添加新的实现。

算法	实现	备注
一类支持向量机	LibSVM
一类线性支持向量机	LibLinear

多标签分类

Tribuo 提供了多标签分类的基础设施，并附带一个包装器，可以将 Tribuo 的任何多分类算法转换为多标签分类算法。我们预计未来会增加更多专门针对多标签分类的实现。

算法	实现	备注
独立包装器	Tribuo	通过为每个标签单独训练一个分类器，将多分类算法转换为多标签分类算法
分类器链	Tribuo	利用 Tribuo 的任意多分类算法构建分类器链及随机化分类器链集成
线性模型	Tribuo	使用随机梯度下降法，并支持任意梯度优化器
因子分解机	Tribuo	使用随机梯度下降法，并支持任意梯度优化器

接口

除了我们自己实现的机器学习算法之外，Tribuo 还为 JVM 上流行的机器学习工具提供了通用接口。如果您有兴趣贡献一个新的接口，请在 GitHub 上提交一个问题，我们将讨论它如何融入 Tribuo。

目前，我们已有的接口包括：

• LibLinear - 通过原生 LibLinear（v2.44）的 LibLinear-java 移植版本。
• LibSVM - 使用 C++ 实现的纯 Java 转换版本（v3.25）。
• ONNX Runtime - 通过我们团队贡献的 Java API（v1.12.1）。
• TensorFlow - 使用 TensorFlow Java v0.4.2（基于 TensorFlow v2.7.4）。这使得完全在 Java 中训练和部署 TensorFlow 模型成为可能。
• XGBoost - 通过内置的 XGBoost4J API（v1.6.2）。

二进制文件

Tribuo 的二进制文件已在 Maven Central 发布，其 groupId 为 org.tribuo。要获取所有兼容 Java 8 的 Tribuo 组件，包括 TensorFlow、ONNX Runtime 和 XGBoost 的绑定（这些是本地库），请使用以下依赖：

Maven:

<dependency>
    <groupId>org.tribuo</groupId>
    <artifactId>tribuo-all</artifactId>
    <version>4.3.2</version>
    <type>pom</type>
</dependency>

或 Gradle:

implementation ("org.tribuo:tribuo-all:4.3.2@pom") {
    transitive = true // 对于 build.gradle（即 Groovy）
    // isTransitive = true // 对于 build.gradle.kts（即 Kotlin）
}

tribuo-all 依赖是一个 pom 文件，它依赖于所有的 Tribuo 子项目，但不包括需要 Java 17 的模型卡片和可复现性项目。

Tribuo 的大部分代码是纯 Java，因此具有跨平台特性，然而部分接口会链接到使用本地代码的库。这些接口（TensorFlow、ONNX Runtime 和 XGBoost）仅能在各自发布二进制文件的支持平台上运行，而 Tribuo 并不能控制具体提供哪些二进制文件。如果您需要特定平台的支持，请联系这些项目的维护者。截至 4.1 版本，这些本地包都提供了适用于 Windows、macOS 和 Linux 的 x86_64 二进制文件。此外，也可以为 macOS ARM64（即 Apple Silicon）编译每个包，不过目前 Maven Central 尚未提供适用于该平台的 TensorFlow 或 XGBoost 二进制文件。从 4.3 版本开始，Tribuo 现在依赖于一个支持 macOS ARM64 和 Linux aarch64 平台的 ONNX Runtime 版本。在 ARM 平台上开发时，您可以在 Tribuo 的 pom.xml 中选择 arm 配置文件来禁用本地库测试。

Tribuo 的各个模块也分别发布了单独的 jar 文件。建议仅依赖于项目所需的模块，这样可以避免您的代码不必要地引入像 TensorFlow 这样的大型依赖项。

从源码编译

Tribuo 使用 Apache Maven v3.5 或更高版本进行构建。Tribuo 兼容 Java 8 及以上版本，并且我们在 LTS 版本的 Java 以及最新版本上进行测试。要构建，只需运行 mvn clean package 即可。Tribuo 的所有依赖项应可在 Maven Central 获取。如果您在构建过程中遇到问题，请提交一个问题（但在提交之前，请先检查是否缺少 Maven 的代理设置，因为这通常是构建失败的常见原因，且不在我们的控制范围内）。请注意，如果您使用 Java 16 或更早版本进行构建，模型卡片和可复现性相关的包将会被禁用。

仓库布局

开发工作在 main 分支上进行，该分支的版本号为下一个 Tribuo 发布版本，并附加了 -SNAPSHOT 后缀。Tribuo 的主要和次要版本将在 main 分支上打标签，然后从标记的提交中分支出名为 vA.B.X-release-branch 的分支，用于后续的点版本发布（例如 vA.B.1、vA.B.2 等）。这些点版本会在相应的发布分支上打标签，比如 v4.0.2 就会在 v4.0.X-release-branch 分支上打标签。

贡献

我们欢迎各种贡献！请参阅我们的贡献指南。

我们有一个讨论邮件列表 tribuo-devel@oss.oracle.com，存档在此处：这里。我们正在探索不同的实时聊天方式，敬请期待。对于错误报告、功能请求或其他问题，请在 GitHub 上提交一个问题。

安全

请参阅安全指南，了解我们负责任的安全漏洞披露流程。

许可证

Tribuo 根据 Apache 2.0 许可证授权。

发布说明：

• v4.3.2 - 修复了一些小 bug，特别是在 Protocol Buffers 序列化和树模型方面，并升级了依赖项。
• v4.3.1 - 修复了一些小 bug，特别是在 CART 树和 Example.densify 方法中，并将依赖项升级到更安全的版本。
• v4.3.0 - 增加了模型卡片支持、分类任务中的特征选择功能、Protocol Buffers 序列化格式、用于距离计算的 kd 树，以及稀疏线性模型的速度优化。同时更新了大多数依赖项的版本，并进行了其他多项小修复和改进。
• v4.2.2 - 修复了一些小 bug，将 TF-Java 升级至 0.4.2，Jackson 升级至 2.13.4，protobuf-java 升级至 3.19.6，OpenCSV 升级至 5.7.1。
• v4.2.1 - 修复了 KMeans 的多线程问题、影响 ONNX 导出和 K-Means 初始化的非确定性迭代顺序等问题，并将 TF-Java 升级至 0.4.1。
• v4.2.0 - 新增了因子分解机、分类器链和 HDBSCAN 聚类算法。增加了 ONNX 导出和 OCI 数据科学集成功能，并引入了可复现性框架。此外还进行了多项小修复和改进，包括 v4.1.1 中的回归问题修复。补充了剩余的 Javadoc 文档，新增了 4 个教程（ONNX 导出、多标签分类、可复现性、HDBSCAN），并扩展了现有教程。
• v4.1.1 - 修复了多输出回归、多标签评估、在 SecurityManager 环境下使用 KMeans 和 KNN 时的问题，并将 TF-Java 更新至 0.4.0。
• v4.1.0 - 新增了 TensorFlow 训练支持、BERT 特征提取器、ExtraTrees 随机森林、K-Means++ 算法，以及多项线性模型和 CRF 模型的性能优化。同时新增了关于 TensorFlow 和文档分类的教程，并修复了大量 bug 和文档问题。
• v4.0.2 - 修复了许多 bug（CSVDataSource、JsonDataSource、RowProcessor、LibSVMTrainer、Evaluations、Regressor 序列化等）。改进了 Javadoc 和文档，并新增了两个教程（列式数据和外部模型）。
• v4.0.1 - 修复了 CSVReader 在处理空行时的问题，并新增了 IDXDataSource，以支持加载原生 MNIST 格式的数据。
• v4.0.0 - 初次公开发布。
• v3 - 新增了溯源系统、外部模型支持和 ONNX 集成。
• v2 - 功能从单纯的分类系统扩展到支持回归、聚类和多标签分类。
• v1 - 初始内部版本。该版本仅支持多分类任务。

Tribuo 快速上手指南

Tribuo 是由 Oracle Labs 开发的 Java 机器学习库，支持多类分类、回归、聚类、异常检测和多标签分类。它提供了统一的接口，既包含原生算法实现，也封装了 LibSVM、XGBoost、TensorFlow 等流行工具。

环境准备

• 操作系统：Windows 10, macOS, Linux (RHEL/OL/CentOS 7+)。
  • 注意：若使用 TensorFlow、ONNX Runtime 或 XGBoost 等涉及本地代码的接口，主要支持 x86_64 架构。macOS ARM64 (Apple Silicon) 和 Linux aarch64 在部分组件（如 ONNX Runtime）上已获支持。
• JDK 版本：Java 8 或更高版本。
  • 核心库兼容 Java 8+。
  • 若需使用“模型卡片 (Model Card)"和“可复现性 (Reproducibility)"功能，必须使用 Java 17。
• 构建工具：Apache Maven 3.5+ 或 Gradle。

安装步骤

Tribuo 发布在 Maven Central 仓库。推荐根据项目需求引入依赖，避免打包过大的非必要组件（如 TensorFlow）。

方案 A：引入完整包（推荐新手）

此方式会引入除需要 Java 17 的模块外的所有 Tribuo 子项目（包括 TensorFlow, ONNX, XGBoost 绑定）。

Maven (pom.xml):

<dependency>
    <groupId>org.tribuo</groupId>
    <artifactId>tribuo-all</artifactId>
    <version>4.3.2</version>
    <type>pom</type>
</dependency>

Gradle (build.gradle):

implementation ("org.tribuo:tribuo-all:4.3.2@pom") {
    transitive = true
}

方案 B：按需引入模块（生产环境推荐）

仅引入需要的算法模块，减小打包体积。例如，仅使用原生随机森林算法：

Maven:

<dependency>
    <groupId>org.tribuo</groupId>
    <artifactId>tribuo-ensemble</artifactId>
    <version>4.3.2</version>
</dependency>
<dependency>
    <groupId>org.tribuo</groupId>
    <artifactId>tribuo-core</artifactId>
    <version>4.3.2</version>
</dependency>

国内加速提示：如果下载依赖缓慢，请在 Maven settings.xml 或 Gradle build.gradle 中配置阿里云镜像源：

• Maven 镜像 URL: https://maven.aliyun.com/repository/public
• Gradle 镜像 URL: https://maven.aliyun.com/repository/public

基本使用

以下示例展示如何使用 Tribuo 原生的随机森林 (Random Forest) 算法进行简单的多类分类任务。

1. 准备数据与训练模型

import org.tribuo.MutableDataset;
import org.tribuo.data.columnar.ColumnarDataLoader;
import org.tribuo.data.columnar.ResponseProcessor;
import org.tribuo.data.columnar.FieldProcessor;
import org.tribuo.data.columnar.joiners.JoinedDataLoader;
import org.tribuo.classification.example.IrisUtil;
import org.tribuo.classification.RandomForestTrainer;
import org.tribuo.classification.ensemble.BaggingTrainer;
import org.tribuo.classification.dtree.CARTTrainer;
import org.tribuo.Model;
import org.tribuo.evaluation.Evaluator;
import org.tribuo.classification.evaluation.ClassificationEvaluator;

import java.util.HashMap;
import java.util.Map;

public class QuickStart {
    public static void main(String[] args) {
        // 1. 加载数据 (此处使用内置的鸢尾花数据集示例)
        // 实际项目中可使用 ColumnarDataLoader 加载 CSV 等文件
        MutableDataset<String> dataset = IrisUtil.loadTrainData();

        // 2. 配置基础学习器 (CART 决策树)
        CARTTrainer cartTrainer = new CARTTrainer();

        // 3. 配置集成学习器 (随机森林 = Bagging + CART)
        // 设置树的数量为 100
        RandomForestTrainer rfTrainer = new RandomForestTrainer(cartTrainer, 100);

        // 4. 训练模型
        System.out.println("开始训练...");
        Model<String> model = rfTrainer.train(dataset);
        System.out.println("训练完成：" + model.toString());

        // 5. 评估模型
        Evaluator<?> evaluator = new ClassificationEvaluator<>();
        var output = evaluator.evaluate(model, dataset);
        System.out.println(output.confusionString());
        
        // 6. 进行预测
        // 获取第一条数据作为测试样本
        var example = dataset.getExample(0);
        var prediction = model.predict(example);
        System.out.println("预测结果: " + prediction.getOutput());
        System.out.println("置信度: " + prediction.getScore());
    }
}

2. 模型持久化与溯源

Tribuo 内置了完整的溯源（Provenance）系统，模型可直接通过 Java 序列化保存，其中包含了训练时间、数据指纹、超参数等信息。

import java.io.FileOutputStream;
import java.io.ObjectOutputStream;

// 保存模型
try (ObjectOutputStream oos = new ObjectOutputStream(new FileOutputStream("rf_model.ser"))) {
    oos.writeObject(model);
    System.out.println("模型已保存至 rf_model.ser");
} catch (Exception e) {
    e.printStackTrace();
}

// 加载模型
try (ObjectInputStream ois = new ObjectInputStream(new FileInputStream("rf_model.ser"))) {
    Model<String> loadedModel = (Model<String>) ois.readObject();
    // 使用 loadedModel 进行预测...
} catch (Exception e) {
    e.printStackTrace();
}

关键特性提示

• 配置系统：所有训练器均可通过 XML 或 JSON 文件配置（基于 OLCUT），便于复现实验。
• ONNX 导出：许多 Tribuo 模型支持导出为 ONNX 格式，以便在其他语言或云平台部署。
• 解释性：内置 LIME 算法实现，可用于解释分类器的预测结果（支持文本和表格数据）。