Requisitos de los contenedores personalizados

Si deseas usar un contenedor personalizado para entregar predicciones, debes proporcionar AI Platform Prediction con 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 AI Platform Prediction. También se describe cómo AI Platform Prediction interactúa con el 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 usarla con AI Platform Prediction.

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 KFServing 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.

Como alternativa, puedes especificar los campos containerSpec.command y containerSpec.args cuando crees tu versión del modelo para anular tu contenedor de la imagen ENTRYPOINT y CMD, respectivamente. 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 una versión del modelo, 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

AI Platform Prediction realiza una verificación de actividad cuando el contenedor comienza a garantizar que el servidor se esté ejecutando. Durante el proceso de creación de la versión, AI Platform Prediction 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, AI Platform Prediction reinicia 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

AI Platform Prediction realiza verificaciones de estado de forma intermitente en el servidor HTTP mientras se ejecuta a fin de garantizar que esté listo para manejar 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 en el campo routes.health cuando crees una versión del modelo. 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 con el código de estado 200 OK. El contenido del cuerpo de la respuesta no tiene importancia; AI Platform Prediction las ignora.

    Esta respuesta implica que el servidor está en buen estado.

  • Si el servidor no está listo para manejar solicitudes de predicción, no respondas a la solicitud de verificación de estado 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 implica que el servidor no está en buen estado.

Si el sondeo de estado recibe una respuesta en mal estado de tu servidor, enviará hasta 3 verificaciones de estado adicionales a intervalos de 10 segundos. Durante este período, AI Platform Prediction todavía considera que el servidor está 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, AI Platform Prediction detiene el enrutamiento del tráfico de predicción al contenedor. (Si la versión del modelo se escala para usar varios nodos de predicción, AI Platform Prediction enruta las solicitudes de predicción a otros contenedores en buen estado).

AI Platform Prediction 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 projects.predict solicitud a la AI Platform Training y la API de Prediction, AI Platform Prediction reenvía esta solicitud como una solicitud HTTP POST a una ruta de predicción configurable en tu servidor. Especifica esta ruta en el campo routes.predict cuando crees una versión del modelo. 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.

AI Platform Prediction no valida las solicitudes de predicción y las respuestas. Pasa cada solicitud de predicción sin modificar al servidor HTTP en tu contenedor y pasa las respuestas del servidor al cliente.

Cada solicitud de predicción y respuesta debe tener 1.5 MB o menos. Sin embargo, no es necesario que sigas los otros requisitos para los cuerpos de solicitud y los requisitos para los cuerpos de respuesta. Estos requisitos solo se aplican a las versiones del modelo que no usan un contenedor personalizado. Cuando usas un contenedor personalizado, los cuerpos de solicitudes y respuestas pueden adoptar cualquier formato.

Sin embargo, te recomendamos que diseñes tu servidor HTTP de acuerdo con los requisitos de solicitud y respuesta descritos en los vínculos anteriores. Si no lo haces, no hay garantía de que otras funciones de AI Platform Prediction, como el registro, la supervisión y AI Explanations funcionen de forma correcta.

Requisitos para la publicación de imágenes en contenedores

Debes enviar tu imagen de contenedor a Artifact Registry para usarla con AI Platform Prediction. 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

El repositorio debe usar una región que coincida con el extremo regional en el que planeas crear una versión del modelo. Por ejemplo, si planeas crear una versión del modelo en el extremo us-central1-ml.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

AI Platform Prediction debe tener permiso para extraer la imagen de contenedor cuando creas una versión del modelo. Específicamente, el servicio de AI Platform debe tener la permisos del rol de Lector de Artifact Registry (roles/artifactregistry.reader) para el repositorio de la imagen del contenedor.

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

Por otro lado, si enviaste la imagen de contenedor a un proyecto de Google Cloud desde el que uses AI Platform Prediction. Debes otorgar el rol de Lector de Artifact Registry para el servicio repositorio al Agente de servicio de AI Platform.

Accede a artefactos de modelo

Cuando creas una versión del modelo sin un contenedor personalizado, debes especificar el URI de un directorio de Cloud Storage con los artefactos del modelo como el campo deploymentUri Cuando creas una versión del modelo con un contenedor personalizado, es opcional proporcionar artefactos de modelo en Cloud Storage.

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 deploymentUri, el contenedor debe cargar estos artefactos cuando comience a ejecutarse. Cuando AI Platform Prediction 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 deploymentUri cuando creas la versión del modelo. En cambio, AIP_STORAGE_URI apunta a una copia del directorio de artefactos de modelo en un bucket de Cloud Storage diferente, que AI Platform Prediction administra. AI Platform Prediction propaga este directorio cuando creas una versión del modelo. No puedes actualizar el contenido del directorio. Si deseas usar artefactos de modelo nuevos, debes crear una versión de modelo nueva.

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 creas una versión del modelo, AI Platform Prediction otorga automáticamente a tu cuenta de servicio especificada la función del visualizador de objetos de almacenamiento (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.

Como el contenedor admite ADC para el agente de servicio de AI Platform (o una cuenta de servicio personalizada, si especificaste una), también puede acceder a cualquier otro servicio de Google Cloud cuya cuenta de servicio tenga los permisos para ello.

Variables de entorno disponibles en el contenedor

Cuando se ejecuta, el comando de entrypoint del contenedor puede hacer referencia a las variables de entorno que configuraste de forma manual, así como a las variables de entorno que configura AI Platform Prediction de forma automática. En esta sección, se describe cada método para configurar las variables de entorno y se proporcionan detalles sobre las variables que establece AI Platform Prediction automáticamente.

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 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 la versión del modelo.

Variables establecidas por AI Platform Prediction

Cuando AI Platform Prediction comienza a ejecutar el contenedor, configura 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 AI Platform Training y API de Prediction también pueden hacer referencia a estas variables, lee la referencia de la API para ContainerSpec.

Nombre de la variable Valor predeterminado Cómo configurar el valor Detalles
AIP_ACCELERATOR_TYPE Sin establecer Cuando crees una versión del modelo, configura el campo acceleratorConfig.type. 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_FRAMEWORK CUSTOM_CONTAINER No configurable
AIP_HEALTH_ROUTE /v1/models/MODEL/versions/VERSION

En esta string, reemplaza MODEL por el valor de la variable AIP_MODEL_NAME y reemplaza VERSION por el valor de la variable AIP_VERSION_NAME.		 Cuando crees una versión del modelo, configura el campo routes.health. Esta variable especifica la ruta HTTP en el contenedor al que AI Platform Prediction envía las verificaciones de estado.
AIP_HTTP_PORT 8080 Cuando crees una versión del modelo, configura el campo containerSpec.ports. La primera entrada de este campo se convierte en el valor de AIP_HTTP_PORT. AI Platform Prediction 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 crees una versión del modelo, configura el campo 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 se está ejecutando en AI Platform Prediction 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 y solo use ciertas rutas de código cuando se ejecute en AI Platform Prediction.
AIP_MODE_VERSION 1.0.0 No configurable Esta variable representa la versión de los requisitos de contenedores personalizados (este documento) que AI Platform Prediction espera que cumpla con el contenedor. Este documento se actualiza según el control de versiones semántico.
AIP_MODEL_NAME No hay una configuración predeterminada; se debe configurar Cuando creas un modelo (el elemento superior de la versión del modelo que usa el contenedor), especifica el campo name. El valor no incluye el prefijo projects/PROJECT_ID/models/ que la API de Platform Training y de Prediction produce en el resultado.
AIP_PREDICT_ROUTE /v1/models/MODEL/versions/VERSION:predict

En esta string, reemplaza MODEL por el valor de la variable AIP_MODEL_NAME y reemplaza VERSION por el valor de la variable AIP_VERSION_NAME.		 Cuando crees una versión del modelo, configura el campo routes.predict. Esta variable especifica la ruta de acceso HTTP en el contenedor al que AI Platform Prediction reenvía las solicitudes de predicción.
AIP_PROJECT_NUMBER El número del proyecto de Google Cloud en el que usas AI Platform Prediction No configurable
AIP_STORAGE_URI
  • Si no estableces el campo deploymentUri cuando creas una versión del modelo: una string vacía
  • Si estableces el campo deploymentUri cuando creas una versión del modelo: un URI de Cloud Storage (a partir de gs://), que especifica un directorio en un bucket administrado por AI Platform Prediction
 No configurable Esta variable especifica el directorio que contiene una copia de los artefactos de tu modelo, si corresponde.
AIP_VERSION_NAME No hay una configuración predeterminada; se debe configurar Cuando crees una versión del modelo, configura el campo name. El valor no incluye el prefijo projects/PROJECT_ID/models/MODEL/versions/ que la API de Platform Training y de Prediction produce en el resultado.

Variables establecidas en el recurso de versión

Cuando creas una versión del modelo, puedes configurar variables de entorno adicionales en el campo container.env.

El comando entrypoint del contenedor puede acceder a estas variables. Para saber qué campos de AI Platform Training y API de Prediction también pueden hacer referencia a estas variables, lee la referencia de la API para ContainerSpec.

¿Qué sigue?