Criar um modelo no Amazon SageMaker com o ModelBuilder

Preparar seu modelo para implantação em um endpoint do SageMaker requer várias etapas, incluindo escolher uma imagem de modelo, definir a configuração do endpoint, codificar suas funções de serialização e desserialização para transferir dados de e para o servidor e o cliente, identificar dependências do modelo e enviá-las para o Amazon S3. O ModelBuilder pode reduzir a complexidade da configuração e implantação iniciais para ajudar você a criar um modelo implantável em uma única etapa.

O ModelBuilder executa as seguintes tarefas para você:

Criar seu modelo com o ModelBuilder

ModelBuilder é uma classe Python que usa um modelo de estrutura, como XGBoost ou PyTorch, ou uma especificação de inferência especificada pelo usuário e a converte em um modelo implantável. O ModelBuilder fornece uma função de construção que gera os artefatos para implantação. O artefato do modelo gerado é específico para o servidor do modelo, que você também pode especificar como uma das entradas. Para obter mais detalhes sobre a classe ModelBuilder, consulte ModelBuilder.

O diagrama a seguir ilustra o fluxo de trabalho geral de criação do modelo quando você usa ModelBuilder. O ModelBuilder aceita uma especificação de modelo ou inferência junto com seu esquema para criar um modelo implantável que você possa testar localmente antes da implantação.

O ModelBuilder pode lidar com qualquer personalização que você queira aplicar. No entanto, para implantar um modelo de estrutura, o construtor de modelos espera no mínimo um modelo, uma amostra de entrada e saída e a função. No exemplo de código a seguir, ModelBuilder é chamado com um modelo de estrutura e uma instância de SchemaBuilder com argumentos mínimos (para inferir as funções correspondentes para serializar e desserializar a entrada e saída do endpoint). Nenhum contêiner é especificado e nenhuma dependência empacotada é passada: o SageMaker infere automaticamente esses recursos quando você cria seu modelo.

from sagemaker.serve.builder.model_builder import ModelBuilder
from sagemaker.serve.builder.schema_builder import SchemaBuilder

model_builder = ModelBuilder(
    model=model,
    schema_builder=SchemaBuilder(input, output),
    role_arn="execution-role",
)

O exemplo de código a seguir invoca ModelBuilder com uma especificação de inferência (como uma instância InferenceSpec) em vez de um modelo, com personalização adicional. Nesse caso, a chamada para o construtor de modelos inclui um caminho para armazenar artefatos do modelo e também ativa a captura automática de todas as dependências disponíveis. Para obter detalhes adicionais sobre InferenceSpec, consulte Personalizar o carregamento do modelo e o tratamento de solicitações.

model_builder = ModelBuilder(
    mode=Mode.LOCAL_CONTAINER,
    model_path=model-artifact-directory,
    inference_spec=your-inference-spec,
    schema_builder=SchemaBuilder(input, output),
    role_arn=execution-role,
    dependencies={"auto": True}
)

Defina métodos de serialização e desserialização

Ao invocar um endpoint do SageMaker, os dados são enviados por meio de cargas úteis HTTP com diferentes tipos de MIME. Por exemplo, uma imagem enviada ao endpoint para inferência precisa ser convertida em bytes no lado do cliente e enviada por meio de uma carga útil HTTP para o endpoint. Quando o endpoint recebe a carga útil, ele precisa desserializar a sequência de bytes de volta ao tipo de dados esperado pelo modelo (também conhecido como desserialização do lado do servidor). Depois que o modelo termina a predição, os resultados também precisam ser serializados em bytes que podem ser enviados de volta por meio da carga útil HTTP para o usuário ou o cliente. Depois que o cliente recebe os dados de bytes de resposta, ele precisa realizar a desserialização do lado do cliente para converter os dados de bytes de volta ao formato de dados esperado, como JSON. No mínimo, é preciso converter os dados para as seguintes tarefas:

O diagrama a seguir mostra os processos de serialização e desserialização que ocorrem quando você invoca o endpoint.

Quando você fornece amostras de entrada e saída para SchemaBuilder, o criador de esquemas gera as funções de empacotamento correspondentes para serializar e desserializar a entrada e a saída. Você pode personalizar ainda mais suas funções de serialização com CustomPayloadTranslator. Mas, na maioria dos casos, um serializador simples, como o seguinte, funcionaria:

input = "How is the demo going?"
output = "Comment la démo va-t-elle?"
schema = SchemaBuilder(input, output)

Para obter mais detalhes sobre o SchemaBuilder, consulte SchemaBuilder.

O trecho de código a seguir descreve um exemplo em que você deseja personalizar as funções de serialização e desserialização nos lados do cliente e do servidor. Você pode definir seus próprios tradutores de solicitação e resposta com CustomPayloadTranslator e repassar esses tradutores para SchemaBuilder.

Ao incluir as entradas e saídas com os tradutores, o construtor do modelo pode extrair o formato de dados que o modelo espera. Por exemplo, suponha que a entrada de amostra seja uma imagem bruta e seus tradutores personalizados recortem a imagem e enviem a imagem recortada para o servidor como um tensor. O ModelBuilder precisa da entrada bruta e de qualquer código personalizado de pré-processamento ou pós-processamento para derivar um método para converter dados no lado do cliente e do servidor.

from sagemaker.serve import CustomPayloadTranslator

# request translator
class MyRequestTranslator(CustomPayloadTranslator):
    # This function converts the payload to bytes - happens on client side
    def serialize_payload_to_bytes(self, payload: object) -> bytes:
        # converts the input payload to bytes
        ... ...
        return  //return object as bytes

    # This function converts the bytes to payload - happens on server side
    def deserialize_payload_from_stream(self, stream) -> object:
        # convert bytes to in-memory object
        ... ...
        return //return in-memory object

# response translator
class MyResponseTranslator(CustomPayloadTranslator):
    # This function converts the payload to bytes - happens on server side
    def serialize_payload_to_bytes(self, payload: object) -> bytes:
        # converts the response payload to bytes
        ... ...
        return //return object as bytes

    # This function converts the bytes to payload - happens on client side
    def deserialize_payload_from_stream(self, stream) -> object:
        # convert bytes to in-memory object
        ... ...
        return //return in-memory object

Você passa o exemplo de entrada e saída junto com os tradutores personalizados definidos anteriormente ao criar o objeto SchemaBuilder, conforme mostrado no seguinte exemplo:

my_schema = SchemaBuilder(
    sample_input=image,
    sample_output=output,
    input_translator=MyRequestTranslator(),
    output_translator=MyResponseTranslator()
)

Em seguida, você passa a amostra de entrada e saída, junto com os tradutores personalizados definidos anteriormente, para o objeto SchemaBuilder.

my_schema = SchemaBuilder(
    sample_input=image,
    sample_output=output,
    input_translator=MyRequestTranslator(),
    output_translator=MyResponseTranslator()
)

As seções a seguir explicam em detalhes como criar seu modelo ModelBuilder e usar suas classes de apoio para personalizar a experiência para seu caso de uso.

Personalizar o carregamento do modelo e o tratamento de solicitações

Fornecer seu próprio código de inferência por meio do InferenceSpec oferece uma camada adicional de personalização. Com o InferenceSpec, você pode personalizar como o modelo é carregado e como ele lida com as solicitações de inferência recebidas, ignorando seus mecanismos padrão de carregamento e tratamento de inferência. Essa flexibilidade é particularmente benéfica ao trabalhar com modelos não padrão ou pipelines de inferência personalizados. Você pode personalizar o método invoke para controlar como o modelo pré-processa e pós-processa as solicitações recebidas. O método invoke garante que o modelo trate corretamente as solicitações de inferência. O exemplo a seguir usa o InferenceSpec para gerar um modelo com o pipeline HuggingFace. Para obter mais detalhes sobre o InferenceSpec, consulte o InferenceSpec.

from sagemaker.serve.spec.inference_spec import InferenceSpec
from transformers import pipeline

class MyInferenceSpec(InferenceSpec):
    def load(self, model_dir: str):
        return pipeline("translation_en_to_fr", model="t5-small")

    def invoke(self, input, model):
        return model(input)

inf_spec = MyInferenceSpec()

model_builder = ModelBuilder(
    inference_spec=your-inference-spec,
    schema_builder=SchemaBuilder(X_test, y_pred)
)

O exemplo a seguir ilustra uma variação mais personalizada de um exemplo anterior. Um modelo é definido com uma especificação de inferência que tem dependências. Nesse caso, o código na especificação de inferência depende do pacote lang-segment. O argumento para dependencies contém uma declaração que direciona o construtor a instalar o lang-segment usando o Git. Como o construtor de modelos é orientado pelo usuário a instalar uma dependência de forma personalizada, a chave auto é False para desativar a captura automática de dependências.

model_builder = ModelBuilder(
    mode=Mode.LOCAL_CONTAINER,
    model_path=model-artifact-directory,
    inference_spec=your-inference-spec,
    schema_builder=SchemaBuilder(input, output),
    role_arn=execution-role,
    dependencies={"auto": False, "custom": ["-e git+https://github.com/luca-medeiros/lang-segment-anything.git#egg=lang-sam"],}
)

Criar e implantar seu modelo

Chame a função build para criar seu modelo implantável. Essa etapa cria um código de inferência (como inference.py) em seu diretório de trabalho com o código necessário para criar seu esquema, executar a serialização e desserialização de entradas e saídas e executar outra lógica personalizada especificada pelo usuário.

Como uma verificação de integridade, o SageMaker empacota e seleciona os arquivos necessários para implantação como parte da função de compilação ModelBuilder. Durante esse processo, o SageMaker também cria a assinatura HMAC para o arquivo pickle e adiciona a chave secreta na API CreateModel como uma variável de ambiente durante deploy (ou create). A inicialização do endpoint usa a variável de ambiente para validar a integridade do arquivo pickle.

# Build the model according to the model server specification and save it as files in the working directory
model = model_builder.build()

Implante seu modelo com o método deploy existente do modelo. Nesta etapa, o SageMaker configura um endpoint para hospedar seu modelo à medida que ele começa a fazer predições sobre as solicitações recebidas. Embora o ModelBuilder faça inferência dos recursos de endpoint necessários para implantar seu modelo, você pode substituir essas estimativas por seus próprios valores de parâmetros. O exemplo a seguir orienta o SageMaker a implantar o modelo em uma única instância ml.c6i.xlarge. Um modelo construído do ModelBuilder permite o registro ao vivo durante a implantação como um atributo adicional.

predictor = model.deploy(
    initial_instance_count=1,
    instance_type="ml.c6i.xlarge"
)

Se você quiser um controle mais refinado sobre os recursos de endpoint atribuídos ao seu modelo, você pode usar um objeto ResourceRequirements. Com o objeto ResourceRequirements, você pode solicitar um número mínimo de CPUs, aceleradores e cópias dos modelos que deseja implantar. Você também pode solicitar um limite mínimo e máximo de memória (em MB). Para usar esse atributo, você precisa especificar seu tipo de endpoint como EndpointType.INFERENCE_COMPONENT_BASED. O exemplo a seguir solicita que quatro aceleradores, um tamanho mínimo de memória de 1024 MB e uma cópia do seu modelo sejam implantados em um endpoint do tipo EndpointType.INFERENCE_COMPONENT_BASED.

resource_requirements = ResourceRequirements(
    requests={
        "num_accelerators": 4,
        "memory": 1024,
        "copies": 1,
    },
    limits={},
)
predictor = model.deploy(
    mode=Mode.SAGEMAKER_ENDPOINT,
    endpoint_type=EndpointType.INFERENCE_COMPONENT_BASED,
    resources=resource_requirements,
    role="role"
)

Traga seu próprio contêiner (BYOC)

Se quiser trazer seu próprio contêiner (estendido de um contêiner do SageMaker), você também pode especificar o URI da imagem, conforme mostrado no exemplo a seguir. Você também precisa identificar o servidor de modelos que corresponde à imagem para o ModelBuilder gerar artefatos específicos para o servidor de modelos.

model_builder = ModelBuilder(
    model=model,
    model_server=ModelServer.TORCHSERVE,
    schema_builder=SchemaBuilder(X_test, y_pred),
    image_uri="123123123123.dkr.ecr.ap-southeast-2.amazonaws.com/byoc-image:xgb-1.7-1")
)

Usar o ModelBuilder no modo local

Você pode implantar seu modelo localmente usando o argumento mode para alternar entre o teste local e a implantação em um endpoint. Você precisa armazenar os artefatos do modelo no diretório de trabalho, conforme mostrado no seguinte trecho:

model = XGBClassifier()
model.fit(X_train, y_train)
model.save_model(model_dir + "/my_model.xgb")

Aprove o objeto do modelo, uma instância SchemaBuilder, e defina o modo como Mode.LOCAL_CONTAINER. Quando você chama a função build, o ModelBuilder automaticamente identifica o contêiner da estrutura compatível e verifica as dependências. O exemplo a seguir demonstra a criação de um modelo com um modelo XGBoost no modo local.

model_builder_local = ModelBuilder(
    model=model,
    schema_builder=SchemaBuilder(X_test, y_pred),
    role_arn=execution-role,
    mode=Mode.LOCAL_CONTAINER
)
xgb_local_builder = model_builder_local.build()

Chame a função deploy para implantar localmente, conforme mostrado no trecho a seguir. Se você especificar parâmetros para tipo ou contagem de instâncias, esses argumentos serão ignorados.

predictor_local = xgb_local_builder.deploy()

Solução de problemas no modo local

Dependendo de sua configuração local individual, você pode ter dificuldades para executar o ModelBuilder sem problemas em seu ambiente. Consulte a lista a seguir para ver alguns problemas que você pode enfrentar e como resolvê-los.

Exemplos de ModelBuilder

Para obter mais exemplos de uso do ModelBuilder para criar seus modelos, consulte exemplos de cadernos do ModelBuilder.