Requisitos de los contenedores personalizados para la inferencia

Para usar un contenedor personalizado con el fin de servir inferencias de un modelo con entrenamiento personalizado, 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 ser compatible con Vertex AI. En el documento también se describe cómo interactúa Vertex AI con tu contenedor personalizado una vez que empieza a ejecutarse. En otras palabras, en este documento se describe lo que debes tener en cuenta al diseñar una imagen de contenedor para usarla con Vertex AI.

Para obtener información sobre cómo usar una imagen de contenedor personalizada para ofrecer inferencias, consulta Usar un contenedor personalizado.

Requisitos de las imágenes de contenedor

Cuando la imagen de contenedor Docker se ejecuta como un contenedor, este debe ejecutar un servidor HTTP. En concreto, el contenedor debe escuchar y responder a las comprobaciones de actividad, las comprobaciones de estado y las solicitudes de inferencia. En las siguientes subsecciones se describen estos requisitos en detalle.

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

Ejecutar el servidor HTTP

Puedes ejecutar un servidor HTTP con una ENTRYPOINT instrucción, una CMD instrucción o ambas en el archivo Dockerfile que uses para crear tu imagen de contenedor. Consulta información sobre la interacción entre CMD y ENTRYPOINT.

También puede especificar los campos containerSpec.command y containerSpec.args cuando cree el recurso Model para anular los valores ENTRYPOINT y CMD de la imagen del contenedor, respectivamente. Si especificas uno de estos campos, podrás usar una imagen de contenedor que, de lo contrario, no cumpliría los requisitos debido a que tiene una versión de ENTRYPOINT o CMD incompatible (o inexistente).

Sin embargo, independientemente del comando que elijas para que se ejecute el contenedor cuando se inicie, asegúrate de que la instrucción ENTRYPOINT se ejecute de forma indefinida. Por ejemplo, no ejecutes un comando que inicie un servidor HTTP en segundo plano y, a continuación, se cierre. Si lo haces, el contenedor se cerrará inmediatamente después de iniciarse.

Tu servidor HTTP debe recibir solicitudes en 0.0.0.0, en un puerto de tu elección. Cuando crees un Model, especifica este puerto en el campo containerSpec.ports. Para saber cómo puede acceder el contenedor a este valor, consulta la sección de este documento sobre la variable de entorno AIP_HTTP_PORT.

Comprobaciones de actividad

Vertex AI realiza una comprobación de actividad cuando se inicia el contenedor para asegurarse de que el servidor está en funcionamiento. Cuando despliegas un modelo con entrenamiento personalizado en un Endpoint recurso, Vertex AI usa una prueba de actividad TCP para intentar establecer una conexión TCP con tu contenedor en el puerto configurado. La sonda intenta establecer una conexión hasta 4 veces y espera 10 segundos después de cada fallo. Si la sonda sigue sin establecer una conexión en este punto, Vertex AI reinicia el contenedor.

Tu servidor HTTP no tiene que hacer nada especial para gestionar estas comprobaciones. Mientras esté escuchando solicitudes en el puerto configurado, la sonda de actividad podrá establecer una conexión.

Comprobaciones del estado

También puedes especificar startup_probe o health_probe.

La prueba de inicio comprueba si se ha iniciado la aplicación del contenedor. Si no se proporciona una sonda de inicio, no habrá ninguna y las comprobaciones de estado empezarán inmediatamente. Si se proporciona una sonda de inicio, las comprobaciones del estado no se realizan hasta que la sonda de inicio se completa correctamente.

Las aplicaciones antiguas que puedan requerir un tiempo de inicio adicional en su primera inicialización deben configurar una sonda de inicio. Por ejemplo, si la aplicación necesita copiar los artefactos del modelo de una fuente externa, se debe configurar una sonda de inicio para que devuelva un valor correcto cuando se complete la inicialización.

La comprobación de estado comprueba si un contenedor está listo para aceptar tráfico. Si no se proporciona una sonda de estado, Vertex AI usa las comprobaciones de estado predeterminadas, tal como se describe en Comprobaciones de estado predeterminadas.

Las aplicaciones antiguas que no devuelven 200 OK para indicar que el modelo se ha cargado y está listo para aceptar tráfico deben configurar una sonda de estado. Por ejemplo, una aplicación puede devolver 200 OK para indicar que la solicitud se ha realizado correctamente, aunque el estado de carga del modelo que se indica en el cuerpo de la respuesta sea que el modelo no se ha cargado y, por lo tanto, no esté listo para aceptar tráfico. En este caso, se debe configurar una sonda de estado para que devuelva un valor correcto solo cuando el modelo se haya cargado y esté listo para servir tráfico.

Para realizar una comprobación, Vertex AI ejecuta el comando exec especificado en el contenedor de destino. Si el comando se ejecuta correctamente, devuelve 0 y el contenedor se considera activo y en buen estado.

Comprobaciones del estado predeterminadas

De forma predeterminada, Vertex AI realiza comprobaciones de estado de forma intermitente en tu servidor HTTP mientras se está ejecutando para asegurarse de que está listo para gestionar solicitudes de inferencia. El servicio usa una sonda de estado para enviar solicitudes HTTP GET a una ruta de comprobación del estado configurable en tu servidor. Especifica esta ruta en el campo containerSpec.healthRoute cuando crees un Model. Para saber cómo puede acceder el contenedor a este valor, consulte 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 comprobación de estado de la siguiente manera:

• Si el servidor está listo para gestionar solicitudes de inferencia, responde a la solicitud de comprobación de estado en un plazo de 10 segundos con el código de estado 200 OK. El contenido del cuerpo de la respuesta no importa, ya que Vertex AI lo ignora.

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

• Si el servidor no está listo para gestionar solicitudes de inferencia, no respondas a la solicitud de comprobación del estado en un plazo de 10 segundos o responde con cualquier código de estado que no sea 200 OK. Por ejemplo, responde con el código de estado 503 Service Unavailable.

  Esta respuesta (o la falta de ella) significa que el servidor no está en buen estado.

Si la sonda de estado recibe una respuesta incorrecta de tu servidor (o no recibe ninguna respuesta en un plazo de 10 segundos), enviará hasta 3 comprobaciones de estado adicionales con intervalos de 10 segundos. Durante este periodo, Vertex AI sigue considerando que tu servidor está en buen estado. Si la sonda recibe una respuesta correcta a alguna de estas comprobaciones, vuelve inmediatamente a su programación intermitente de comprobaciones del estado. Sin embargo, si la sonda recibe 4 respuestas incorrectas consecutivas, Vertex AI dejará de enrutar el tráfico de inferencia al contenedor. Si el recurso DeployedModel se escala para usar varios nodos de inferencia, Vertex AI dirige las solicitudes de inferencia a otros contenedores en buen estado.

Vertex AI no reinicia el contenedor, sino que la sonda de comprobación del estado sigue enviando solicitudes de comprobación del estado intermitentes al servidor en mal estado. Si recibe una respuesta correcta, marca ese contenedor como correcto y vuelve a enrutar el tráfico de inferencia a él.

Orientación práctica

En algunos casos, es suficiente con que el servidor HTTP de tu contenedor responda siempre con el código de estado 200 OK a las comprobaciones de estado. Si tu contenedor carga recursos antes de iniciar el servidor, el contenedor no estará en buen estado durante el periodo de inicio y durante los periodos en los que falle el servidor HTTP. En el resto de los casos, responde como correcto.

Para una configuración más sofisticada, puede que quieras diseñar el servidor HTTP para que responda a las comprobaciones de estado con un estado incorrecto en determinados momentos. Por ejemplo, puede que quieras bloquear el tráfico de inferencia a un nodo durante un periodo para que el contenedor pueda realizar tareas de mantenimiento.

Solicitudes de inferencia

Hay dos patrones para configurar rutas al servidor del modelo. Una definida por Vertex AI (/predict) y otra que permite una personalización completa para que puedas usar el servidor de modelos que quieras (/invoke).

Ruta /predict definida en Vertex

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

Requisitos de la solicitud

Si el modelo se implementa en un endpoint público compartido, cada solicitud de inferencia debe tener un tamaño de 1,5 MB o menos. El servidor HTTP debe aceptar solicitudes de inferencia que tengan el encabezado HTTP Content-Type: application/json y cuerpos JSON con el siguiente formato:

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

En estas solicitudes:

• INSTANCES es una matriz de uno o varios valores JSON de cualquier tipo. Cada values representa una instancia para la que estás proporcionando una inferencia.

• PARAMETERS es un objeto JSON que contiene los parámetros que necesita tu contenedor para ofrecer inferencias sobre las instancias. Vertex AI considera que el campo parameters es opcional, por lo que puedes diseñar tu contenedor para que lo requiera, solo lo use cuando se proporcione o lo ignore.

Más información sobre los requisitos del cuerpo de la solicitud

Requisitos de respuesta

Si el modelo se implementa en un endpoint público compartido, cada respuesta de inferencia debe tener un tamaño de 1,5 MB o menos. El servidor HTTP debe enviar respuestas con cuerpos JSON que cumplan el siguiente formato:

{
  "predictions": INFERENCES
}

En estas respuestas, sustituye INFERENCES por una matriz de valores JSON que representen las inferencias que ha generado tu contenedor para cada uno de los INSTANCES de la solicitud correspondiente.

Después de que tu servidor HTTP envíe esta respuesta, Vertex AI añade un deployedModelId campo a la respuesta antes de devolverla al cliente. Este campo especifica qué DeployedModel de un Endpoint envía la respuesta. Más información sobre el formato del cuerpo de la respuesta

Rutas de inferencia personalizadas

Si el servidor de modelos implementa varias rutas de inferencia, se recomienda usar la API invoke para acceder a varias rutas de inferencia. La invocación de la API se puede habilitar durante la subida del modelo configurando el campo Model.containerSpec.invokeRoutePrefix como "/*". Una vez desplegada, una solicitud HTTP a la ruta /invoke/foo/bar se reenviará al modelo como la ruta /foo/bar del servidor. Para obtener más información, consulta el artículo sobre cómo usar rutas personalizadas arbitrarias.

Requisitos de publicación de imágenes de contenedor

Debes insertar tu imagen de contenedor en Artifact Registry para usarla con Vertex AI. Consulta cómo enviar una imagen de contenedor a Artifact Registry.

En concreto, debes enviar la imagen de contenedor a un repositorio que cumpla 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 endpoint de ubicación en el que quieras crear un Model. Por ejemplo, si tienes previsto crear un Model en el endpoint us-central1-aiplatform.googleapis.com, el nombre completo de tu imagen de contenedor debe empezar por us-central1-docker.pkg.dev/. No utilices un repositorio multirregional para tu imagen de contenedor.

Permisos

Vertex AI debe tener permiso para extraer la imagen del contenedor cuando crees un Model. En concreto, el agente de servicio de Vertex AI de tu proyecto debe tener los permisos del rol 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 de tu proyecto para interactuar con otros servicios. Google Cloud Esta cuenta de servicio tiene la dirección de correo service-PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com, donde PROJECT_NUMBER se sustituye por el número de proyecto de tu proyecto de Vertex AI.

Si has subido tu imagen de contenedor al mismo Google Cloud proyecto en el que estás usando Vertex AI, no tienes que configurar ningún permiso. Los permisos predeterminados concedidos al agente de servicio de Vertex AI son suficientes.

Por otro lado, si has insertado tu imagen de contenedor en unGoogle Cloud proyecto distinto de aquel en el que usas Vertex AI, debes conceder el rol Lector de Artifact Registry al agente de servicio de Vertex AI para el repositorio de Artifact Registry.

Permiso para acceder a artefactos de modelos.

Cuando creas un Model entrenado de forma personalizada sin un contenedor personalizado, debes especificar el URI de un directorio de Cloud Storage con artefactos del modelo como el artifactUri. Cuando creas un Model con un contenedor personalizado, puedes proporcionar artefactos de modelo en Cloud Storage.

Si la imagen de contenedor incluye los artefactos del modelo que necesitas para publicar inferencias, no es necesario cargar archivos de Cloud Storage. Sin embargo, si proporcionas artefactos de modelo especificando el campo artifactUri, el contenedor debe cargar estos artefactos cuando empiece a ejecutarse. Cuando Vertex AI inicia el contenedor, asigna a la variable de entorno AIP_STORAGE_URI un URI de Cloud Storage que empieza por 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 al crear el Model. En su lugar, AIP_STORAGE_URI apunta a una copia del directorio de artefactos de tu modelo en otro segmento de Cloud Storage, que gestiona Vertex AI. Vertex AI rellena este directorio cuando creas un Model. No puedes actualizar el contenido del directorio. Si quieres usar nuevos artefactos de modelo, debes crear un nuevo Model.

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 al implementar el Model en un Endpoint, Vertex AI concede automáticamente a la cuenta de servicio especificada el rol de lector de objetos de Storage (roles/storage.objectViewer) para el bucket de Cloud Storage del URI.

Usa cualquier biblioteca que admita credenciales de aplicación predeterminadas (ADC) para cargar los artefactos del modelo. No es necesario que configures la autenticación de forma explícita.

Variables de entorno disponibles en el contenedor

Durante la ejecución, la instrucción ENTRYPOINT del contenedor puede hacer referencia a las variables de entorno que hayas configurado manualmente, así como a las variables de entorno definidas automáticamente por Vertex AI. En esta sección se describe cada una de las formas en las que puedes definir variables de entorno y se proporcionan detalles sobre las variables que define automáticamente Vertex AI.

Variables definidas en la imagen del contenedor

Para definir variables de entorno en la imagen de contenedor al compilarla, usa la ENV instrucción de Docker. No definas ninguna variable de entorno que empiece por 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 definidas por Vertex AI

Cuando Vertex AI empieza a ejecutar el contenedor, define las siguientes variables de entorno en el entorno del contenedor. Cada variable empieza con el prefijo AIP_. No defina 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, consulta la referencia de la API de ModelContainerSpec.

Variables definidas en el recurso Model

Cuando creas un Model, puedes definir 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, consulta la referencia de la API de ModelContainerSpec.

Siguientes pasos

• Consulta más información sobre cómo publicar inferencias con un contenedor personalizado, incluido cómo especificar los campos de la API relacionados con el contenedor al importar un modelo.