Requisitos de los contenedores personalizados para la inferencia

Para ver un ejemplo de cómo usar un contenedor personalizado, ejecuta el notebook "Vertex AI Inference: Deploying Iris-detection model using FastAPI and custom container serving" en uno de los siguientes entornos:

Abrir en Colab | Abrir en Colab Enterprise | Abrir en Agent Platform 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 inferencias desde un modelo entrenado de forma personalizada, debes proporcionar a Gemini Enterprise Agent Platform 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 Gemini Enterprise Agent Platform. En el documento, también se describe cómo interactúa la plataforma de agentes 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 usarla con Agent Platform.

Para obtener instrucciones sobre cómo usar una imagen de contenedor personalizada para entregar inferencias, consulta 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 inferencia. 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 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

Agent Platform 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, Agent Platform usa un sondeo de funcionamiento 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, Agent Platform 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

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, Agent Platform 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, Agent Platform 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, Agent Platform realiza verificaciones de estado de forma intermitente en tu servidor HTTP mientras se ejecuta para garantizar que esté listo para controlar solicitudes de inferencia. 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 inferencia, 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; Agent Platform lo ignora.

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

• Si el servidor no está listo para manejar las solicitudes de inferencia, 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, Agent Platform 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, Agent Platform dejará de dirigir el tráfico de inferencia al contenedor. (Si el recurso DeployedModel se escala para usar varios nodos de inferencia, Agent Platform enrutará las solicitudes de inferencia a otros contenedores en buen estado).

Agent Platform 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, marca ese contenedor como en buen estado y comienza 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 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 inferencia a un nodo durante un período para que el contenedor pueda realizar tareas de mantenimiento.

Solicitudes de inferencia

Existen dos patrones para configurar rutas al servidor de modelos. Uno definido por Gemini Enterprise Agent Platform (/predict) y el otro que permite la personalización completa para que puedas simplemente colocar el servidor de modelos que elijas (/invoke).

Ruta /predict definida por Vertex

Cuando un cliente envía una solicitud projects.locations.endpoints.predict a la API de Agent Platform, esta reenvía la solicitud como una solicitud HTTP POST a una ruta de inferencia 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 compartido, cada solicitud de inferencia debe ser de 1.5 MB o menos. El servidor HTTP debe aceptar solicitudes de inferencia 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 inferencia.

• PARAMETERS es un objeto JSON que contiene los parámetros que tu contenedor requiere para ayudar a entregar inferencias en las instancias. Agent Platform considera que el campo parameters es opcional, por lo que puedes diseñar tu contenedor para que lo requiera, usarlo solo cuando se proporcione o ignorarlo.

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 compartido, cada respuesta de inferencia debe ser de 1.5 MB o menos. El servidor HTTP debe enviar respuestas con cuerpos JSON que cumplan con el siguiente formato:

{
  "predictions": INFERENCES
}

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

Después de que tu servidor HTTP envía esta respuesta, Agent Platform agrega un campo deployedModelId a la respuesta antes de devolverla 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 inferencias sin procesar.

Rutas de inferencia personalizadas

Si el servidor de modelos implementa varias rutas de inferencia, se recomienda usar la API de invocación para acceder a varias rutas de inferencia. La API de Invoke se puede habilitar durante la carga del modelo configurando el campo Model.containerSpec.invokeRoutePrefix en "/*". Una vez implementada, se reenviará una solicitud HTTP a la ruta /invoke/foo/bar a la ruta /foo/bar del servidor de modelos. Para conocer los detalles, consulta Usa rutas personalizadas arbitrarias.

Requisitos para la publicación de imágenes de contenedor

Debes enviar tu imagen de contenedor a Artifact Registry para usarla con Agent Platform. Obtén información para enviar una imagen de contenedor a Artifact Registry.

En particular, la imagen de contenedor y el repositorio deben cumplir con los siguientes requisitos de ubicación, formato de URI y permisos.

Ubicación

Cuando usas Artifact Registry, el repositorio debe usar una región que coincida con el extremo de ubicación 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.

Formato del URI de imagen

Cuando crees un Model, especifica containerSpec.imageUri en uno de los siguientes formatos:

• Por resumen: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE@sha256:DIGEST
• Por etiqueta: LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE:TAG
• Sin una etiqueta o un resumen (el valor predeterminado es :latest): LOCATION-docker.pkg.dev/PROJECT_ID/REPOSITORY/IMAGE

No incluyas una etiqueta y un resumen en el mismo URI (por ejemplo, IMAGE:TAG@sha256:DIGEST). Agent Platform rechaza los URIs de imagen que combinan una etiqueta y un resumen durante la carga del modelo.

Permisos

Agent Platform debe tener permiso para extraer la imagen de contenedor cuando creas un Model. En particular, el agente de servicio de Agent Platform para tu proyecto debe tener los permisos del rol de lector de Artifact Registry (roles/artifactregistry.reader) para el repositorio de la imagen de contenedor.

Agent Platform usa el agente de servicio de Agent Platform 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 Agent Platform.

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

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

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. Agent Platform 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 inferencias, 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 Agent Platform 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 Agent Platform. Agent Platform 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 el Model en un Endpoint, Agent Platform otorga automáticamente a la cuenta de servicio especificada el rol de visualizador 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, la instrucción ENTRYPOINT del contenedor puede hacer referencia a las variables de entorno que configuraste manualmente, así como a las variables de entorno que configuró Agent Platform 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 Agent Platform.

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 Agent Platform

Cuando Agent Platform 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 Agent Platform 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 Agent Platform.

Nota: Agent Platform 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 de acceso HTTP en el contenedor a la que Agent Platform envía las 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.	Agent Platform envía verificaciones de actividad, verificaciones de estado y solicitudes de inferencia 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 indica que el contenedor se está ejecutando en Agent Platform para entregar inferencias 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 procesamiento, pero solo use ciertas rutas de acceso de código cuando se ejecute en Agent Platform.
AIP_MODE_VERSION	1.0.0	No configurable	Esta variable indica la versión de los requisitos del contenedor personalizado (este documento) que Agent Platform 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 de acceso HTTP en el contenedor a la que Agent Platform reenvía las solicitudes de inferencia.
AIP_PROJECT_NUMBER	Es el número de proyecto del proyecto de Google Cloud en el que usas Agent Platform.	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 Agent Platform	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 Agent Platform 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 Agent Platform.

¿Qué sigue?

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