Panduan ini menjelaskan cara menggunakan Java SDK untuk memanggil layanan model Elastic Algorithm Service (EAS), serta menyediakan contoh input/output dan program sampel.
Untuk kasus penggunaan dan prinsip SDK, lihat SDK pemanggilan layanan.
Prasyarat
Untuk menggunakan Java SDK EAS dalam proyek Maven Anda, tambahkan dependensi eas-sdk ke bagian <dependencies> pada file pom.xml Anda. Untuk versi terbaru, periksa Repositori Maven.
<dependency>
<groupId>com.aliyun.openservices.eas</groupId>
<artifactId>eas-sdk</artifactId>
<version>2.0.20</version>
</dependency>SDK EAS versi 2.0.5 dan yang lebih baru mencakup fungsionalitas client QueueService untuk layanan antrian asinkron multi-prioritas. Untuk menggunakan fitur ini dan menghindari konflik dependensi, tambahkan dua dependensi berikut dan sesuaikan versinya jika diperlukan:
<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>Mulai cepat
Untuk melakukan pemanggilan layanan dengan Java SDK, ikuti tiga langkah berikut:
-
Dapatkan informasi pemanggilan: Di halaman detail layanan di Konsol EAS, buka tab Call Information untuk mendapatkan titik akhir, nama layanan, dan token.
-
Pilih jenis permintaan dan tulis kode: Pilih kelas Request/Response yang sesuai berdasarkan format data masukan model Anda, lalu tulis kode Anda menggunakan contoh minimal di bawah ini.
CatatanJika Anda menerapkan layanan dengan Built-in Processor, SDK menyediakan kelas input dan output yang sesuai. Sebagai contoh, TensorFlow Processor bawaan berkorespondensi dengan
TFRequest. Untuk informasi lebih lanjut, lihat dokumentasi setiap prosesor di bawah Built-in Processors. -
Jalankan dan verifikasi: Jalankan program client dan verifikasi tanggapan. Jika terjadi kesalahan, rujuk panduan Pemecahan Masalah.
Kode berikut merupakan contoh end-to-end minimal untuk permintaan berbasis string. Untuk contoh lainnya, lihat Contoh Program:
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());
// Untuk menggunakan koneksi langsung VPC, panggil metode setDirectEndpoint. Formatnya biasanya {uid}.vpc.{region-id}.pai-eas.aliyuncs.com.
client.setDirectEndpoint("182848887922****.vpc.cn-shanghai.aliyuncs.com");
// Titik akhir publik untuk layanan EAS. Formatnya biasanya {uid}.{region-id}.pai-eas.aliyuncs.com.
// client.setEndpoint("182848887922****.cn-shanghai.pai-eas.aliyuncs.com");
// Nama layanan EAS.
client.setModelName("your_service_name");
client.setToken("YOUR_SERVICE_TOKEN");
// Jalur permintaan. URL permintaan lengkapnya adalah http://<endpoint>/api/direct/<modelName>/<requestPath>.
client.setRequestPath("your_custom_path");
// Bangun badan permintaan. Kelas input yang didukung bergantung pada SDK. Contoh ini menggunakan String.
String request = "[{}]";
String response = client.predict(request);
System.out.println(response);
client.shutdown();
}
}Referensi API
Java SDK menyediakan kelas-kelas berikut:
|
Grup |
Deskripsi kelas |
|
Main Client Class |
|
|
Konfigurasi koneksi |
|
|
Input/output |
|
|
Layanan antrian |
|
Kelas PredictClient
Kelas client utama. Kelas ini mengonfigurasi informasi layanan, mengirim permintaan, dan menerima hasil prediksi.
|
API |
Deskripsi |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Menetapkan URL permintaan kustom. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Kelas HttpConfig
Mengonfigurasi parameter koneksi HTTP dasar, seperti timeout, jumlah thread, dan kolam koneksi.
|
API |
Deskripsi |
|
|
|
|
|
Penting
Timeout ini hanya berlaku setelah koneksi terbentuk. Berbeda dengan timeout permintaan yang ditetapkan oleh metode |
|
|
Penting
Timeout ini mencakup seluruh siklus hidup permintaan, termasuk pembentukan koneksi, transfer data, dan pemrosesan server. Berbeda dengan timeout baca yang ditetapkan oleh metode |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Mengembalikan kode status dari pemanggilan API terakhir. |
|
|
Mengembalikan pesan status dari pemanggilan API terakhir. |
Kelas TFRequest
Membangun data masukan untuk model TensorFlow.
|
API |
Deskripsi |
|
|
|
|
|
|
|
|
|
Kelas TFResponse
Mengurai dan mengakses data keluaran dari prediksi model TensorFlow.
|
API |
Deskripsi |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Kelas QueueClient
Berinteraksi dengan layanan antrian EAS untuk memproduksi, mengonsumsi, dan mengelola data.
|
API |
Deskripsi |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Penting
Saat memanggil
|
|
|
|
|
|
|
|
|
Menutup koneksi ke layanan antrian. |
Kelas DataFrame
Pembungkus untuk item data dari layanan antrian.
|
API |
Deskripsi |
|
|
|
|
|
|
|
|
|
Contoh kode
Contoh inferensi sinkron
Pilih contoh yang sesuai dengan format input dan output layanan Anda.
String
Jika Anda menerapkan layanan dengan prosesor kustom, Anda biasanya menggunakan string untuk memanggilnya. Praktik ini umum untuk layanan model PMML, sebagaimana ditunjukkan pada contoh berikut.
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 {
// Inisialisasi client. Objek client harus dibagikan. Jangan membuat objek client baru untuk setiap permintaan.
PredictClient client = new PredictClient(new HttpConfig());
client.setToken("YWFlMDYyZDNmNTc3M2I3MzMwYmY0MmYwM2Y2MTYxMTY4NzBkNzdj****");
// Untuk menggunakan koneksi jaringan langsung, panggil metode setDirectEndpoint.
// Contoh: client.setDirectEndpoint("182848887922****.vpc.cn-shanghai.aliyuncs.com");
// Untuk mengaktifkan koneksi jaringan langsung, Anda harus mengaktifkannya di Konsol EAS dan menyediakan vSwitch sumber yang digunakan untuk mengakses layanan EAS. Ini melewati gerbang, memungkinkan Anda mengakses instans layanan secara langsung melalui load balancing perangkat lunak untuk meningkatkan stabilitas dan kinerja.
// Catatan: Untuk akses gerbang standar, gunakan titik akhir yang dimulai dengan ID pengguna Anda. Anda dapat menemukan titik akhir ini di "Call Information" layanan di Konsol EAS. Untuk koneksi jaringan langsung, gunakan nama domain dalam format 182848887922****.vpc.{region_id}.aliyuncs.com.
client.setEndpoint("182848887922****.vpc.cn-shanghai.pai-eas.aliyuncs.com");
client.setModelName("scorecard_pmml_example");
// Definisikan string input.
String request = "[{\"money_credit\": 3000000}, {\"money_credit\": 10000}]";
System.out.println(request);
// Dapatkan string tanggapan dari EAS.
try {
String response = client.predict(request);
System.out.println(response);
} catch (Exception e) {
e.printStackTrace();
}
// Matikan client.
client.shutdown();
return;
}
}TensorFlow
Jika Anda menggunakan model TensorFlow, gunakan kelas TFRequest dan TFResponse untuk input dan output, sebagaimana ditunjukkan pada contoh berikut.
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());
// Untuk menggunakan koneksi jaringan langsung, panggil metode setDirectEndpoint. Format titik akhirnya adalah {uid}.vpc.{region_id}.aliyuncs.com.
// client.setDirectEndpoint("182848887922****.vpc.cn-shanghai.aliyuncs.com");
// Untuk akses gerbang standar, gunakan titik akhir yang dimulai dengan ID pengguna Anda. Anda dapat menemukan titik akhir ini di "Call Information" layanan di Konsol EAS.
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();
}
}Contoh layanan antrian
Untuk mengakses layanan antrian, gunakan antarmuka QueueClient. Contoh berikut menunjukkan caranya.
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 {
/** Buat client layanan antrian. */
String queueEndpoint = "18*******.cn-hangzhou.pai-eas.aliyuncs.com";
String inputQueueName = "test_queue_service";
String sinkQueueName = "test_queue_service/sink";
String queueToken = "test-token";
/** Antrian input. Layanan inferensi secara otomatis membaca data permintaan dari antrian ini. */
QueueClient inputQueue =
new QueueClient(queueEndpoint, inputQueueName, queueToken, new HttpConfig(), new QueueUser());
/** Antrian output. Setelah layanan inferensi memproses data input, hasilnya ditulis ke antrian ini. */
QueueClient sinkQueue =
new QueueClient(queueEndpoint, sinkQueueName, queueToken, new HttpConfig(), new QueueUser());
/** Hapus data antrian. Gunakan dengan hati-hati. */
inputQueue.clear();
sinkQueue.clear();
/** Tambahkan data ke antrian input. */
int count = 10;
for (int i = 0; i < count; ++i) {
String data = Integer.toString(i);
inputQueue.put(data.getBytes(), null);
/** Layanan antrian mendukung beberapa prioritas. Anda dapat menggunakan metode put untuk menetapkan prioritas data. Prioritas default-nya adalah 0. */
// inputQueue.put(data.getBytes(), 0L, null);
}
/** Gunakan metode watch untuk berlangganan data dari antrian output. Ukuran jendelanya adalah 5. */
WebSocketWatcher watcher = sinkQueue.watch(0L, 5L, false, true, null);
/** Gunakan parameter WatchConfig untuk menyesuaikan jumlah percobaan ulang, interval percobaan ulang (dalam detik), dan apakah akan mencoba ulang tanpa batas. Jika Anda tidak mengonfigurasi WatchConfig, sistem default-nya adalah 3 kali percobaan ulang dengan interval 5 detik. */
// 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));
/** Dapatkan data output. */
for (int i = 0; i < count; ++i) {
try {
/** Metode getDataFrame() mengambil data DataFrame. Pemanggilan ini memblokir hingga data tersedia. */
byte[] data = watcher.getDataFrame().getData();
System.out.println("[watch] data = " + new String(data));
} catch (RuntimeException ex) {
System.out.println("[watch] error = " + ex.getMessage());
break;
}
}
/** Tutup objek watcher. Setiap instance client hanya mendukung satu objek watcher. Jika Anda tidak menutup watcher, akan terjadi kesalahan pada eksekusi berikutnya. */
watcher.close();
Thread.sleep(2000);
JSONObject attrs = sinkQueue.attributes();
System.out.println(attrs.toString());
/** Matikan client. */
inputQueue.shutdown();
sinkQueue.shutdown();
}
}Memanggil layanan dengan Java SDK melibatkan langkah-langkah berikut:
-
Gunakan antarmuka
QueueClientuntuk membuat objek client layanan antrian. Jika Anda membuat layanan inferensi, Anda juga harus membuat objek antrian input dan antrian output. -
Gunakan fungsi
put()untuk mengirim data ke antrian input, dan gunakan fungsiwatch()untuk berlangganan data dari antrian output.CatatanDi lingkungan produksi, Anda harus menggunakan thread terpisah untuk mengirim data dan berlangganan data. Untuk tujuan demonstrasi, contoh ini melakukan operasi tersebut dalam satu thread.
Kompresi data permintaan
Untuk permintaan yang berisi banyak data, EAS mendukung kompresi data menggunakan format Zlib atau Gzip sebelum mengirimkannya ke sisi server. Untuk mengaktifkan fitur ini, Anda harus menentukan rpc.decompressor dalam konfigurasi layanan.
Konfigurasi layanan adalah sebagai berikut:
"metadata": {
"rpc": {
"decompressor": "zlib"
}
}Berikut adalah contoh kodenya:
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{
// Inisialisasi client.
PredictClient client = new PredictClient(new HttpConfig());
client.setEndpoint("18*******.cn-hangzhou.pai-eas.aliyuncs.com");
client.setModelName("echo_compress");
client.setToken("YzZjZjQwN2E4NGRkMDMxNDk5NzhhZDcwZDBjOTZjOGYwZDYxZGM2****");
// Anda juga dapat menggunakan Compressor.Gzip.
client.setCompressor(Compressor.Zlib);
// Definisikan string input.
String request = "[{\"money_credit\": 3000000}, {\"money_credit\": 10000}]";
System.out.println(request);
// Dapatkan string tanggapan dari EAS.
String response = client.predict(request);
System.out.println(response);
// Matikan client.
client.shutdown();
return;
}
}Pemecahan Masalah
Untuk memecahkan masalah Java SDK exception pemanggilan, termasuk isu umum terkait otentikasi, routing, koneksi, dan kesalahan sisi server, lihat bagian "Pemecahan Masalah Exception Pemanggilan" dalam SDK Pemanggilan Layanan.
Untuk daftar lengkap kodes status layanan, makna pesan kesalahan, dan tindakan yang direkomendasikan, lihat Lampiran: Kode Status Layanan dan Kesalahan Umum.