TensorFlow for Java

欢迎来到 TensorFlow 的 Java 世界！

TensorFlow 可以在任何 JVM 上运行，用于构建、训练和部署机器学习模型。它提供了一系列工具和框架，可以帮助数据科学家和该领域的开发者完成大多数常见任务。Java 以及 Scala 或 Kotlin 等其他 JVM 语言在全球各地的中小型企业中被广泛使用，这使得 TensorFlow 成为大规模采用机器学习的战略性选择。

本仓库

早期，TensorFlow 的 Java 绑定托管在 主仓库 中，并且仅在核心库的新版本准备发布时才会一起发布，而这种情况一年通常只发生几次。现在，所有与 Java 相关的代码已被迁移到本仓库，以便能够独立于官方 TensorFlow 发布进行开发和更新。此外，大部分构建任务已从 Bazel 迁移到 Maven，这对于大多数 Java 开发者来说更加熟悉。

以下描述了仓库的布局及其不同构件：

• tensorflow-core

  • 构建 TensorFlow Java 核心语言绑定的所有构件
  • 目标用户：在 TensorFlow 基础之上提供自有 API 或框架的项目，只需要一个轻量级的层来从 JVM 访问 TensorFlow 原生库

• tensorflow-framework

  • 使用 TensorFlow 构建和训练神经网络的主要 API
  • 目标用户：神经网络开发者
  • 更多信息请参阅：tensorflow-framework/README.md

注：NdArray 库模块现已拥有自己的 仓库，并已从 TensorFlow Java 项目中移出。

沟通方式

本仓库由 TensorFlow JVM 特别兴趣小组（SIG）维护。您可以通过在 TensorFlow 论坛 上发帖并添加 sig_jvm 标签，或通过 sig-jvm Gitter 频道 联系我们。您也可以直接向本仓库提交拉取请求或提出问题。

构建源代码

请参阅 CONTRIBUTING.md。

使用 Maven 构件

将 TensorFlow Java 作为依赖项添加到您的 Maven 项目中有两种方式：分别为每个目标平台单独添加依赖，或者使用一个同时支持所有平台的单一依赖。

单独添加依赖

采用这种方式时，您需要先添加 tensorflow-core-api 的依赖，然后再添加一个或多个带有特定平台分类器的 tensorflow-core-native 依赖。这种方法更受推荐，因为它只包含您所需的 TensorFlow 构建，从而最小化应用程序的大小，但同时也更具限制性。

虽然 TensorFlow Java 可以针对 多种平台 进行编译，但本项目目前仅支持并分发以下平台的二进制文件：

• linux-x86_64：基于 Intel/AMD 芯片的 Linux 平台
• linux-x86_64-gpu：支持 CUDA GPU 的 Intel/AMD 芯片上的 Linux 平台
• linux-arm64：基于 Arm 芯片的 Linux 平台
• macosx-arm64：基于 Apple Silicon 芯片的 macOS X 平台
• windows-x86_64：基于 Intel/AMD 芯片的 Windows 平台（v1.1.0 及更早版本）

适用于 macosx-x86_64 的二进制文件仅在 TF-Java 1.0 系列及更早版本中可用；自 TF-Java 1.1 及更高版本起，由于 Google 已不再支持或发布这些版本，因此相关二进制文件已被移除。

例如，如果您要构建一个仅用于部署在无 GPU 支持的 Linux 系统上的 JAR 包，应添加以下依赖：

<dependency>
  <groupId>org.tensorflow</groupId>
  <artifactId>tensorflow-core-api</artifactId>
  <version>1.1.0</version>
</dependency>
<dependency>
  <groupId>org.tensorflow</groupId>
  <artifactId>tensorflow-core-native</artifactId>
  <version>1.1.0</version>
  <classifier>linux-x86_64</classifier>
</dependency>

或使用 Gradle：

def tfVersion = '1.1.0'
implementation "org.tensorflow:tensorflow-core-api:$tfVersion"
implementation "org.tensorflow:tensorflow-core-native:$tfVersion:linux-x86_64"

另一方面，如果您计划将 JAR 包部署到更多平台上，则需要添加额外的原生依赖，如下所示：

<dependency>
  <groupId>org.tensorflow</groupId>
  <artifactId>tensorflow-core-api</artifactId>
  <version>1.1.0</version>
</dependency>
<dependency>
  <groupId>org.tensorflow</groupId>
  <artifactId>tensorflow-core-native</artifactId>
  <version>1.1.0</version>
  <classifier>linux-x86_64-gpu</classifier>
</dependency>
<dependency>
  <groupId>org.tensorflow</groupId>
  <artifactId>tensorflow-core-native</artifactId>
  <version>1.1.0</version>
  <classifier>macosx-arm64</classifier>
</dependency>
<dependency>
  <groupId>org.tensorflow</groupId>
  <artifactId>tensorflow-core-native</artifactId>
  <version>1.1.0</version>
  <classifier>windows-x86_64</classifier>
</dependency>

或使用 Gradle：

def tfVersion = '1.1.0'
implementation "org.tensorflow:tensorflow-core-api:$tfVersion"
implementation "org.tensorflow:tensorflow-core-native:$tfVersion:linux-x86_64-gpu"
implementation "org.tensorflow:tensorflow-core-native:$tfVersion:macosx-arm64"
implementation "org.tensorflow:tensorflow-core-native:$tfVersion:windows-x86_64"

每个平台只能添加一个依赖，这意味着您不能在同一项目中同时添加 linux-x86_64 和 linux-x86_64-gpu 的原生依赖。

若要使用 NVIDIA GPU，您需要安装 NVIDIA 设备驱动程序、CUDA Toolkit 和 cuDNN。对于 Ubuntu 24.04，您可以使用以下命令安装它们： sudo apt install -y nvidia-driver-550 nvidia-cuda-toolkit nvidia-cudnn

单一依赖项

在某些情况下，添加一个包含运行 TensorFlow Java 所需所有工件的单一依赖项可能是更优的选择，这些工件会以传递方式引入，适用于任何受支持的平台。

• tensorflow-core-platform：包含 tensorflow-core-api，以及针对 linux-x86_64、linux-x86_64-arm64、macosx-arm64 和 windows-x86_64 的原生工件。

例如，要在本项目分发二进制文件的任何 CPU 平台上运行 TensorFlow Java，只需将以下依赖项添加到您的应用中：

<dependency>
  <groupId>org.tensorflow</groupId>
  <artifactId>tensorflow-core-platform</artifactId>
  <version>1.1.0</version>
</dependency>

或使用 Gradle：

implementation "org.tensorflow:tensorflow-core-platform:1.1.0"

不过请注意，TensorFlow 的构建产物体积较大，如果包含过多的原生依赖，可能会显著增加应用程序的大小。因此，建议将依赖限制为您目标运行的平台。为此，这些工件包含了遵循本页面约定的配置文件：

• 减少依赖数量

快照版本

TensorFlow Java 工件的快照版本会在代码每次更新后自动发布。要使用这些快照版本，您需要在 pom.xml 中添加 Sonatype OSS 仓库，如下所示：

<repositories>
    <repository>
        <id>tensorflow-snapshots</id>
        <url>https://oss.sonatype.org/content/repositories/snapshots/</url>
        <snapshots>
            <enabled>true</enabled>
        </snapshots>
    </repository>
</repositories>
<dependencies>
    <!-- 依赖示例，更多选项请参阅上文 -->
    <dependency>
        <groupId>org.tensorflow</groupId>
        <artifactId>tensorflow-core-platform</artifactId>
        <version>1.2.0-SNAPSHOT</version>
    </dependency>
</dependencies>

或使用 Gradle：

repositories {
  mavenCentral()
  maven {
    url = uri("https://oss.sonatype.org/content/repositories/snapshots")
  }
}

dependencies {
    // 依赖示例，更多选项请参阅上文
    implementation "org.tensorflow:tensorflow-core-platform:1.2.0-SNAPSHOT"
}

TensorFlow/Java 版本支持

下表展示了 TensorFlow、TensorFlow Java 与最低支持 Java 版本之间的对应关系。

TensorFlow Java 版本	TensorFlow 版本	最低 Java 版本
0.2.0	2.3.1	8
0.3.0	2.4.1	8
0.3.1	2.4.1	8
0.3.2	2.4.1	8
0.3.3	2.4.1	8
0.4.0	2.7.0	8
0.4.1	2.7.1	8
0.4.2	2.7.4	8
0.5.0	2.10.1	11
1.0.0-rc.1	2.16.1	11
1.0.0-rc.2	2.16.2	11
1.0.0	2.16.2	11
1.1.0	2.18.0	11
1.2.0-SNAPSHOT	2.20.0	11

如何贡献？

欢迎各位贡献代码和建议，具体指南请参阅 CONTRIBUTING.md。

代码与使用示例

请查看此仓库：https://github.com/tensorflow/java-models

TensorFlow for Java 快速上手指南

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：
  • Linux (x86_64, arm64)
  • macOS (Apple Silicon arm64)
  • Windows (x86_64)
  • 注意：macOS x86_64 (Intel) 在 1.1.0 及更高版本中已不再支持。
• JDK 版本：最低需要 Java 11 (针对 TensorFlow Java 1.x 版本)。
• 构建工具：Maven 或 Gradle。
• GPU 支持（可选）： 若需使用 NVIDIA GPU 进行加速，需预先安装 NVIDIA 驱动、CUDA Toolkit 和 cuDNN。 以 Ubuntu 24.04 为例，安装命令如下：

  sudo apt install -y nvidia-driver-550 nvidia-cuda-toolkit nvidia-cudnn
  

2. 安装步骤

根据您的项目需求，选择以下两种方式之一将 TensorFlow Java 添加为依赖。推荐方式一以减小应用体积。

方式一：指定平台依赖（推荐）

此方式仅包含您目标运行平台所需的原生库，能有效减小打包体积。您需要同时引入 tensorflow-core-api 和对应平台的 tensorflow-core-native。

Maven (pom.xml)

针对 Linux x86_64 (无 GPU) 环境：

<dependency>
  <groupId>org.tensorflow</groupId>
  <artifactId>tensorflow-core-api</artifactId>
  <version>1.1.0</version>
</dependency>
<dependency>
  <groupId>org.tensorflow</groupId>
  <artifactId>tensorflow-core-native</artifactId>
  <version>1.1.0</version>
  <classifier>linux-x86_64</classifier>
</dependency>

若需支持多平台（例如同时支持 Linux GPU、macOS ARM 和 Windows），可添加多个 native 依赖：

<dependency>
  <groupId>org.tensorflow</groupId>
  <artifactId>tensorflow-core-api</artifactId>
  <version>1.1.0</version>
</dependency>
<dependency>
  <groupId>org.tensorflow</groupId>
  <artifactId>tensorflow-core-native</artifactId>
  <version>1.1.0</version>
  <classifier>linux-x86_64-gpu</classifier>
</dependency>
<dependency>
  <groupId>org.tensorflow</groupId>
  <artifactId>tensorflow-core-native</artifactId>
  <version>1.1.0</version>
  <classifier>macosx-arm64</classifier>
</dependency>
<dependency>
  <groupId>org.tensorflow</groupId>
  <artifactId>tensorflow-core-native</artifactId>
  <version>1.1.0</version>
  <classifier>windows-x86_64</classifier>
</dependency>

Gradle (build.gradle)

def tfVersion = '1.1.0'
implementation "org.tensorflow:tensorflow-core-api:$tfVersion"
// 根据目标平台选择 classifier，例如 linux-x86_64
implementation "org.tensorflow:tensorflow-core-native:$tfVersion:linux-x86_64"

方式二：全平台依赖（便捷模式）

如果您希望代码能在任何支持的平台上直接运行，而不关心具体架构，可以使用 tensorflow-core-platform。但这会显著增加最终构建的 JAR 包体积。

Maven (pom.xml)

<dependency>
  <groupId>org.tensorflow</groupId>
  <artifactId>tensorflow-core-platform</artifactId>
  <version>1.1.0</version>
</dependency>

Gradle (build.gradle)

implementation "org.tensorflow:tensorflow-core-platform:1.1.0"

提示：如需使用最新的开发快照版本（Snapshot），需在构建配置中添加 Sonatype OSS 仓库地址，并将版本号改为如 1.2.0-SNAPSHOT。

3. 基本使用

TensorFlow for Java 提供了两种主要的使用层级：

1. tensorflow-core: 底层 API，用于直接调用 TensorFlow 原生功能。
2. tensorflow-framework: 高层 API，类似于 Python 中的 tf.keras，用于快速构建和训练神经网络。

以下是一个使用 tensorflow-framework 构建并训练简单模型的示例：

import org.tensorflow.framework.losses.Losses;
import org.tensorflow.framework.metrics.Metrics;
import org.tensorflow.framework.optimizers.SGD;
import org.tensorflow.ndarray.NdArrays;
import org.tensorflow.types.TFloat32;

public class QuickStart {
    public static void main(String[] args) {
        // 1. 准备数据 (简单的线性关系 y = 2x)
        var xTrain = NdArrays.ofFloats(new float[][]{{1}, {2}, {3}, {4}});
        var yTrain = NdArrays.ofFloats(new float[][]{{2}, {4}, {6}, {8}});

        // 2. 构建模型 (单层线性回归)
        try (var model = new org.tensorflow.framework.models.Sequential<>()) {
            model.add(org.tensorflow.framework.layers.Dense.builder()
                    .units(1)
                    .inputShape(org.tensorflow.types.Shape.of(1))
                    .build());

            // 3. 编译模型
            model.compile(SGD.builder().learningRate(0.01).build(), 
                          Losses.MSE, 
                          Metrics.MAE);

            // 4. 训练模型
            model.fit(xTrain, yTrain, 100); // 训练 100 个 epoch

            // 5. 预测
            var xTest = NdArrays.ofFloats(new float[][]{{5}});
            var prediction = model.predict(xTest);
            
            System.out.println("预测结果 (输入 5): " + prediction.getObject(0)); 
            // 预期输出接近 10.0
        }
    }
}

更多复杂的模型示例和预训练模型用法，请参考官方示例仓库：https://github.com/tensorflow/java-models