Requisitos de los contenedores personalizados para la predicci�n

Si quieres usar un contenedor personalizado para entregar predicciones desde un modelo entrenado de forma personalizada, debes proporcionar a Vertex�AI una imagen de contenedor de Docker que ejecute un servidor HTTP. En este documento, se describen los requisitos que debe cumplir una imagen de contenedor para que sea compatible con Vertex�AI. En el documento, tambi�n se describe c�mo interact�a Vertex AI con tu contenedor personalizado una vez que comienza a ejecutarse. En otras palabras, en este documento, se describe lo que debes tener en cuenta cuando dise�as una imagen de contenedor para usar con Vertex�AI.

Si deseas consultar c�mo usar una imagen de contenedor personalizada para entregar predicciones, lee Usa un contenedor personalizado.

Requisitos de la imagen de contenedor

Cuando la imagen de contenedor de Docker se ejecuta como un contenedor, este debe ejecutar un servidor HTTP. Espec�ficamente, el contenedor debe escuchar y responder verificaciones de actividad, verificaciones de estado y solicitudes de predicci�n. En las siguientes subsecciones, se describen estos requisitos en detalle.

Puedes implementar el servidor HTTP de cualquier forma, con cualquier lenguaje de programaci�n, siempre que cumpla con los requisitos de esta secci�n. Por ejemplo, puedes escribir un servidor HTTP personalizado mediante un framework web como Flask o usar software de entrega de aprendizaje autom�tico (AA) que ejecute un servidor HTTP, como TensorFlow�Serving, TorchServe o el KServe Python Server.

Ejecuta el servidor HTTP

Puedes ejecutar un servidor HTTP mediante una instrucci�n ENTRYPOINT, una instrucci�n CMD o ambas en el Dockerfile que uses para compilar la imagen de contenedor. Lee sobre la interacci�n entre CMD y ENTRYPOINT.

Tambi�n puedes especificar los campos containerSpec.command y containerSpec.args cuando crees tu recurso Model a fin de anular los campos ENTRYPOINT y CMD, respectivamente, de la imagen de contenedor. Especificar uno de estos campos te permite usar una imagen de contenedor que, de lo contrario, no cumplir�a con los requisitos debido a que ENTRYPOINT o CMD no son compatibles o no existen.

Sin embargo, determinas qu� comando ejecuta tu contenedor cuando se inicia. Aseg�rate de que este comando entrypoint se ejecute de forma indefinida. Por ejemplo, no ejecutes un comando que inicie un servidor HTTP en segundo plano y, luego, se cierre. Si lo haces, el contenedor se cierra inmediatamente despu�s de que comience a ejecutarse.

El servidor HTTP debe detectar las solicitudes en 0.0.0.0 en el puerto que elijas. Cuando crees un Model, especifica este puerto en el campo containerSpec.ports. Para saber c�mo el contenedor puede acceder a este valor, lee la secci�n de este documento sobre la variable de entorno AIP_HTTP_PORT.

Verificaciones de actividad

Vertex AI realiza una verificaci�n de actividad cuando el contenedor comienza a garantizar que el servidor se est� ejecutando. Cuando implementas un modelo de entrenamiento personalizado en un recurso Endpoint, Vertex AI usa un sondeo de actividad de TCP para intentar establecer una conexi�n TCP a tu contenedor en el puerto configurado. El sondeo consta de hasta 4�intentos para establecer una conexi�n y espera 10 segundos despu�s de cada falla. Si el sondeo a�n no estableci� una conexi�n en este punto, Vertex AI reiniciar� el contenedor.

Tu servidor HTTP no necesita realizar ning�n comportamiento especial para manejar estas verificaciones. Siempre que est� escuchando las solicitudes en el puerto configurado, el sondeo de actividad puede establecer una conexi�n.

Verificaciones de estado

De manera opcional, puedes especificar startup_probe o health_probe.

El sondeo de inicio verifica si se inici� la aplicaci�n de contenedor. Si no se proporciona el sondeo de inicio, no hay sondeo de inicio y las verificaciones de estado comienzan de inmediato. Si se proporciona un sondeo de inicio, las verificaciones de estado no se realizan hasta que el sondeo de inicio se realice correctamente.

Las aplicaciones heredadas que podr�an requerir tiempo de inicio adicional en su primera inicializaci�n deben configurar un sondeo de inicio. Por ejemplo, si la aplicaci�n necesita copiar los artefactos del modelo de una fuente externa, se debe configurar un sondeo de inicio para que muestre un resultado correcto cuando se complete esa inicializaci�n.

El sondeo de estado verifica si un contenedor est� listo para aceptar tr�fico. Si no se proporciona el sondeo de estado, Vertex AI usa las verificaciones de estado predeterminadas, como se describe en Verificaciones de estado predeterminadas.

Las aplicaciones heredadas que no muestran 200 OK para indicar que el modelo est� cargado y listo para aceptar tr�fico deben configurar un sondeo de estado. Por ejemplo, una aplicaci�n puede mostrar 200 OK para indicar que la carga del modelo se realiz� correctamente, aunque el estado de carga real del modelo que se encuentra en el cuerpo de la respuesta indique que el modelo podr�a no estar cargado y, por lo tanto, podr�a no estar listo para aceptar el tr�fico. En este caso, un sondeo de estado se debe configurar para mostrar �xito solo cuando el modelo est� cargado y listo para entregar tr�fico.

Para realizar un sondeo, Vertex AI ejecuta el comando exec especificado en el contenedor de destino. Si el comando se ejecuta correctamente, muestra 0 y se considera que el contenedor est� activo y en buen estado.

Verificaciones de estado predeterminadas

De forma predeterminada, Vertex AI realiza verificaciones de estado de forma intermitente en tu servidor HTTP mientras se ejecuta para garantizar que est� lista para controlar solicitudes de predicci�n. El servicio usa un sondeo de estado para enviar solicitudes HTTP GET a una ruta de verificaci�n de estado configurable en tu servidor. Especifica esta ruta de acceso en el campo containerSpec.healthRoute cuando crees un Model. Para saber c�mo el contenedor puede acceder a este valor, lee la secci�n de este documento sobre la variable de entorno AIP_HEALTH_ROUTE.

Configura el servidor HTTP para que responda a cada solicitud de verificaci�n de estado de la siguiente manera:

Si el servidor est� listo para manejar las solicitudes de predicci�n, responde a la solicitud de verificaci�n de estado en el plazo de 10 segundos con el c�digo de estado 200 OK. El contenido del cuerpo de la respuesta no tiene importancia; Vertex AI lo ignora.

Esta respuesta implica que el servidor est� en buen estado.
Si el servidor no est� listo para manejar las solicitudes de predicci�n, no respondas a la solicitud de verificaci�n de estado en un plazo de 10 segundos ni respondas con ning�n c�digo de estado, excepto 200 OK. Por ejemplo, responde con el c�digo de estado 503 Service Unavailable.

Esta respuesta (o falta de respuesta) indica que el servidor se encuentra en mal estado.

Si el sondeo de estado recibe una respuesta en mal estado de tu servidor (incluida la falta de respuesta en el plazo de 10 segundos), enviar� hasta 3 verificaciones de estado adicionales a intervalos de 10 segundos. Durante este per�odo, Vertex AI a�n considera que el servidor se encuentra en buen estado. Si el sondeo recibe una respuesta en buen estado de cualquiera de estas verificaciones, el sondeo vuelve inmediatamente a su programaci�n intermitente de verificaciones de estado. Sin embargo, si el sondeo recibe 4 respuestas en mal estado consecutivas, Vertex AI dejar� de dirigir el tr�fico de predicci�n al contenedor. (Si el recurso DeployedModel se escala para usar varios nodos de predicci�n, Vertex AI enrutar� las solicitudes de predicci�n a otros contenedores en buen estado).

Vertex AI no reinicia el contenedor. En su lugar, el sondeo de estado contin�a enviando de forma intermitente solicitudes de verificaci�n de estado al servidor en mal estado. Si recibe una respuesta en buen estado, entonces se marca ese contenedor como en buen estado y comienza a enrutar el tr�fico de predicci�n a �l.

Orientaci�n pr�ctica

En algunos casos, es suficiente con que el servidor HTTP de tu contenedor siempre responda con el c�digo de estado 200 OK a las verificaciones de estado. Si tu contenedor carga recursos antes de iniciar el servidor, el contenedor estar� en mal estado durante el per�odo de inicio y durante cualquier per�odo en el que el servidor HTTP falle. En todos los dem�s casos, responder� como en buen estado.

A fin de obtener una configuraci�n m�s sofisticada, debes dise�ar de manera deliberada el servidor HTTP para que responda a las verificaciones de estado con un mal estado en determinados momentos. Por ejemplo, es posible que desees bloquear el tr�fico de predicci�n a un nodo durante un per�odo para que el contenedor pueda realizar el mantenimiento.

Solicitudes de predicci�n

Cuando un cliente env�a una solicitud projects.locations.endpoints.predict a la API de Vertex AI, Vertex AI reenv�a esta solicitud como una solicitud POST HTTP a una ruta de predicci�n configurable en tu servidor. Especifica esta ruta de acceso en el campo containerSpec.predictRoute cuando crees un Model. Para saber c�mo el contenedor puede acceder a este valor, lee la secci�n de este documento sobre la variable de entorno AIP_PREDICT_ROUTE.

Requisitos de las solicitudes

Si el modelo se implementa en un extremo p�blico, cada solicitud de predicci�n debe ser de 1.5�MB o menos. El servidor HTTP debe aceptar solicitudes de predicci�n que tengan los cuerpos JSON y el encabezado HTTP Content-Type: application/json con el siguiente formato:

{
  "instances": INSTANCES,
  "parameters": PARAMETERS
}

En estas solicitudes:

INSTANCES es un arreglo de uno o m�s valores JSON de cualquier tipo. Cada valor representa una instancia para la que proporcionas una predicci�n.
PARAMETERS es un objeto JSON que contiene cualquier par�metro que el contenedor requiera para ayudar a entregar predicciones en las instancias. Vertex AI considera el campo parameters opcional, por lo que puedes dise�ar tu contenedor para que lo solicite, lo use solo cuando se lo proporcione o lo ignore.

Obt�n m�s informaci�n sobre los requisitos del cuerpo de la solicitud.

Requisitos de las respuestas

Si el modelo se implementa en un extremo p�blico, cada respuesta de predicci�n debe ser de 1.5�MB o menos. El servidor HTTP debe enviar respuestas con cuerpos JSON que cumplan con el siguiente formato:

{
  "predictions": PREDICTIONS
}

En estas respuestas, reemplaza PREDICTIONS por un array de valores JSON que represente las predicciones que tu contenedor gener� para cada una de las INSTANCES en la solicitud correspondiente.

Una vez que tu servidor HTTP env�a esta respuesta, Vertex AI agrega un campo deployedModelId a la respuesta antes de mostr�rsela al cliente. Este campo especifica qu� DeployedModel en un Endpoint env�a la respuesta. Obt�n m�s informaci�n sobre el formato del cuerpo de la respuesta.

Requisitos para la publicaci�n de im�genes en contenedores

Debes enviar tu imagen de contenedor a Artifact Registry para usarla con Vertex AI. Obt�n informaci�n para enviar una imagen de contenedor a Artifact Registry.

En particular, debes enviar la imagen del contenedor a un repositorio que cumpla con los siguientes requisitos de ubicaci�n y permisos.

Ubicaci�n

Cuando usas Artifact Registry, el repositorio debe usar una regi�n que coincida con el extremo regional en el que planeas crear un Model. Por ejemplo, si planeas crear un Model en el extremo us-central1-aiplatform.googleapis.com, el nombre completo de tu imagen de contenedor debe comenzar con us-central1-docker.pkg.dev/. No uses un repositorio multirregional para la imagen de contenedor.

Permisos

Vertex AI debe tener permiso para extraer la imagen del contenedor cuando crees un Model. En particular, el agente de servicio de Vertex AI para tu proyecto debe tener los permisos de la funci�n Lector de Artifact Registry (roles/artifactregistry.reader) para el repositorio de la imagen de contenedor.

El agente de servicio de Vertex�AI de tu proyecto es la cuenta de servicio administrada por Google que usa Vertex�AI para interactuar con otros servicios de Google�Cloud. Esta cuenta de servicio tiene la direcci�n de correo electr�nico service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com, en la que PROJECT_NUMBER se reemplaza por el n�mero de tu proyecto de Vertex AI.

Si enviaste tu imagen de contenedor al mismo proyecto de Google Cloud en el que usas Vertex AI, no es necesario que configures ning�n permiso. Los permisos predeterminados otorgados al agente de servicio de Vertex�AI son suficientes.

Por otro lado, si enviaste tu imagen de contenedor a un proyecto de Google Cloud diferente del que est�s usando con Vertex AI, debes otorgar el rol de lector de Artifact Registry al repositorio de Artifact Registry en el agente de servicio de Vertex AI.

Accede a los artefactos del modelo

Cuando creas un entrenamiento personalizadoModel sin un contenedor personalizado, debes especificar el URI de un directorio de Cloud�Storage con artefactos de modelos como el campo campo artifactUri. Cuando creas un Model con un contenedor personalizado, proporcionar artefactos de modelo en Cloud�Storage es opcional.

Si la imagen de contenedor incluye los artefactos del modelo que necesitas para entregar predicciones, no es necesario cargar archivos de Cloud Storage. Sin embargo, si proporcionas artefactos del modelo mediante la especificaci�n del campo artifactUri, el contenedor debe cargar estos artefactos cuando comience a ejecutarse. Cuando Vertex AI inicia tu contenedor, establece la variable de entorno AIP_STORAGE_URI en un URI de Cloud Storage que comienza con gs://. El comando entrypoint de tu contenedor puede descargar el directorio especificado por este URI para acceder a los artefactos del modelo.

Ten en cuenta que el valor de la variable de entorno AIP_STORAGE_URI no es id�ntico al URI de Cloud Storage que especificas en el campo artifactUri cuando creas el Model. En cambio, AIP_STORAGE_URI apunta a una copia del directorio de artefactos de tu modelo en un bucket de Cloud Storage diferente, que administra Vertex AI. Vertex AI propaga este directorio cuando creas un Model. No puedes actualizar el contenido del directorio. Si deseas usar artefactos de modelos nuevos, debes crear un Model nuevo.

La cuenta de servicio que usa tu contenedor de forma predeterminada tiene permiso para leer desde este URI.

Por otro lado, si especificas una cuenta de servicio personalizada cuando implementas Model en Endpoint, Vertex�AI otorga autom�ticamente a tu cuenta de servicio especificada la funci�n de Lector de objetos de Storage (roles/storage.objectViewer) para el bucket de Cloud�Storage del URI.

Usa cualquier biblioteca que admita las credenciales predeterminadas de la aplicaci�n (ADC) para cargar los artefactos del modelo. No necesitas configurar la autenticaci�n de forma expl�cita.

Variables de entorno disponibles en el contenedor

Cuando se encuentra en ejecuci�n, el comando entrypoint del contenedor puede hacer referencia a las variables de entorno que configuraste manualmente, as� como a las variables de entorno que configur� Vertex AI autom�ticamente. En esta secci�n, se describe cada m�todo para configurar las variables de entorno y se proporcionan detalles sobre las variables que establece autom�ticamente Vertex AI.

Variables establecidas en la imagen del contenedor

Para establecer variables de entorno en la imagen del contenedor cuando la compilas, usa la instrucci�n ENV de Docker. No establezcas ninguna variable de entorno que comience con el prefijo AIP_.

El comando de punto de entrada del contenedor puede usar estas variables de entorno, pero no puedes hacer referencia a ellas en ninguno de los campos de la API de Model.

Variables establecidas por Vertex�AI

Cuando Vertex AI comienza a ejecutar el contenedor, establece las siguientes variables de entorno en el entorno del contenedor. Cada variable comienza con el prefijo AIP_. No establezcas manualmente ninguna variable de entorno que use este prefijo.

El comando entrypoint del contenedor puede acceder a estas variables. Para saber qu� campos de la API de Vertex�AI tambi�n pueden hacer referencia a estas variables, lee la referencia de la API para ModelContainerSpec.

Nombre de la variable	Valor predeterminado	C�mo configurar el valor	Detalles
AIP_ACCELERATOR_TYPE	Sin establecer	Cuando implementes un `Model` como `DeployedModel` en un recurso `Endpoint`, configura el campo `dedicatedResources.machineSpec.acceleratorType`.	Si corresponde, esta variable especifica el tipo de acelerador que usa la instancia de m�quina virtual (VM) en la que se ejecuta el contenedor.
AIP_DEPLOYED_MODEL_ID	Una string de d�gitos que identifica el `DeployedModel` en el que se implement� el `Model` de este contenedor.	No configurable	Este valor es el campo `id` de `DeployedModel`.
AIP_ENDPOINT_ID	Una string de d�gitos que identifica el `Endpoint` en el que se implement� el `Model` del contenedor.	No configurable	Este valor es el �ltimo segmento del campo `name` de `Endpoint` (despu�s de `endpoints/`).
AIP_FRAMEWORK	`CUSTOM_CONTAINER`	No configurable
AIP_HEALTH_ROUTE	`/v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL` En esta string, reemplaza `ENDPOINT` por el valor de la variable `AIP_ENDPOINT_ID` y reemplaza `DEPLOYED_MODEL` por el valor de la variable `AIP_DEPLOYED_MODEL_ID`.	Cuando crees un `Model`, configura el campo `containerSpec.healthRoute`.	Esta variable especifica la ruta HTTP en el contenedor al que Vertex�AI env�a verificaciones de estado.
AIP_HTTP_PORT	`8080`	Cuando crees un `Model`, configura el campo `containerSpec.ports`. La primera entrada de este campo se convierte en el valor de `AIP_HTTP_PORT`.	Vertex AI env�a verificaciones de actividad, verificaciones de estado y solicitudes de predicci�n a este puerto en el contenedor. El servidor HTTP de tu contenedor debe detectar solicitudes en este puerto.
AIP_MACHINE_TYPE	No hay una configuraci�n predeterminada; se debe configurar	Cuando implementes un `Model` como `DeployedModel` en un recurso `Endpoint`, configura el campo `dedicatedResources.machineSpec.machineType`.	Esta variable especifica el tipo de VM en la que se ejecuta el contenedor.
AIP_MODE	`PREDICTION`	No configurable	Esta variable significa que el contenedor est� en ejecuci�n en Vertex AI para entregar predicciones en l�nea. Puedes usar esta variable de entorno para agregar l�gica personalizada a tu contenedor, de modo que pueda ejecutarse en varios entornos de computaci�n, pero solo se pueda usar en rutas de c�digo espec�ficas cuando se ejecuten en Vertex AI.
AIP_MODE_VERSION	`1.0.0`	No configurable	Esta variable indica la versi�n de los requisitos del contenedor personalizado (este documento) que Vertex�AI espera que cumpla el contenedor. Este documento se actualiza seg�n el control de versiones sem�ntico.
AIP_MODEL_NAME	Se muestra el valor de la variable `AIP_ENDPOINT_ID`	No configurable	Consulta la fila `AIP_ENDPOINT_ID`. Esta variable existe por motivos de compatibilidad.
AIP_PREDICT_ROUTE	`/v1/endpoints/ENDPOINT/deployedModels/DEPLOYED_MODEL:predict` En esta string, reemplaza `ENDPOINT` por el valor de la variable `AIP_ENDPOINT_ID` y reemplaza `DEPLOYED_MODEL` por el valor de la variable `AIP_DEPLOYED_MODEL_ID`.	Cuando crees un `Model`, configura el campo `containerSpec.predictRoute`.	Esta variable especifica la ruta HTTP en el contenedor al que Vertex�AI env�a solicitudes de predicci�n.
AIP_PROJECT_NUMBER	El n�mero del proyecto de Google Cloud en el que usas Vertex�AI	No configurable
AIP_STORAGE_URI	Si no configuras el campo `artifactUri` cuando creas un `Model`: una string vac�a Si configuras el campo `artifactUri` cuando creas un `Model`: un URI de Cloud�Storage (que comienza con `gs://`) que especifica un directorio en un bucket administrado por Vertex�AI	No configurable	Esta variable especifica el directorio que contiene una copia de los artefactos de tu modelo, si corresponde.
AIP_VERSION_NAME	Se muestra el valor de la variable `AIP_DEPLOYED_MODEL_ID`	No configurable	Consulta la fila `AIP_DEPLOYED_MODEL_ID`. Esta variable existe por motivos de compatibilidad.

Variables establecidas en el recurso `Model`

Cuando creas un Model, puedes configurar variables de entorno adicionales en el campo containerSpec.env.

�Qu� sigue?

Obt�n m�s informaci�n sobre c�mo entregar predicciones con un contenedor personalizado, lo que incluye c�mo especificar campos de API relacionados con contenedores cuando importas un modelo.