Implementación y puntuación de un modelo de aprendizaje automático mediante un punto de conexión en línea

SE APLICA A:Extensión ML de la CLI de Azure v2 (actual)SDK de Python azure-ai-ml v2 (actual)

En este artículo, aprenderá a implementar el modelo en un punto de conexión en línea para usarlo en inferencia en tiempo real. Comenzará por implementar un modelo en la máquina local para depurar los errores. A continuación, implementará y probará el modelo en Azure. También aprenderá a ver los registros de implementación y a supervisar el Acuerdo de Nivel de Servicio (SLA). Al final de este artículo, tendrá un punto de conexión HTTPS/REST escalable que puede usar para la inferencia en tiempo real.

Los puntos de conexión en línea son puntos de conexión que se usan para las inferencias en tiempo real. Hay dos tipos de puntos de conexión en línea: puntos de conexión en línea administrados y puntos de conexión en línea de Kubernetes. Para más información sobre los puntos de conexión y las diferencias entre los puntos de conexión en línea administrados y los puntos de conexión en línea de Kubernetes, consulte ¿Qué son los puntos de conexión de Azure Machine Learning?.

Los puntos de conexión en línea administrados ayudan a implementar los modelos de ML de forma inmediata. Los puntos de conexión en línea administrados funcionan con máquinas eficaces de CPU y GPU en Azure de una manera escalable y totalmente administrada. Los puntos de conexión en línea administrados se encargan de atender, escalar, proteger y supervisar los modelos, lo que le libera de la sobrecarga de configurar y administrar la infraestructura subyacente.

En el ejemplo principal de este documento se usan puntos de conexión en línea administrados para la implementación. Para usar Kubernetes en su lugar, consulte las notas de este documento insertadas en la explicación de los puntos de conexión en línea administrados.

Requisitos previos

SE APLICA A:Extensión de ML de la CLI de Azure v2 (actual)

Antes de seguir los pasos de este artículo, asegúrese de que tiene los siguientes requisitos previos:

  • Los controles de acceso basado en rol de Azure (RBAC de Azure) se usan para conceder acceso a las operaciones en Azure Machine Learning. Para realizar los pasos descritos en este artículo, la cuenta de usuario debe tener asignado el rol de propietario o colaborador para el área de trabajo de Azure Machine Learning, o un rol personalizado que permita Microsoft.MachineLearningServices/workspaces/onlineEndpoints/*. Si usa Studio para crear o administrar puntos de conexión o implementaciones en línea, necesitará un permiso adicional "Microsoft.Resources/deployments/write" del propietario del grupo de recursos. Para obtener más información, consulte Administración del acceso a un área de trabajo de Azure Machine Learning.

  • (Opcional) Para implementar localmente, debe instalar el motor de Docker en el equipo local. Se recomienda esta opción, para que sea más sencillo depurar los problemas.

Asignación de la cuota de máquina virtual para la implementación

En el caso de los puntos de conexión en línea administrados, Azure Machine Learning reserva el 20 % de los recursos de proceso para realizar actualizaciones en algunas SKU de máquina virtual. Si solicita un número determinado de instancias en una implementación, debe tener una cuota para ceil(1.2 * number of instances requested for deployment) * number of cores for the VM SKU disponible para evitar errores. Por ejemplo, si solicita 10 instancias de una máquina virtual Standard_DS3_v2 (que viene con 4 núcleos) en una implementación, debería tener disponible una cuota de 48 núcleos (12 instances * 4 cores). Para ver el uso y los aumentos de cuota de solicitud, consulte Ver el uso y las cuotas en Azure Portal.

Hay determinadas SKU de máquina virtual que están exentas de la reserva de cuota adicional. Para ver la lista completa, consulte Lista de SKU de puntos de conexión en línea administrados.

Azure Machine Learning proporciona un grupo de cuota compartida desde el que todos los usuarios pueden acceder a la cuota para realizar pruebas durante un tiempo limitado. Cuando se usa studio para implementar modelos Llama-2, Phi, Nemotron, Mistral, Dolly y Deci-Deci-DeciLM desde el catálogo de modelos en un punto de conexión en línea administrado, Azure Machine Learning le permite acceder a esta cuota compartida durante un breve tiempo.

Para obtener más información sobre cómo usar la cuota compartida para la implementación de puntos de conexión en línea, consulte Implementación de modelos básicos mediante Studio.

Preparación del sistema

Establecimiento de variables de entorno

Si aún no ha establecido los valores predeterminados de la CLI de Azure, guarde la configuración predeterminada. Para evitar pasar los valores de la suscripción, el área de trabajo y el grupo de recursos varias veces, ejecute este código:

az account set --subscription <subscription ID>
az configure --defaults workspace=<Azure Machine Learning workspace name> group=<resource group>

Clone el repositorio de ejemplos

Para seguir este artículo, primero clone el repositorio de ejemplos (azureml-examples). A continuación, ejecute el código siguiente para ir al directorio cli/ del repositorio:

git clone --depth 1 https://github.com/Azure/azureml-examples
cd azureml-examples
cd cli

Sugerencia

Use --depth 1 para clonar solamente la confirmación más reciente en el repositorio, lo cual reduce el tiempo para completar la operación.

Los comandos de este tutorial están en los archivos deploy-local-endpoint.sh y deploy-managed-online-endpoint.sh en el directorio cli, y los archivos de configuración YAML se encuentran en el subdirectorio endpoints/online/managed/sample/.

Nota

Los archivos de configuración de YAML para los puntos de conexión en línea de Kubernetes están en el endpoints/online/kubernetes/ subdirectorio.

Definición del punto de conexión

Para definir un punto de conexión, deberá especificar:

  • Nombre del punto de conexión: Nombre del punto de conexión. El valor debe ser único dentro de la región de Azure. Para más información acerca de las reglas de nomenclatura, consulte límites del punto de conexión.
  • Modo de autenticación: método de autenticación del punto de conexión. Elija entre la autenticación basada en claves y la autenticación basada en tokens de Azure Machine Learning. Una clave no expira, pero un token sí. Para más información sobre la autenticación, consulte Autenticación en un punto de conexión en línea.
  • Opcionalmente, puede agregar una descripción y etiquetas al punto de conexión.

Establecimiento de un nombre de punto de conexión

Para establecer el nombre de punto de conexión, ejecute el siguiente comando (reemplace YOUR_ENDPOINT_NAME por un nombre único).

Para Linux, ejecute este comando:

export ENDPOINT_NAME="<YOUR_ENDPOINT_NAME>"

Configuración del punto de conexión

El siguiente fragmento de código muestra el archivo endpoints/online/managed/sample/endpoint.yml:

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-endpoint
auth_mode: key

La referencia para el formato YAML del punto de conexión se describe en la tabla siguiente. Para aprender a especificar estos atributos, consulte la referencia de YAML de puntos de conexión en línea. Para obtener información sobre los límites relacionados con los puntos de conexión administrados, consulte límites para los puntos de conexión en línea.

Clave Descripción
$schema (Opcional) El esquema de YAML. Para ver todas las opciones disponibles en el archivo YAML, puede ver el esquema del fragmento de código anterior en un explorador.
name Nombre del punto de conexión.
auth_mode Use key para la autenticación basada en claves. Use aml_token para la autenticación basada en tokens de Azure Machine Learning. Para obtener el token más reciente, use el comando az ml online-endpoint get-credentials.

Definir la implementación

Una implementación es un conjunto de recursos necesarios para hospedar el modelo que realiza la inferencia real. Para implementar un modelo debe tener:

  • Archivos de modelo (o el nombre y la versión de un modelo ya registrado en el área de trabajo). En el ejemplo, tenemos un modelo scikit-learn que realiza la regresión.
  • Un script de puntuación, es decir,el código que ejecuta el modelo en una solicitud de entrada determinada. El script de puntuación recibe los datos enviados a un servicio web implementado y los pasa al modelo. A continuación, el script ejecuta el modelo y devuelve su respuesta al cliente. El script de puntuación es específico para el modelo y debe entender los datos que el modelo espera como entrada y devuelve como salida. En este ejemplo, tenemos un archivo score-py.
  • Entorno en el que se ejecuta el modelo. El entorno puede ser una imagen de Docker con dependencias de Conda o un archivo Dockerfile.
  • Configuración para especificar el tipo de instancia y la capacidad de escalado.

En la tabla siguiente, se describen los atributos clave de una implementación:

Atributo Description
Nombre Nombre de la implementación.
El nombre del punto de conexión El nombre del punto de conexión en el que se creará la implementación.
Modelo Modelo que se usará para la implementación. Este valor puede ser una referencia a un modelo con versiones existente en el área de trabajo o una especificación de modelo en línea.
Ruta de acceso al código Ruta de acceso al directorio en el entorno de desarrollo local que contiene todo el código fuente de Python para puntuar el modelo. Puede usar directorios y paquetes anidados.
Script de puntuación La ruta de acceso relativa al archivo de puntuación en el directorio de código fuente. Este código de Python debe tener una función init() y una función run(). Se llamará a la función init() después de crear o actualizar el modelo (puede usarla para copiar en caché el modelo en la memoria, por ejemplo). Se llama a la función run() en cada invocación del punto de conexión para realizar la puntuación o predicción reales.
Entorno Entorno para hospedar el modelo y el código. Este valor puede ser una referencia a un entorno con versiones existente en el área de trabajo o una especificación de entorno en línea.
Tipo de instancia Tamaño de máquina virtual que se usará para la implementación. Para la lista de tamaños admitidos, consulte Lista de SKU de puntos de conexión en línea administrados.
Recuento de instancias El número de instancias que se usarán para la implementación. Base el valor en la carga de trabajo esperada. Para lograr alta disponibilidad, se recomienda establecer el valor en al menos 3. Reservamos un 20 % adicional para realizar actualizaciones. Para más información, consulte Asignación de la cuota de máquina virtual para la implementación.

Nota:

  • La implementación puede volver a hacer referencia a la imagen de modelo y contenedor (tal como se define en Entorno) en cualquier momento cuando las instancias detrás de la implementación pasan por revisiones de seguridad u otras operaciones de recuperación. Si ha usado un modelo registrado o una imagen de contenedor en Azure Container Registry para la implementación y ha quitado el modelo o la imagen de contenedor, las implementaciones que dependen de estos recursos pueden producir un error al volver a crear la imagen. Si ha quitado el modelo o la imagen de contenedor, asegúrese de que las implementaciones dependientes se vuelven a crear o actualizar con una imagen de contenedor o modelo alternativo.
  • El registro de contenedor al que hace referencia el entorno solo puede ser privado si la identidad del punto de conexión tiene permiso para acceder a él a través de la autenticación de Microsoft Entra y RBAC de Azure. Por el mismo motivo, no se admiten registros privados de Docker distintos de Azure Container Registry.

Configuración de una implementación

El fragmento de código siguiente muestra el archivo endpoints/online/managed/sample/blue-deployment.yml con todas las entradas necesarias para configurar una implementación:

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: my-endpoint
model:
  path: ../../model-1/model/
code_configuration:
  code: ../../model-1/onlinescoring/
  scoring_script: score.py
environment: 
  conda_file: ../../model-1/environment/conda.yaml
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
instance_type: Standard_DS3_v2
instance_count: 1

Nota:

En el archivo blue-deployment.yml, hemos especificado los siguientes atributos de implementación:

  • model - En este ejemplo, se especifican las propiedades del modelo en línea mediante el path. Los archivos de modelo se cargan y se registran de manera automática con un nombre generado automáticamente.
  • environment - En este ejemplo, hay definiciones insertadas que incluyen path. Usaremos environment.docker.image para la imagen. Las dependencias conda_file se instalarán encima de la imagen.

Durante la implementación, los archivos locales, como el origen de Python para el modelo de puntuación, se cargan desde el entorno de desarrollo.

Para más información sobre el esquema de YAML, consulte la referencia de YAML del punto de conexión en línea.

Nota:

Para usar Kubernetes en lugar de puntos de conexión administrados como destino de proceso:

  1. Cree el clúster de Kubernetes y asócielo como destino de proceso al área de Azure Machine Learning mediante Estudio de Azure Machine Learning.
  2. Utilice el archivo YAML de punto de conexión para usar Kubernetes como destino en lugar del archivo YAML del punto de conexión administrado. Tendrá que editar el archivo YAML para cambiar el valor de target por el nombre del destino de proceso registrado. Puede usar este archivo deployment.yaml que tiene propiedades adicionales aplicables a la implementación de Kubernetes.

Todos los comandos que se usan en este artículo (excepto la supervisión opcional del Acuerdo de Nivel de Servicio y la integración de Azure Log Analytics) se pueden usar con puntos de conexión administrados o con puntos de conexión de Kubernetes.

Registro del modelo y el entorno por separado

En este ejemplo se especifica path (desde donde cargar archivos) insertado. La CLI carga automáticamente los archivos y registra el modelo y el entorno. Como procedimiento recomendado en producción, debe registrar el modelo y el entorno y especificar el nombre y la versión registrados por separado en el archivo YAML. Utilice el formulario model: azureml:my-model:1 o environment: azureml:my-env:1.

Para el registro, puede extraer las definiciones de YAML de model y environment en archivos YAML diferentes y usar los comandos az ml model create y az ml environment create. Para más información sobre estos comandos, ejecute az ml model create -h y az ml environment create -h.

Para más información sobre cómo registrar el modelo como un recurso, consulte Registro del modelo como recurso en Machine Learning mediante la CLI. Para más información sobre cómo crear un entorno, consulte Administración de entornos de Azure Machine Learning con la CLI y el SDK (v2).

Uso de diferentes tipos de instancia de CPU y GPU e imágenes

La definición anterior del archivo blue-deployment.yml usa una instancia de tipo Standard_DS3_v2 de uso general y una imagen mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest de Docker que no es de GPU. Para el proceso de GPU, elija una SKU de tipo de proceso de GPU y una imagen de Docker de GPU.

Para ver los tipos de instancia de GPU y de uso general admitidos, consulte Las SKU de máquina virtual compatibles con los puntos de conexión en línea administrados. Para obtener una lista de las imágenes base de GPU y CPU de Azure Machine Learning, consulte las imágenes base de Azure Machine Learning.

Nota:

Para usar Kubernetes en lugar de puntos de conexión administrados como destino de proceso, consulte Introducción al destino de proceso de Kubernetes.

Identificar la ruta de acceso del modelo con respecto a AZUREML_MODEL_DIR

Al implementar el modelo en Azure Machine Learning, debe especificar la ubicación del modelo que desea implementar como parte de la configuración de implementación. En Azure Machine Learning, se realiza un seguimiento de la ruta de acceso al modelo con la variable de entorno AZUREML_MODEL_DIR. Al identificar la ruta de acceso del modelo con respecto a AZUREML_MODEL_DIR, puede implementar uno o varios modelos que se almacenan localmente en la máquina o implementar un modelo registrado en el área de trabajo de Azure Machine Learning.

Por ejemplo, la siguiente estructura de carpetas local sirve de referencia para los dos primeros casos en los que se implementa un único modelo o se implementan varios modelos almacenados localmente:

A screenshot showing a folder structure containing multiple models.

Usar un único modelo local en una implementación

Para usar un único modelo que tenga en la máquina local en una implementación, especifique el path al model en el YAML de implementación. Este es un ejemplo de YAML de implementación con la ruta de acceso /Downloads/multi-models-sample/models/model_1/v1/sample_m1.pkl:

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json 
name: blue 
endpoint_name: my-endpoint 
model: 
  path: /Downloads/multi-models-sample/models/model_1/v1/sample_m1.pkl 
code_configuration: 
  code: ../../model-1/onlinescoring/ 
  scoring_script: score.py 
environment:  
  conda_file: ../../model-1/environment/conda.yml 
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest 
instance_type: Standard_DS3_v2 
instance_count: 1 

Después de crear la implementación, la variable de entorno AZUREML_MODEL_DIR apuntará a la ubicación de almacenamiento dentro de Azure donde se almacena el modelo. Por ejemplo, /var/azureml-app/azureml-models/81b3c48bbf62360c7edbbe9b280b9025/1 contendrá el modelo sample_m1.pkl.

En el script de puntuación (score.py), puede cargar el modelo (en este ejemplo, sample_m1.pkl) en la función init():

def init(): 
    model_path = os.path.join(str(os.getenv("AZUREML_MODEL_DIR")), "sample_m1.pkl") 
    model = joblib.load(model_path) 

Usar varios modelos locales en una implementación

Aunque la CLI de Azure, el SDK de Python y otras herramientas de cliente permiten especificar solo un modelo por implementación en la definición de la implementación, puede seguir usando varios modelos en una implementación registrando una carpeta de modelos que contenga todos los modelos como archivos o subdirectorios.

En la estructura de carpetas de ejemplo anterior, observará que hay varios modelos en la carpeta models. En el YAML de implementación, puede especificar la ruta de acceso a la carpeta models de la siguiente manera:

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json 
name: blue 
endpoint_name: my-endpoint 
model: 
  path: /Downloads/multi-models-sample/models/ 
code_configuration: 
  code: ../../model-1/onlinescoring/ 
  scoring_script: score.py 
environment:  
  conda_file: ../../model-1/environment/conda.yml 
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest 
instance_type: Standard_DS3_v2 
instance_count: 1 

Después de crear la implementación, la variable de entorno AZUREML_MODEL_DIR apuntará a la ubicación de almacenamiento dentro de Azure donde se almacenan los modelos. Por ejemplo, /var/azureml-app/azureml-models/81b3c48bbf62360c7edbbe9b280b9025/1 contendrá los modelos y la estructura de archivos.

En este ejemplo, el contenido de la carpeta AZUREML_MODEL_DIR tendrá este aspecto:

A screenshot of the folder structure of the storage location for multiple models.

En el script de puntuación (score.py), puede cargar los modelos en la función init(). El código siguiente carga el modelo sample_m1.pkl:

def init(): 
    model_path = os.path.join(str(os.getenv("AZUREML_MODEL_DIR")), "models","model_1","v1", "sample_m1.pkl ") 
    model = joblib.load(model_path) 

Para ver un ejemplo de cómo implementar varios modelos en una implementación, consulte Implementación de varios modelos en una implementación (ejemplo de la CLI) e Implementación de varios modelos en una implementación (ejemplo del SDK).

Sugerencia

Si tiene más de 1500 archivos para registrar, considere la posibilidad de comprimir los archivos o subdirectorios como .tar.gz al registrar el modelo. Para consumir los modelos, puede descomprimir los archivos o subdirectorios de la función init() del script de puntuación. Como alternativa, al registrar los modelos, establezca la propiedad azureml.unpack en True, para descomprimir automáticamente los archivos o subdirectorios. En cualquier caso, la descompresión se produce una vez en la fase de inicialización.

Usar modelos registrados en el área de trabajo de Azure Machine Learning en una implementación

Para usar uno o varios modelos, que se registran en el área de trabajo de Azure Machine Learning, en la implementación, especifique el nombre de los modelos registrados en el YAML de implementación. Por ejemplo, la siguiente configuración de YAML de implementación especifica el nombre registrado model como azureml:local-multimodel:3:

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json 
name: blue 
endpoint_name: my-endpoint 
model: azureml:local-multimodel:3 
code_configuration: 
  code: ../../model-1/onlinescoring/ 
  scoring_script: score.py 
environment:  
  conda_file: ../../model-1/environment/conda.yml 
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest 
instance_type: Standard_DS3_v2 
instance_count: 1 

Para este ejemplo, considere que local-multimodel:3 contiene los siguientes artefactos de modelo, que se pueden ver desde la pestaña Modelos en el Estudio de Azure Machine Learning:

A screenshot of the folder structure showing the model artifacts of the registered model.

Después de crear la implementación, la variable de entorno AZUREML_MODEL_DIR apuntará a la ubicación de almacenamiento dentro de Azure donde se almacenan los modelos. Por ejemplo, /var/azureml-app/azureml-models/local-multimodel/3 contendrá los modelos y la estructura de archivos. AZUREML_MODEL_DIR apuntará a la carpeta que contiene la raíz de los artefactos del modelo. En función de este ejemplo, el contenido de la carpeta AZUREML_MODEL_DIR tendrá este aspecto:

A screenshot of the folder structure showing multiple models.

En el script de puntuación (score.py), puede cargar los modelos en la función init(). Por ejemplo, cargue el modelo diabetes.sav:

def init(): 
    model_path = os.path.join(str(os.getenv("AZUREML_MODEL_DIR"), "models", "diabetes", "1", "diabetes.sav") 
    model = joblib.load(model_path) 

Descripción del script de puntuación

Sugerencia

El formato del script de puntuación para los puntos de conexión en línea es el mismo que se usaba en la versión anterior de la CLI y en el SDK de Python.

Como se ha indicado antes, el script de puntuación especificado en code_configuration.scoring_script debe tener una función init() y una función run().

En este ejemplo se usa el archivo score.py: score.py

import os
import logging
import json
import numpy
import joblib


def init():
    """
    This function is called when the container is initialized/started, typically after create/update of the deployment.
    You can write the logic here to perform init operations like caching the model in memory
    """
    global model
    # AZUREML_MODEL_DIR is an environment variable created during deployment.
    # It is the path to the model folder (./azureml-models/$MODEL_NAME/$VERSION)
    # Please provide your model's folder name if there is one
    model_path = os.path.join(
        os.getenv("AZUREML_MODEL_DIR"), "model/sklearn_regression_model.pkl"
    )
    # deserialize the model file back into a sklearn model
    model = joblib.load(model_path)
    logging.info("Init complete")


def run(raw_data):
    """
    This function is called for every invocation of the endpoint to perform the actual scoring/prediction.
    In the example we extract the data from the json input and call the scikit-learn model's predict()
    method and return the result back
    """
    logging.info("model 1: request received")
    data = json.loads(raw_data)["data"]
    data = numpy.array(data)
    result = model.predict(data)
    logging.info("Request processed")
    return result.tolist()

Se llama a la función init() cuando se inicializa o se inicia el contenedor. La inicialización suele producirse poco después de crear o actualizar la implementación. La función init es el lugar para escribir la lógica para realizar operaciones de inicialización globales, como almacenar en caché el modelo en memoria (como se hace en este ejemplo).

Se llama a la función run() en cada invocación del punto de conexión y realiza la puntuación y predicción reales. En este ejemplo, extraeremos los datos de una entrada JSON, llamaremos al método predict() del modelo scikit-learn y devolveremos el resultado.

Implementación y depuración locales mediante puntos de conexión locales

Se recomienda encarecidamente que ejecute el punto de conexión localmente mediante la validación y depuración del código y la configuración antes de implementarlo en Azure. La CLI de Azure y el SDK de Python admiten puntos de conexión e implementaciones locales, mientras que las plantillas de ARM y Estudio de Azure Machine Learning, no.

Para realizar la implementación localmente, deberá tener instalado y ejecutándose el motor de Docker. Este motor normalmente se inicia cuando se inicia el equipo. Si no lo hace, puede solucionar el problema aquí.

Sugerencia

Puede usar el paquete de Python del servidor HTTP de inferencia de Azure Machine Learning para depurar el script de puntuación localmente sin Docker Engine. La depuración con el servidor de inferencia le ayuda a depurar el script de puntuación antes de implementar en los puntos de conexión locales para que pueda depurar sin verse afectado por las configuraciones del contenedor de implementación.

Nota:

Los puntos de conexión locales tienen las siguientes limitaciones:

  • No admiten reglas de tráfico, autenticación ni configuración de sondeo.
  • Solo admiten una implementación por punto de conexión.
  • Admiten archivos de modelo locales y entorno solo con el archivo conda local. Si quiere probar los modelos registrados, primero descárguelos mediante la CLI o el SDK y, después, use path en la definición de implementación para hacer referencia a la carpeta primaria. Si quiere probar entornos registrados, compruebe el contexto del entorno en Estudio de Azure Machine Learning y prepare el archivo conda local para usarlo. En el ejemplo de este artículo se muestra cómo usar el modelo local y el entorno con el archivo conda local, que admite la implementación local.

Para obtener más información sobre cómo depurar puntos de conexión en línea localmente antes de implementarlos en Azure, consulte Depuración de puntos de conexión en línea localmente en Visual Studio Code.

Implementación del modelo localmente

En primer lugar, cree un punto de conexión. Opcionalmente, en el caso de un punto de conexión local, puede omitir este paso y crear directamente la implementación (paso siguiente), lo que, a su vez, crea los metadatos necesarios. La implementación de modelos localmente es útil para fines de desarrollo y pruebas.

az ml online-endpoint create --local -n $ENDPOINT_NAME -f endpoints/online/managed/sample/endpoint.yml

Ahora cree una implementación de nombre blue en el punto de conexión.

az ml online-deployment create --local -n blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml

La marca --local indica a la CLI que implemente el punto de conexión en el entorno de Docker.

Sugerencia

Use Visual Studio Code para probar y depurar los puntos de conexión localmente. Para más información, consulte Depuración local de puntos de conexión en línea en Visual Studio Code.

Comprobación de que la implementación local se ha realizado correctamente

Compruebe el estado para ver si el modelo se ha implementado sin errores:

az ml online-endpoint show -n $ENDPOINT_NAME --local

La salida debe tener un aspecto similar al del siguiente JSON. El valor de provisioning_state es Succeeded.

{
  "auth_mode": "key",
  "location": "local",
  "name": "docs-endpoint",
  "properties": {},
  "provisioning_state": "Succeeded",
  "scoring_uri": "http://localhost:49158/score",
  "tags": {},
  "traffic": {}
}

La tabla siguiente contiene los posibles valores para provisioning_state:

State Descripción
Creating Se está creando el recurso.
Actualizando Se está actualizando el recurso.
Eliminando Se está eliminando el recurso.
Correcto La operación de creación y actualización se realizó correctamente.
Erróneo Error en la operación de creación, actualización y eliminación.

Invocación del punto de conexión local para puntuar los datos con el modelo

Invoque el punto de conexión para puntuar el modelo usando el práctico comando invoke y pasando los parámetros de consulta almacenados en un archivo JSON:

az ml online-endpoint invoke --local --name $ENDPOINT_NAME --request-file endpoints/online/model-1/sample-request.json

Si desea usar un cliente REST (como curl), debe tener el URI de puntuación. Para obtener el identificador URI de puntuación, ejecute az ml online-endpoint show --local -n $ENDPOINT_NAME. En los datos devueltos, busque el atributo scoring_uri. Los comandos de ejemplo basados en curl están disponibles más adelante en este documento.

Revisión de los registros para obtener la salida de la operación de invocación

En el archivo score.py de ejemplo, el método run() registra alguna salida en la consola.

Puede ver esta salida usando el comando get-logs:

az ml online-deployment get-logs --local -n blue --endpoint $ENDPOINT_NAME

Implementación del punto de conexión en línea en Azure

A continuación, implemente el punto de conexión en línea en Azure.

Implementar en Azure

Para crear el punto de conexión en la nube, ejecute el código siguiente:

az ml online-endpoint create --name $ENDPOINT_NAME -f endpoints/online/managed/sample/endpoint.yml

Para crear la implementación de nombre blue en el punto de conexión, ejecute el código siguiente:

az ml online-deployment create --name blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml --all-traffic

Esta implementación puede tardar un máximo de 15 minutos, dependiendo de si es la primera vez que se crean el entorno o la imagen subyacentes. Las implementaciones posteriores que usan el mismo entorno terminarán de procesarse más rápidamente.

Sugerencia

  • Si prefiere no bloquear la consola de la CLI, puede agregar la marca --no-wait al comando. Sin embargo, se detendrá la presentación interactiva del estado de implementación.

Importante

La marca --all-traffic del elemento az ml online-deployment create anterior asigna el 100 % del tráfico del punto de conexión a la implementación azul creada recientemente. Aunque esto es útil para fines de desarrollo y prueba, en producción es posible que quiera abrir el tráfico a la nueva implementación mediante un comando explícito. Por ejemplo, az ml online-endpoint update -n $ENDPOINT_NAME --traffic "blue=100".

Comprobación del estado del punto de conexión

El comando show contiene información de provisioning_state tanto para el punto de conexión como para la implementación:

az ml online-endpoint show -n $ENDPOINT_NAME

Puede enumerar todos los puntos de conexión del área de trabajo en un formato de tabla con el comando list:

az ml online-endpoint list --output table

Comprobación del estado de la implementación en línea

Compruebe los registros para ver si el modelo se implementó sin errores.

Para ver la salida del registro de un contenedor, use el siguiente comando de la CLI:

az ml online-deployment get-logs --name blue --endpoint $ENDPOINT_NAME

De forma predeterminada, los registros se extraen del contenedor del servidor de inferencia. Para ver los registros del contenedor del inicializador de almacenamiento, agregue la marca --container storage-initializer. Para más información sobre los registros de implementación, consulte Obtención de registros de contenedor.

Invocación del punto de conexión para puntuar los datos con el modelo

Puede usar el comando invoke o un cliente REST de su elección para invocar el punto de conexión y puntuar algunos datos:

az ml online-endpoint invoke --name $ENDPOINT_NAME --request-file endpoints/online/model-1/sample-request.json

En el ejemplo siguiente se muestra cómo obtener la clave usada para autenticarse en el punto de conexión:

Sugerencia

Puede controlar qué entidades de seguridad de Microsoft Entra pueden obtener la clave de autenticación mediante su asignación a un rol personalizado que permita Microsoft.MachineLearningServices/workspaces/onlineEndpoints/token/action y Microsoft.MachineLearningServices/workspaces/onlineEndpoints/listkeys/action. Para obtener más información, consulte Administración del acceso a un área de trabajo de Azure Machine Learning.

ENDPOINT_KEY=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -o tsv --query primaryKey)

Luego use curl para puntuar los datos.

SCORING_URI=$(az ml online-endpoint show -n $ENDPOINT_NAME -o tsv --query scoring_uri)

curl --request POST "$SCORING_URI" --header "Authorization: Bearer $ENDPOINT_KEY" --header 'Content-Type: application/json' --data @endpoints/online/model-1/sample-request.json

Observe que se usan los comandos show y get-credentials para obtener las credenciales de autenticación. Observe también que se está usando la marca --query para filtrar los atributos a fin de obtener solo los necesarios. Puede encontrar más información sobre --query en Consulta de la salida del comando de la CLI de Azure.

Para ver los registros de invocación, vuelva a ejecutar get-logs.

Para obtener información sobre la autenticación mediante un token, consulte Autenticación en puntos de conexión en línea.

(Opcional) Actualización de la implementación

Si quiere actualizar el código, el modelo o el entorno, actualice el archivo YAML y ejecute el comando az ml online-endpoint update.

Nota

Si actualiza el recuento de instancias (para escalar la implementación) junto con otras configuraciones del modelo (como código, modelo o entorno) en un solo comando update: se realizará la operación de escalado en primer lugar y, luego, se aplicarán las demás actualizaciones. Se recomienda realizar estas operaciones por separado en un entorno de producción.

Para comprender cómo funciona update:

  1. Abra el archivo online/model-1/onlinescoring/score.py.

  2. Cambie la última línea de la función init(): después de logging.info("Init complete"), agregue logging.info("Updated successfully").

  3. Guarde el archivo.

  4. Ejecute este comando:

    az ml online-deployment update -n blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml
    

    Nota:

    La actualización mediante YAML es declarativa. Es decir, los cambios en el archivo YAML se reflejan en los recursos de Azure Resource Manager subyacentes (puntos de conexión e implementaciones). El enfoque declarativo facilita GitOps: Todos los cambios en los puntos de conexión o implementaciones (incluso instance_count) pasan por YAML.

    Sugerencia

    • Puede usar parámetros de actualización genéricos, como el parámetro --set, con el comando de la CLI update para invalidar atributos en YAML o para establecer atributos específicos sin pasarlos en el archivo YAML. El uso de --set para atributos únicos es especialmente valioso en escenarios de implementación y pruebas. Por ejemplo, para escalar verticalmente el valor de instance_count de la primera implementación, podría usar la marca --set instance_count=2. Sin embargo, como YAML no está actualizado, esta técnica no facilita GitOps.
    • La especificación del archivo YAML NO es obligatoria. Por ejemplo, si deseara probar una configuración de simultaneidad diferente para una implementación determinada, podría probar algo parecido a az ml online-deployment update -n blue -e my-endpoint --set request_settings.max_concurrent_requests_per_instance=4 environment_variables.WORKER_COUNT=4. Esto mantendrá toda la configuración existente, pero actualizará solo los parámetros especificados.
  5. Dado que ha modificado la función init(), que se ejecuta cuando se crea o actualiza el punto de conexión, el mensaje Updated successfully estará en los registros. Recupere los registros ejecutando:

    az ml online-deployment get-logs --name blue --endpoint $ENDPOINT_NAME
    

El comando update también funciona con implementaciones locales. Use el mismo comando az ml online-deployment update con la marca --local.

Nota

La actualización anterior a la implementación es un ejemplo de una actualización gradual local.

  • En el caso de un punto de conexión en línea administrado, la implementación se actualizará a la nueva configuración con un 20 % de nodos a la vez. Es decir, si la implementación tuviera diez nodos, se actualizarán dos nodos cada vez.
  • En el caso de un punto de conexión en línea de Kubernetes, el sistema creará en iteración una nueva instancia de implementación con la nueva configuración y eliminará la antigua.
  • Para uso de producción, debería considerar la implementación azul-verde, que ofrece una alternativa más segura para actualizar un servicio web.

(Opcional) Configuración de la escalabilidad automática

La escalabilidad automática ejecuta automáticamente la cantidad adecuada de recursos para controlar la carga en la aplicación. Los puntos de conexión administrados en línea admiten la escalabilidad automática mediante la integración con la característica de escalabilidad automática de Azure Monitor. Para configurar la escalabilidad automática, vea Escalabilidad automática de puntos de conexión en línea.

(Opcional) Supervisión del Acuerdo de Nivel de Servicio mediante Azure Monitor

Para ver las métricas y establecer alertas en función del Acuerdo de Nivel de Servicio, complete los pasos que se describen en Supervisión de puntos de conexión en línea.

(Opcional) Integración con Log Analytics

El comando get-logs para la CLI o el método get_logs para el SDK solo proporciona los últimos cientos de líneas de registros de una instancia seleccionada automáticamente. Sin embargo, Log Analytics proporciona una manera de almacenar y analizar los registros de forma duradera. Para más información sobre el uso del registro, consulte Supervisión de puntos de conexión en línea.

Eliminación del punto de conexión y la implementación

Si no va a usar la implementación, debe eliminarla mediante la ejecución del código siguiente (se elimina el punto de conexión y todas las implementaciones subyacentes):

az ml online-endpoint delete --name $ENDPOINT_NAME --yes --no-wait