Depuración de scripts de puntuación mediante el servidor HTTP de inferencia de Azure Machine Learning

El servidor HTTP de inferencia de Azure Machine Learning es un paquete de Python que expone su función de puntuación como un punto de conexión HTTP y envuelve el código y las dependencias del servidor Flask en un paquete singular. El servidor de inferencia se incluye en las imágenes de Docker precompiladas para la inferencia que se usan al implementar un modelo en Azure Machine Learning. Cuando se usa solo el paquete, puede implementar el modelo localmente para producción. También puede validar fácilmente el script de puntuación (entrada) en un entorno de desarrollo local. Si hay un problema con el script de puntuación, el servidor de inferencia devuelve un error y la ubicación del error.

También puede usar el servidor de inferencia para crear puertas de validación en un proceso de integración y despliegue continuos. Por ejemplo, puede iniciar el servidor de inferencia con el script candidato y ejecutar el conjunto de pruebas en el punto de conexión local.

Este artículo ayuda a los desarrolladores que desean usar el servidor de inferencia para depurar localmente. En este artículo, verá cómo usar el servidor de inferencia con puntos de conexión en línea.

Requisitos previos

• Python 3.8 o versiones posteriores
• Anaconda

El servidor de inferencia se ejecuta en sistemas operativos basados en Windows y Linux.

Explorar las opciones de depuración local para puntos de conexión en línea

Al depurar localmente los puntos de conexión antes de implementarlos en la nube, puede detectar errores en el código y la configuración de manera temprana. Para depurar puntos de conexión localmente, tiene varias opciones, entre las que se incluyen:

• Servidor HTTP de inferencia de Azure Machine Learning.
• Un punto de conexión local.

En la tabla siguiente se proporciona información general sobre la compatibilidad que ofrece cada opción para varios escenarios de depuración:

En este artículo se describe cómo usar el servidor de inferencia.

Al ejecutar el servidor de inferencia localmente, concéntrese en depurar el script de puntuación sin preocuparse por las configuraciones del contenedor de implementación.

Depuración local del script de puntuación

Para depurar tu script de puntuación de manera local, tienes varias opciones para evaluar el comportamiento del servidor de inferencia:

• Utiliza un script de puntuación simulado.
• Use VS Code para depurar con el paquete azureml-inference-server-http.
• Ejecute un script de puntuación real, un archivo de modelo y un archivo de entorno desde el repositorio de ejemplos.

En las secciones siguientes se proporciona información sobre cada opción.

Uso de un script de puntuación ficticio para probar el comportamiento del servidor de inferencia

1. Cree un directorio denominado server_quickstart para almacenar los archivos:

   mkdir server_quickstart
   cd server_quickstart
   

2. Para evitar conflictos de paquetes, cree un entorno virtual, como myenv, y actívelo:

   python -m virtualenv myenv
   

   Nota:

   En Linux, ejecute el comando source myenv/bin/activate para activar el entorno virtual.

   Después de probar el servidor de inferencia, puede ejecutar el deactivate comando para desactivar el entorno virtual de Python.

3. Instale el paquete azureml-inference-server-http desde la fuente Índice de paquetes de Python (PyPI):

   python -m pip install azureml-inference-server-http
   

4. Creación del script de entrada. En el ejemplo siguiente se crea un script de entrada básico y se guarda en un archivo denominado score.py:

   echo -e 'import time\ndef init(): \n\ttime.sleep(1) \n\ndef run(input_data): \n\treturn {"message":"Hello, World!"}' > score.py
   

5. Use el azmlinfsrv comando para iniciar el servidor de inferencia y establecer el archivo score.py como script de entrada:

   azmlinfsrv --entry_script score.py
   

   Nota:

   El servidor de inferencia se hospeda en 0.0.0.0, lo que significa que escucha todas las direcciones IP del equipo de hospedaje.

6. Use la curl utilidad para enviar una solicitud de puntuación al servidor de inferencia:

   curl -p 127.0.0.1:5001/score
   

   El servidor de inferencia envía la siguiente respuesta:

   {"message": "Hello, World!"}
   

7. Cuando finalice la prueba, seleccione Ctrl+C para detener el servidor de inferencia.

Puede modificar el archivo de script de puntuación llamado score.py. A continuación, puede probar los cambios mediante el azmlinfsrv --entry_script score.py comando para volver a ejecutar el servidor de inferencia.

Integración con VS Code

En VS Code, puede usar la extensión de Python para depurar con el paquete azureml-inference-server-http . VS Code ofrece dos modos de depuración: iniciar y adjuntar.

Antes de usar cualquiera de los modos, instale el azureml-inference-server-http paquete mediante la ejecución del comando siguiente:

python -m pip install azureml-inference-server-http

Modo de inicio

Para el modo de inicio, siga estos pasos para configurar el archivo de configuración de VS Code launch.json e iniciar el servidor de inferencia en VS Code:

1. Inicie VS Code y abra la carpeta que contiene el script de score.py.

2. Para esa área de trabajo en VS Code, agregue la siguiente configuración al archivo launch.json:

   {
       "version": "0.2.0",
       "configurations": [
           {
               "name": "Debug score.py",
               "type": "debugpy",
               "request": "launch",
               "module": "azureml_inference_server_http.amlserver",
               "args": [
                   "--entry_script",
                   "score.py"
               ]
           }
       ]
     }
   

3. Inicie la sesión de depuración en VS Code seleccionando Ejecutar>iniciar depuración o seleccionando F5.

Modo de Asociar

Para el modo de asociación, siga estos pasos para usar VS Code con la extensión de Python para asociar al proceso del servidor de inferencia:

1. Inicie VS Code y abra la carpeta que contiene el script de score.py.

2. Para esa área de trabajo en VS Code, agregue la siguiente configuración al archivo launch.json:

   {
       "version": "0.2.0",
       "configurations": [
           {
               "name": "Python: Attach using Process ID",
               "type": "debugpy",
               "request": "attach",
               "processId": "${command:pickProcess}",
               "justMyCode": true
           }
       ]
     }
   

3. En una ventana de comandos, inicie el servidor de inferencia ejecutando el azmlinfsrv --entry_script score.py comando .

4. Siga estos pasos para iniciar la sesión de depuración en VS Code:

   1. Seleccione Ejecutar>Iniciar depuración, o seleccione F5.

   2. En la ventana de comandos, busque los registros del servidor de inferencia para buscar el identificador de proceso del azmlinfsrv proceso:

      

      Asegúrese de localizar el identificador del azmlinfsrv proceso, no el gunicorn proceso.

   3. En el depurador de VS Code, escriba el identificador del azmlinfsrv proceso.

      Si no ve el selector de procesos de VS Code, escriba manualmente el identificador de proceso en el processId campo del archivo launch.json del área de trabajo.

Para los modos de inicio y asociación, puede establecer puntos de interrupción y depurar el script paso a paso.

Usar un ejemplo completo

El procedimiento siguiente ejecuta el servidor de inferencia localmente con archivos de ejemplo del repositorio de ejemplo de Azure Machine Learning. Los archivos de ejemplo incluyen un script de puntuación, un archivo de modelo y un archivo de entorno. Para obtener más ejemplos de cómo usar estos archivos de ejemplo, consulte Implementar y puntuar un modelo de Machine Learning mediante un punto de conexión en línea.

1. Clone el repositorio de ejemplo y vaya a la carpeta que contiene los archivos de ejemplo pertinentes:

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

2. Use Conda para crear y activar un entorno virtual:

   En este ejemplo, el paquete azureml-inference-server-http se instala automáticamente. El paquete se incluye como una biblioteca dependiente del azureml-defaults paquete, que aparece en el archivo conda.yaml.

   # Create the environment from the YAML file.
   conda env create --name model-env -f ./environment/conda.yaml
   # Activate the new environment.
   conda activate model-env
   

3. Revise el script de puntuación, onlinescoring/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()
   

4. Ejecute el servidor de inferencia especificando el script de puntuación y la ruta de acceso a la carpeta del modelo.

   Durante la implementación, la AZUREML_MODEL_DIR variable se define para almacenar la ruta de acceso a la carpeta del modelo. Especifique ese valor en el model_dir parámetro . Cuando se ejecuta el script de puntuación, recupera el valor de la AZUREML_MODEL_DIR variable .

   En este caso, use el directorio actual, ./, como valor model_dir, ya que el script de puntuación especifica el subdirectorio como model/sklearn_regression_model.pkl.

   azmlinfsrv --entry_script ./onlinescoring/score.py --model_dir ./
   

   Cuando el servidor de inferencia se inicia e invoca correctamente el script de puntuación, se abre el ejemplo registro de inicio. De lo contrario, el registro muestra mensajes de error.

5. Pruebe el script de puntuación con datos de ejemplo siguiendo estos pasos:

   1. Abra otra ventana de comandos y vaya al mismo directorio de trabajo en el que ejecutó el azmlinfsrv comando.

   2. Use la siguiente curl utilidad para enviar una solicitud de ejemplo al servidor de inferencia y recibir un resultado de puntuación:

      curl --request POST "127.0.0.1:5001/score" --header "Content-Type:application/json" --data @sample-request.json
      

      Cuando no hay ningún problema en el script de puntuación, el script devuelve el resultado de puntuación. Si se producen problemas, puede actualizar el script de puntuación y, a continuación, volver a iniciar el servidor de inferencia para probar el script actualizado.

Revisión de las rutas del servidor de inferencia

El servidor de inferencia escucha en el puerto 5001 de forma predeterminada en las rutas siguientes:

Revisión de los parámetros del servidor de inferencia

El servidor de inferencia acepta los parámetros siguientes:

Exploración del procesamiento de solicitudes del servidor de inferencia

Los pasos siguientes muestran cómo el servidor de inferencia, azmlinfsrv, controla las solicitudes entrantes:

1. Un contenedor de la CLI de Python se encuentra alrededor de la pila de red del servidor de inferencia y se usa para iniciar el servidor de inferencia.

2. Un cliente envía una solicitud al servidor de inferencia.

3. El servidor de inferencia envía la solicitud a través del servidor de Web Server Gateway Interface (WSGI), que envía la solicitud a una de las siguientes aplicaciones de trabajo de Flask:

   • En Windows: waitress
   • En Linux: gunicorn

4. La aplicación de trabajo Flask controla la solicitud, lo que incluye cargar el script de entrada y todas las dependencias.

5. El script de entrada recibe la solicitud. El script de entrada realiza una llamada de inferencia al modelo cargado y devuelve una respuesta.

Exploración de los registros del servidor de inferencia

Hay dos maneras de obtener datos de registro para la prueba del servidor de inferencia:

• Ejecute el azureml-inference-server-http paquete localmente y vea la salida del registro.
• Use puntos de conexión en línea y vea los registros de contenedor. El registro del servidor de inferencia se denomina <versión> del servidor HTTP de inferencia de Azure Machine Learning.

Visualizar registros de inicio

Cuando se inicia el servidor de inferencia, los registros muestran la siguiente configuración de servidor inicial:

Azure ML Inferencing HTTP server <version>


Server Settings
---------------
Entry Script Name: <entry-script>
Model Directory: <model-directory>
Config File: <configuration-file>
Worker Count: <worker-count>
Worker Timeout (seconds): None
Server Port: <port>
Health Port: <port>
Application Insights Enabled: false
Application Insights Key: <Application-Insights-instrumentation-key>
Inferencing HTTP server version: azmlinfsrv/<version>
CORS for the specified origins: <access-control-allow-origins>
Create dedicated endpoint for health: <health-check-endpoint>


Server Routes
---------------
Liveness Probe: GET   127.0.0.1:<port>/
Score:          POST  127.0.0.1:<port>/score

<logs>

Por ejemplo, al ejecutar el servidor de inferencia siguiendo los pasos del ejemplo de extremo a extremo, los registros contienen la siguiente información:

Azure ML Inferencing HTTP server v1.2.2


Server Settings
---------------
Entry Script Name: /home/user-name/azureml-examples/cli/endpoints/online/model-1/onlinescoring/score.py
Model Directory: ./
Config File: None
Worker Count: 1
Worker Timeout (seconds): None
Server Port: 5001
Health Port: 5001
Application Insights Enabled: false
Application Insights Key: None
Inferencing HTTP server version: azmlinfsrv/1.2.2
CORS for the specified origins: None
Create dedicated endpoint for health: None

Server Routes
---------------
Liveness Probe: GET   127.0.0.1:5001/
Score:          POST  127.0.0.1:5001/score

2022-12-24 07:37:53,318 I [32726] gunicorn.error - Starting gunicorn 20.1.0
2022-12-24 07:37:53,319 I [32726] gunicorn.error - Listening at: http://0.0.0.0:5001 (32726)
2022-12-24 07:37:53,319 I [32726] gunicorn.error - Using worker: sync
2022-12-24 07:37:53,322 I [32756] gunicorn.error - Booting worker with pid: 32756
Initializing logger
2022-12-24 07:37:53,779 I [32756] azmlinfsrv - Starting up app insights client
2022-12-24 07:37:54,518 I [32756] azmlinfsrv.user_script - Found user script at /home/user-name/azureml-examples/cli/endpoints/online/model-1/onlinescoring/score.py
2022-12-24 07:37:54,518 I [32756] azmlinfsrv.user_script - run() is not decorated. Server will invoke it with the input in JSON string.
2022-12-24 07:37:54,518 I [32756] azmlinfsrv.user_script - Invoking user's init function
2022-12-24 07:37:55,974 I [32756] azmlinfsrv.user_script - Users's init has completed successfully
2022-12-24 07:37:55,976 I [32756] azmlinfsrv.swagger - Swaggers are prepared for the following versions: [2, 3, 3.1].
2022-12-24 07:37:55,976 I [32756] azmlinfsrv - Scoring timeout is set to 3600000
2022-12-24 07:37:55,976 I [32756] azmlinfsrv - Worker with pid 32756 ready for serving traffic

Comprender formato de datos de registro

Todos los registros del servidor de inferencia, excepto el script del iniciador, presentan datos en el formato siguiente:

<UTC-time> <level> [<process-ID>] <logger-name> - <message>

Cada entrada consta de los siguientes componentes:

• <UTC-time>: la hora a la que se introduce la entrada en el registro.
• <level>: el primer carácter del nivel de registro de la entrada, como E para ERROR, I para INFO, etc.
• <process-ID>: el identificador del proceso asociado a la entrada.
• <logger-name>: el nombre del recurso asociado a la entrada de registro.
• <message>: el contenido del mensaje de registro

Hay seis niveles de registro en Python. Cada nivel tiene un valor numérico asignado según su gravedad:

Solución de problemas del servidor de inferencia

En las secciones siguientes se proporcionan sugerencias básicas de solución de problemas para el servidor de inferencia. Para solucionar problemas de puntos de conexión en línea, consulte Solución de problemas de implementación y puntuación de puntos de conexión en línea.

Compruebe los paquetes instalados

Siga estos pasos para solucionar problemas con los paquetes instalados:

1. Recopile información sobre los paquetes instalados y las versiones del entorno de Python.

2. En el archivo de entorno, compruebe la versión del azureml-inference-server-http paquete de Python especificado. En los registros de inicio del servidor HTTP de inferencia de Azure Machine Learning, compruebe la versión del servidor de inferencia que se muestra. Confirme que las dos versiones coinciden.

   En algunos casos, el solucionador de dependencias pip instala versiones de paquete inesperadas. Es posible que tenga que ejecutar pip para corregir los paquetes y versiones instalados.

3. Si especifica Flask o sus dependencias en su entorno, elimine esos elementos.

   • Los paquetes dependientes incluyen flask, jinja2, itsdangerous, werkzeug, markupsafe y click.
   • El flask paquete se muestra como una dependencia en el paquete del servidor de inferencia. El mejor enfoque es permitir que el servidor de inferencia instale el paquete flask.
   • Cuando el servidor de inferencia está configurado para admitir nuevas versiones de Flask, el servidor de inferencia recibe automáticamente las actualizaciones del paquete a medida que están disponibles.

Comprobación de la versión del servidor de inferencia

El paquete de servidor azureml-inference-server-http se publica en PyPI. En la página PyPI se muestra el registro de cambios y todas las versiones del paquete.

Si usa una versión temprana del paquete, actualice la configuración a la versión más reciente. En la tabla siguiente se resumen las versiones estables, los problemas comunes y los ajustes recomendados:

Comprobar dependencias del paquete

Los paquetes dependientes más relevantes para el paquete de servidor azureml-inference-server-http incluyen:

• flask
• opencensus-ext-azure
• inference-schema

Si especifica el paquete azureml-defaults en su entorno de Python, el paquete azureml-inference-server-http es un paquete dependiente. La dependencia se instala automáticamente.

TypeError durante el inicio del servidor de inferencia

Es posible que encuentre lo siguiente TypeError durante el inicio del servidor de inferencia:

TypeError: register() takes 3 positional arguments but 4 were given

  File "/var/azureml-server/aml_blueprint.py", line 251, in register

    super(AMLBlueprint, self).register(app, options, first_registration)

TypeError: register() takes 3 positional arguments but 4 were given

Este error se produce cuando tiene Flask 2 instalado en el entorno de Python, pero la versión del paquete azureml-inference-server-http no es compatible con Flask 2. La compatibilidad con Flask 2 está disponible en el azureml-inference-server-http paquete 0.7.0 y versiones posteriores, y el azureml-defaults paquete 1.44 y versiones posteriores.

• Si no usa el paquete Flask 2 en una imagen de Docker de Azure Machine Learning, use la versión más reciente del paquete de azureml-inference-server-http o azureml-defaults.

• Si usa el paquete flask 2 en una imagen de Docker de Azure Machine Learning, confirme que la versión de compilación de la imagen es July 2022 o posterior.

  La versión de la imagen la pueden encontrar en los registros del contenedor. Por ejemplo, consulte las siguientes declaraciones de registro:

  2022-08-22T17:05:02,147738763+00:00 | gunicorn/run | AzureML Container Runtime Information
  2022-08-22T17:05:02,161963207+00:00 | gunicorn/run | ###############################################
  2022-08-22T17:05:02,168970479+00:00 | gunicorn/run | 
  2022-08-22T17:05:02,174364834+00:00 | gunicorn/run | 
  2022-08-22T17:05:02,187280665+00:00 | gunicorn/run | AzureML image information: openmpi4.1.0-ubuntu20.04, Materialization Build:20220708.v2
  2022-08-22T17:05:02,188930082+00:00 | gunicorn/run | 
  2022-08-22T17:05:02,190557998+00:00 | gunicorn/run | 
  

  La fecha de compilación de la imagen aparece después de la notación Materialization Build. En el ejemplo anterior, la versión de la imagen es 20220708, o el 8 de julio de 2022. La imagen de este ejemplo es compatible con Flask 2.

  Si no ve un mensaje similar en el registro de contenedor, la imagen no está actualizada y debe actualizarse. Si usa una imagen de arquitectura de dispositivo unificado de proceso (CUDA) y no encuentra una imagen más reciente, compruebe el repositorio AzureML-Containers para ver si la imagen está en desuso. Puede encontrar reemplazos designados para imágenes en desuso.

  Si usa el servidor de inferencia con un punto de conexión en línea, también puede encontrar los registros en Azure Machine Learning Studio. En la página del punto de conexión, seleccione la pestaña Registros .

Si implementa con el SDK v1 y no especifica explícitamente una imagen en la configuración de implementación, el servidor de inferencia aplica el openmpi4.1.0-ubuntu20.04 paquete con una versión que coincida con el conjunto de herramientas del SDK local. Sin embargo, es posible que la versión instalada no sea la versión más reciente disponible de la imagen.

Para la versión 1.43 del SDK, el servidor de inferencia instala la openmpi4.1.0-ubuntu20.04:20220616 versión del paquete de forma predeterminada, pero esta versión del paquete no es compatible con SDK 1.43. Asegúrese de usar el SDK más reciente para la implementación.

Si no puede actualizar la imagen, puede evitar temporalmente el problema anclando las entradas azureml-defaults==1.43 o azureml-inference-server-http~=0.4.13 en el archivo de entorno. Estas entradas dirigen el servidor de inferencia para instalar la versión anterior con flask 1.0.x.

ImportError o ModuleNotFoundError durante el inicio del servidor de inferencia

Es posible que encuentre un ImportError o ModuleNotFoundError en módulos específicos, como opencensus, jinja2, markupsafe o click, durante el inicio del servidor de inferencia. En el ejemplo siguiente se muestra el mensaje de error:

ImportError: cannot import name 'Markup' from 'jinja2'

Los errores de importación y módulo se producen cuando se usa la versión 0.4.10 o versiones anteriores del servidor de inferencia que no anclan la dependencia de Flask a una versión compatible. Para evitar el problema, instale una versión posterior del servidor de inferencia.

Contenido relacionado

• Implementación y puntuación de un modelo de aprendizaje automático mediante un punto de conexión en línea
• Imágenes de Docker precompiladas para la inferencia