Depuración de puntos de conexión en línea localmente en Visual Studio Code

Artículo
04/11/2024

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

Obtenga información sobre cómo usar el depurador de Microsoft Visual Studio Code para probar y depurar puntos de conexión en línea localmente antes de implementarlos en Azure.

Los puntos de conexión locales de Azure Machine Learning le ayudan a probar y depurar localmente el script de puntuación, la configuración del entorno, la configuración de código y el modelo de Machine Learning.

Importante

Esta característica actualmente está en su versión preliminar pública. Esta versión preliminar se ofrece sin un Acuerdo de Nivel de Servicio y no se recomienda para cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que tengan sus funcionalidades limitadas.

Para más información, consulte Términos de uso complementarios de las Versiones Preliminares de Microsoft Azure.

Depurar puntos de conexión localmente antes de implementarlos en la nube puede ayudarle a detectar antes errores en el código y en la configuración. Tiene distintas opciones para depurar puntos de conexión localmente con Visual Studio Code.

Servidor HTTP de inferencia de Azure Machine Learning
Punto de conexión local

Esta guía se centra en los puntos de conexión locales.

En la tabla siguiente encontrará información general sobre los escenarios que le ayudarán a elegir lo que le funcione mejor en su caso.

Escenario	Servidor HTTP de inferencia	Punto de conexión local
Actualización del entorno de Python local, sin recompilación de imágenes de Docker	Sí	No
Actualización del script de puntuación	Sí	Sí
Actualización de las configuraciones de implementación (implementación, entorno, código, modelo)	No	Sí
Integración del depurador de Visual Studio Code	Sí	Sí

En esta guía se da por supuesto que los siguientes elementos se han instalados localmente en el equipo.

Para obtener más información, vea la guía sobre cómo preparar el sistema para implementar puntos de conexión en línea.

Los ejemplos de este artículo se basan en ejemplos de código que se encuentran en el repositorio de GitHub azureml-examples. Para ejecutar los comandos de forma local sin tener que copiar/pegar YAML y otros archivos, clone el repositorio y luego cambie los directorios a azureml-examples/cli:

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

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 los comandos siguientes. Reemplace los parámetros siguientes por valores para su configuración específica:

Reemplace <subscription> con la identificación de su suscripción de Azure.
Reemplace <workspace> por el nombre del área de trabajo de Azure Machine Learning.
Reemplace <resource-group> por el grupo de recursos de Azure que contiene el área de trabajo.
Reemplace <location> por la región de Azure que contiene el área de trabajo.

az account set --subscription <subscription>
az configure --defaults workspace=<workspace> group=<resource-group> location=<location>

Sugerencia

Puede ver cuáles son los valores predeterminados actuales mediante el comando az configure -l.

SE APLICA A: SDK de Python azure-ai-ml v2 (actual)

En esta guía se da por supuesto que los siguientes elementos se han instalados localmente en el equipo.

Para obtener más información, vea la guía sobre cómo preparar el sistema para implementar puntos de conexión en línea.

Los ejemplos de este artículo se pueden encontrar en la instancia de Jupyter Notebook denominada Depurar los puntos de conexión en línea localmente en Visual Studio Code del repositorioazureml-examples. Para ejecutar el código localmente, clone el repositorio y, luego, cambie los directorios al directorio primario sdk/endpoints/online/managed del cuaderno.

git clone https://github.com/Azure/azureml-examples --depth 1
cd azureml-examples
cd sdk/python/endpoints/online/managed

Abra Jupyter Notebook e importe los módulos necesarios:

from azure.ai.ml import MLClient
from azure.ai.ml.entities import (
    ManagedOnlineEndpoint,
    ManagedOnlineDeployment,
    Model,
    CodeConfiguration,
    Environment,
)
from azure.identity import DefaultAzureCredential

Configure variables para el área de trabajo y el punto de conexión:

subscription_id = "<SUBSCRIPTION_ID>"
resource_group = "<RESOURCE_GROUP>"
workspace_name = "<AML_WORKSPACE_NAME>"

endpoint_name = "<ENDPOINT_NAME>"

Inicio del contenedor de desarrollo

CLI de Azure
Python

Los puntos de conexión locales de Azure Machine Learning usan contenedores de desarrollo de Docker y Visual Studio Code para compilar y configurar un entorno de depuración local. Con los contenedores de desarrollo, puede aprovechar las características de Visual Studio Code desde dentro de un contenedor de Docker. Para obtener más información sobre los contenedores de desarrollo, consulte Creación de un contenedor de desarrollo.

Para depurar puntos de conexión en línea localmente en Visual Studio Code, use la marca --vscode-debug al crear o actualizar una implementación en línea de Azure Machine Learning. En el comando siguiente se usa un ejemplo de implementación del repositorio de ejemplos:

az ml online-deployment create --file endpoints/online/managed/sample/blue-deployment.yml --local --vscode-debug

Importante

En el Subsistema de Windows para Linux (WSL), deberá actualizar la variable de entorno PATH para incluir la ruta de acceso al ejecutable de Visual Studio Code o usar la interoperabilidad de WSL. Para obtener más información, consulte Interoperabilidad de Windows con Linux.

Una imagen de Docker se ha creado localmente. Todo error de configuración del entorno o archivo de modelo se muestra en esta fase del proceso.

Nota:

La primera vez que inicie un contenedor de desarrollo nuevo o actualizado, puede tardar varios minutos.

Una vez que la imagen se compile correctamente, el contenedor de desarrollo se abrirá en una ventana de Visual Studio Code.

Usará algunas extensiones de Visual Studio Code para depurar las implementaciones en el contenedor de desarrollo. Azure Machine Learning instala automáticamente estas extensiones en el contenedor de desarrollo.

Depuración de inferencia
Pylance
Jupyter
Python

Importante

Antes de iniciar la sesión de depuración, asegúrese de que las extensiones de Visual Studio Code hayan terminado de instalarse en el contenedor de desarrollo.

Obtenga un manipulador para el área de trabajo:

credential = DefaultAzureCredential()
ml_client = MLClient(
    credential,
    subscription_id=subscription_id,
    resource_group_name=resource_group,
    workspace_name=workspace_name,
)

Para depurar puntos de conexión en línea localmente en Visual Studio Code, establezca las marcas vscode-debug y local al crear o actualizar una implementación en línea de Azure Machine Learning. En el comando siguiente se refleja un ejemplo de implementación del repositorio de ejemplos:

deployment = ManagedOnlineDeployment(
    name="blue",
    endpoint_name=endpoint_name,
    model=Model(path="../model-1/model/sklearn_regression_model.pkl"),
    code_configuration=CodeConfiguration(
        code="../model-1/onlinescoring", scoring_script="score.py"
    ),
    environment=Environment(
        conda_file="../model-1/environment/conda.yaml",
        image="mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04",
    ),
    instance_type="Standard_DS3_v2",
    instance_count=1,
)

deployment = ml_client.online_deployments.begin_create_or_update(
    deployment, local=True, vscode_debug=True
).result()

Importante

Una imagen de Docker se ha creado localmente. Todo error de configuración del entorno o archivo de modelo se muestra en esta fase del proceso.

Nota:

El inicio de un contenedor de desarrollo nuevo o actualizado por primera vez puede tardar varios minutos.

Una vez que la imagen se compile correctamente, el contenedor de desarrollo se abrirá en una ventana de Visual Studio Code.

Depuración de inferencia
Pylance
Jupyter
Python

Importante

Antes de iniciar la sesión de depuración, asegúrese de que las extensiones de Visual Studio Code hayan terminado de instalarse en el contenedor de desarrollo.

Inicio de la sesión de depuración

Una vez configurado el entorno, use el depurador de Visual Studio Code para probar y depurar la implementación localmente.

Abra el script de puntuación en Visual Studio Code.

Sugerencia

El script score.py usado por el punto de conexión implementado anteriormente se encuentra en azureml-samples/cli/endpoints/online/managed/sample/score.py en el repositorio que ha clonado. Sin embargo, los pasos de esta guía funcionan con cualquier script de puntuación.
Establezca un punto de interrupción en el script de puntuación.
- Para depurar el comportamiento de inicio, coloque los puntos de interrupción dentro de la función init.
- Para depurar el comportamiento de puntuación, coloque los puntos de interrupción dentro de la función run.
Seleccione la vista de trabajo de Visual Studio Code.
En la lista desplegable Ejecutar y depurar, seleccione Azure ML: depurar punto de conexión local para iniciar la depuración local del punto de conexión.

En la sección Puntos de interrupción de la vista de ejecución, compruebe que:
- Raised Exceptions (Excepciones generadas) esté sin activar.
- Uncaught Exceptions (Excepciones no detectadas) esté activada.
Seleccione el icono de reproducción situado junto a la lista desplegable Ejecutar y depurar para iniciar la sesión de depuración.

En este momento, se detectan los puntos de interrupción de la función init. Use las acciones de depuración para avanzar por el código. Para obtener más información sobre las acciones de depuración, consulte la guía de acciones de depuración.

Para obtener más información sobre el depurador de Visual Studio Code, consulte Depuración.

Depuración del punto de conexión

CLI de Azure
Python

Ahora que la aplicación se está ejecutando en el depurador, intente realizar una predicción para depurar el script de puntuación.

Use el comando invoke de la extensión ml para realizar una solicitud al punto de conexión local.

az ml online-endpoint invoke --name <ENDPOINT-NAME> --request-file <REQUEST-FILE> --local

En este caso, <REQUEST-FILE> es un archivo JSON que contiene ejemplos de datos de entrada para el modelo con el fin de realizar predicciones en forma similar al siguiente JSON:

{"data": [
    [1,2,3,4,5,6,7,8,9,10], 
    [10,9,8,7,6,5,4,3,2,1]
]}

Sugerencia

El URI de puntuación es la dirección donde el punto de conexión escucha las solicitudes. Use la extensión ml para obtener el URI de puntuación.

az ml online-endpoint show --name <ENDPOINT-NAME> --local

La salida debe tener una apariencia similar a la siguiente:

{
 "auth_mode": "aml_token",
 "location": "local",
 "name": "my-new-endpoint",
 "properties": {},
 "provisioning_state": "Succeeded",
 "scoring_uri": "http://localhost:5001/score",
 "tags": {},
 "traffic": {},
 "type": "online"
}

El URI de puntuación se puede encontrar en la propiedad scoring_uri.

En este momento, se detectan los puntos de interrupción de la función run. Use las acciones de depuración para avanzar por el código. Para obtener más información sobre las acciones de depuración, consulte la guía de acciones de depuración.

Ahora que la aplicación se está ejecutando en el depurador, intente realizar una predicción para depurar el script de puntuación.

Use el método invoke en el objeto MLClient para hacer una solicitud al punto de conexión local.

endpoint = ml_client.online_endpoints.get(name=endpoint_name, local=True)

request_file_path = "../model-1/sample-request.json"

ml_client.online_endpoints.invoke(endpoint_name, request_file_path, local=True)

En este caso, <REQUEST-FILE> es un archivo JSON que contiene ejemplos de datos de entrada para el modelo con el fin de realizar predicciones en forma similar al siguiente JSON:

{"data": [
    [1,2,3,4,5,6,7,8,9,10], 
    [10,9,8,7,6,5,4,3,2,1]
]}

Sugerencia

El URI de puntuación es la dirección donde el punto de conexión escucha las solicitudes. El método as_dict de los objetos del punto de conexión devuelve información similar a show en la CLI de Azure. El objeto del punto de conexión se puede obtener mediante .get.

print(endpoint)

La salida debe tener una apariencia similar a la siguiente:

{
 "auth_mode": "aml_token",
 "location": "local",
 "name": "my-new-endpoint",
 "properties": {},
 "provisioning_state": "Succeeded",
 "scoring_uri": "http://localhost:5001/score",
 "tags": {},
 "traffic": {},
 "type": "online"
}

El URI de puntuación se puede encontrar en la clave scoring_uri.

Edición del punto de conexión

CLI de Azure
Python

A medida que depura y soluciona los problemas de la aplicación, hay escenarios en los que tendrá que actualizar el script de puntuación y las configuraciones.

Para aplicar cambios en el código:

Actualice el código.
Reinicie la sesión de depuración con el comando Developer: Reload Window de la paleta de comandos. Para obtener más información, consulte la documentación de la paleta de comandos.

Nota

Puesto que el directorio que contiene el código y los recursos del punto de conexión está montado en el contenedor de desarrollo, los cambios que realice en el contenedor de desarrollo se sincronizarán con el sistema de archivos local.

Para realizar cambios más exhaustivos que impliquen actualizaciones en la configuración del entorno y del punto de conexión, use el comando update de la extensión ml. Esto desencadena una recompilación de la imagen completa con los cambios.

az ml online-deployment update --file <DEPLOYMENT-YAML-SPECIFICATION-FILE> --local --vscode-debug

Una vez que se haya compilado la imagen actualizada y se inicie el contenedor de desarrollo, use el depurador de Visual Studio Code para probar y solucionar los problemas del punto de conexión actualizado.

A medida que depura y soluciona los problemas de la aplicación, hay escenarios en los que tendrá que actualizar el script de puntuación y las configuraciones.

Para aplicar cambios en el código:

Actualice el código.
Reinicie la sesión de depuración con el comando Developer: Reload Window de la paleta de comandos. Para obtener más información, consulte la documentación de la paleta de comandos.

Nota

Para hacer cambios más exhaustivos que impliquen actualizaciones en la configuración del entorno y punto de conexión, use el módulo o método online_deployments.update de MLClient. Esto desencadena una recompilación de la imagen completa con los cambios.

new_deployment = ManagedOnlineDeployment(
    name="green",
    endpoint_name=endpoint_name,
    model=Model(path="../model-2/model/sklearn_regression_model.pkl"),
    code_configuration=CodeConfiguration(
        code="../model-2/onlinescoring", scoring_script="score.py"
    ),
    environment=Environment(
        conda_file="../model-2/environment/conda.yaml",
        image="mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04",
    ),
    instance_type="Standard_DS3_v2",
    instance_count=2,
)

deployment = ml_client.online_deployments.begin_create_or_update(
    new_deployment, local=True, vscode_debug=True
).result()

Depuración de puntos de conexión en línea localmente en Visual Studio Code

Requisitos previos

Inicio del contenedor de desarrollo

Inicio de la sesión de depuración

Depuración del punto de conexión

Edición del punto de conexión

Contenido relacionado

Recursos adicionales