This guide explains how to use the Java SDK to call Elastic Algorithm Service (EAS) model services, and provides input/output examples and a sample program.
For the use cases and principles of the SDK, see service invocation SDK.
Prerequisites
To use the EAS Java SDK in your Maven project, add the eas-sdk dependency to the <dependencies> section of your pom.xml file. For the latest version, check the Maven repository.
<dependency>
<groupId>com.aliyun.openservices.eas</groupId>
<artifactId>eas-sdk</artifactId>
<version>2.0.20</version>
</dependency>EAS SDK 2.0.5 and later includes QueueService client functionality for the multi-priority asynchronous queue service. To use this feature and avoid dependency conflicts, add the following two dependencies and adjust their versions as necessary:
<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>Quick start
To make a service call with the Java SDK, follow these three steps:
Get call information: On the service details page in the EAS console, go to the Call Information tab to get the endpoint, service name, and token.
Choose a request type and write code: Select the appropriate Request/Response class based on your model's input data format, and then write your code using the minimal example below.
NoteIf you deployed your service with a built-in Processor, the SDK provides corresponding input and output classes. For example, the built-in TensorFlow Processor corresponds to
TFRequest. For more information, see the documentation for each processor under Built-in Processors.Run and verify: Run the client program and verify the response. If an error occurs, refer to the Troubleshooting guide.
The following code is a minimal end-to-end example of a string request. For more examples, see Program Examples:
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());
// To use a VPC direct connection, call the setDirectEndpoint method. The format is typically {uid}.vpc.{region-id}.pai-eas.aliyuncs.com.
client.setDirectEndpoint("182848887922****.vpc.cn-shanghai.aliyuncs.com");
// The public endpoint for the EAS service. The format is typically {uid}.{region-id}.pai-eas.aliyuncs.com.
// client.setEndpoint("182848887922****.cn-shanghai.pai-eas.aliyuncs.com");
// The name of the EAS service.
client.setModelName("your_service_name");
client.setToken("YOUR_SERVICE_TOKEN");
// The request path. The complete request URL is http://<endpoint>/api/direct/<modelName>/<requestPath>.
client.setRequestPath("your_custom_path");
// Construct the request body. The supported input classes depend on the SDK. This example uses a String.
String request = "[{}]";
String response = client.predict(request);
System.out.println(response);
client.shutdown();
}
}API reference
The Java SDK provides the following classes:
Group | Class description |
Main Client Class |
|
Connection configuration |
|
Input/output |
|
Queue service |
|
PredictClient class
The main client class. It configures service information, sends requests, and receives prediction results.
API | Description |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| Sets a custom request URL. |
|
|
|
|
|
|
|
|
|
|
|
|
HttpConfig class
Configures underlying HTTP connection parameters, such as timeouts, thread count, and the connection pool.
API | Description |
|
|
|
Important This timeout applies only after a connection is established. It is different from the request timeout set by the |
|
Important This timeout covers the entire request lifecycle, including connection establishment, data transfer, and server processing. It is different from the read timeout set by the |
|
|
|
|
|
|
|
|
| Returns the status code of the last API call. |
| Returns the status message of the last API call. |
TFRequest class
Builds the input data for a TensorFlow model.
API | Description |
|
|
|
|
|
|
TFResponse class
Parses and accesses the output data from a TensorFlow model prediction.
API | Description |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
QueueClient class
Interacts with the EAS queue service to produce, consume, and manage data.
API | Description |
|
|
|
|
|
|
|
|
|
|
|
|
|
Important When calling
|
|
|
|
|
| Closes the connection to the queue service. |
DataFrame class
A wrapper for a data item from the queue service.
API | Description |
|
|
|
|
|
|
Code examples
Synchronous inference examples
Choose the example that matches the input and output format of your service.
String
If you deployed a service with a custom processor, you typically use strings to call it. This practice is common for PMML model services, as the following example shows.
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 {
// Initialize the client. The client object should be shared. Do not create a new client object for each request.
PredictClient client = new PredictClient(new HttpConfig());
client.setToken("YWFlMDYyZDNmNTc3M2I3MzMwYmY0MmYwM2Y2MTYxMTY4NzBkNzdj****");
// To use a direct network connection, call the setDirectEndpoint method.
// Example: client.setDirectEndpoint("182848887922****.vpc.cn-shanghai.aliyuncs.com");
// To enable a direct network connection, you must enable it in the EAS console and provide the source vSwitch used to access the EAS service. This bypasses the gateway, allowing you to directly access service instances via software load balancing for improved stability and performance.
// Note: For standard gateway access, use the endpoint that starts with your user ID. You can find this endpoint in the "Call Information" of the service in the EAS console. For direct network connections, use a domain name in the format 182848887922****.vpc.{region_id}.aliyuncs.com.
client.setEndpoint("182848887922****.vpc.cn-shanghai.pai-eas.aliyuncs.com");
client.setModelName("scorecard_pmml_example");
// Define the input string.
String request = "[{\"money_credit\": 3000000}, {\"money_credit\": 10000}]";
System.out.println(request);
// Get the response string from EAS.
try {
String response = client.predict(request);
System.out.println(response);
} catch (Exception e) {
e.printStackTrace();
}
// Shut down the client.
client.shutdown();
return;
}
}TensorFlow
If you use a TensorFlow model, use the TFRequest and TFResponse classes for input and output, as the following example demonstrates.
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());
// To use a direct network connection, call the setDirectEndpoint method. The endpoint format is {uid}.vpc.{region_id}.aliyuncs.com.
// client.setDirectEndpoint("182848887922****.vpc.cn-shanghai.aliyuncs.com");
// For standard gateway access, use the endpoint that starts with your user ID. You can find this endpoint in the "Call Information" of the service in the EAS console.
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();
}
}Queue service example
To access the queue service, use the QueueClient interface. The following example shows how.
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 {
/** Create a queue service client. */
String queueEndpoint = "18*******.cn-hangzhou.pai-eas.aliyuncs.com";
String inputQueueName = "test_queue_service";
String sinkQueueName = "test_queue_service/sink";
String queueToken = "test-token";
/** The input queue. The inference service automatically reads request data from this queue. */
QueueClient inputQueue =
new QueueClient(queueEndpoint, inputQueueName, queueToken, new HttpConfig(), new QueueUser());
/** The output queue. After the inference service processes the input data, it writes the results to this queue. */
QueueClient sinkQueue =
new QueueClient(queueEndpoint, sinkQueueName, queueToken, new HttpConfig(), new QueueUser());
/** Clear queue data. Use with caution. */
inputQueue.clear();
sinkQueue.clear();
/** Add data to the input queue. */
int count = 10;
for (int i = 0; i < count; ++i) {
String data = Integer.toString(i);
inputQueue.put(data.getBytes(), null);
/** The queue service supports multiple priorities. You can use the put method to set the data priority. The default priority is 0. */
// inputQueue.put(data.getBytes(), 0L, null);
}
/** Use the watch method to subscribe to data from the output queue. The window size is 5. */
WebSocketWatcher watcher = sinkQueue.watch(0L, 5L, false, true, null);
/** Use the WatchConfig parameter to customize the number of retries, retry interval (in seconds), and whether to retry indefinitely. If you do not configure WatchConfig, the system defaults to 3 retries with a 5-second interval. */
// WebSocketWatcher watcher = sink_queue.watch(0L, 5L, false, true, null, new WatchConfig(3, 1));
// WebSocketWatcher watcher = sink_queue.watch(0L, 5L, false, true, null, new WatchConfig(true, 10));
/** Get the output data. */
for (int i = 0; i < count; ++i) {
try {
/** The getDataFrame() method retrieves DataFrame data. This call blocks until data is available. */
byte[] data = watcher.getDataFrame().getData();
System.out.println("[watch] data = " + new String(data));
} catch (RuntimeException ex) {
System.out.println("[watch] error = " + ex.getMessage());
break;
}
}
/** Close the watcher object. Each client instance supports only one watcher object. If you do not close the watcher, an error occurs on the next run. */
watcher.close();
Thread.sleep(2000);
JSONObject attrs = sinkQueue.attributes();
System.out.println(attrs.toString());
/** Shut down the clients. */
inputQueue.shutdown();
sinkQueue.shutdown();
}
}Calling a service with the Java SDK involves the following steps:
Use the
QueueClientinterface to create a queue service client object. If you create an inference service, you must also create input queue and output queue objects.Use the
put()function to send data to the input queue, and use thewatch()function to subscribe to data from the output queue.NoteIn a production environment, you should use separate threads for sending data and subscribing to data. For demonstration purposes, this example performs these operations in the same thread.
Request data compression
For requests that contain a large amount of data, EAS supports compressing the data by using the Zlib or Gzip format before sending it to the server-side. To enable this feature, you must specify rpc.decompressor in the service configuration.
The service configuration is as follows:
"metadata": {
"rpc": {
"decompressor": "zlib"
}
}The following is a code example:
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{
// Initialize the client.
PredictClient client = new PredictClient(new HttpConfig());
client.setEndpoint("18*******.cn-hangzhou.pai-eas.aliyuncs.com");
client.setModelName("echo_compress");
client.setToken("YzZjZjQwN2E4NGRkMDMxNDk5NzhhZDcwZDBjOTZjOGYwZDYxZGM2****");
// You can also use Compressor.Gzip.
client.setCompressor(Compressor.Zlib);
// Define the input string.
String request = "[{\"money_credit\": 3000000}, {\"money_credit\": 10000}]";
System.out.println(request);
// Get the response string from EAS.
String response = client.predict(request);
System.out.println(response);
// Shut down the client.
client.shutdown();
return;
}
}Troubleshooting
To troubleshoot Java SDK invocation exceptions, including common issues with authentication, routing, connection, and server-side errors, see the "Troubleshooting Invocation Exceptions" section in Service Invocation SDK.
For a complete list of service status codes, error message meanings, and recommended actions, see Appendix: Service Status Codes and Common Errors.