介紹 (Introduction)

Within many development languages, there is a popular paradigm of using N-Dimensional arrays. They allow you to write numerical code that would otherwise require many levels of nested loops in only a few simple operations. Because of the ability to parallelize, it often runs even faster than the standard looping as well. This is now standard practice in many fields such as data science, graphics, and deep learning, but can be used in applications far beyond this. In Python, the standard library for NDArrays is called NumPy. However, there is no equivalent standard library in Java. One offering for Java developers interested in working with NDArrays is AWS’s Deep Java Library (DJL). Although it also contains Deep Learning, the core is a powerful NDArray system that can be used on its own to bring this paradigm into Java. With support for several Deep Learning Frameworks (PyTorch, TensorFlow, MXNet), DJL can allow the NDArray operations to run at a large-scale and across multiple platforms. No matter whether you are running on CPU or GPU, PC or Android, it simply works. In this tutorial, we will walk through how you can leverage the NDArray from DJL to write your NumPy code in Java and apply NDArray into a real-world application.

在許多開發語言中，存在使用N維數組的流行范例。 它們使您能夠編寫數字代碼，而這些數字代碼僅需執行幾個簡單的操作就需要多層嵌套循環。 由于具有并行化的能力，它通常也比標準循環運行得更快。 現在，這是許多領域(例如數據科學，圖形和深度學習)的標準做法，但可以用于遠遠超出此范圍的應用程序中。 在Python中，NDArrays的標準庫稱為NumPy。 但是，Java中沒有等效的標準庫。 AWS的Deep Java Library(DJL)是對有興趣使用NDArrays的Java開發人員提供的一種服務。 盡管它還包含深度學習，但其核心是功能強大的NDArray系統，可以單獨使用以將該范例引入Java。 借助對幾種深度學習框架(PyTorch，TensorFlow，MXNet)的支持，DJL可以使NDArray操作在多個平臺上大規模運行。 無論您是在CPU還是GPU，PC或Android上運行，它都可以正常工作。 在本教程中，我們將逐步介紹如何利用DJL中的NDArray來用Java編寫NumPy代碼并將NDArray應用到實際應用程序中。

建立 (Setup)

You can use the following configuration in a gradle project. Or, you can skip the setup and try it directly in our interactive online console.

您可以在gradle項目中使用以下配置。 或者，您可以跳過設置并直接在我們的網站中嘗試 交互式在線控制臺 。

plugins {
    id 'java'
}
repositories {                           
    jcenter()
}
dependencies {
    implementation "ai.djl:api:0.6.0"
    // PyTorch
    runtimeOnly "ai.djl.pytorch:pytorch-engine:0.6.0"
    runtimeOnly "ai.djl.pytorch:pytorch-native-auto:1.5.0"
}

That’s it, now we can start our implementation.

就是這樣，現在我們可以開始實施了。

基本操作 (Basic operation)

Let’s first create a try block to create a scope for our code (If you are using the interactive console, you can skip this step):

讓我們首先創建一個try塊來為我們的代碼創建作用域(如果使用交互式控制臺，則可以跳過此步驟)：

try(NDManager manager = NDManager.newBaseManager()) {
}

NDManager helps manage the memory usage of the NDArrays. It creates them and helps clear them as well. Once you finish using an NDManager, it will clear all of the NDArrays that were created within it’s scope as well. NDManager helps the overall system utilize memory efficiently by tracking the NDArray usage. For comparison, let’s see how the code looks in Python’s NumPy as well. We will start by importing the NumPy library with the standard alias.

NDManager有助于管理的內存使用情況NDArrays 。 它創建它們并幫助清除它們。 使用完NDManager后，它還將清除在其作用域內創建的所有NDArray。 NDManager通過跟蹤NDArray的使用情況來幫助整個系統有效地利用內存。 為了進行比較，讓我們看看代碼在Python的NumPy中的外觀。 我們將從導入具有標準別名的NumPy庫開始。

import NumPy as np

In the following sections, we are going to compare the implementation and result between NumPy and DJL’s NDArray.

在以下各節中，我們將比較NumPy和DJL的NDArray之間的實現和結果。

NDArray創建 (NDArray Creation)

ones is an operation to generate N-dim array filled with 1. NumPy

ones是生成填充1的N維數組的操作。NumPy

nd = np.ones((2, 3))
```
[[1. 1. 1.]
 [1. 1. 1.]]
```

NDArray

NDArray

NDArray nd = manager.ones(new Shape(2, 3));
/*
ND: (2, 3) cpu() float32
[[1., 1., 1.],
 [1., 1., 1.],
]
*/

You can also try out random generation. For example, we will generate random uniform data from 0 to 1. NumPy

您也可以嘗試隨機生成。 例如，我們將生成從0到1的隨機統一數據。

nd = np.random.uniform(0, 1, (1, 1, 4))
# [[[0.7034806  0.85115891 0.63903668 0.39386125]]]

NDArray

NDArray

NDArray nd = manager.randomUniform(0, 1, new Shape(1, 1, 4));
/*
ND: (1, 1, 4) cpu() float32
[[[0.932 , 0.7686, 0.2031, 0.7468],
 ],
]
*/

This is just a quick demo of some commonly used functions. The NDManager now offers more than 20 NDArray creation methods that cover most of the methods available in NumPy.

這只是一些常用功能的快速演示。 NDManager現在提供了20多種NDArray創建方法 ，涵蓋了NumPy中可用的大多數方法。

數學運算 (Math operation)

We can also try some math operations using NDArrays. Assume we are trying to do a transpose and add a number to each element of the NDArray. We can achieve this by doing the following: NumPy

我們也可以嘗試使用NDArrays進行一些數學運算。 假設我們正在嘗試進行轉置并將數字添加到NDArray的每個元素中。 我們可以通過執行以下操作來實現此目的：NumPy

nd = np.arange(1, 10).reshape(3, 3)
nd = nd.transpose()
nd = nd + 10
```
[[11 14 17]
 [12 15 18]
 [13 16 19]]
```

NDArray

NDArray

NDArray nd = manager.arange(1, 10).reshape(3, 3);
nd = nd.transpose();
nd = nd.add(10);
/*
ND: (3, 3) cpu() int32
[[11, 14, 17],
 [12, 15, 18],
 [13, 16, 19],
]
*/

DJL now supports more than 60 different NumPy math methods covering most of the basic and advanced math functions.

DJL現在支持涵蓋大多數基本和高級數學功能的60多種NumPy數學方法 。

獲取并設置 (Get and Set)

One of the most powerful features of NDArray is its flexible data indexing inspired by a similar feature in NumPy. Let’s assume we would like to filter all values in a matrix that are smaller than 10. NumPy

NDArray的最強大功能之一是其靈活的數據索引，其靈感來自于NumPy中的類似功能。 假設我們要過濾矩陣中小于10的所有值。

nd = np.arange(5, 14)
nd = nd[nd >= 10]
# [10 11 12 13]

NDArray:

NDArray：

NDArray nd = manager.arange(5, 14);
nd = nd.get(nd.gte(10));
/*
ND: (4) cpu() int32
[10, 11, 12, 13]
*/

Now let’s try to do something more complicated. Assume we have 3x3 matrix and we would like to multiply the second column by 2. NumPy

現在，讓我們嘗試做一些更復雜的事情。 假設我們有3x3矩陣，我們想將第二列乘以2。

nd = np.arange(1, 10).reshape(3, 3)
nd[:, 1] *= 2
```
[[ 1  4  3]
 [ 4 10  6]
 [ 7 16  9]]
```

NDArray

NDArray

NDArray nd = manager.arange(1, 10).reshape(3, 3);
nd.set(new NDIndex(":, 1"), array -> array.mul(2));
/*
ND: (3, 3) cpu() int32
[[ 1,  4,  3],
 [ 4, 10,  6],
 [ 7, 16,  9],
]
*/

In the above example, we introduce a concept in Java called NDIndex. It mirrors most of the NDArray get/set functionalities that NumPy supports. By simply passing a String representation, developers can do all kinds of array manipulations seamlessly in Java.

在上面的示例中，我們介紹了Java中的一個名為NDIndex的概念。 它鏡像了NumPy支持的大多數NDArray獲取/設置功能。 通過簡單地傳遞String表示，開發人員可以在Java中無縫地進行各種數組操作。

實際應用 (Real world application)

These operations are really helpful when we need to manipulate a huge dataset. Let’s walk through a specific use case: Token Classification. In this case, developers were trying to do Sentiment Analysis on the text information they gathered from the users through applying a Deep Learning algorithm to it. NDArray operations were applied in the preprocessing and post-processing to encode and decode information.

當我們需要處理龐大的數據集時，這些操作非常有用。 讓我們來看一個特定的用例：令牌分類。 在這種情況下，開發人員試圖通過對其應用深度學習算法，對從用戶那里收集的文本信息進行情感分析。 在預處理和后處理中應用了NDArray操作以對信息進行編碼和解碼。

代幣化 (Tokenization)

Before we feed the data into an NDArray, we tokenize the input text into numbers. The tokenizer in the code block below is a Map<String, Integer> that serves as a vocabulary to convert text into a corresponding vector.

在將數據輸入NDArray之前，我們將輸入文本標記為數字。 下面的代碼塊中的tokenizer是Map<String, Integer> ，用作將文本轉換為相應向量的詞匯表。

String text = "The rabbit cross the street and kick the fox";
String[] tokens = text.toLowerCase().split(" ");
int[] vector = new int[tokens.length];
/*
String[9] { "the", "rabbit", "cross", "the", "street",
"and", "kick", "the", "fox" }
*/
for (int i = 0; i < tokens.length; i++) {
    vector[i] = tokenizer.get(tokens[i]);
}
vector
/*
int[9] { 1, 6, 5, 1, 3, 2, 8, 1, 12 }
*/

處理中 (Processing)

After that, we create an NDArray. To proceed further, we need to create a batch of tokens and apply some transformations to them.

之后，我們創建一個NDArray 。 為了進一步進行，我們需要創建一批令牌并對其進行一些轉換。

NDArray array = manager.create(vector);
array = array.reshape(new Shape(vector.length, 1)); // form a batch
array = array.div(10.0);
/*
ND: (9, 1) cpu() float64
[[0.1],
 [0.6],
 [0.5],
 [0.1],
 [0.3],
 [0.2],
 [0.8],
 [0.1],
 [1.2],
]
*/

Then, we can send this data to a deep learning model. To achieve the same thing in pure Java would require far more work. If we are trying to implement the reshape function above, we need to create an N-dimensional array in Java that looks like: List<List<List<...List<Float>...>>> to cover all the different dimensions. We would then have to dynamically insert a new List<Float> containing the elements to build resulting data structure.

然后，我們可以將這些數據發送到深度學習模型。 要在純Java中實現同一目標，將需要做更多的工作。 如果我們嘗試實現上述的reshape函數，則需要在Java中創建一個N維數組，其外觀如下： List<List<List<...List<Float>...>>>以涵蓋所有不同的尺寸。 然后，我們將不得不動態插入一個新的List<Float>其中包含用于構建結果數據結構的元素。

為什么要使用NDArray？ (Why should I use NDArray?)

With the previous walkthrough, you should have a basic experience using NDArray in Java. To summarize, here is the three key advantages using it:

在上一個演練中，您應該具有在Java中使用NDArray的基本經驗。 總結一下，這是使用它的三個主要優點：

• Easy: Access to 60+ operators in Java with a simple input and the same output.
  簡易：使用簡單的輸入和相同的輸出即可訪問Java中的60多個運算符。
• Fast: Full support for the most used deep learning frameworks including TensorFlow, PyTorch, and MXNet. Now, you can get your computation accelerated by MKLDNN on CPU, CUDA on GPU and lots more.
  快速：全面支持最常用的深度學習框架，包括TensorFlow，PyTorch和MXNet。 現在，您可以通過CPU上的MKLDNN，GPU上的CUDA以及更多功能來加速計算。
• Deep Learning ready: It supports high dimensional arrays and sparse NDArray inputs*. You can apply this toolkit on all platforms including Apache Spark and Apache Beam for large-scale data processing. It’s a perfect tool for data preprocessing and post-processing.
  深度學習就緒：它支持高維數組和稀疏NDArray輸入*。 您可以將此工具包應用于所有平臺，包括Apache Spark和Apache Beam，以進行大規模數據處理。 這是進行數據預處理和后處理的理想工具。

*Sparse currently only covers COO in PyTorch and CSR/Row_Sparse in MXNet.

* Sparse當前僅涵蓋PyTorch中的COO和MXNet中的CSR / Row_Sparse。

關于NDArray和DJL (About NDArray and DJL)

After trying NDArray creation and operation, you might wonder how DJL implement NDArray to achieve these behaviors. In this section, we will briefly walkthrough the architecture of NDArray.

在嘗試了NDArray的創建和操作之后，您可能想知道DJL如何實現NDArray來實現這些行為。 在本節中，我們將簡要介紹NDArray的體系結構。

NDArray架構 (NDArray Architecture)

As shown above, there are three key layers to the NDArray. The Interface layer contains NDArray, it is a Java Interface that defines what the NDArray should look like. We carefully evaluated it and made all functions’ signature general enough and easy to use. In the EngineProvider layer, there are different engine’s implementation to the NDArray. This layer served as an interpretation layer that maps Engine specific behavior to NumPy behavior. As a result, all engines implementation are behaved the same way as NumPy have. In the C++ Layer, we built JNI and JNA that expose C++ methods for Java to call. It would ensure we have enough methods to build the entire NDArray stack. Also it ensures the best performance by calling directly from Java to C++ since all Engines are implemented in C/C++.

如上所示，NDArray有三個關鍵層。 接口層包含NDArray，它是一個Java接口，用于定義NDArray的外觀。 我們對其進行了仔細評估，使所有功能的簽名足夠通用且易于使用。 在EngineProvider層中，NDArray有不同的引擎實現。 該層用作將引擎特定行為映射到NumPy行為的解釋層。 結果，所有引擎實現的行為都與NumPy相同。 在C ++層中，我們構建了JNI和JNA，它們公開了Java調用的C ++方法。 這將確保我們有足夠的方法來構建整個NDArray堆棧。 由于所有引擎都是在C / C ++中實現的，因此它還可以通過直接從Java調用C ++來確保最佳性能。

關于DJL (About DJL)

Deep Java Library (DJL) is a Deep Learning Framework written in Java, supporting both training and inference. DJL is built on top of modern Deep Learning frameworks (TenserFlow, PyTorch, MXNet, etc). You can easily use DJL to train your model or deploy your favorite models from a variety of engines without any additional conversion. It contains a powerful ModelZoo design that allows you to manage trained models and load them in a single line. The built-in ModelZoo currently supports more than 70 pre-trained and ready to use models from GluonCV, HuggingFace, TorchHub and Keras. The addition of the NDArray makes DJL the best toolkit in Java to run your Deep Learning application. It can automatically identify the platform you are running on and figure out whether to leverage GPU to run your application. From the most recent release, DJL 0.6.0 officially supports MXNet 1.7.0, PyTorch 1.5.0 and TensorFlow 2.2.0. We also have experimental support for PyTorch on Android. Follow our GitHub, demo repository, Slack channel and twitter for more documentation and examples of DJL!

深度Java庫(DJL)是用Java編寫的深度學習框架，同時支持訓練和推理。 DJL建立在現代深度學習框架(TenserFlow，PyTorch，MXNet等)之上。 您可以輕松地使用DJL訓練模型或從各種引擎部署您喜歡的模型，而無需進行任何其他轉換。 它包含一個功能強大的ModelZoo設計，使您可以管理經過訓練的模型并將其加載到一行中。 內置的ModelZoo目前支持來自GluonCV，HuggingFace，TorchHub和Keras的70多種預訓練并可以使用的模型。 NDArray的添加使DJL成為Java中運行深度學習應用程序的最佳工具包。 它可以自動識別您正在運行的平臺，并確定是否利用GPU來運行您的應用程序。 從最新版本開始，DJL 0.6.0正式支持MXNet 1.7.0，PyTorch 1.5.0和TensorFlow 2.2.0。 我們還在Android上提供了對PyTorch的實驗性支持。 請關注我們的GitHub ， 演示存儲庫 ， Slack頻道和Twitter ，以獲取DJL的更多文檔和示例！