Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # Contenedores con código de inferencia personalizado Puede utilizar Amazon SageMaker AI para interactuar con contenedores de Docker y ejecutar código de inferencia propio de una de las dos formas siguientes: + Si desea utilizar código de inferencia propio con un punto de conexión persistente para obtener una predicción a la vez, utilice servicios de alojamiento de SageMaker AI. + Si desea utilizar código de inferencia propio para obtener predicciones para todo el conjunto de datos, utilice la transformación por lotes de SageMaker. **Topics** + [ # Código de inferencia personalizado con los servicios de alojamiento ](your-algorithms-inference-code.md) + [ # Código de inferencia personalizado con la transformación por lotes ](your-algorithms-batch-code.md) # Código de inferencia personalizado con los servicios de alojamiento En esta sección se explica cómo Amazon SageMaker AI interactúa con un contenedor de Docker que ejecuta su propio código de inferencia para los servicios de alojamiento. Utilice esta información para escribir el código de inferencia y crear una imagen de Docker. **Topics** + [ ## Cómo ejecuta la SageMaker IA su imagen de inferencia ](#your-algorithms-inference-code-run-image) + [ ## Cómo carga la SageMaker IA los artefactos de tus modelos ](#your-algorithms-inference-code-load-artifacts) + [ ## Cómo debe responder su contenedor a las solicitudes de inferencia ](#your-algorithms-inference-code-container-response) + [ ## Cómo debe responder su contenedor a las solicitudes de comprobación de estado (ping) ](#your-algorithms-inference-algo-ping-requests) + [ ## Container Contract to Support Bidirectional Streaming Capabilities ](#your-algorithms-inference-algo-bidi) + [ # Utilice un registro privado de Docker para contenedores de inferencia en tiempo real ](your-algorithms-containers-inference-private.md) ## Cómo ejecuta la SageMaker IA su imagen de inferencia Para configurar un contenedor para que se inicie como un archivo ejecutable, utilice una instrucción `ENTRYPOINT` en un Dockerfile. Tenga en cuenta lo siguiente: + Para la inferencia de modelos, la SageMaker IA ejecuta el contenedor de la siguiente manera: ``` docker run image serve ``` SageMaker La IA anula `CMD` las sentencias predeterminadas de un contenedor especificando el `serve` argumento después del nombre de la imagen. El argumento `serve` anula los argumentos que proporciona con el comando `CMD` en el Dockerfile.   + SageMaker La IA espera que todos los contenedores se ejecuten con usuarios root. Cree su contenedor de modo que solo utilice usuarios raíz. Cuando la SageMaker IA ejecuta tu contenedor, los usuarios que no tienen acceso desde la raíz pueden provocar problemas de permisos.   + Le recomendamos que utilice la forma `exec` de la instrucción `ENTRYPOINT`: ``` ENTRYPOINT ["executable", "param1", "param2"] ``` Por ejemplo: ``` ENTRYPOINT ["python", "k_means_inference.py"] ``` La forma `exec` de la instrucción `ENTRYPOINT` inicia el archivo ejecutable directamente, no como un elemento secundario de `/bin/sh`. Esto le permite recibir señales como `SIGTERM` y `SIGKILL` desde las operaciones de la SageMaker API, lo cual es un requisito.   Por ejemplo, cuando utilizas la [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateEndpoint.html)API para crear un punto final, la SageMaker IA proporciona el número de instancias de procesamiento de aprendizaje automático que requiere la configuración del punto final, que especificas en la solicitud. SageMaker La IA ejecuta el contenedor de Docker en esas instancias.   Si reduces el número de instancias que respaldan el punto final (mediante una llamada a la [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateEndpointWeightsAndCapacities.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateEndpointWeightsAndCapacities.html)API), la SageMaker IA ejecuta un comando para detener el contenedor de Docker en las instancias que se van a terminar. El comando envía la señal `SIGTERM` y, a continuación, envía la señal `SIGKILL` 30 segundos más tarde.   Si actualizas el punto final (mediante una llamada a la [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateEndpoint.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_UpdateEndpoint.html)API), la SageMaker IA lanza otro conjunto de instancias informáticas de aprendizaje automático y ejecuta los contenedores de Docker que contienen tu código de inferencia. A continuación se ejecuta un comando para detener los contenedores de Docker anteriores. Para detener un contenedor de Docker, el comando envía la señal `SIGTERM` y, a continuación, envía la señal `SIGKILL` 30 segundos más tarde.   + SageMaker AI usa la definición de contenedor que proporcionaste en tu [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html)solicitud para establecer las variables de entorno y el nombre de host DNS del contenedor de la siguiente manera:   + Establece las variables de entorno mediante el `ContainerDefinition.Environment` string-to-string mapa. + Establece el nombre de host de DNS mediante `ContainerDefinition.ContainerHostname`.   + Si tiene previsto utilizar los dispositivos GPU para inferencias de modelos (especificando instancias de computación de ML basadas en GPU en su solicitud `CreateEndpointConfig`), asegúrese de que los contenedores son compatibles con `nvidia-docker`. No cree un paquete con controladores de NVIDIA con la imagen. Para obtener más información sobre `nvidia-docker`, consulte [NVIDIA/nvidia-docker](https://github.com/NVIDIA/nvidia-docker).   + No puedes usar el `tini` inicializador como punto de entrada en los contenedores de SageMaker IA porque los argumentos `train` y `serve` lo confunden. ## Cómo carga la SageMaker IA los artefactos de tus modelos En su solicitud de [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html)API, puede utilizar el `S3DataSource` parámetro `ModelDataUrl` o para identificar la ubicación S3 en la que se almacenan los artefactos del modelo. SageMaker La IA copia los artefactos del modelo de la ubicación de S3 al `/opt/ml/model` directorio para utilizarlos en el código de inferencia. Su contenedor tiene acceso de solo lectura a `/opt/ml/model`. No escriba en este directorio. La `ModelDataUrl` debe apuntar a un archivo tar.gz. De lo contrario, SageMaker AI no descargará el archivo. Si ha entrenado su modelo en SageMaker IA, los artefactos del modelo se guardan como un único archivo tar comprimido en Amazon S3. Si ha entrenado su modelo fuera de la SageMaker IA, debe crear este único archivo tar comprimido y guardarlo en una ubicación S3. SageMaker AI descomprime este archivo tar en el opt/ml/model directorio/antes de que se inicie el contenedor. Para implementar modelos de gran tamaño, recomendamos que siga [Implementación de modelos sin comprimir](large-model-inference-uncompressed.md). ## Cómo debe responder su contenedor a las solicitudes de inferencia Para obtener inferencias, la aplicación cliente envía una solicitud POST al punto final de la SageMaker IA. SageMaker La IA pasa la solicitud al contenedor y devuelve el resultado de la inferencia del contenedor al cliente. Para obtener más información sobre las solicitudes de inferencia que recibirá su contenedor, consulte las siguientes acciones en la *referencia de la API de Amazon SageMaker AI*: + [ 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 los contenedores de inferencia** Para responder a las solicitudes de inferencia, su contenedor debe cumplir los siguientes requisitos: + SageMaker La IA elimina todos los `POST` encabezados excepto los compatibles con. `InvokeEndpoint` SageMaker La IA podría añadir encabezados adicionales. Los contenedores de inferencia deben poder ignorar de forma segura estos encabezados adicionales. + Para recibir solicitudes de inferencia, el contenedor debe tener un servidor web que realice la escucha en el puerto 8080 y debe aceptar las solicitudes `POST` en los punto de conexión `/invocations` y `/ping`. + Los contenedores de modelo de un cliente deben aceptar las solicitudes de conexión del socket en un plazo de 250 ms. + Los contenedores de modelos de un cliente deben responder a las solicitudes en un plazo de 60 segundos. El propio modelo puede tardar un tiempo máximo de procesamiento de 60 segundos antes de responder a las `/invocations`. Si el modelo tiene un tiempo de procesamiento de entre 50 y 60 segundos, deberá establecer el tiempo de espera del conector del SDK en 70 segundos. + El contenedor modelo de un cliente que admita la transmisión bidireccional debe: + admite WebSockets conexiones en el puerto 8080 a/de forma invocations-bidirectional-stream predeterminada. + tienen un servidor web que escucha en el puerto 8080 y deben aceptar las solicitudes POST a los puntos finales /ping. + Además de las comprobaciones de estado del contenedor a través de HTTP, el contenedor debe responder con Pong Frame per ([RFC6455](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.3)), si se envía WebSocket Ping Frame. **Example funciones de invocación** En los siguientes ejemplos se muestra cómo el código del contenedor puede procesar las solicitudes de inferencia. Estos ejemplos gestionan las solicitudes que las aplicaciones cliente envían mediante la InvokeEndpoint acción. FastAPI es un marco web para construir APIs con 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 . . . ``` En este ejemplo, la `invocations` función gestiona la solicitud de inferencia que la SageMaker IA envía al `/invocations` punto final. Flask es un marcopara desarrollar aplicaciones web con 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') ``` En este ejemplo, la `invoke` función gestiona la solicitud de inferencia que la SageMaker IA envía al `/invocations` punto final. **Example funciones de invocación para solicitudes de streaming** En los siguientes ejemplos se muestra cómo el código del contenedor de inferencia puede procesar las solicitudes de streaming. Estos ejemplos gestionan las solicitudes que las aplicaciones cliente envían mediante la InvokeEndpointWithResponseStream acción. Cuando un contenedor gestiona una solicitud de inferencia de streaming, devuelve la inferencia del modelo como una serie de partes de forma incremental a medida que el modelo las genera. Las aplicaciones cliente comienzan a recibir respuestas inmediatamente cuando están disponibles. No necesitan esperar a que el modelo genere la respuesta completa. Puede implementar la transmisión en streaming para que admita experiencias interactivas rápidas, como chatbots, asistentes virtuales y generadores de música. FastAPI es un marco web para construir APIs con 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 . . . ``` En este ejemplo, la `invocations` función gestiona la solicitud de inferencia que la SageMaker IA envía al `/invocations` punto final. Para transmitir la respuesta, el ejemplo utiliza la clase `StreamingResponse` del marco Starlette. Flask es un marcopara desarrollar aplicaciones web con 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') . . . ``` En este ejemplo, la `invocations` función gestiona la solicitud de inferencia que la SageMaker IA envía al `/invocations` punto final. Para transmitir la respuesta, el ejemplo utiliza la función `flask.stream_with_context` del marco Flask. **Example Ejemplos de funciones de invocación para la transmisión bidireccional** Los siguientes ejemplos muestran cómo el código de su contenedor puede procesar las solicitudes y respuestas de inferencia de streaming. Estos ejemplos gestionan las solicitudes de streaming que las aplicaciones cliente envían mediante la InvokeEndpointWithBidirectionalStream acción. Un contenedor con capacidad de transmisión bidireccional gestiona las solicitudes de inferencia de transmisión en las que las piezas se generan de forma incremental en el cliente y se transmiten al contenedor. Devuelve la inferencia del modelo al cliente como una serie de partes a medida que el modelo las genera. Las aplicaciones cliente comienzan a recibir respuestas inmediatamente cuando están disponibles. No necesitan esperar a que la solicitud se genere por completo en el cliente ni a que el modelo genere la respuesta completa. Puedes implementar la transmisión bidireccional para ofrecer experiencias interactivas rápidas, como chatbots, asistentes de voz interactivos con inteligencia artificial y traducciones en tiempo real, para disfrutar de una experiencia más en tiempo real. FastAPI es un marco web para construir APIs con 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() ``` En este ejemplo, la `websocket_invoke` función gestiona la solicitud de inferencia que la SageMaker IA envía al `/invocations-bidirectional-stream` punto final. Muestra cómo se gestionan las solicitudes de transmisión y las respuestas de las transmisiones al cliente. ## Cómo debe responder su contenedor a las solicitudes de comprobación de estado (ping) SageMaker La IA lanza nuevos contenedores de inferencia en las siguientes situaciones: + Responder a las llamadas a la API `CreateEndpoint`, `UpdateEndpoint` y `UpdateEndpointWeightsAndCapacities` + Creación de parches de seguridad + Reemplazo de instancias con estado incorrecto Poco después del inicio del contenedor, la SageMaker IA comienza a enviar solicitudes GET periódicas al `/ping` punto final. El requisito más sencillo en el contenedor es responder con un código de estado HTTP 200 y un cuerpo vacío. Esto le indica a SageMaker AI que el contenedor está listo para aceptar solicitudes de inferencia en el `/invocations` punto final. Si el contenedor no comienza a superar las comprobaciones de estado y responde de forma constante durante 200 segundos durante los 8 minutos posteriores al inicio, no se inicia la nueva instancia. Esto provoca un error de `CreateEndpoint` y el punto de conexión quedará en un estado de error. No se ha completado la actualización solicitada por `UpdateEndpoint`, no se han aplicado los parches de seguridad y no se han reemplazado las instancias en mal estado. Puesto que la barrera mínima es que el contenedor devuelva un código 200 estático, un desarrollador del contenedor puede usar esta funcionalidad para realizar más comprobaciones. El tiempo de espera de la solicitud en los intentos de `/ping` es de 2 segundos. Además, un contenedor que sea capaz de gestionar solicitudes de streaming bidireccionales debe responder con una Ping Frame (según el WebSocket protocolo [RFC6455](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.3)) a una Ping Frame. Si no se recibe ningún Pong Frame durante 5 pings consecutivos, la plataforma de SageMaker IA cerrará la conexión al contenedor. SageMaker La plataforma AI también responderá a los Ping Frames de un contenedor modelo con Pong Frames. ## Container Contract to Support Bidirectional Streaming Capabilities Si desea alojar su contenedor modelo como terminal de SageMaker IA que admita capacidades de transmisión bidireccional, el contenedor modelo debe ser compatible con el siguiente contrato: **1. Etiqueta Docker bidireccional** El contenedor modelo debe tener una etiqueta Docker que indique a la plataforma de SageMaker IA que este contenedor admite la capacidad de transmisión bidireccional. ``` com.amazonaws.sagemaker.capabilities.bidirectional-streaming=true ``` **2. Support WebSocket Connection para invocaciones** El contenedor modelo de un cliente que admite la transmisión bidireccional debe admitir WebSockets las conexiones en el puerto 8080 de forma predeterminada. `/invocations-bidirectional-stream` Esta ruta se puede anular pasando el encabezado X-Amzn-SageMaker-Model -Invocation-Path al invocar la API. InvokeEndpointWithBidirectionalStream Además, los usuarios pueden especificar una cadena de consulta para añadirla a esta ruta pasando el encabezado -Query-String al invocar la API. X-Amzn-SageMaker-Model InvokeEndpointWithBidirectionalStream **3. Gestión del flujo de solicitudes** Las cargas útiles de entrada de la InvokeEndpointWithBidirectionalStream API se transmiten como una serie de PayloadParts, que es solo un contenedor de un fragmento binario («Bytes»:): ****** ``` { "PayloadPart": { "Bytes": , "DataType": , "CompletionState": "P": } } ``` **3.1. Marcos de datos** SageMaker La IA pasa la entrada PayloadParts al contenedor del modelo como marcos de WebSocket datos ([RFC6455-Section-5.6](https://datatracker.ietf.org/doc/html/rfc6455#section-5.6)) 1. SageMaker La IA no inspecciona el fragmento binario. 1. Al recibir una entrada PayloadPart + SageMaker La IA crea exactamente un marco de WebSocket datos a partir del `PayloadPart.Bytes` cual lo pasa al contenedor modelo. + Si`PayloadPart.DataType = UTF8`, SageMaker AI crea un marco de datos de texto + Si `PayloadPart.DataType` no lo presenta`PayloadPart.DataType = BINARY`, la SageMaker IA crea un marco de datos binario 1. Para una secuencia de PayloadParts con y terminada PayloadPart con `PayloadPart.CompletionState = COMPLETE` un signo`PayloadPart.CompletionState = PARTIAL`, la SageMaker IA la traduce en un mensaje WebSocket fragmentado [RFC6455-Sección 5.4: Fragmentación:](https://datatracker.ietf.org/doc/html/rfc6455#section-5.4) + La inicial PayloadPart con se `PayloadPart.CompletionState = PARTIAL` traducirá a un marco de WebSocket datos, con el bit FIN libre. + El siguiente PayloadParts con se `PayloadPart.CompletionState = PARTIAL` traducirá a marcos de WebSocket continuación con el bit FIN limpio. + El ancho final PayloadPart se `PayloadPart.CompletionState = COMPLETE` traducirá a un marco de WebSocket continuación con el conjunto de bits FIN. 1. SageMaker La IA no codifica ni decodifica el fragmento binario de la entrada PayloadPart, sino que los bytes se pasan al contenedor del modelo tal cual. 1. SageMaker La IA no combina varias entradas en una sola. PayloadParts BinaryDataFrame 1. SageMaker La IA no divide una entrada PayloadPart en varias BinaryDataFrames. **Ejemplo: flujo de mensajes 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. Marcos de control** Además de los marcos de datos, la SageMaker IA también envía marcos de control al contenedor de modelos ([RFC6455-Section-5.5](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5)): 1. Cerrar marco: la SageMaker IA puede enviar un marco cerrado ([RFC6455-Section-5.5.1](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.1)) al contenedor modelo en caso de que la conexión se cierre por cualquier motivo. 1. Ping Frame: la SageMaker IA envía Ping Frame ([RFC6455-Section-5.5.2](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.2)) una vez cada 60 segundos, el contenedor modelo debe responder con Pong Frame. Si no se recibe ningún Pong Frame ([RFC6455-Sección-5.5.3](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.3)) durante 5 pings consecutivos, la IA cerrará la conexión. SageMaker 1. Pong Frame: la SageMaker IA responderá a los Ping Frames desde un contenedor modelo con Pong Frames. **4. Manejo del flujo de respuesta** La salida se transmite como una serie de PayloadParts, ModelStreamErrors o InternalStreamFailures. ``` { "PayloadPart": { "Bytes": , "DataType": , "CompletionState": , }, "ModelStreamError": { "ErrorCode": , "Message": }, "InternalStreamFailure": { "Message": } } ``` **4.1. Marcos de datos** SageMaker La IA convierte los marcos de datos recibidos del contenedor del modelo en resultados PayloadParts: 1. Al recibir un marco de datos de WebSocket texto del contenedor del modelo, la SageMaker IA obtiene los bytes sin procesar del marco de datos de texto y los agrupa en una respuesta PayloadPart, mientras está configurada`PayloadPart.DataType = UTF8`. 1. Al recibir un marco de datos WebSocket binario del contenedor del modelo, la SageMaker IA agrupa directamente los bytes del marco de datos en una respuesta PayloadPart, mientras está configurada. `PayloadPart.DataType = BINARY` 1. Para mensajes fragmentados, tal como se define en la [RFC6455Sección -5.4:](https://datatracker.ietf.org/doc/html/rfc6455#section-5.4) Fragmentación: + El marco de datos inicial con el bit FIN libre se traducirá a un ancho. PayloadPart `PayloadPart.CompletionState = PARTIAL` + Los fotogramas de continuación siguientes con el bit FIN limpio se traducirán a PayloadParts con`PayloadPart.CompletionState = PARTIAL`. + El último cuadro de continuación con el conjunto de bits FIN se traducirá a PayloadPart con`PayloadPart.CompletionState = COMPLETE`. 1. SageMaker La IA no codifica ni decodifica los bytes recibidos de los contenedores del modelo, sino que los pasa al contenedor del modelo tal cual. 1. SageMaker La IA no combina varios marcos de datos recibidos del contenedor modelo en una sola respuesta. PayloadPart 1. SageMaker La IA no divide un marco de datos recibido del contenedor del modelo en respuestas PayloadParts múltiples. **Ejemplo: flujo de respuesta en 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. Marcos de control** SageMaker La IA responde a los siguientes marcos de control desde el contenedor del modelo: 1. Al recibir un cuadro cerrado ([RFC6455-Sección-5.5.1](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.1)) del contenedor modelo, la SageMaker IA empaquetará el código de estado ([RFC6455-Sección-7.4](https://datatracker.ietf.org/doc/html/rfc6455#section-7.4)) y los mensajes de error y los transmitirá al usuario ModelStreamError final. 1. Al recibir un Ping Frame ([RFC6455-Section-5.5.2](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.2)) del contenedor modelo, la IA responderá con un Pong Frame. SageMaker 1. Pong Frame ([RFC6455-Sección-5.5.3](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.3)): Si no se recibe ningún Pong Frame durante 5 pings consecutivos, la IA cerrará la conexión. SageMaker # Utilice un registro privado de Docker para contenedores de inferencia en tiempo real El alojamiento Amazon SageMaker AI le permite utilizar imágenes almacenadas en Amazon ECR para crear sus contenedores para realizar inferencias en tiempo real de forma predeterminada. Si lo desea, puede crear contenedores para realizar inferencias en tiempo real a partir de imágenes en un registro privado de Docker. Debe poder acceder al registro privado desde una VPC de Amazon de su cuenta. Los modelos que cree en función de las imágenes almacenadas en su registro privado de Docker deben configurarse para conectarse a la misma VPC desde la que se puede acceder al registro privado de Docker. Para obtener más información sobre cómo conectarse a una VPC, consulte [Ofrezca a los puntos de conexión alojados en SageMaker IA acceso a los recursos de su Amazon VPC](host-vpc.md). Su registro de Docker protegerse con un certificado TLS de una autoridad de certificación pública conocida (CA). **nota** Su registro privado de Docker debe permitir el tráfico entrante de los grupos de seguridad que especifique en la configuración de VPC de su modelo, de modo que SageMaker AI hosting pueda extraer imágenes de modelos de su registro. SageMaker La IA puede extraer imágenes de modelos DockerHub si hay un camino hacia la Internet abierta dentro de su VPC. **Topics** + [ ## Almacene las imágenes en un registro de Docker privado que no sea Amazon Elastic Container Registry ](#your-algorithms-containers-inference-private-registry) + [ ## Utilice una imagen de un registro privado de Docker para contenedores de inferencia en tiempo real ](#your-algorithms-containers-inference-private-use) + [ ## Permita que SageMaker AI se autentique en un registro privado de Docker ](#inference-private-docker-authenticate) + [ ## Crear la función de Lambda ](#inference-private-docker-lambda) + [ ## Conceder permiso de rol de ejecución a Lambda ](#inference-private-docker-perms) + [ ## Crear un punto de conexión de VPC de la interfaz para Lambda ](#inference-private-docker-vpc-interface) ## Almacene las imágenes en un registro de Docker privado que no sea Amazon Elastic Container Registry Si desea utilizar un registro de Docker privado para almacenar sus imágenes para su inferencia SageMaker mediante IA en tiempo real, cree un registro privado al que pueda acceder desde su Amazon VPC. Para obtener información sobre cómo crear un registro de Docker, consulte [Implementar un servidor de registro](https://docs.docker.com/registry/deploying/) en la documentación de Docker. El registro de Docker debe cumplir con lo siguiente: + El registro debe ser [Docker Registry HTTP API V2](https://docs.docker.com/registry/spec/api/). + Se debe poder acceder al registro de Docker desde la misma VPC que especificó en el parámetro `VpcConfig` que especificó al crear el modelo. ## Utilice una imagen de un registro privado de Docker para contenedores de inferencia en tiempo real Al crear un modelo y desplegarlo en un alojamiento de SageMaker IA, puede especificar que utilice una imagen de su registro privado de Docker para crear el contenedor de inferencias. Especifique esto en el objeto `ImageConfig` del parámetro `PrimaryContainer` que pase a una llamada a la función [create\$1model](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_model). **Para usar una imagen almacenada en su registro privado de Docker como contenedor de inferencias** 1. Cree el objeto de configuración de la imagen y especifique un valor de `Vpc` para el campo `RepositoryAccessMode`. ``` image_config = { 'RepositoryAccessMode': 'Vpc' } ``` 1. Si su registro privado de Docker requiere autenticación, debe añadir un objeto `RepositoryAuthConfig` al objeto de configuración de la imagen. En el `RepositoryCredentialsProviderArn` campo del `RepositoryAuthConfig` objeto, especifique el nombre de recurso de Amazon (ARN) de una AWS Lambda función que proporcione credenciales que permitan a SageMaker AI autenticarse en su Docker Registry privado. Para obtener información acerca de cómo crear la función de Lambda para proporcionar autenticación, consulte [Permita que SageMaker AI se autentique en un registro privado de Docker](#inference-private-docker-authenticate). ``` image_config = { 'RepositoryAccessMode': 'Vpc', 'RepositoryAuthConfig': { 'RepositoryCredentialsProviderArn': 'arn:aws:lambda:Region:Acct:function:FunctionName' } } ``` 1. Cree el objeto contenedor principal que desee pasar a `create_model`, utilizando el objeto de configuración de imagen que creó en el paso anterior. Proporcione la imagen en forma de [resumen](https://docs.docker.com/engine/reference/commandline/pull/#pull-an-image-by-digest-immutable-identifier). Si proporciona su imagen con la `:latest` etiqueta, existe el riesgo de que SageMaker AI extraiga una versión de la imagen más reciente de lo previsto. El uso del formulario de resumen garantiza que SageMaker AI extraiga la versión de imagen deseada. ``` primary_container = { 'ContainerHostname': 'ModelContainer', 'Image': 'myteam.myorg.com/docker-local/my-inference-image:', 'ImageConfig': image_config } ``` 1. Especifique el nombre del modelo y el rol de ejecución que desea pasar a `create_model`. ``` model_name = 'vpc-model' execution_role_arn = 'arn:aws:iam::123456789012:role/SageMakerExecutionRole' ``` 1. Especifique uno o más grupos de seguridad y subredes para la configuración de VPC de su modelo. Su registro privado de Docker debe permitir el tráfico entrante de los grupos de seguridad que especifique. Las subredes que especifique deben estar en la misma VPC que su registro privado de Docker. ``` vpc_config = { 'SecurityGroupIds': ['sg-0123456789abcdef0'], 'Subnets': ['subnet-0123456789abcdef0','subnet-0123456789abcdef1'] } ``` 1. Obtenga un cliente Boto3 AI SageMaker . ``` import boto3 sm = boto3.client('sagemaker') ``` 1. Cree el modelo mediante una llamada a `create_model`, utilizando los valores que especificó en los pasos anteriores para los parámetros `PrimaryContainer` y `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 último, llame [create\$1endpoint\$1config](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_endpoint_config) y [create\$1endpoint](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_endpoint) para crear el punto de conexión de alojamiento con el modelo creado en el paso 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) ``` ## Permita que SageMaker AI se autentique en un registro privado de Docker [Para extraer una imagen de inferencia de un registro de Docker privado que requiera autenticación, cree una AWS Lambda función que proporcione credenciales y proporcione el nombre de recurso de Amazon (ARN) de la función Lambda cuando llame a create\$1model.](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/sagemaker.html#SageMaker.Client.create_model) Cuando se ejecuta la SageMaker IA`create_model`, llama a la función Lambda que especificó para obtener las credenciales necesarias para autenticarse en el registro de Docker. ## Crear la función de Lambda Cree una AWS Lambda función que devuelva una respuesta con el siguiente formulario: ``` def handler(event, context): response = { "Credentials": {"Username": "username", "Password": "password"} } return response ``` Según cómo configure la autenticación para su registro privado de Docker, las credenciales que devuelva la función de Lambda pueden significar alguna de las siguientes opciones: + Si configura su registro privado de Docker para usar la autenticación básica, proporcione las credenciales de inicio de sesión para autenticarse en el registro. + Si configura su registro privado de Docker para usar la autenticación con token de portador, las credenciales de inicio de sesión se envían a su servidor de autorización, que devuelve un token de portador que luego se puede usar para autenticarse en el registro privado de Docker. ## Conceder permiso de rol de ejecución a Lambda La función de ejecución que utilice para llamar `create_model` debe tener permisos para llamar a AWS Lambda funciones. Agregue los siguientes permisos como una política en línea al rol de IAM de ejecución de tareas. ``` { "Effect": "Allow", "Action": [ "lambda:InvokeFunction" ], "Resource": [ "arn:aws:lambda:*:*:function:*myLambdaFunction*" ] } ``` ¿Dónde *myLambdaFunction*está el nombre de la función Lambda? Para obtener más información acerca de cómo editar la política de permisos, consulte [Modificación de una política de permisos de rol (consola)](https://docs.aws.amazon.com/IAM/latest/UserGuide/roles-managingrole-editing-console.html#roles-modify_permissions-policy) en la *Guía del usuario de AWS Identity and Access Management *. **nota** Un rol de ejecución con la política `AmazonSageMakerFullAccess` gestionada adjunta tiene permiso para llamar a cualquier función de Lambda que tenga **SageMaker**en su nombre. ## Crear un punto de conexión de VPC de la interfaz para Lambda Cree un punto de conexión de interfaz para que su VPC de Amazon pueda comunicarse con su función AWS Lambda sin enviar tráfico a través de Internet. Para obtener más información sobre cómo hacerlo, consulte [Conexión de puntos de conexión de VPC de la interfaz de entrada para Lambda](https://docs.aws.amazon.com/lambda/latest/dg/configuration-vpc-endpoints.html) en la *AWS Lambda Guía para desarrolladores*. SageMaker El alojamiento de IA envía una solicitud a través de su VPC a`lambda.region.amazonaws.com`, para llamar a su función Lambda. Si elige un nombre de DNS privado al crear el punto de conexión de la interfaz, Amazon Route 53 dirige la llamada al punto de conexión de la interfaz Lambda. Si utiliza un proveedor de DNS diferente, asegúrese de asignar `lambda.region.amazonaws.com` al punto de conexión de la interfaz Lambda. # Código de inferencia personalizado con la transformación por lotes En esta sección se explica cómo Amazon SageMaker AI interactúa con un contenedor de Docker que ejecuta su propio código de inferencia para la transformación por lotes. Utilice esta información para escribir el código de inferencia y crear una imagen de Docker. **Topics** + [ ## Cómo ejecuta la SageMaker IA su imagen de inferencia ](#your-algorithms-batch-code-run-image) + [ ## Cómo carga la SageMaker IA los artefactos de tus modelos ](#your-algorithms-batch-code-load-artifacts) + [ ## Cómo los contenedores ofrecen solicitudes ](#your-algorithms-batch-code-how-containe-serves-requests) + [ ## Cómo debe responder su contenedor a las solicitudes de inferencia ](#your-algorithms-batch-code-how-containers-should-respond-to-inferences) + [ ## Cómo debe responder su contenedor a las solicitudes de comprobación de estado (ping) ](#your-algorithms-batch-algo-ping-requests) ## Cómo ejecuta la SageMaker IA su imagen de inferencia Para configurar un contenedor para que se inicie como un archivo ejecutable, utilice una instrucción `ENTRYPOINT` en un Dockerfile. Tenga en cuenta lo siguiente: + En el caso de las transformaciones por lotes, la SageMaker IA invoca el modelo en su nombre. SageMaker La IA ejecuta el contenedor de la siguiente manera: ``` docker run image serve ``` La entrada a las transformaciones por lotes debe tener un formato que se pueda dividir en archivos más pequeños para procesarlos en paralelo. Estos formatos incluyen CSV, [JSON](https://www.json.org/json-en.html), [JSON Lines [TFRecord](https://www.tensorflow.org/tutorials/load_data/tfrecord)](https://jsonlines.org/)y [Recordio](https://mesos.apache.org/documentation/latest/recordio/). SageMaker AI anula `CMD` las sentencias predeterminadas de un contenedor especificando el `serve` argumento después del nombre de la imagen. El argumento `serve` anula los argumentos que proporciona con el comando `CMD` en el Dockerfile.   + Le recomendamos que utilice la forma `exec` de la instrucción `ENTRYPOINT`: ``` ENTRYPOINT ["executable", "param1", "param2"] ``` Por ejemplo: ``` ENTRYPOINT ["python", "k_means_inference.py"] ```   + SageMaker La IA establece las variables de entorno especificadas en el contenedor [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html)y [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTransformJob.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateTransformJob.html)sobre él. Además, se rellenan las siguientes variables de entorno: + `SAGEMAKER_BATCH` se establece en `true` cuando se ejecuta el contenedor en transformaciones por lotes. + `SAGEMAKER_MAX_PAYLOAD_IN_MB` se establece en la carga de mayor tamaño que se envía al contenedor a través de HTTP. + `SAGEMAKER_BATCH_STRATEGY` se establece en `SINGLE_RECORD` cuando el contenedor se envía un solo registro para cada llamada a invocaciones y `MULTI_RECORD` cuando el contenedor obtiene tantos registros como los que caben en la carga. + `SAGEMAKER_MAX_CONCURRENT_TRANSFORMS` se establece en el número máximo de solicitudes de `/invocations` que pueden abrirse de forma simultánea. **nota** Las últimas tres variables de entorno proceden de la llamada a la API realizadas por el usuario. Si el usuario no establece valores para ellos, no se transmiten. En ese caso, se utilizan los valores predeterminados o los valores solicitados por el algoritmo (en respuesta a los `/execution-parameters`). + Si tiene previsto utilizar los dispositivos GPU para inferencias de modelos (especificando instancias de computación de ML basadas en GPU en su solicitud `CreateTransformJob`), asegúrese de que los contenedores son compatibles con nvidia-docker. No cree un paquete con controladores de NVIDIA con la imagen. Para obtener más información sobre nvidia-docker, consulte [NVIDIA/nvidia-docker](https://github.com/NVIDIA/nvidia-docker).   + No puedes usar el `init` inicializador como punto de entrada en los contenedores de SageMaker IA porque se confunde con el tren y sirve argumentos. ## Cómo carga la SageMaker IA los artefactos de tus modelos En una solicitud [https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_CreateModel.html), las definiciones de contenedor incluyen el parámetro `ModelDataUrl`, que identifica la ubicación de Amazon S3 en la que se almacenan los artefactos de modelo. Cuando se utiliza la SageMaker IA para realizar inferencias, utiliza esta información para determinar desde dónde copiar los artefactos del modelo. Copia los artefactos en el directorio `/opt/ml/model` en el contenedor de Docker para que los utilice el código de interferencia. El parámetro `ModelDataUrl` debe apuntar a un archivo tar.gz. De lo contrario, la SageMaker IA no podrá descargar el archivo. Si entrena un modelo en SageMaker IA, guarda los artefactos como un único archivo tar comprimido en Amazon S3. Si entrena un modelo en otro marco, necesitará almacenar los artefactos del modelo en Amazon S3 como un archivo tar comprimido. SageMaker AI descomprime este archivo tar y lo guarda en el `/opt/ml/model` directorio del contenedor antes de que comience el trabajo de transformación por lotes. ## Cómo los contenedores ofrecen solicitudes Los contenedores deben implementar un servidor web que responda a las invocaciones y solicitudes de ping en el puerto 8080. En el caso de las transformaciones por lotes, tiene la opción de configurar algoritmos para implementar solicitudes de parámetros de ejecución a fin de proporcionar a la IA una configuración de tiempo de ejecución dinámica. SageMaker SageMaker La IA utiliza los siguientes puntos finales: + `ping`—Se utiliza para comprobar periódicamente el estado del contenedor. SageMaker La IA espera un código de `200` estado HTTP y un cuerpo vacío para que una solicitud de ping se ejecute correctamente antes de enviar una solicitud de invocación. Podría utilizar una solicitud de ping para cargar un modelo en la memoria con objeto de generar inferencias al enviar las solicitudes de invocaciones. + (Opcional)`execution-parameters`: permite que el algoritmo proporcione los parámetros de ajuste óptimos para un trabajo durante el tiempo de ejecución. En función de la memoria y de la CPUs disponibilidad de un contenedor, el algoritmo elige los `MaxPayloadInMB` valores y valores adecuados `MaxConcurrentTransforms` para el trabajo. `BatchStrategy` Antes de llamar a la solicitud de invocación, la SageMaker IA intenta invocar la solicitud de parámetros de ejecución. Al crear un trabajo de transformación por lotes, puede proporcionar valores para los parámetros `MaxConcurrentTransforms` y`BatchStrategy`. `MaxPayloadInMB` SageMaker La IA determina los valores de estos parámetros siguiendo este orden de prioridad: 1. Los valores de los parámetros que se proporcionan al crear la solicitud `CreateTransformJob`. 1. Los valores que devuelve el contenedor del modelo cuando la SageMaker IA invoca el punto final de los parámetros de ejecución> 1. Los valores predeterminados de los parámetros, que se muestran en la siguiente tabla. [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/es_es/sagemaker/latest/dg/your-algorithms-batch-code.html) La respuesta para una solicitud execution-parameters `GET` es un objeto JSON con claves para los parámetros `MaxConcurrentTransforms`, `BatchStrategy` y `MaxPayloadInMB`. Este es un ejemplo de respuesta válida: ``` { “MaxConcurrentTransforms”: 8, “BatchStrategy": "MULTI_RECORD", "MaxPayloadInMB": 6 } ``` ## Cómo debe responder su contenedor a las solicitudes de inferencia Para obtener inferencias, Amazon SageMaker AI envía una solicitud POST al contenedor de inferencias. El cuerpo de la solicitud POST contiene datos de Amazon S3. Amazon SageMaker AI pasa la solicitud al contenedor y devuelve el resultado de la inferencia del contenedor, guardando los datos de la respuesta en Amazon S3. Para recibir solicitudes de inferencia, el contenedor debe tener un servidor web que realice la escucha en el puerto 8080 y que acepte las solicitudes POST al punto de enlace `/invocations`. El tiempo de espera de la solicitud de inferencia y el número máximo de reintentos se pueden configurar a través de `[ModelClientConfig](https://docs.aws.amazon.com/sagemaker/latest/APIReference/API_ModelClientConfig.html)`. ## Cómo debe responder su contenedor a las solicitudes de comprobación de estado (ping) El requisito más sencillo en el contenedor es responder con un código de estado HTTP 200 y un cuerpo vacío. Esto le indica a SageMaker AI que el contenedor está preparado para aceptar solicitudes de inferencia en el `/invocations` punto final. Puesto que la barrera mínima es que el contenedor devuelva un código 200 estático, un desarrollador del contenedor puede usar esta funcionalidad para realizar más comprobaciones. El tiempo de espera de la solicitud en los intentos de `/ping` es de 2 segundos.