As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Crie um modelo na Amazon SageMaker AI com ModelBuilder Preparar seu modelo para implantação em um endpoint de SageMaker IA requer várias etapas, incluindo escolher uma imagem do 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. `ModelBuilder`pode reduzir a complexidade da configuração e implantação iniciais para ajudá-lo a criar um modelo implantável em uma única etapa. O `ModelBuilder` executa as seguintes tarefas para você: + Converte modelos de aprendizado de máquina treinados usando várias estruturas, como XGBoost ou PyTorch em modelos implantáveis, em uma única etapa. + Executa a seleção automática de contêineres com base na estrutura do modelo para que você não precise especificar manualmente seu contêiner. Você ainda pode trazer seu próprio contêiner passando seu próprio URI para `ModelBuilder`. + Lida com a serialização dos dados no lado do cliente antes de enviá-los ao servidor para inferência e desserialização dos resultados retornados pelo servidor. Os dados são formatados corretamente sem processamento manual. + Permite a captura automática de dependências e empacota o modelo de acordo com as expectativas do servidor do modelo. A captura automática de dependências do `ModelBuilder` é a melhor abordagem para carregar dependências dinamicamente. (Recomendamos que você teste a captura automatizada localmente e atualize as dependências para atender às suas necessidades.) + Para casos de uso do modelo de linguagem grande (LLM), opcionalmente executa o ajuste de parâmetros locais das propriedades de serviço que podem ser implantadas para melhor desempenho ao hospedar em um SageMaker endpoint de IA. + Suporta a maioria dos servidores e contêineres de modelos populares TorchServe, como Triton DJLServing e contêiner TGI. ## Crie seu modelo com ModelBuilder `ModelBuilder`é uma classe Python que usa um modelo de estrutura, como XGBoost or PyTorch, ou uma especificação de inferência especificada pelo usuário e o converte em um modelo implantável. `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 `ModelBuilder` aula, consulte [ModelBuilder](https://sagemaker.readthedocs.io/en/stable/api/inference/model_builder.html#sagemaker.serve.builder.model_builder.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. ![\[Criação de modelos e fluxo de implantação usando ModelBuilder.\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/images/model-builder-flow.png) 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 — a SageMaker IA 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](#how-it-works-modelbuilder-creation-is). ``` 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 de SageMaker IA, os dados são enviados por meio de cargas 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: 1. Serialização da solicitação de inferência (processada pelo cliente) 1. Desserialização da solicitação de inferência (processada pelo servidor ou algoritmo) 1. Invocar o modelo contra a carga útil e enviando a carga útil da resposta de volta 1. Serialização da resposta de inferência (processada pelo servidor ou algoritmo) 1. Desserialização da resposta de inferência (processada pelo cliente) O diagrama a seguir mostra os processos de serialização e desserialização que ocorrem quando você invoca o endpoint. ![\[Diagrama da serialização e desserialização de dados de cliente para servidor.\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/images/model-builder-serialization.png) 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`SchemaBuilder`, consulte [SchemaBuilder](https://sagemaker.readthedocs.io/en/stable/api/inference/model_builder.html#sagemaker.serve.builder.schema_builder.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. **Topics** + [Crie seu modelo com ModelBuilder](#how-it-works-modelbuilder-creation-mb) + [Defina métodos de serialização e desserialização](#how-it-works-modelbuilder-creation-sb) + [Personalizar o carregamento do modelo e o tratamento de solicitações](#how-it-works-modelbuilder-creation-is) + [Criar e implantar seu modelo](#how-it-works-modelbuilder-creation-deploy) + [Traga seu próprio contêiner (BYOC)](#how-it-works-modelbuilder-creation-mb-byoc) + [Usando ModelBuilder no modo local](#how-it-works-modelbuilder-creation-local) + [ModelBuilder exemplos](#how-it-works-modelbuilder-creation-example) ## 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 é usado `InferenceSpec` para gerar um modelo com o HuggingFace pipeline. Para obter mais detalhes sobre`InferenceSpec`, consulte [InferenceSpec](https://sagemaker.readthedocs.io/en/stable/api/inference/model_builder.html#sagemaker.serve.spec.inference_spec.InferenceSpec)o. ``` 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, a SageMaker IA empacota e seleciona os arquivos necessários para implantação como parte da função de `ModelBuilder` construção. Durante esse processo, a SageMaker IA também cria a assinatura HMAC para o arquivo pickle e adiciona a chave secreta na [CreateModel](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html)API 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, a SageMaker IA configura um endpoint para hospedar seu modelo à medida que ele começa a fazer previsõ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 a SageMaker IA a implantar o modelo em uma única `ml.c6i.xlarge` instância. 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 `ResourceRequirements` objeto, 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 você quiser trazer seu próprio contêiner (estendido de um contêiner de SageMaker IA), 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") ) ``` ## Usando 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 XGBoost modelo 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. + **Já está em uso**: você pode encontrar um erro `Address already in use`. Nesse caso, é possível que um contêiner do Docker esteja sendo executado nessa porta ou que outro processo o esteja utilizando. Você pode seguir a abordagem descrita na [documentação do Linux](https://www.cyberciti.biz/faq/what-process-has-open-linux-port/) para identificar o processo e redirecionar normalmente seu processo local da porta 8080 para outra porta ou limpar a instância do Docker. + **Problema de permissão do IAM**: você pode encontrar um problema de permissão ao tentar extrair uma imagem do Amazon ECR ou acessar o Amazon S3. Nesse caso, navegue até a função de execução do caderno ou da instância do Studio Classic para verificar a política `SageMakerFullAccess` ou as respectivas permissões da API. + **Problema de capacidade de volume do EBS**: se você implantar um grande modelo de linguagem (LLM), poderá ficar sem espaço ao executar o Docker no modo local ou ter limitações de espaço no cache do Docker. Nesse caso, você pode tentar mover o volume do Docker para um sistema de arquivos com espaço suficiente. Para mover seu volume do Docker, faça as seguintes etapas: 1. Abra um terminal e execute `df` para exibir o uso do disco, conforme mostrado na saída a seguir. ``` (python3) sh-4.2$ df Filesystem 1K-blocks Used Available Use% Mounted on devtmpfs 195928700 0 195928700 0% /dev tmpfs 195939296 0 195939296 0% /dev/shm tmpfs 195939296 1048 195938248 1% /run tmpfs 195939296 0 195939296 0% /sys/fs/cgroup /dev/nvme0n1p1 141545452 135242112 6303340 96% / tmpfs 39187860 0 39187860 0% /run/user/0 /dev/nvme2n1 264055236 76594068 176644712 31% /home/ec2-user/SageMaker tmpfs 39187860 0 39187860 0% /run/user/1002 tmpfs 39187860 0 39187860 0% /run/user/1001 tmpfs 39187860 0 39187860 0% /run/user/1000 ``` 1. Mova o diretório padrão do Docker de `/dev/nvme0n1p1` para para para que você `/dev/nvme2n1` possa utilizar totalmente o volume SageMaker AI de 256 GB. Para obter mais detalhes, consulte a documentação sobre como [mover seu diretório Docker](https://www.guguweb.com/2019/02/07/how-to-move-docker-data-directory-to-another-location-on-ubuntu/). 1. Pare o Docker com o seguinte comando: ``` sudo service docker stop ``` 1. Adicione `daemon.json` ou `/etc/docker` ou anexe o seguinte blob JSON ao blob existente: ``` { "data-root": "/home/ec2-user/SageMaker/{created_docker_folder}" } ``` 1. Mova o diretório do Docker no `/var/lib/docker` para `/home/ec2-user/SageMaker AI` com o seguinte comando: ``` sudo rsync -aP /var/lib/docker/ /home/ec2-user/SageMaker/{created_docker_folder} ``` 1. Inicie o Docker com o seguinte comando: ``` sudo service docker start ``` 1. Limpe os resíduos com o seguinte comando: ``` cd /home/ec2-user/SageMaker/.Trash-1000/files/* sudo rm -r * ``` 1. Se você estiver usando uma instância de SageMaker notebook, poderá seguir as etapas no [arquivo de preparação do Docker](https://github.com/melanie531/amazon-sagemaker-pytorch-lightning-distributed-training/blob/main/prepare-docker.sh) para preparar o Docker para o modo local. ## ModelBuilder exemplos Para obter mais exemplos de uso `ModelBuilder` para criar seus modelos, consulte [ModelBuilderexemplos de cadernos](https://github.com/aws-samples/sagemaker-hosting/blob/main/SageMaker-Model-Builder).