Develop custom processors by using Java - Platform For AI

When the built-in Elastic Algorithm Service (EAS) processors don't meet your model's requirements, implement a custom Java processor to control initialization and inference logic directly.

Processor lifecycle

A Java processor is a single class with three lifecycle phases that EAS calls in sequence:

Phase	Method	When called	Required
Initialize	Constructor	Once at service startup	Yes
Load	`Load()`	Once after construction	Yes
Infer	`Process(byte[] input)`	Once per incoming request	Yes
Test	`main(String[] args)`	Only on local machine	No

EAS calls the phases in this order:

Constructor → Load() → Process() [per request] → ...

Constructor: receives the model file path (modelEntry) and the service configuration JSON string (modelConfig) passed at deploy time
Load(): loads the model into memory using the paths received by the constructor
Process(byte[] input): runs inference on each request and returns the result as bytes

Implement the processor class

Define one class in the com.alibaba.eas package. The constructor, Load(), and Process() are required. The main() method is optional and is useful for unit testing locally without deploying to EAS.

package com.alibaba.eas;
import java.util.*;

public class TestProcessor {

    // Called once at startup.
    // modelEntry: path to the model file (local or HTTP URL).
    // modelConfig: the service configuration JSON string passed at deploy time.
    public TestProcessor(String modelEntry, String modelConfig) {
    }

    // Load the model into memory. Called once after construction.
    public void Load() {
    }

    // Run inference. Accepts raw bytes; returns raw bytes.
    // Use byte[] instead of String to avoid character encoding issues.
    public byte[] Process(byte[] input) {
    }

    // Optional: test the class locally without deploying to EAS.
    public static void main(String[] args) {
    }
}

Supported input and output types

Process() supports byte[] and String. Use byte[] to avoid character encoding issues.

Handle exceptions

If Process() throws an uncaught exception, EAS captures it and returns the exception message to the client with HTTP status code 400.

To return a custom error message, catch the exception inside Process() and throw a RuntimeException with the message you want the client to receive:

try {
    // inference logic
} catch (com.alibaba.fastjson.JSONException e) {
    throw new RuntimeException("bad json format, " + e.getMessage());
}

Debug locally with standalone mode

Standalone mode lets you develop and test your processor on a local machine without deploying to a cluster. The local interfaces are fully compatible with the online cluster environment, so you can validate your processor before deploying.

Note

Standalone mode requires Docker. If your model needs a GPU, also install CUDA and Nvidia-Docker on the local machine.

Prerequisites

Before you begin, ensure that you have:

Docker installed on the machine where you run EASCMD
(For GPU models) CUDA and Nvidia-Docker installed

The EASCMD client downloaded for your operating system:

Platform	Download link
Windows 64-bit	`http://eas-data.oss-cn-shanghai.aliyuncs.com/tools/eascmdwin64`
Linux 32-bit	`http://eas-data.oss-cn-shanghai.aliyuncs.com/tools/eascmd32`
Linux 64-bit	`http://eas-data.oss-cn-shanghai.aliyuncs.com/tools/eascmd64`
macOS 64-bit	`http://eas-data.oss-cn-shanghai.aliyuncs.com/tools/eascmdmac64`

Run standalone debugging

Create a service configuration file (for example, service.json):

{
  "name": "diy_test",
  "generate_token": "true",
  "model_path": "http://examplebucket.oss-cn-hangzhou-zmf.aliyuncs.com/scorecard.pmml",
  "processor_path": "./diy_processor_release.tar.gz",
  "processor_mainclass": "com.alibaba.eas.TestProcessor",
  "processor_type": "java",
  "metadata": {
    "resource": "eas-r-9lkbl2jvdm0puv****",
    "instance": 1,
    "cpu": 1,
    "memory": 2000
  }
}

Key parameters:

Parameter	Description
`model_path`	HTTP URL or local path to the model file. Local paths are supported only in standalone mode.
`processor_path`	HTTP URL or local path to the processor package. The package is a `.tar.gz` that extracts to a compiled JAR file. Local paths are supported only in standalone mode.
`processor_mainclass`	Fully qualified name of the class that implements `Load()` and `Process()`.
`processor_type`	Set to `java` for Java processors.
`metadata.resource`	Resource group ID for a dedicated resource group.
`metadata.instance`	Number of service instances.
`metadata.cpu`	Number of CPU cores per instance.
`metadata.memory`	Memory per instance, in MB.

For the full parameter reference, see Run commands to use the EASCMD client.

Run the standalone test:
```
sudo eascmd test service.json
```