Requisitos de los contenedores personalizados para la predicción

Para obtener más información, ejecuta el notebook de Jupyter “Vertex AI Prediction: Implementa el modelo de detección de Iris mediante FastAPI y la entrega de contenedores personalizados” en uno de los siguientes entornos:

Abrir en Colab |Abrir en Colab Enterprise |Abrir en notebooks administrados por el usuario de Vertex AI Workbench |Ver en GitHub

Nota: Esta es la versión 1.0.0 de este documento. El documento se actualiza según el control de versiones semántico.

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 esta instrucción 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 cerrará 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 consecutivas en mal estado, 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 enruta 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.

Nota: Si tu contenedor no cumple con estos requisitos para recibir solicitudes y enviar respuestas, puedes usarlo para las predicciones sin procesar.

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.

Vertex AI usa el agente de servicio de Vertex AI para que tu proyecto interactúe con otros servicios de Google Cloud. Esta cuenta de servicio tiene la dirección de correo electrónico [e-mail], 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.

Nota: Incluso si planeas usar una cuenta de servicio personalizada en tu contenedor personalizado, no es necesario otorgar los permisos de Artifact Registry a tu cuenta de servicio personalizada. Solo el agente de servicio necesita estos permisos. Vertex AI no usa tu cuenta de servicio personalizada para extraer imágenes de contenedor. Solo usa la cuenta de servicio personalizada para ejecutar el código de entrega del modelo.

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://. La instrucción 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 ejecuta, la instrucción ENTRYPOINT del contenedor puede hacer referencia a las variables de entorno que configuraste de forma manual, 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_.

La instrucción ENTRYPOINT 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.

La instrucción 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.

Nota: Las instrucciones de Docker que se usan para compilar la imagen del contenedor, como RUN, no pueden acceder a estas variables porque debes compilar la imagen del contenedor antes de proporcionarla a Vertex AI.

Nota: Vertex AI establece los valores de algunas de las siguientes variables cuando implementas tu Model como DeployedModel en un Endpoint. Puedes hacer referencia en otros campos de la API cuando creas el Model, y los valores se expanden cada vez que implementas Model.

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.

La instrucción 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.

Nota: Las instrucciones de Docker que se usan para compilar la imagen del contenedor, como RUN, no pueden acceder a estas variables porque debes compilar la imagen del contenedor antes de proporcionarla a Vertex AI.

¿Qué sigue?

• Obtén más información acerca de cómo brindar predicciones con un contenedor personalizado, lo que incluye cómo especificar campos de API relacionados con contenedores cuando importas un modelo.