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á. # Contêineres com código de inferência personalizado É possível usar o Amazon SageMaker AI para interagir com contêineres do Docker e executar seu próprio código de inferência de duas maneiras: + Para usar seu próprio código de inferência com um endpoint persistente para obter uma predição por vez, use os serviços de hospedagem do SageMaker AI. + Para usar seu próprio código de inferência para obter predições referentes a um conjunto de dados completo, use a transformação em lote do SageMaker AI. **Topics** + [Código de inferência personalizado com serviços de host](your-algorithms-inference-code.md) + [Código de inferência personalizado com uma transformação em lote](your-algorithms-batch-code.md) # Código de inferência personalizado com serviços de host Esta seção explica como a Amazon SageMaker AI interage com um contêiner Docker que executa seu próprio código de inferência para serviços de hospedagem. Use essas informações para gravar um código de inferência e criar uma imagem do Docker. **Topics** + [Como a SageMaker IA executa sua imagem de inferência](#your-algorithms-inference-code-run-image) + [Como a SageMaker IA carrega seus artefatos de modelo](#your-algorithms-inference-code-load-artifacts) + [Como o contêiner deve responder a solicitações de inferência](#your-algorithms-inference-code-container-response) + [Como o contêiner deve responder a solicitações de verificação de integridade (ping)](#your-algorithms-inference-algo-ping-requests) + [Contrato de contêiner para oferecer suporte a recursos de streaming bidirecional](#your-algorithms-inference-algo-bidi) + [Use um registro privado do Docker para contêineres de inferência em tempo real](your-algorithms-containers-inference-private.md) ## Como a SageMaker IA executa sua imagem de inferência Para que um contêiner funcione como um executável, é preciso configurá-lo com uma instrução `ENTRYPOINT` em um Dockerfile. Observe o seguinte: + Para inferência do modelo, a SageMaker IA executa o contêiner como: ``` docker run image serve ``` SageMaker A IA substitui `CMD` as declarações padrão em um contêiner especificando o `serve` argumento após o nome da imagem. O argumento `serve` substitui os argumentos que você fornece com o comando `CMD` no Dockerfile.   + SageMaker A IA espera que todos os contêineres sejam executados com usuários root. Crie seu contêiner para que ele use somente usuários-raiz. Quando a SageMaker IA executa seu contêiner, os usuários que não têm acesso no nível raiz podem causar problemas de permissões.   + Recomendamos que você use a forma `exec` da instrução `ENTRYPOINT`: ``` ENTRYPOINT ["executable", "param1", "param2"] ``` Por exemplo: ``` ENTRYPOINT ["python", "k_means_inference.py"] ``` A forma `exec` da instrução `ENTRYPOINT` inicia o executável diretamente, não como elemento filho de `/bin/sh`. Isso permite que ele receba sinais como `SIGTERM` e `SIGKILL` das operações da SageMaker API, o que é um requisito.   Por exemplo, quando você usa a [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html)API para criar um endpoint, a SageMaker IA provisiona o número de instâncias de computação de ML exigidas pela configuração do endpoint, que você especifica na solicitação. SageMaker A IA executa o contêiner Docker nessas instâncias.   Se você reduzir o número de instâncias que apoiam o endpoint (chamando a [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateEndpointWeightsAndCapacities.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateEndpointWeightsAndCapacities.html)API), a SageMaker IA executa um comando para interromper o contêiner do Docker nas instâncias que estão sendo encerradas. Primeiramente, o comando envia o sinal `SIGTERM` e, então, envia o sinal `SIGKILL` 30 segundos depois.   Se você atualizar o endpoint (chamando a [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateEndpoint.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateEndpoint.html)API), a SageMaker AI lançará outro conjunto de instâncias de computação de ML e executará os contêineres do Docker que contêm seu código de inferência neles. Em seguida, ele executará um comando para interromper os contêineres anteriores do Docker. Para interromper um contêiner do Docker, primeiramente, o comando envia o sinal `SIGTERM` e, 30 segundos depois, envia o sinal `SIGKILL`.   + SageMaker A IA usa a definição de contêiner que você forneceu em sua [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html)solicitação para definir variáveis de ambiente e o nome do host DNS para o contêiner da seguinte forma:   + Ele define variáveis de ambiente usando o `ContainerDefinition.Environment` string-to-string mapa. + Ele define o nome de host DNS usando `ContainerDefinition.ContainerHostname`.   + Se você planeja usar dispositivos de GPU para inferências de modelo (especificando instâncias de cálculo de ML baseadas em GPU na sua solicitação `CreateEndpointConfig`), verifique se os seus contêineres são compatíveis com `nvidia-docker`. Não empacote drivers NVIDIA com a imagem. Para obter mais informações sobre o `nvidia-docker`, consulte [NVIDIA/nvidia-docker](https://github.com/NVIDIA/nvidia-docker).   + Você não pode usar o `tini` inicializador como seu ponto de entrada em contêineres de SageMaker IA porque ele fica confuso com os argumentos `train` e. `serve` ## Como a SageMaker IA carrega seus artefatos de modelo Em sua solicitação de [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html)API, você pode usar o `S3DataSource` parâmetro `ModelDataUrl` or para identificar o local do S3 onde os artefatos do modelo são armazenados. SageMaker A IA copia os artefatos do seu modelo da localização do S3 para o `/opt/ml/model` diretório para serem usados pelo seu código de inferência. Seu contêiner tem acesso somente leitura ao `/opt/ml/model`. Não grave nesse diretório. O `ModelDataUrl` deve apontar para um arquivo tar.gz. Caso contrário, a SageMaker IA não baixará o arquivo. Se você treinou seu modelo em SageMaker IA, os artefatos do modelo são salvos como um único arquivo tar compactado no Amazon S3. Se você treinou seu modelo fora da SageMaker IA, precisará criar esse único arquivo tar compactado e salvá-lo em um local do S3. SageMaker O AI descompacta esse arquivo tar no opt/ml/model diretório/antes do início do contêiner. Para implantar grandes modelos, recomendamos que você siga [Implantação de modelos não compactados](large-model-inference-uncompressed.md). ## Como o contêiner deve responder a solicitações de inferência Para obter inferências, o aplicativo cliente envia uma solicitação POST para o endpoint de SageMaker IA. SageMaker A IA passa a solicitação para o contêiner e retorna o resultado da inferência do contêiner para o cliente. Para obter mais informações sobre as solicitações de inferência que seu contêiner receberá, consulte as seguintes ações na *Amazon SageMaker AI API Reference:* + [ InvokeEndpoint](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpoint.html) + [ InvokeEndpointAsync](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpointAsync.html) + [ InvokeEndpointWithResponseStream](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpointWithResponseStream.html) + [ InvokeEndpointWithResponseStream](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_runtime_InvokeEndpointWithBidirectionalStream.html) **Requisitos para contêineres de inferência** Para responder às solicitações de inferência, seu contêiner deve atender aos seguintes requisitos: + SageMaker A IA remove todos os `POST` cabeçalhos, exceto aqueles suportados pelo`InvokeEndpoint`. SageMaker A IA pode adicionar cabeçalhos adicionais. É necessário que os contêineres de inferência consigam ignorar esses cabeçalhos adicionais com segurança. + Para receber solicitações de inferência, o contêiner deve ter um servidor web ouvindo na porta 8080 e deve aceitar solicitações `POST` para os endpoints `/invocations` e `/ping`. + Os contêineres de modelo do cliente devem aceitar solicitações de conexão de soquete dentro de 250 ms. + Os contêineres de modelo de um cliente devem responder a solicitações dentro de 60 segundos. O modelo em si pode ter um tempo máximo de processamento de 60 segundos antes de responder às `/invocations`. Se o seu modelo precisar de 50 a 60 segundos de tempo de processamento, o tempo limite de soquete do SDK deverá ser definido como 70 segundos. + O modelo de contêiner de um cliente que ofereça suporte a streaming bidirecional deve: + suporta WebSockets conexões na porta 8080 a/invocations-bidirectional-stream por padrão. + tem um servidor web escutando na porta 8080 e deve aceitar solicitações POST nos endpoints /ping. + Além das verificações de integridade do contêiner via HTTP, o contêiner deve responder com Pong Frame per ([RFC6455](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.3)), para enviar o WebSocket Ping Frame. **Example funções de invocação** Os exemplos a seguir demonstram como o código em seu contêiner pode processar solicitações de inferência. Esses exemplos tratam das solicitações que os aplicativos clientes enviam usando a InvokeEndpoint ação. O FastAPI é uma estrutura web para construção APIs com Python. ``` from fastapi import FastAPI, status, Request, Response . . . app = FastAPI() . . . @app.post('/invocations') async def invocations(request: Request): # model() is a hypothetical function that gets the inference output: model_resp = await model(Request) response = Response( content=model_resp, status_code=status.HTTP_200_OK, media_type="text/plain", ) return response . . . ``` Neste exemplo, a `invocations` função manipula a solicitação de inferência que a SageMaker IA envia para o `/invocations` endpoint. O Flask é um framework para o desenvolvimento de aplicações web com Python. ``` import flask . . . app = flask.Flask(__name__) . . . @app.route('/invocations', methods=["POST"]) def invoke(request): # model() is a hypothetical function that gets the inference output: resp_body = model(request) return flask.Response(resp_body, mimetype='text/plain') ``` Neste exemplo, a `invoke` função manipula a solicitação de inferência que a SageMaker IA envia para o `/invocations` endpoint. **Example funções de invocação para solicitações de streaming** Os exemplos a seguir demonstram como o código em seu contêiner pode processar solicitações de inferência de streaming. Esses exemplos tratam das solicitações que os aplicativos clientes enviam usando a InvokeEndpointWithResponseStream ação. Quando um contêiner processa uma solicitação de inferência de streaming, ele retorna a inferência do modelo como uma série de partes incrementalmente à medida que o modelo as gera. As aplicações cliente começam a receber respostas imediatamente conforme elas ficam disponíveis. Eles não precisam esperar que o modelo gere a resposta completa. Você pode implementar o streaming para oferecer apoio a experiências interativas rápidas, como chatbots, assistentes virtuais e geradores de música. O FastAPI é uma estrutura web para construção APIs com Python. ``` from starlette.responses import StreamingResponse from fastapi import FastAPI, status, Request . . . app = FastAPI() . . . @app.post('/invocations') async def invocations(request: Request): # Streams inference response using HTTP chunked encoding async def generate(): # model() is a hypothetical function that gets the inference output: yield await model(Request) yield "\n" response = StreamingResponse( content=generate(), status_code=status.HTTP_200_OK, media_type="text/plain", ) return response . . . ``` Neste exemplo, a `invocations` função manipula a solicitação de inferência que a SageMaker IA envia para o `/invocations` endpoint. Para transmitir a resposta, o exemplo usa a classe `StreamingResponse` do framework Starlette. O Flask é um framework para o desenvolvimento de aplicações web com Python. ``` import flask . . . app = flask.Flask(__name__) . . . @app.route('/invocations', methods=["POST"]) def invocations(request): # Streams inference response using HTTP chunked encoding def generate(): # model() is a hypothetical function that gets the inference output: yield model(request) yield "\n" return flask.Response( flask.stream_with_context(generate()), mimetype='text/plain') . . . ``` Neste exemplo, a `invocations` função manipula a solicitação de inferência que a SageMaker IA envia para o `/invocations` endpoint. Para transmitir a resposta, o exemplo usa função `flask.stream_with_context` do framework Flask. **Example Exemplo de funções de invocação para streaming bidirecional** Os exemplos a seguir demonstram como o código em seu contêiner pode processar solicitações e respostas de inferência de streaming. Esses exemplos lidam com solicitações de streaming que os aplicativos clientes enviam usando a InvokeEndpointWithBidirectionalStream ação. Um contêiner com capacidade de streaming bidirecional lida com solicitações de inferência de streaming em que as partes são geradas incrementalmente no cliente e transmitidas para o contêiner. Ele retorna a inferência do modelo ao cliente como uma série de partes à medida que o modelo as gera. As aplicações cliente começam a receber respostas imediatamente conforme elas ficam disponíveis. Eles não precisam esperar que a solicitação seja totalmente gerada no cliente ou que o modelo gere a resposta inteira. Você pode implementar o streaming bidirecional para oferecer suporte a experiências interativas rápidas, como chatbots, assistentes de IA de voz interativos e traduções em tempo real para uma experiência mais em tempo real. O FastAPI é uma estrutura web para construção APIs com Python. ``` import sys import asyncio import json from fastapi import FastAPI, WebSocket, WebSocketDisconnect from fastapi.responses import JSONResponse import uvicorn app = FastAPI() ... @app.websocket("/invocations-bidirectional-stream") async def websocket_invoke(websocket: WebSocket): """ WebSocket endpoint with RFC 6455 ping/pong and fragmentation support Handles: - Text messages (JSON) - including fragmented frames - Binary messages - including fragmented frames - Ping frames (automatically responds with pong) - Pong frames (logs receipt) - Fragmented frames per RFC 6455 Section 5.4 """ await manager.connect(websocket) # Fragment reassembly buffers per RFC 6455 Section 5.4 text_fragments = [] binary_fragments = [] while True: # Use receive() to handle all WebSocket frame types message = await websocket.receive() print(f"Received message: {message}") if message["type"] == "websocket.receive": if "text" in message: # Handle text frames (including fragments) text_data = message["text"] more_body = message.get("more_body", False) if more_body: # This is a fragment, accumulate it text_fragments.append(text_data) print(f"Received text fragment: {len(text_data)} chars (more coming)") else: # This is the final frame or a complete message if text_fragments: # Reassemble fragmented message text_fragments.append(text_data) complete_text = "".join(text_fragments) text_fragments.clear() print(f"Reassembled fragmented text message: {len(complete_text)} chars total") await handle_text_message(websocket, complete_text) else: # Complete message in single frame await handle_text_message(websocket, text_data) elif "bytes" in message: # Handle binary frames (including fragments) binary_data = message["bytes"] more_body = message.get("more_body", False) if more_body: # This is a fragment, accumulate it binary_fragments.append(binary_data) print(f"Received binary fragment: {len(binary_data)} bytes (more coming)") else: # This is the final frame or a complete message if binary_fragments: # Reassemble fragmented message binary_fragments.append(binary_data) complete_binary = b"".join(binary_fragments) binary_fragments.clear() print(f"Reassembled fragmented binary message: {len(complete_binary)} bytes total") await handle_binary_message(websocket, complete_binary) else: # Complete message in single frame await handle_binary_message(websocket, binary_data) elif message["type"] == "websocket.ping": # Handle ping frames - RFC 6455 Section 5.5.2 ping_data = message.get("bytes", b"") print(f"Received PING frame with payload: {ping_data}") # FastAPI automatically sends pong response elif message["type"] == "websocket.pong": # Handle pong frames pong_data = message.get("bytes", b"") print(f"Received PONG frame with payload: {pong_data}") elif message["type"] == "websocket.close": # Handle close frames - RFC 6455 Section 5.5.1 close_code = message.get("code", 1000) close_reason = message.get("reason", "") print(f"Received CLOSE frame - Code: {close_code}, Reason: '{close_reason}'") # Send close frame response if not already closing try: await websocket.close(code=close_code, reason=close_reason) print(f"Sent CLOSE frame response - Code: {close_code}") except Exception as e: print(f"Error sending close frame: {e}") break elif message["type"] == "websocket.disconnect": print("Client initiated disconnect") break else: print(f"Received unknown message type: {message['type']}") break async def handle_binary_message(websocket: WebSocket, binary_data: bytes): """Handle incoming binary messages (complete or reassembled from fragments)""" print(f"Processing complete binary message: {len(binary_data)} bytes") try: # Echo back the binary data await websocket.send_bytes(binary_data) except Exception as e: print(f"Error handling binary message: {e}") async def handle_text_message(websocket: WebSocket, data: str): """Handle incoming text messages""" try: # Send response back to the same client await manager.send_personal_message(data, websocket) except Exception as e: print(f"Error handling text message: {e}") def main(): if len(sys.argv) > 1 and sys.argv[1] == "serve": print("Starting server on port 8080...") uvicorn.run(app, host="0.0.0.0", port=8080) else: print("Usage: python app.py serve") sys.exit(1) if __name__ == "__main__": main() ``` Neste exemplo, a `websocket_invoke` função manipula a solicitação de inferência que a SageMaker IA envia para o `/invocations-bidirectional-stream` endpoint. Ele mostra como lidar com solicitações de stream e transmitir respostas de volta para o cliente. ## Como o contêiner deve responder a solicitações de verificação de integridade (ping) SageMaker A IA lança novos contêineres de inferência nas seguintes situações: + Respondendo a chamadas de API `CreateEndpoint`, `UpdateEndpoint`, `UpdateEndpointWeightsAndCapacities` + Patches de segurança + Substituição de instâncias não íntegras Logo após a inicialização do contêiner, a SageMaker IA começa a enviar solicitações GET periódicas para o `/ping` endpoint. O requisito mais simples é que o contêiner deve responder com um código de status HTTP 200 e um corpo vazio. Isso indica à SageMaker IA que o contêiner está pronto para aceitar solicitações de inferência no `/invocations` endpoint. Se o contêiner não começar a passar pelas verificações de integridade, respondendo consistentemente com 200s durante os 8 minutos após a inicialização, a execução da nova instância falhará. Isso fará o `CreateEndpoint` falhar, deixando o endpoint em um estado de falha. A atualização solicitada por `UpdateEndpoint` não será concluída, os patches de segurança não serão aplicados e as instâncias não íntegras não serão substituídas. Embora a exigência mínima seja para o contêiner retornar um 200 estático, um desenvolvedor de contêiner pode usar essa funcionalidade para executar verificações mais profundas. O tempo limite da solicitação em tentativas `/ping` é de 2 segundos. Além disso, um contêiner capaz de lidar com solicitações de streaming bidirecional deve responder com um Pong Frame (por WebSocket protocolo [RFC6455](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.3)) a um Ping Frame. Se nenhum Pong Frame for recebido por 5 pings consecutivos, a conexão com o contêiner será fechada pela plataforma SageMaker AI. SageMaker A plataforma de IA também responderá aos Ping Frames do contêiner do modelo com Pong Frames. ## Contrato de contêiner para oferecer suporte a recursos de streaming bidirecional Se você quiser hospedar seu contêiner de modelo como um endpoint de SageMaker IA que ofereça suporte a recursos de streaming bidirecional, o contêiner de modelo deve oferecer suporte ao contrato abaixo: **1. Etiqueta Docker bidirecional** O contêiner do modelo deve ter um rótulo Docker indicando à plataforma de SageMaker IA que a capacidade de streaming bidirecional é compatível com esse contêiner. ``` com.amazonaws.sagemaker.capabilities.bidirectional-streaming=true ``` **2. Support WebSocket Connection para invocações** O modelo de contêiner do cliente que suporta streaming bidirecional deve suportar WebSockets conexões na porta 8080 ou, por padrão. `/invocations-bidirectional-stream` Esse caminho pode ser substituído passando o cabeçalho X-Amzn-SageMaker-Model -Invocation-Path ao invocar a API. InvokeEndpointWithBidirectionalStream Além disso, os usuários podem especificar uma string de consulta a ser anexada a esse caminho passando o cabeçalho X-Amzn-SageMaker-Model -Query-String ao invocar a API. InvokeEndpointWithBidirectionalStream **3. Tratamento de fluxo de solicitações** As cargas de entrada da InvokeEndpointWithBidirectionalStream API são transmitidas como uma série de PayloadParts, que é apenas um invólucro de um fragmento binário (“Bytes”:): ****** ``` { "PayloadPart": { "Bytes": , "DataType": , "CompletionState": "P": } } ``` **3.1. Quadros de dados** SageMaker A IA passa a entrada PayloadParts para o contêiner do modelo como quadros de WebSocket dados ([RFC6455-Seção-5.6](https://datatracker.ietf.org/doc/html/rfc6455#section-5.6)) 1. SageMaker A IA não inspeciona o fragmento binário. 1. Ao receber uma entrada PayloadPart + SageMaker A IA cria exatamente um quadro de WebSocket dados `PayloadPart.Bytes` e o passa para o contêiner do modelo. + Se`PayloadPart.DataType = UTF8`, a SageMaker IA criar um quadro de dados de texto + Se `PayloadPart.DataType` não estiver presente ou`PayloadPart.DataType = BINARY`, a SageMaker IA cria um quadro de dados binário 1. Para uma sequência de PayloadParts com e terminada por uma PayloadPart com `PayloadPart.CompletionState = PARTIAL``PayloadPart.CompletionState = COMPLETE`, a SageMaker IA as traduz em mensagem WebSocket fragmentada [RFC6455-Seção-5.4](https://datatracker.ietf.org/doc/html/rfc6455#section-5.4): Fragmentação: + A largura inicial PayloadPart `PayloadPart.CompletionState = PARTIAL` será traduzida em um quadro de WebSocket dados, com o FIN um pouco claro. + O texto subsequente PayloadParts `PayloadPart.CompletionState = PARTIAL` será traduzido em Quadros de WebSocket Continuação com FIN um pouco claro. + A largura final PayloadPart `PayloadPart.CompletionState = COMPLETE` será traduzida em WebSocket Continuation Frame com o bit FIN definido. 1. SageMaker A IA não codifica nem decodifica o fragmento binário da entrada PayloadPart, os bytes são passados para o contêiner do modelo no estado em que se encontram. 1. SageMaker A IA não combina várias entradas PayloadParts em uma BinaryDataFrame. 1. SageMaker A IA não divide uma entrada PayloadPart em várias BinaryDataFrames. **Exemplo: fluxo de mensagens fragmentado** ``` Client sends: PayloadPart 1: {Bytes: "Hello ", DataType: "UTF8", CompletionState: "PARTIAL"} PayloadPart 2: {Bytes: "World", DataType: "UTF8", CompletionState: "COMPLETE"} Container receives: Frame 1: Text Data Frame with "Hello " (FIN=0) Frame 2: Continuation Frame with "World" (FIN=1) ``` **3.2. Quadros de controle** Além dos quadros de dados, a SageMaker IA também envia quadros de controle para o contêiner do modelo ([RFC6455-Seção-5.5](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5)): 1. Fechar quadro: a SageMaker AI pode enviar o Close Frame ([RFC6455-Seção-5.5.1](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.1)) para o contêiner do modelo caso a conexão seja fechada por qualquer motivo. 1. Ping Frame: a SageMaker IA envia o Ping Frame ([RFC6455-Seção-5.5.2](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.2)) uma vez a cada 60 segundos, o contêiner do modelo deve responder com o Pong Frame. Se nenhum Pong Frame ([RFC6455-Seção-5.5.3](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.3)) for recebido por 5 pings consecutivos, a conexão será fechada pela IA. SageMaker 1. Pong Frame: A SageMaker IA responderá aos Ping Frames do contêiner do modelo com Pong Frames. **4. Tratamento do fluxo de resposta** A saída é transmitida como uma série de PayloadParts, ModelStreamErrors ou InternalStreamFailures. ``` { "PayloadPart": { "Bytes": , "DataType": , "CompletionState": , }, "ModelStreamError": { "ErrorCode": , "Message": }, "InternalStreamFailure": { "Message": } } ``` **4.1. Quadros de dados** SageMaker A IA converte os quadros de dados recebidos do contêiner do modelo em saída PayloadParts: 1. Ao receber um quadro de dados de WebSocket texto do contêiner do modelo, a SageMaker IA obtém os bytes brutos do quadro de dados de texto e os agrupa em uma resposta PayloadPart, enquanto isso é definido`PayloadPart.DataType = UTF8`. 1. Ao receber um quadro de dados WebSocket binário do contêiner do modelo, a SageMaker IA agrupa diretamente os bytes do quadro de dados em uma resposta PayloadPart, enquanto isso é definido`PayloadPart.DataType = BINARY`. 1. Para mensagens fragmentadas, conforme definido em [RFC6455-Seção-5.4:](https://datatracker.ietf.org/doc/html/rfc6455#section-5.4) Fragmentação: + O quadro de dados inicial com FIN bit clear será traduzido em um PayloadPart with`PayloadPart.CompletionState = PARTIAL`. + Os quadros de continuação subsequentes com FIN bit clear serão traduzidos para PayloadParts com`PayloadPart.CompletionState = PARTIAL`. + O quadro de continuação final com o conjunto de bits FIN será traduzido para PayloadPart com`PayloadPart.CompletionState = COMPLETE`. 1. SageMaker A IA não codifica nem decodifica os bytes recebidos dos contêineres do modelo; os bytes são passados para o contêiner do modelo no estado em que se encontram. 1. SageMaker A IA não combina vários quadros de dados recebidos do contêiner do modelo em uma resposta PayloadPart. 1. SageMaker A IA não divide um quadro de dados recebido do contêiner do modelo em várias respostas PayloadParts. **Exemplo: fluxo de resposta de streaming** ``` Container sends: Frame 1: Text Data Frame with "Generating" (FIN=0) Frame 2: Continuation Frame with " response..." (FIN=1) Client receives: PayloadPart 1: {Bytes: "Generating", DataType: "UTF8", CompletionState: "PARTIAL"} PayloadPart 2: {Bytes: " response...", DataType: "UTF8", CompletionState: "COMPLETE"} ``` **4.2. Quadros de controle** SageMaker A IA responde aos seguintes quadros de controle do contêiner do modelo: 1. Ao receber um Close Frame ([RFC6455-Section-5.5.1](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.1)) do contêiner do modelo, a SageMaker IA empacotará o código de status ([RFC6455-Seção-7.4](https://datatracker.ietf.org/doc/html/rfc6455#section-7.4)) e as mensagens de falha e os transmitirá de volta ao ModelStreamError usuário final. 1. Ao receber um Ping Frame ([RFC6455-Seção-5.5.2](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.2)) do contêiner do modelo, a SageMaker IA responderá com o Pong Frame. 1. Pong Frame ([RFC6455-Seção-5.5.3](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.3)): Se nenhum Pong Frame for recebido por 5 pings consecutivos, a conexão será fechada pela IA. SageMaker # Use um registro privado do Docker para contêineres de inferência em tempo real A hospedagem Amazon SageMaker AI permite que você use imagens armazenadas no Amazon ECR para criar seus contêineres para inferência em tempo real por padrão. Opcionalmente, você pode criar contêineres para inferência em tempo real a partir de imagens em um registro privado do Docker. O registro privado deve ser acessível a partir de uma Amazon VPC na sua conta. Os modelos que você cria com base nas imagens armazenadas no seu registro privado do Docker devem ser configurados para se conectar à mesma VPC em que o registro privado do Docker está acessível. Para obter mais informações sobre como conectar seu modelo a uma VPC, consulte [Dê aos endpoints hospedados por SageMaker IA acesso aos recursos em sua Amazon VPC](host-vpc.md). Seu registro do Docker deve ser protegido com um certificado TLS de uma autoridade de certificação (CA) pública conhecida. **nota** Seu registro privado do Docker deve permitir o tráfego de entrada dos grupos de segurança que você especifica na configuração da VPC para seu modelo, para que a hospedagem de SageMaker IA possa extrair imagens de modelo do seu registro. SageMaker A IA pode extrair imagens de modelos DockerHub se houver um caminho para a Internet aberta dentro da sua VPC. **Topics** + [Armazene imagens em um registro privado do Docker que não seja o registro de contêiner do Amazon Elastic](#your-algorithms-containers-inference-private-registry) + [Use uma imagem de um registro privado do Docker para inferência em tempo real](#your-algorithms-containers-inference-private-use) + [Permitir que a SageMaker IA se autentique em um registro privado do Docker](#inference-private-docker-authenticate) + [Criar a função do Lambda](#inference-private-docker-lambda) + [Dê permissão ao seu perfil de execução para o Lambda](#inference-private-docker-perms) + [Criar um endpoint de interface da VPC para o Lambda](#inference-private-docker-vpc-interface) ## Armazene imagens em um registro privado do Docker que não seja o registro de contêiner do Amazon Elastic Para usar um registro privado do Docker para armazenar suas imagens para inferência de SageMaker IA em tempo real, crie um registro privado que seja acessível a partir da sua Amazon VPC. Para obter informações sobre como criar um registro do Docker, consulte [Implantar um servidor de registro](https://docs.docker.com/registry/deploying/) na documentação do Docker. O registro do Docker deve estar em conformidade com o seguinte: + O registro deve ser um registro da [API HTTP V2](https://docs.docker.com/registry/spec/api/) do registro do Docker. + O registro do Docker deve estar acessível a partir da mesma VPC que você especificar no parâmetro `VpcConfig` que você especificou ao criar seu modelo. ## Use uma imagem de um registro privado do Docker para inferência em tempo real Ao criar um modelo e implantá-lo na hospedagem de SageMaker IA, você pode especificar que ele use uma imagem do seu registro privado do Docker para criar o contêiner de inferência. Especifique isso no objeto `ImageConfig` no parâmetro `PrimaryContainer` que você passa para uma chamada para a função [create\$1model](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_model). **Usando uma imagem armazenada no seu registro privado do Docker para seu contêiner de inferência** 1. Crie o objeto de configuração de imagem e especifique um valor de `Vpc` para o campo `RepositoryAccessMode`. ``` image_config = { 'RepositoryAccessMode': 'Vpc' } ``` 1. Se o seu registro privado do Docker exigir autenticação, adicione um objeto `RepositoryAuthConfig` ao objeto de configuração de imagem. Para o `RepositoryCredentialsProviderArn` campo do `RepositoryAuthConfig` objeto, especifique o Amazon Resource Name (ARN) de uma AWS Lambda função que fornece credenciais que permitem que a SageMaker IA se autentique em seu Docker Registry privado. Para obter informações sobre como criar a função do Lambda para fornecer autenticação, consulte [Permitir que a SageMaker IA se autentique em um registro privado do Docker](#inference-private-docker-authenticate). ``` image_config = { 'RepositoryAccessMode': 'Vpc', 'RepositoryAuthConfig': { 'RepositoryCredentialsProviderArn': 'arn:aws:lambda:Region:Acct:function:FunctionName' } } ``` 1. Crie o objeto de contêiner primário que você deseja passar para `create_model`, usando o objeto de configuração de imagem que você criou na etapa anterior. Forneça sua imagem em formato de [resumo](https://docs.docker.com/engine/reference/commandline/pull/#pull-an-image-by-digest-immutable-identifier). Se você fornecer sua imagem usando a `:latest` tag, existe o risco de a SageMaker IA extrair uma versão mais recente da imagem do que a pretendida. O uso do formulário de resumo garante que a SageMaker IA obtenha a versão de imagem pretendida. ``` primary_container = { 'ContainerHostname': 'ModelContainer', 'Image': 'myteam.myorg.com/docker-local/my-inference-image:', 'ImageConfig': image_config } ``` 1. Especifique o nome do modelo e o perfil de execução para o qual você quer passar para `create_model`. ``` model_name = 'vpc-model' execution_role_arn = 'arn:aws:iam::123456789012:role/SageMakerExecutionRole' ``` 1. Especifique um ou mais grupos de segurança e sub-redes para a configuração da VPC do seu modelo. Seu registro particular do Docker deve permitir o tráfego de entrada dos grupos de segurança que você especifica. As sub-redes que você especifica devem estar na mesma VPC do seu registro particular do Docker. ``` vpc_config = { 'SecurityGroupIds': ['sg-0123456789abcdef0'], 'Subnets': ['subnet-0123456789abcdef0','subnet-0123456789abcdef1'] } ``` 1. Obtenha um cliente de SageMaker IA Boto3. ``` import boto3 sm = boto3.client('sagemaker') ``` 1. Crie o modelo chamando `create_model`, usando os valores que você especificou nas etapas anteriores para os parâmetros `PrimaryContainer` e `VpcConfig`. ``` try: resp = sm.create_model( ModelName=model_name, PrimaryContainer=primary_container, ExecutionRoleArn=execution_role_arn, VpcConfig=vpc_config, ) except Exception as e: print(f'error calling CreateModel operation: {e}') else: print(resp) ``` 1. Por fim, chame [create\$1endpoint\$1config](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_endpoint_config) e [create\$1endpoint](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_endpoint) para criar o endpoint de hospedagem, usando o modelo que você criou na etapa anterior. ``` endpoint_config_name = 'my-endpoint-config' sm.create_endpoint_config( EndpointConfigName=endpoint_config_name, ProductionVariants=[ { 'VariantName': 'MyVariant', 'ModelName': model_name, 'InitialInstanceCount': 1, 'InstanceType': 'ml.t2.medium' }, ], ) endpoint_name = 'my-endpoint' sm.create_endpoint( EndpointName=endpoint_name, EndpointConfigName=endpoint_config_name, ) sm.describe_endpoint(EndpointName=endpoint_name) ``` ## Permitir que a SageMaker IA se autentique em um registro privado do Docker [Para extrair uma imagem de inferência de um registro privado do Docker que requer autenticação, crie uma AWS Lambda função que forneça credenciais e forneça o Amazon Resource Name (ARN) da função Lambda ao chamar create\$1model.](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_model) Quando a SageMaker IA é executada`create_model`, ela chama a função Lambda que você especificou para obter credenciais para se autenticar no seu registro do Docker. ## Criar a função do Lambda Crie uma AWS Lambda função que retorne uma resposta com o seguinte formato: ``` def handler(event, context): response = { "Credentials": {"Username": "username", "Password": "password"} } return response ``` Dependendo de como você configura a autenticação para seu registro privado do Docker, as credenciais que sua função do Lambda retorna podem significar uma das seguintes opções: + Se você configurar seu registro privado do Docker para usar a autenticação básica, forneça as credenciais de login para se autenticar no registro. + Se você configurar seu registro privado do Docker para usar a autenticação do token do portador, as credenciais de login serão enviadas ao seu servidor de autorização, que retornará um token do portador que pode ser usado para autenticar no registro privado do Docker. ## Dê permissão ao seu perfil de execução para o Lambda A função de execução que você usa para chamar `create_model` deve ter permissões para chamar AWS Lambda funções. Adicione as políticas de permissões a seguir como o seu ao perfil de execução. ``` { "Effect": "Allow", "Action": [ "lambda:InvokeFunction" ], "Resource": [ "arn:aws:lambda:*:*:function:*myLambdaFunction*" ] } ``` Onde *myLambdaFunction*está o nome da sua função Lambda. Para saber mais sobre como editar a política de permissões de uma função, consulte [Modificar a política de permissões de um perfil (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/roles-managingrole-editing-console.html#roles-modify_permissions-policy) no *Guia do usuário do IAM AWS Identity and Access Management *. **nota** Uma função de execução com a política `AmazonSageMakerFullAccess` gerenciada anexada a ela tem permissão para chamar qualquer função Lambda com **SageMaker**seu nome. ## Criar um endpoint de interface da VPC para o Lambda Crie um endpoint de interface para que sua Amazon VPC possa se comunicar com sua função AWS Lambda sem enviar tráfego pela Internet. Para obter mais informações sobre como fazer isso, consulte [Configurar endpoints da VPC da interface para o Lambda](https://docs.aws.amazon.com/lambda/latest/dg/configuration-vpc-endpoints.html) no *Guia do desenvolvedor AWS Lambda *. SageMaker A hospedagem de IA envia uma solicitação por meio de sua VPC para`lambda.region.amazonaws.com`, para chamar sua função Lambda. Se você escolher o nome DNS privado ao criar seu endpoint de interface, o Amazon Route 53 roteará a chamada para o endpoint da interface Lambda. Se você usa um provedor de DNS diferente, certifique-se de mapear `lambda.region.amazonaws.com` para o seu endpoint da interface Lambda. # Código de inferência personalizado com uma transformação em lote Esta seção explica como a Amazon SageMaker AI interage com um contêiner do Docker que executa seu próprio código de inferência para transformação em lote. Use essas informações para gravar um código de inferência e criar uma imagem do Docker. **Topics** + [Como a SageMaker IA executa sua imagem de inferência](#your-algorithms-batch-code-run-image) + [Como a SageMaker IA carrega seus artefatos de modelo](#your-algorithms-batch-code-load-artifacts) + [Como os contêineres atendem a solicitações](#your-algorithms-batch-code-how-containe-serves-requests) + [Como o contêiner deve responder a solicitações de inferência](#your-algorithms-batch-code-how-containers-should-respond-to-inferences) + [Como o contêiner deve responder a solicitações de verificação de integridade (ping)](#your-algorithms-batch-algo-ping-requests) ## Como a SageMaker IA executa sua imagem de inferência Para que um contêiner funcione como um executável, é preciso configurá-lo com uma instrução `ENTRYPOINT` em um Dockerfile. Observe o seguinte: + Para transformações em lote, a SageMaker IA invoca o modelo em seu nome. SageMaker A IA executa o contêiner como: ``` docker run image serve ``` A entrada para as transformações em lote deve ter um formato que possa ser dividido em arquivos menores para serem processados em paralelo. [Esses formatos incluem CSV, [JSON, JSON](https://www.json.org/json-en.html)[Lines](https://jsonlines.org/) e [TFRecord](https://www.tensorflow.org/tutorials/load_data/tfrecord)Recordio.](https://mesos.apache.org/documentation/latest/recordio/) SageMaker A IA substitui `CMD` as declarações padrão em um contêiner especificando o `serve` argumento após o nome da imagem. O argumento `serve` substitui os argumentos que você fornece com o comando `CMD` no Dockerfile.   + Recomendamos que você use a forma `exec` da instrução `ENTRYPOINT`: ``` ENTRYPOINT ["executable", "param1", "param2"] ``` Por exemplo: ``` ENTRYPOINT ["python", "k_means_inference.py"] ```   + SageMaker A IA define variáveis de ambiente especificadas em [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html)e [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTransformJob.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTransformJob.html)no seu contêiner. Além disso, as seguintes variáveis de ambiente serão preenchidas: + `SAGEMAKER_BATCH` sempre é definida como `true` quando o contêiner é executado em transformação em lote. + `SAGEMAKER_MAX_PAYLOAD_IN_MB` é definida como a carga útil de maior tamanho que será enviada ao contêiner via HTTP. + `SAGEMAKER_BATCH_STRATEGY` será definida como `SINGLE_RECORD` quando o contêiner receber um único registro por chamada para invocações e como `MULTI_RECORD` quando o contêiner tiver o número máximo possível de registros na carga útil. + `SAGEMAKER_MAX_CONCURRENT_TRANSFORMS` é definida como o número máximo de solicitações `/invocations` que podem ser abertas simultaneamente. **nota** As últimas três variáveis de ambiente são provenientes da chamada de API feita pelo usuário. Se o usuário não definir valores para elas, elas não serão transmitidas. Nesse caso, os valores padrão ou os valores solicitados pelo algoritmo (em resposta a `/execution-parameters`) serão usados. + Se você planeja usar dispositivos de GPU para inferências de modelo (especificando instâncias de cálculo de ML baseadas em GPU na sua solicitação `CreateTransformJob`), verifique se os seus contêineres são compatíveis com nvidia-docker. Não empacote drivers NVIDIA com a imagem. Para obter mais informações sobre o nvidia-docker, consulte [NVIDIA/nvidia-docker](https://github.com/NVIDIA/nvidia-docker).   + Você não pode usar o `init` inicializador como ponto de entrada em contêineres de SageMaker IA porque ele fica confuso com os argumentos de trem e serviço. ## Como a SageMaker IA carrega seus artefatos de modelo Em uma solicitação [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html), as definições de contêiner incluem o parâmetro `ModelDataUrl`, que identifica o local no Amazon S3 em que os artefatos do modelo são armazenados. Quando você usa a SageMaker IA para executar inferências, ela usa essas informações para determinar de onde copiar os artefatos do modelo. Ele copia os artefatos para o diretório `/opt/ml/model` no contêiner do Docker para uso pelo seu código de inferência. O parâmetro `ModelDataUrl` deve apontar para um arquivo tar.gz. Caso contrário, a SageMaker IA não poderá baixar o arquivo. Se você treinar um modelo em SageMaker IA, ele salva os artefatos como um único arquivo tar compactado no Amazon S3. Se você treinar um modelo em outra estrutura, precisará armazenar os artefatos do modelo no Amazon S3 como um arquivo tar compactado. SageMaker O AI descompacta esse arquivo tar e o salva no `/opt/ml/model` diretório do contêiner antes do início do trabalho de transformação em lote. ## Como os contêineres atendem a solicitações Os contêineres devem implementar um servidor web que responda a invocações e solicitações de ping na porta 8080. Para transformações em lote, você tem a opção de definir algoritmos para implementar solicitações de parâmetros de execução para fornecer uma configuração dinâmica de tempo de execução para a IA. SageMaker SageMaker A IA usa os seguintes endpoints: + `ping`—Usado para verificar periodicamente a integridade do contêiner. SageMaker A IA espera por um código de `200` status HTTP e um corpo vazio para uma solicitação de ping bem-sucedida antes de enviar uma solicitação de invocações. Você pode usar uma solicitação de ping para carregar um modelo na memória a fim de gerar inferência quando forem enviadas solicitações de invocação. + (Opcional) `execution-parameters`: permite que o algoritmo forneça os parâmetros ideais de ajuste para um trabalho durante o runtime. Com base na memória e na CPUs disponibilidade de um contêiner, o algoritmo escolhe os `MaxPayloadInMB` valores e apropriados `MaxConcurrentTransforms` para o trabalho. `BatchStrategy` Antes de chamar a solicitação de invocações, a SageMaker IA tenta invocar a solicitação de parâmetros de execução. Ao criar um trabalho de transformação em lote, você pode fornecer valores para os `MaxPayloadInMB` parâmetros `MaxConcurrentTransforms``BatchStrategy`, e. SageMaker A IA determina os valores desses parâmetros usando esta ordem de precedência: 1. Os valores de parâmetro que você fornece ao criar a solicitação `CreateTransformJob`. 1. Os valores que o contêiner do modelo retorna quando a SageMaker IA invoca o endpoint dos parâmetros de execução> 1. Os valores de parâmetros padrão, listados na seguinte tabela: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/pt_br/sagemaker/latest/dg/your-algorithms-batch-code.html) A resposta para uma solicitação de parâmetros de execução `GET` é um objeto JSON com chaves para os parâmetros `MaxConcurrentTransforms`, `BatchStrategy`, e `MaxPayloadInMB`. Aqui está um exemplo de resposta válida: ``` { “MaxConcurrentTransforms”: 8, “BatchStrategy": "MULTI_RECORD", "MaxPayloadInMB": 6 } ``` ## Como o contêiner deve responder a solicitações de inferência Para obter inferências, a Amazon SageMaker AI envia uma solicitação POST para o contêiner de inferência. O corpo da solicitação POST contém dados do Amazon S3. O Amazon SageMaker AI passa a solicitação para o contêiner e retorna o resultado da inferência do contêiner, salvando os dados da resposta no Amazon S3. Para receber solicitações de inferência, o contêiner deve ter um servidor web que escute na porta 8080 e deve aceitar solicitações POST para o endpoint `/invocations`. O tempo limite da solicitação de inferência e o máximo de novas tentativas podem ser configurados por meio de `[ModelClientConfig](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ModelClientConfig.html)`. ## Como o contêiner deve responder a solicitações de verificação de integridade (ping) O requisito mais simples é que o contêiner deve responder com um código de status HTTP 200 e um corpo vazio. Isso indica à SageMaker IA que o contêiner está pronto para aceitar solicitações de inferência no `/invocations` endpoint. Embora a exigência mínima seja para o contêiner retornar um 200 estático, um desenvolvedor de contêiner pode usar essa funcionalidade para executar verificações mais profundas. O tempo limite da solicitação em tentativas `/ping` é de 2 segundos.