Desenvolva processadores personalizados com C ou C++ - Platform For AI: Central de Documentação do Alibaba Cloud

O PAI Elastic Algorithm Service (EAS) permite estender o runtime de inferência com um processador personalizado escrito em C ou C++. Um processador personalizado é um arquivo de objeto compartilhado (.so) que exporta duas funções — initialize() e process() — que o EAS chama em pontos específicos do ciclo de vida do serviço. Use essa abordagem quando os processadores nativos não oferecerem suporte ao formato do seu modelo ou à lógica de inferência desejada.

Demonstração de início rápido

Baixe o projeto pai-prediction-example, que inclui dois processadores personalizados prontos para execução:

echo: Retorna a entrada do usuário sem alterações, junto com uma lista de arquivos no diretório do modelo.
image_classification: Classifica imagens MNIST no formato JPG e retorna a categoria prevista.

Para instruções de compilação, consulte o README na raiz do projeto. Para orientações sobre depuração local, veja o README no diretório de cada processador.

Definição da interface

Todo processador personalizado deve exportar exatamente duas funções C: initialize() e process(). Ambas são obrigatórias, pois o EAS as chama em momentos distintos do ciclo de vida do serviço.

Para ver um exemplo funcional completo dessas funções, acesse a seção Código de exemplo.

initialize()

O EAS chama initialize() uma única vez na inicialização do serviço, antes de processar qualquer requisição. Use esta função para carregar seu modelo na memória.

Assinatura da função:

void *initialize(const char *model_entry, const char *model_config, int *state)

Parâmetro	Direção	Descrição
`model_entry`	Entrada	Arquivo de entrada do pacote do modelo. Corresponde ao campo `model_entry` na configuração de implantação JSON. Aceita um nome de arquivo (por exemplo, `randomforest.pmml`) ou um caminho de diretório (por exemplo, `./model`). Para mais detalhes, consulte Parâmetros para implantação JSON.
`model_config`	Entrada	Configuração personalizada para o modelo. Corresponde ao campo `model_config` na configuração de implantação JSON. Para mais detalhes, consulte Parâmetros para implantação JSON.
`state`	Saída	Status de carregamento do modelo. Defina como `0` em caso de sucesso; qualquer outro valor indica falha no carregamento.
Valor de retorno		Ponteiro para o modelo carregado na memória. O EAS passa esse ponteiro para cada chamada subsequente de `process()` como `model_buf`.

process()

O EAS chama process() a cada requisição de inferência. Use esta função para executar a inferência e gerar a resposta.

Assinatura da função:

int process(void *model_buf, const void *input_data, int input_size,
            void **output_data, int *output_size)

Parâmetro	Direção	Descrição
`model_buf`	Entrada	Endereço de memória do modelo retornado por `initialize()`.
`input_data`	Entrada	Payload da requisição. Pode ser uma string ou dados binários.
`input_size`	Entrada	Tamanho dos dados de entrada.
`output_data`	Saída	Payload da resposta. Aloque no heap — o modelo libera essa memória conforme a configuração.
`output_size`	Saída	Tamanho dos dados de saída.
Valor de retorno		Código de status HTTP da resposta. Retorne `0` ou `200` para indicar sucesso.

Valores de retorno que não correspondam a códigos de status HTTP reconhecidos são convertidos automaticamente para HTTP 400. Sempre use um código de status HTTP padrão (como 400 ou 500 ) ao retornar um erro.

Requisitos de implementação

Antes de implantar seu processador, verifique se ele atende aos seguintes requisitos:

Requisito	Detalhes
Exportação de ambas as funções	As funções `initialize()` e `process()` devem estar presentes e exportadas pela biblioteca compartilhada.
Alocação de heap para saída	O parâmetro `output_data` deve apontar para memória alocada no heap. O modelo libera essa memória conforme configurado. Não use memória de pilha ou buffers estáticos.
Uso exclusivo de códigos HTTP válidos	Retorne `0` ou `200` para sucesso. Em caso de erro, use códigos de status HTTP padrão (`400`, `500`, etc.). Códigos não reconhecidos serão convertidos para `400`.
Formato de biblioteca compartilhada	Compile para um arquivo `.so` com código independente de posição (`-fPIC`).
Configuração correta do processor_type	Defina `processor_type` como `"cpp"` na configuração de implantação JSON.

Código de exemplo

O exemplo abaixo implementa um processador echo: ele valida a entrada e a retorna sem modificações. Nenhum modelo é carregado.

Etapa 1: Escreva o código do processador

#include <stdio.h>
#include <string.h>

extern "C" {
    // Called once at service startup. No model to load, so state is set to 0 (success).
    void *initialize(const char *model_entry, const char *model_config, int *state)
    {
        *state = 0;
        return NULL;
    }

    // Called on every inference request. Returns the input as-is.
    int process(void *model_buf, const void *input_data, int input_size,
                void **output_data, int *output_size)
    {
        if (input_size == 0) {
            const char *errmsg = "input data should not be empty";
            *output_data = strdup(errmsg);
            *output_size = strlen(errmsg);
            return 400;  // HTTP 400: bad request
        }

        // Allocate output on the heap — the model releases this memory as configured.
        *output_data = strdup((char *)input_data);
        *output_size = input_size;
        return 200;
    }
}

Etapa 2: Compile como um arquivo de objeto compartilhado (.so)

Use o Makefile abaixo para compilar o processador em um arquivo de objeto compartilhado chamado libpredictor.so:

CC=g++
CCFLAGS=-I./ -D_GNU_SOURCE -Wall -g -fPIC
LDFLAGS= -shared -Wl,-rpath=./
OBJS=processor.o
TARGET=libpredictor.so

all: $(TARGET)

$(TARGET): $(OBJS)
	$(CC) -o $(TARGET) $(OBJS) $(LDFLAGS) -L./

%.o: %.cc
	$(CC) $(CCFLAGS) -c $< -o $@

clean:
	rm -f $(TARGET) $(OBJS)

Etapa 3: Implante o serviço EAS

Crie uma configuração de implantação JSON que referencie seu processador. Defina processor_entry com o nome do arquivo .so compilado e processor_type como "cpp".

{
    "name": "test_echo",
    "model_path": "http://*****.oss-cn-shanghai.aliyuncs.com/****/saved_model.tar.gz",
    "processor_path": "oss://path/to/echo_processor_release.tar.gz",
    "processor_entry": "libpredictor.so",
    "processor_type": "cpp",
    "metadata": {
        "instance": 1
    }
}

Campo	Descrição
`processor_path`	Caminho no OSS para o pacote compactado do processador (`.tar.gz`).
`processor_entry`	Arquivo principal de objeto compartilhado dentro do pacote. O EAS carrega este arquivo como ponto de entrada do processador.
`processor_type`	Deve ser definido como `"cpp"` para processadores C/C++.