Eseguire il debug degli script di assegnazione dei punteggi usando il server HTTP di inferenza di Azure Machine Learning

Il server HTTP di inferenza di Azure Machine Learning è un pacchetto Python che espone la funzione di punteggio come endpoint HTTP ed esegue il wrapping del codice e delle dipendenze del server Flask in un pacchetto singolare. Il server di inferenza è incluso nelle immagini Docker predefinite per l'inferenza usata quando si distribuisce un modello in Azure Machine Learning. Quando si usa solo il pacchetto, è possibile distribuire il modello in locale per la produzione. È anche possibile convalidare facilmente lo script di valutazione (entry) in un ambiente di sviluppo locale. Se si verifica un problema con lo script di assegnazione dei punteggi, il server di inferenza restituisce un errore e la posizione dell'errore.

È anche possibile usare il server di inferenza per creare controlli di convalida in una pipeline di integrazione e distribuzione continua. Ad esempio, è possibile avviare il server di inferenza con lo script candidato ed eseguire il gruppo di test sull'endpoint locale.

Questo articolo supporta gli sviluppatori che vogliono usare il server di inferenza per eseguire il debug in locale. In questo articolo viene illustrato come usare il server di inferenza con endpoint online.

Prerequisiti

• Python 3.8 o versioni successive
• Anaconda

Il server di inferenza viene eseguito nei sistemi operativi basati su Windows e Linux.

Esplorare le opzioni di debug locale per gli endpoint online

Eseguendo il debug degli endpoint in locale prima della distribuzione nel cloud, è possibile rilevare gli errori nel codice e nella configurazione all'inizio. Per eseguire il debug degli endpoint in locale, sono disponibili diverse opzioni, tra cui:

• Server HTTP di inferenza di Azure Machine Learning.
• Endpoint locale.

La tabella seguente offre una panoramica del supporto offerto da ogni opzione per diversi scenari di debug:

Questo articolo descrive come usare il server di inferenza.

Quando si esegue il server di inferenza in locale, è possibile concentrarsi sul debug dello script di assegnazione dei punteggi senza preoccuparsi delle configurazioni dei contenitori di distribuzione.

Eseguire il debug dello script di assegnazione dei punteggi in locale

Per eseguire il debug dello script di assegnazione dei punteggi in locale, sono disponibili diverse opzioni per testare il comportamento del server di inferenza:

• Usare uno script di assegnazione dei punteggi fittizi.
• Usare VS Code per eseguire il debug con il pacchetto azureml-inference-server-http .
• Esegui uno script di assegnazione dei punteggi reale, un file di modello e un file di ambiente dal repository di esempi.

Le sezioni seguenti forniscono informazioni su ogni opzione.

Usare uno script di assegnazione dei punteggi fittizi per testare il comportamento del server di inferenza

1. Creare una directory denominata server_quickstart per contenere i file:

   mkdir server_quickstart
   cd server_quickstart
   

2. Per evitare conflitti di pacchetti, creare un ambiente virtuale, ad esempio myenve attivarlo:

   python -m virtualenv myenv
   

   Nota

   In Linux eseguire il comando source myenv/bin/activate per attivare l'ambiente virtuale.

   Dopo aver testato il server di inferenza, è possibile eseguire il deactivate comando per disattivare l'ambiente virtuale Python.

3. Installare il pacchetto azureml-inference-server-http dal feed Python Package Index (PyPI):

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

4. Creare lo script di immissione. L'esempio seguente crea uno script di immissione di base e lo salva in un file denominato 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. Usare il azmlinfsrv comando per avviare il server di inferenza e impostare il file score.py come script di immissione:

   azmlinfsrv --entry_script score.py
   

   Nota

   Il server di inferenza è ospitato in 0.0.0.0, il che significa che è in ascolto di tutti gli indirizzi IP del computer di hosting.

6. Usare l'utilità curl per inviare una richiesta di assegnazione dei punteggi al server di inferenza:

   curl -p 127.0.0.1:5001/score
   

   Il server di inferenza invia la risposta seguente:

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

7. Al termine del test, selezionare CTRL+C per arrestare il server di inferenza.

È possibile modificare il file di script di assegnazione dei punteggi score.py. È quindi possibile testare le modifiche usando il azmlinfsrv --entry_script score.py comando per eseguire di nuovo il server di inferenza.

Integrazione con VS Code

In VS Code è possibile usare l'estensione Python per il debug con il pacchetto azureml-inference-server-http . VS Code offre due modalità per il debug: avvio e collegamento.

Prima di usare una delle due modalità, installare il azureml-inference-server-http pacchetto eseguendo il comando seguente:

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

Modalità di avvio

Per la modalità di avvio, seguire questa procedura per configurare vs Code launch.json file di configurazione e avviare il server di inferenza all'interno di VS Code:

1. Avviare VS Code e aprire la cartella contenente lo script score.py.

2. Per tale area di lavoro in VS Code, aggiungere la configurazione seguente al file 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. Avviare la sessione di debug in VS Code selezionando Esegui avvia>debug o selezionando F5.

Modalità collegamento

Per la modalità di collegamento, seguire questa procedura per usare VS Code con l'estensione Python per connettersi al processo del server di inferenza:

1. Avviare VS Code e aprire la cartella contenente lo script score.py.

2. Per tale area di lavoro in VS Code, aggiungere la configurazione seguente al file launch.json:

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

3. In una finestra di comando avviare il server di inferenza eseguendo il azmlinfsrv --entry_script score.py comando .

4. Per avviare la sessione di debug in VS Code, seguire questa procedura:

   1. Selezionare Avvia>Avvia Debugging oppure F5.

   2. Nella finestra di comando cercare i log dal server di inferenza per individuare l'ID processo del azmlinfsrv processo:

      

      Assicurarsi di individuare l'ID del azmlinfsrv processo, non il gunicorn processo.

   3. Nel debugger di VS Code immettere l'ID del azmlinfsrv processo.

      Se non viene visualizzata la selezione del processo di VS Code, immettere manualmente l'ID processo nel campo processId del file launch.json relativo all'area di lavoro.

Per le modalità di avvio e collegamento, è possibile impostare punti di interruzione ed eseguire il debug dello script in modo dettagliato.

Usare un esempio end-to-end

La procedura seguente esegue il server di inferenza in locale con file di esempio dal repository di esempio di Azure Machine Learning. I file di esempio includono uno script di assegnazione dei punteggi, un file di modello e un file di ambiente. Per altri esempi su come usare i file di esempio, vedere Distribuire e assegnare un punteggio a un modello di Machine Learning usando un endpoint online.

1. Clonare il repository di esempio e passare alla cartella contenente i file di esempio pertinenti:

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

2. Usare conda per creare e attivare un ambiente virtuale:

   In questo esempio il pacchetto azureml-inference-server-http viene installato automaticamente. Il pacchetto è incluso come libreria dipendente del azureml-defaults pacchetto, elencato nel file 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. Esaminare lo script di assegnazione dei punteggi, 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. Eseguire il server di inferenza specificando lo script di assegnazione dei punteggi e il percorso della cartella del modello.

   Durante la distribuzione, la AZUREML_MODEL_DIR variabile viene definita per archiviare il percorso della cartella del modello. Si specifica quel valore nel parametro model_dir. Quando viene eseguito lo script di assegnazione dei punteggi, recupera il valore dalla AZUREML_MODEL_DIR variabile .

   In questo caso, usare la directory corrente, ./, come valore di model_dir, perché lo script di valutazione specifica la sottodirectory come model/sklearn_regression_model.pkl.

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

   Quando il server di inferenza viene avviato e richiama correttamente lo script di assegnazione dei punteggi, viene aperto il log di avvio di esempio. In caso contrario, il log mostra i messaggi di errore.

5. Testare lo script di assegnazione dei punteggi con i dati di esempio seguendo questa procedura:

   1. Aprire un'altra finestra di comando e passare alla stessa directory di lavoro in cui è stato eseguito il azmlinfsrv comando.

   2. Usare l'utilità seguente curl per inviare una richiesta di esempio al server di inferenza e ricevere un risultato di assegnazione dei punteggi:

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

      Quando non sono presenti problemi nello script di assegnazione dei punteggi, lo script restituisce il risultato dell'assegnazione dei punteggi. Se si verificano problemi, è possibile aggiornare lo script di assegnazione dei punteggi e quindi avviare di nuovo il server di inferenza per testare lo script aggiornato.

Esaminare i percorsi del server di inferenza

Il server di inferenza è in ascolto sulla porta 5001, di default, nelle route seguenti:

Esaminare i parametri del server di inferenza

Il server di inferenza accetta i parametri seguenti:

Esplorare l'elaborazione delle richieste del server di inferenza

I passaggi seguenti illustrano come il server di inferenza, azmlinfsrv, gestisce le richieste in ingresso:

1. Un wrapper CLI Python gestisce lo stack di rete del server di inferenza e viene utilizzato per avviare il server di inferenza.

2. Un client invia una richiesta al server di inferenza.

3. Il server di inferenza invia la richiesta tramite il server WSGI (Web Server Gateway Interface), che invia la richiesta a una delle applicazioni di lavoro Flask seguenti:

   • In Windows: cameriere
   • In Linux: gunicorn

4. L'app ruolo di lavoro Flask gestisce la richiesta, che include il caricamento dello script di immissione e le eventuali dipendenze.

5. Lo script di immissione riceve la richiesta. Lo script di immissione effettua una chiamata di inferenza al modello caricato e restituisce una risposta.

Esplorare i log del server di inferenza

Esistono due modi per ottenere i dati di log per il test del server di inferenza:

• Eseguire il azureml-inference-server-http pacchetto localmente e visualizzare l'output del log.
• Usare gli endpoint online e visualizzare i log dei contenitori. Il log per il server di inferenza è denominato Server HTTP di inferenza di Azure Machine Learning <versione>.

Visualizzare i log di avvio

All'avvio del server di inferenza, i log mostrano le impostazioni iniziali del server seguenti:

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>

Ad esempio, quando si esegue il server di inferenza seguendo i passaggi dell'esempio end-to-end, i log contengono le seguenti informazioni:

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

Informazioni sul formato dei dati di log

Tutti i log dal server di inferenza, ad eccezione dello script di avvio, presentano i dati nel formato seguente:

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

Ogni voce è costituita dai componenti seguenti:

• <UTC-time>: l'ora in cui la voce viene registrata nel registro
• <level>: primo carattere del livello di registrazione per la voce, ad esempio E per ERROR, I per INFO e così via
• <process-ID>: ID del processo associato alla voce corrispondente
• <logger-name>: il nome della risorsa associata alla voce di log
• <message>: contenuto del messaggio di log

Esistono sei livelli di registrazione in Python. Ogni livello ha un valore numerico assegnato in base alla relativa gravità:

Risolvere i problemi del server di inferenza

Le sezioni seguenti forniscono suggerimenti di base per la risoluzione dei problemi per il server di inferenza. Per risolvere i problemi relativi agli endpoint online, vedere Risolvere i problemi di distribuzione e assegnazione dei punteggi degli endpoint online.

Controllare i pacchetti installati

Per risolvere i problemi relativi ai pacchetti installati, seguire questa procedura:

1. Raccogliere informazioni su pacchetti e versioni installati per l'ambiente Python.

2. Nel file di ambiente controllare la versione del azureml-inference-server-http pacchetto Python specificato. Nei log di avvio del server HTTP di inferenza di Azure Machine Learning controllare la versione del server di inferenza visualizzato. Verificare che le due versioni corrispondano.

   In alcuni casi, il sistema di risoluzione delle dipendenze pip installa versioni impreviste del pacchetto. Potrebbe essere necessario eseguire pip per correggere i pacchetti e le versioni installati.

3. Se si specifica Flask o le relative dipendenze nell'ambiente, rimuovere tali elementi.

   • I pacchetti dipendenti includono flask, jinja2itsdangerous, werkzeug, markupsafe, e click.
   • Il flask pacchetto è elencato come dipendenza nel pacchetto del server di inferenza. L'approccio migliore consiste nel consentire al server di inferenza di installare il pacchetto flask.
   • Quando il server di inferenza è configurato per supportare le nuove versioni di Flask, il server di inferenza riceve automaticamente gli aggiornamenti del pacchetto non appena diventano disponibili.

Controllare la versione del server di inferenza

Il pacchetto server azureml-inference-server-http viene pubblicato in PyPI. La pagina PyPI elenca il log delle modifiche e tutte le versioni del pacchetto.

Se si usa una versione anticipata del pacchetto, aggiornare la configurazione alla versione più recente. La tabella seguente riepiloga le versioni stabili, i problemi comuni e le modifiche consigliate:

Verificare le dipendenze del pacchetto

I pacchetti dipendenti più rilevanti per il pacchetto server azureml-inference-server-http includono:

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

Se si specifica il pacchetto azureml-defaults nell'ambiente Python, azureml-inference-server-http è un pacchetto dipendente. La dipendenza viene installata automaticamente.

TypeError durante l'avvio del server di inferenza

Durante l'avvio del server di inferenza potrebbe verificarsi quanto segue TypeError :

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

Questo errore si verifica quando Flask 2 è installato nell'ambiente Python, ma la versione del pacchetto azureml-inference-server-http non supporta Flask 2. Il supporto per Flask 2 è disponibile nel azureml-inference-server-http pacchetto 0.7.0 e versioni successive e nel azureml-defaults pacchetto 1.44 e versioni successive.

• Se non si usa il pacchetto Flask 2 in un'immagine Docker di Azure Machine Learning, usare la versione più recente del pacchetto azureml-inference-server-http o azureml-defaults.

• Se si usa il pacchetto Flask 2 in un'immagine Docker di Azure Machine Learning, verificare che la versione della build dell'immagine sia July 2022 o successiva.

  È possibile trovare la versione dell'immagine nei log del contenitore. Ad esempio, vedere le istruzioni di log seguenti:

  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 data di compilazione dell'immagine viene visualizzata dopo la notazione Materialization Build. Nell'esempio precedente la versione dell'immagine è 20220708, o 8 luglio 2022. L'immagine in questo esempio è compatibile con Flask 2.

  Se nel log del contenitore non viene visualizzato un messaggio simile, l'immagine non è aggiornata e deve essere aggiornata. Se si usa un'immagine CUDA (Compute Unified Device Architecture) e non è possibile trovare un'immagine più recente, controllare il repository AzureML-Containers per verificare se l'immagine è deprecata. È possibile trovare sostituzioni designate per le immagini deprecate.

  Se si usa il server di inferenza con un endpoint online, è anche possibile trovare i log in Azure Machine Learning Studio. Nella pagina dell'endpoint selezionare la scheda Log .

Se si esegue la distribuzione con l'SDK v1 e non si specifica in modo esplicito un'immagine nella configurazione di distribuzione, il server di inferenza applica il openmpi4.1.0-ubuntu20.04 pacchetto con una versione corrispondente al set di strumenti DELL'SDK locale. Tuttavia, la versione installata potrebbe non essere la versione disponibile più recente dell'immagine.

Per SDK versione 1.43, il server di inferenza installa la versione del openmpi4.1.0-ubuntu20.04:20220616 pacchetto per impostazione predefinita, ma questa versione del pacchetto non è compatibile con SDK 1.43. Assicurarsi di usare l'SDK più recente per la distribuzione.

Se non è possibile aggiornare l'immagine, è possibile evitare temporaneamente il problema aggiungendo le voci azureml-defaults==1.43 o azureml-inference-server-http~=0.4.13 nel file di ambiente. Queste voci indirizzano il server di inferenza a installare la versione precedente con flask 1.0.x.

ImportError o ModuleNotFoundError durante l'avvio del server di inferenza

Durante l'avvio del server di inferenza, potresti incontrare un ImportError o ModuleNotFoundError in moduli specifici, come opencensus, jinja2, markupsafe o click. L'esempio seguente mostra il messaggio di errore:

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

Gli errori di importazione e di modulo si verificano quando si usa la versione 0.4.10 o versioni precedenti del server di inferenza che non fissano la dipendenza di Flask a una versione compatibile. Per evitare il problema, installare una versione successiva del server di inferenza.

Contenuto correlato

• Distribuire e assegnare un punteggio a un modello di Machine Learning usando un endpoint online
• Immagini Docker predefinite per l'inferenza