このガイドでは、Java SDK を使用して Elastic Algorithm Service (EAS) のモデルサービスを呼び出す方法を、入出力の例やサンプルプログラムとあわせて説明します。
SDK のユースケースと原則については、「サービス呼び出し SDK」をご参照ください。
前提条件
Maven プロジェクトで EAS Java SDK を使用するには、pom.xml ファイルの <dependencies> セクションに eas-sdk の依存関係を追加してください。最新バージョンについては、Maven リポジトリ を確認してください。
<dependency>
<groupId>com.aliyun.openservices.eas</groupId>
<artifactId>eas-sdk</artifactId>
<version>2.0.20</version>
</dependency>EAS SDK 2.0.5 以降には、マルチ優先度非同期キューサービス向けの QueueService クライアント機能が含まれています。この機能を使用し、依存関係の競合を回避するには、次の 2 つの依存関係を追加し、必要に応じてそれぞれのバージョンを調整してください：
<dependency>
<groupId>org.java-websocket</groupId>
<artifactId>Java-WebSocket</artifactId>
<version>1.5.1</version>
</dependency>
<dependency>
<groupId>org.apache.commons</groupId>
<artifactId>commons-lang3</artifactId>
<version>3.1</version>
</dependency>クイックスタート
Java SDK を使用してサービス呼び出しを行うには、次の 3 つのステップを実行します。
-
呼び出し情報の取得：EAS コンソールのサービス詳細ページで、[Call Information] タブに移動し、エンドポイント、サービス名、トークンを取得します。
-
リクエストタイプの選択とコードの記述：モデルの入力データ形式に基づいて適切なリクエスト/レスポンス クラスを選択し、以下の最小限の例を使用してコードを記述します。
説明組み込みプロセッサを使用してサービスをデプロイした場合、SDK は対応する入出力クラスを提供します。たとえば、組み込みのTensorFlow プロセッサは
TFRequestに対応します。詳細については、組み込みプロセッサの各プロセッサのドキュメントをご参照ください。 -
実行と検証：クライアントプログラムを実行し、レスポンスを検証します。エラーが発生した場合は、トラブルシューティング ガイドをご参照ください。
次のコードは、文字列リクエストの最小限のエンドツーエンドの例です。その他の例については、「プログラム例」をご参照ください。
import com.aliyun.openservices.eas.predict.http.PredictClient;
import com.aliyun.openservices.eas.predict.http.HttpConfig;
public class TestString {
public static void main(String[] args) throws Exception {
PredictClient client = new PredictClient(new HttpConfig());
// VPC 専用接続を使用するには、setDirectEndpoint メソッドを呼び出します。形式は通常 {uid}.vpc.{region-id}.pai-eas.aliyuncs.com です。
client.setDirectEndpoint("182848887922****.vpc.cn-shanghai.aliyuncs.com");
// EAS サービスのパブリックエンドポイント。形式は通常 {uid}.{region-id}.pai-eas.aliyuncs.com です。
// client.setEndpoint("182848887922****.cn-shanghai.pai-eas.aliyuncs.com");
// EAS サービスの名前。
client.setModelName("your_service_name");
client.setToken("YOUR_SERVICE_TOKEN");
// リクエストパス。完全なリクエスト URL は http://<endpoint>/api/direct/<modelName>/<requestPath> です。
client.setRequestPath("your_custom_path");
// リクエストボディを構築します。サポートされる入力クラスは SDK によって異なります。この例では文字列を使用します。
String request = "[{}]";
String response = client.predict(request);
System.out.println(response);
client.shutdown();
}
}API リファレンス
Java SDK には、次のクラスが用意されています。
|
グループ |
クラスの説明 |
|
メインクライアントクラス |
|
|
接続設定 |
|
|
入出力 |
|
|
キューサービス |
|
PredictClient クラス
メインクライアントクラスです。サービス情報を設定し、リクエストを送信し、予測結果を受信します。
|
API |
説明 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
カスタムのリクエスト URL を設定します。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
HttpConfig クラス
タイムアウト、スレッド数、接続プールなど、基盤となる HTTP 接続パラメーターを設定します。
|
API |
説明 |
|
|
|
|
|
重要
このタイムアウトは接続確立後にのみ適用されます。 |
|
|
重要
このタイムアウトは、接続確立、データ転送、サーバー処理を含むリクエストのライフサイクル全体をカバーします。 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
直前の API 呼び出しのステータスコードを返します。 |
|
|
直前の API 呼び出しのステータスメッセージを返します。 |
TFRequest クラス
TensorFlow モデルの入力データを構築します。
|
API |
説明 |
|
|
|
|
|
|
|
|
|
TFResponse クラス
TensorFlow モデルの予測結果から出力データを解析してアクセスします。
|
API |
説明 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
QueueClient class
Interacts with the EAS queue service to produce, consume, and manage data.
|
API |
Description |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
重要
When calling
|
|
|
|
|
|
|
|
|
Closes the connection to the queue service. |
DataFrame クラス
キューサービスのデータ項目のラッパーです。
|
API |
説明 |
|
|
|
|
|
|
|
|
|
コード例
同期推論の例
サービスの入出力形式に一致する例を選択してください。
String
カスタムプロセッサを使用してサービスをデプロイした場合、通常は文字列を使用して呼び出します。次の例に示すように、この方法は PMML モデルサービスで一般的に用いられます。
import com.aliyun.openservices.eas.predict.http.PredictClient;
import com.aliyun.openservices.eas.predict.http.HttpConfig;
public class TestString {
public static void main(String[] args) throws Exception {
// クライアントを初期化します。クライアントオブジェクトは共有してください。リクエストごとに新しいクライアントオブジェクトを作成しないでください。
PredictClient client = new PredictClient(new HttpConfig());
client.setToken("YWFlMDYyZDNmNTc3M2I3MzMwYmY0MmYwM2Y2MTYxMTY4NzBkNzdj****");
// ダイレクトネットワーク接続を使用するには、setDirectEndpoint メソッドを呼び出します。
// 例：client.setDirectEndpoint("182848887922****.vpc.cn-shanghai.aliyuncs.com");
// ダイレクトネットワーク接続を有効にするには、EAS コンソールで有効化し、EAS サービスへのアクセスに使用するソース vSwitch を指定する必要があります。これによりゲートウェイをバイパスし、ソフトウェアロードバランシングを介してサービスインスタンスに直接アクセスできるため、安定性とパフォーマンスが向上します。
// 注：標準のゲートウェイアクセスでは、ユーザー ID で始まるエンドポイントを使用します。このエンドポイントは、EAS コンソールのサービスの [Call Information] で確認できます。ダイレクトネットワーク接続では、182848887922****.vpc.{region_id}.aliyuncs.com の形式のドメイン名を使用します。
client.setEndpoint("182848887922****.vpc.cn-shanghai.pai-eas.aliyuncs.com");
client.setModelName("scorecard_pmml_example");
// 入力文字列を定義します。
String request = "[{\"money_credit\": 3000000}, {\"money_credit\": 10000}]";
System.out.println(request);
// EAS からレスポンス文字列を取得します。
try {
String response = client.predict(request);
System.out.println(response);
} catch (Exception e) {
e.printStackTrace();
}
// クライアントをシャットダウンします。
client.shutdown();
return;
}
}TensorFlow
TensorFlow モデルを使用する場合は、次の例に示すように、入出力に TFRequest クラスと TFResponse クラスを使用します。
import java.util.List;
import com.aliyun.openservices.eas.predict.http.PredictClient;
import com.aliyun.openservices.eas.predict.http.HttpConfig;
import com.aliyun.openservices.eas.predict.request.TFDataType;
import com.aliyun.openservices.eas.predict.request.TFRequest;
import com.aliyun.openservices.eas.predict.response.TFResponse;
public class TestTF {
public static TFRequest buildPredictRequest() {
TFRequest request = new TFRequest();
request.setSignatureName("predict_images");
float[] content = new float[784];
for (int i = 0; i < content.length; i++) {
content[i] = (float) 0.0;
}
request.addFeed("images", TFDataType.DT_FLOAT, new long[]{1, 784}, content);
request.addFetch("scores");
return request;
}
public static void main(String[] args) throws Exception {
PredictClient client = new PredictClient(new HttpConfig());
// ダイレクトネットワーク接続を使用するには、setDirectEndpoint メソッドを呼び出します。エンドポイントの形式は {uid}.vpc.{region_id}.aliyuncs.com です。
// client.setDirectEndpoint("182848887922****.vpc.cn-shanghai.aliyuncs.com");
// 標準のゲートウェイアクセスでは、ユーザー ID で始まるエンドポイントを使用します。このエンドポイントは、EAS コンソールのサービスの [Call Information] で確認できます。
client.setEndpoint("182848887922****.vpc.cn-shanghai.pai-eas.aliyuncs.com");
client.setModelName("mnist_saved_model_example");
client.setToken("YTg2ZjE0ZjM4ZmE3OTc0NzYxZDMyNmYzMTJjZTQ1YmU0N2FjMTAy****");
long startTime = System.currentTimeMillis();
int count = 1000;
for (int i = 0; i < count; i++) {
try {
TFResponse response = client.predict(buildPredictRequest());
List<Float> result = response.getFloatVals("scores");
System.out.print("Predict Result: [");
for (int j = 0; j < result.size(); j++) {
System.out.print(result.get(j).floatValue());
if (j != result.size() - 1) {
System.out.print(", ");
}
}
System.out.print("]\n");
} catch (Exception e) {
e.printStackTrace();
}
}
long endTime = System.currentTimeMillis();
System.out.println("Spend Time: " + (endTime - startTime) + "ms");
client.shutdown();
}
}キューサービスの例
キューサービスにアクセスするには、QueueClient インターフェイスを使用します。その方法を次の例に示します。
import com.alibaba.fastjson.JSONObject;
import com.aliyun.openservices.eas.predict.http.HttpConfig;
import com.aliyun.openservices.eas.predict.http.QueueClient;
import com.aliyun.openservices.eas.predict.queue_client.QueueUser;
import com.aliyun.openservices.eas.predict.queue_client.WebSocketWatcher;
public class DemoWatch {
public static void main(String[] args) throws Exception {
/** キューサービス クライアントを作成します。 */
String queueEndpoint = "18*******.cn-hangzhou.pai-eas.aliyuncs.com";
String inputQueueName = "test_queue_service";
String sinkQueueName = "test_queue_service/sink";
String queueToken = "test-token";
/** 入力キュー。推論サービスはこのキューからリクエストデータを自動的に読み取ります。 */
QueueClient inputQueue =
new QueueClient(queueEndpoint, inputQueueName, queueToken, new HttpConfig(), new QueueUser());
/** 出力キュー。推論サービスが入力データを処理した後、このキューに結果を書き込みます。 */
QueueClient sinkQueue =
new QueueClient(queueEndpoint, sinkQueueName, queueToken, new HttpConfig(), new QueueUser());
/** キューデータをクリアします。取り扱いにご注意ください。 */
inputQueue.clear();
sinkQueue.clear();
/** 入力キューにデータを追加します。 */
int count = 10;
for (int i = 0; i < count; ++i) {
String data = Integer.toString(i);
inputQueue.put(data.getBytes(), null);
/** キューサービスは複数の優先度をサポートしています。put メソッドを使用してデータの優先度を設定できます。デフォルトの優先度は 0 です。 */
// inputQueue.put(data.getBytes(), 0L, null);
}
/** watch メソッドを使用して、出力キューのデータをサブスクライブします。ウィンドウサイズは 5 です。 */
WebSocketWatcher watcher = sinkQueue.watch(0L, 5L, false, true, null);
/** WatchConfig パラメーターを使用して、再試行回数、再試行間隔 (秒単位)、および無期限に再試行するかどうかをカスタマイズできます。WatchConfig を設定しない場合、システムはデフォルトで 5 秒間隔で 3 回再試行します。 */
// WebSocketWatcher watcher = sinkQueue.watch(0L, 5L, false, true, null, new WatchConfig(3, 1));
// WebSocketWatcher watcher = sinkQueue.watch(0L, 5L, false, true, null, new WatchConfig(true, 10));
/** 出力データを取得します。 */
for (int i = 0; i < count; ++i) {
try {
/** getDataFrame() メソッドは DataFrame データを取得します。この呼び出しは、データが利用可能になるまでブロックされます。 */
byte[] data = watcher.getDataFrame().getData();
System.out.println("[watch] data = " + new String(data));
} catch (RuntimeException ex) {
System.out.println("[watch] error = " + ex.getMessage());
break;
}
}
/** watcher オブジェクトを閉じます。各クライアントインスタンスは 1 つの watcher オブジェクトのみをサポートします。watcher を閉じない場合、次回の実行時にエラーが発生します。 */
watcher.close();
Thread.sleep(2000);
JSONObject attrs = sinkQueue.attributes();
System.out.println(attrs.toString());
/** クライアントをシャットダウンします。 */
inputQueue.shutdown();
sinkQueue.shutdown();
}
}Java SDK を使用してサービスを呼び出す手順は次のとおりです：
-
QueueClientインターフェイスを使用して、キューサービスのクライアントオブジェクトを作成します。キューサービスを使用する推論サービスでは、入力キューと出力キューのオブジェクトも作成する必要があります。 -
put()関数を使用して入力キューにデータを送信し、watch()関数を使用して出力キューのデータをサブスクライブします。説明本番環境では、データの送信とデータのサブスクライブに別々のスレッドを使用してください。説明のため、この例では同一スレッドでこれらの操作を実行しています。
リクエストデータの圧縮
大量のデータを含むリクエストの場合、EAS は、データを Zlib または Gzip 形式で圧縮してからサーバーに送信することに対応しています。この機能を有効にするには、サービス構成で rpc.decompressor を指定する必要があります。
サービス構成は次のとおりです：
"metadata": {
"rpc": {
"decompressor": "zlib"
}
}コード例を次に示します：
package com.aliyun.openservices.eas.predict;
import com.aliyun.openservices.eas.predict.http.Compressor;
import com.aliyun.openservices.eas.predict.http.PredictClient;
import com.aliyun.openservices.eas.predict.http.HttpConfig;
public class TestString {
public static void main(String[] args) throws Exception{
// クライアントを初期化します。
PredictClient client = new PredictClient(new HttpConfig());
client.setEndpoint("18*******.cn-hangzhou.pai-eas.aliyuncs.com");
client.setModelName("echo_compress");
client.setToken("YzZjZjQwN2E4NGRkMDMxNDk5NzhhZDcwZDBjOTZjOGYwZDYxZGM2****");
// Compressor.Gzip も使用できます。
client.setCompressor(Compressor.Zlib);
// 入力文字列を定義します。
String request = "[{\"money_credit\": 3000000}, {\"money_credit\": 10000}]";
System.out.println(request);
// EAS からレスポンス文字列を取得します。
String response = client.predict(request);
System.out.println(response);
// クライアントをシャットダウンします。
client.shutdown();
return;
}
}トラブルシューティング
Java SDK の 呼び出し例外 (認証、ルーティング、接続、サーバー側のエラーなど) をトラブルシューティングするには、「Service Invocation SDK」の「呼び出し例外のトラブルシューティング」セクションをご参照ください。
サービスステータスコード と エラーメッセージ の意味、および推奨されるアクションの一覧については、「付録：サービスステータスコードと一般的なエラー」をご参照ください。