Debuggen von Bewertungsskripts mit dem HTTP-Rückschlussserver für Azure Machine Learning

Der HTTP-Rückschlussserver von Azure Machine Learning ist ein Python-Paket, das Ihre Bewertungsfunktion als HTTP-Endpunkt verfügbar macht und den Flask-Servercode und die Abhängigkeiten in ein einzelnes Paket packt. Der Server ist in den vordefinierten Docker-Images für Rückschlüsse enthalten, die beim Bereitstellen eines Modells mit Azure Machine Learning verwendet werden. Mithilfe des Pakets können Sie das Modell lokal für die Produktion bereitstellen und Ihr Bewertungsskript (Einstiegsskript) sehr einfach in einer lokalen Entwicklungsumgebung überprüfen. Wenn ein Problem mit dem Bewertungsskript auftritt, gibt der Server einen Fehler und den Speicherort des Fehlers zurück.

Der Server kann auch verwendet werden, um Validierungsgates in einer Pipeline für Continuous Integration und Continuous Deployment zu erstellen. Beispielsweise können Sie den Server mit dem Kandidatenskript starten und die Testsammlung für den lokalen Endpunkt ausführen.

Dieser Artikel unterstütz Entwickler*innen, die den Rückschlussserver zum lokalen Debuggen verwenden möchten, und beschreibt, wie Sie den Rückschlussserver mit Onlineendpunkten unter Windows verwenden.

Voraussetzungen

Zur Verwendung des HTTP-Rückschlussservers für Azure Machine Learning zum lokalen Debuggen muss Ihre Konfiguration die folgenden Komponenten enthalten:

• Python 3.8 oder höher
• Anaconda

Der HTTP-Rückschlussserver für Azure Machine Learning kann unter Windows- und Linux-basierten Betriebssystemen ausgeführt werden.

Erkunden lokaler Debuggingoptionen für Onlineendpunkte

Wenn Sie Endpunkte lokal debuggen, bevor Sie sie in der Cloud bereitstellen, können Sie Fehler in Ihrem Code und Ihrer Konfiguration früher abfangen. Um Endpunkte lokal zu debuggen, haben Sie mehrere Optionen, unter anderem:

• den HTTP-Rückschlussserver für Azure Machine Learning
• einen lokalen Endpunkt

Dieser Artikel beschreibt, wie Sie mit dem HTTP-Server für Azure Machine Learning unter Windows arbeiten.

Die folgende Tabelle enthält eine Übersicht über Szenarien, damit Sie die für Sie am besten geeignete Option auswählen können:

Wenn Sie den HTTP-Rückschlussserver lokal ausführen, können Sie sich auf das Debuggen Ihres Bewertungsskripts konzentrieren, ohne sich um die Bereitstellungscontainerkonfigurationen zu kümmern.

Installieren des Pakets azureml-inference-server-http

Um das Paket azureml-inference-server-http zu installieren, führen Sie den folgenden Befehl aus:

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

Lokales Debuggen des Bewertungsskripts

Um Ihr Bewertungsskript lokal zu debuggen, haben Sie mehrere Optionen zum Testen des Serververhaltens:

• Probieren Sie ein Dummybewertungsskript aus.
• Verwenden Sie Visual Studio Code zum Debuggen mit dem Paket azureml-inference-server-http.
• Führen Sie ein tatsächliches Bewertungsskript, eine Modelldatei und eine Umgebungsdatei aus unserem Repository mit Beispielen aus.

Testen des Serververhaltens mit einem Dummybewertungsskript

1. Erstellen Sie ein Verzeichnis mit dem Namen server_quickstart, in dem Ihre Dateien gespeichert werden sollen:

   mkdir server_quickstart
   cd server_quickstart
   

2. Erstellen Sie eine virtuelle Umgebung, z. B. myenv, und aktivieren Sie sie, um Paketkonflikte zu vermeiden:

   python -m virtualenv myenv
   

   Hinweis

   Führen Sie unter Linux den Befehl source myenv/bin/activate aus, um die virtuelle Umgebung zu aktivieren.

   Nachdem Sie den Server getestet haben, können Sie den Befehl deactivate ausführen, um die virtuelle Python-Umgebung zu deaktivieren.

3. Installieren Sie das azureml-inference-server-http-Paket aus dem pypi-Feed:

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

4. Erstellen Sie Ihr Einstiegsskript. Im folgenden Beispiel wird ein grundlegendes Einstiegsskript erstellt und in einer Datei mit dem Namen score.pygespeichert:

   echo -e "import time def init(): \n\t time.sleep(1) \n\n def run(input_data): \n\t return {"message":"Hello, World!"}" > score.py
   

5. Starten Sie den Server mit dem Befehl azmlinfsrv, und legen Sie die Datei score.py als Einstiegsskript fest:

   azmlinfsrv --entry_script score.py
   

   Hinweis

   Der Server wird auf 0.0.0.0 gehostet. Dies bedeutet, dass er auf alle IP-Adressen des Hostcomputers lauscht.

6. Senden Sie eine Bewertungsanforderung mithilfe des Hilfsprogramms curl an den Server:

   curl -p 127.0.0.1:5001/score
   

   Der Server sendet die folgende Antwort:

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

7. Drücken Sie nach dem Testen die Tastenkombination STRG + C, um den Server zu beenden.

Nun können Sie die Bewertungsskriptdatei (score.py) ändern und Ihre Änderungen testen, indem Sie den Server erneut mit dem Befehl azmlinfsrv --entry_script score.py ausführen.

Integrieren mit Visual Studio Code

Um VS Code und die Python-Erweiterung zum Debuggen mit dem Paket azureml-inference-server-http zu verwenden, stehen Ihnen der Startmodus und Anfügemodus zur Verfügung.

• Für den Startmodus richten Sie die Datei launch.json in VS Code ein, und starten Sie den HTTP-Rückschlussserver für Azure Machine Learning in VS Code:

  1. Starten Sie VS Code, und öffnen Sie den Ordner mit dem Skript (score.py).

  2. Fügen Sie der Datei launch.json für diesen Arbeitsbereich die folgende Konfiguration in VS Code hinzu:

     launch.json

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

  3. Starten Sie die Debugsitzung in VS Code, indem Sie Ausführen>Debuggen starten auswählen oder die Tastenkombination F5 verwenden.

• Für den Anfügemodus starten Sie den HTTP-Rückschlussserver für Azure Machine Learning in einem Befehlsfenster, und verwenden Sie VS Code mit der Python-Erweiterung zum Anfügen an den Prozess:

  Hinweis

  Installieren Sie unter Linux zunächst das Paket gdb, indem Sie den Befehl sudo apt-get install -y gdb ausführen.

  1. Fügen Sie der Datei launch.json für diesen Arbeitsbereich die folgende Konfiguration in VS Code hinzu:

     launch.json

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

  2. Starten Sie in einem Befehlsfenster den HTTP-Rückschlussserver mit dem Befehl azmlinfsrv --entry_script score.py.

  3. Starten Sie eine Debugsitzung in VS Code:

     1. Wählen Sie Ausführen>Debuggen starten aus, oder verwenden Sie die Tastenkombination F5.

     2. Zeigen Sie im Befehlsfenster die Protokolle vom Rückschlussserver an, und suchen Sie die Prozess-ID des Befehls azmlinfsrv (nicht gunicorn):

        

     3. Geben Sie im VS-Code-Debugger die Prozess-ID des Befehls azmlinfsrv ein.

        Wenn die VS Code-Prozessauswahl nicht angezeigt wird, können Sie die Prozess-ID manuell in das Feld processId der Datei launch.json für diesen Arbeitsbereich eingeben.

Für beide Modi können Sie Haltepunkte festlegen und das Skript schrittweise debuggen.

Verwenden eines End-to-End-Beispiels

Im folgenden Verfahren wird der Server lokal mit Beispieldateien (Bewertungsskript, Modelldatei und Umgebung) vom Azure Machine Learning-Repository mit Beispielen ausgeführt. Weitere Beispiele zur Verwendung dieser Beispieldateien finden Sie unter Bereitstellen und Bewerten eines Machine Learning-Modells mithilfe eines Onlineendpunkts.

1. Klonen Sie das Beispielrepository:

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

2. Erstellen Sie eine virtuelle Umgebung mit conda, und aktivieren Sie sie:

   In diesem Beispiel wird das Paket azureml-inference-server-http automatisch installiert. Das Paket ist als abhängige Bibliothek des Pakets azureml-defaults in der Datei conda.yml enthalten:

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

3. Überprüfen Sie Ihr Bewertungsskript:

   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. Führen Sie den HTTP-Rückschlussserver unter Angabe des Bewertungsskripts und der Modelldatei aus:

   Das im Parameter model_dir angegebene Modellverzeichnis wird durch Verwendung der Variable AZUREML_MODEL_DIR definiert und im Bewertungsskript abgerufen.

   In diesem Fall geben Sie das aktuelle Verzeichnis ./ an, da das Unterverzeichnis im Bewertungsskript als model/sklearn_regression_model.pkl angegeben ist.

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

   Wenn der Server das Bewertungsskript startet und erfolgreich aufruft, wird das Beispiel Startprotokoll geöffnet. Andernfalls zeigt das Protokoll Fehlermeldungen an.

5. Testen Sie das Bewertungsskript mit Beispieldaten:

   Öffnen Sie ein weiteres Befehlsfenster, und wechseln Sie in dasselbe Arbeitsverzeichnis, in dem Sie den Befehl ausführen.

   Verwenden Sie den das Hilfsprogramm curl, um eine Beispielanforderung an den Server zu senden und ein Bewertungsergebnis zu erhalten:

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

   Wenn in Ihrem Bewertungsskript keine Probleme bestehen, gibt das Skript das Bewertungsergebnis zurück. Wenn Probleme auftreten, können Sie das Bewertungsskript aktualisieren und den Server erneut starten, um das aktualisierte Skript zu testen.

Überprüfen der Serverrouten

Der HTTP-Rückschlussserver lauscht an den folgenden Routen standardmäßig auf Port 5001:

Überprüfen der Serverparameter

Der HTTP-Rückschlussserver akzeptiert die folgenden Parameter:

Erkunden der Serveranforderungsverarbeitung

In den folgenden Schritten wird gezeigt, wie der HTTP-Rückschlussserver für Azure Machine Learning (azmlinfsrv) eingehende Anforderungen verarbeitet:

1. Ein Python CLI-Wrapper umgibt den Netzwerkstapel des Servers und wird zum Starten des Servers verwendet.

2. Ein Client sendet eine Anforderung an den Server.

3. Der Server sendet die Anforderung über den Web Server Gateway Interface (WSGI)-Server, der die Anforderung an eine Flask-Workeranwendung weiterleitet:

   • Windows: waitress
   • Linux: gunicorn

4. Die Flask-Workeranwendung verarbeitet die Anforderung, einschließlich des Ladens des Einstiegsskripts und aller Abhängigkeiten.

5. Ihr Einstiegsskript empfängt die Anforderung. Das Einstiegsskript sendet einen Rückschlussaufruf an das geladene Modell und gibt eine Antwort zurück:

Erkunden der Serverprotokolle

Es gibt zwei Möglichkeiten zum Abrufen von Protokolldaten für den Test des HTTP-Rückschlussservers:

• Führen Sie das Paket azureml-inference-server-http lokal aus, und zeigen Sie die Protokollausgabe an.
• Verwenden Sie Onlineendpunkte, und zeigen Sie die Containerprotokolle an. Das Protokoll für den Rückschlussserver hat den Namen HTTP-Rückschlussserver für Azure Machine Learning <Version>.

Anzeigen der Startprotokolle

Wenn der Server gestartet wird, zeigen die Protokolle die anfänglichen Servereinstellungen wie folgt an:

Azure Machine Learning Inferencing HTTP server <version>

Server Settings
---------------
Entry Script Name: <entry_script>
Model Directory: <model_dir>
Worker Count: <worker_count>
Worker Timeout (seconds): None
Server Port: <port>
Application Insights Enabled: false
Application Insights Key: <appinsights_instrumentation_key>
Inferencing HTTP server version: azmlinfsrv/<version>
CORS for the specified origins: <access_control_allow_origins>

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

<logs>

Wenn Sie den Server starten, indem Sie dem End-to-End-Beispiel folgen, wird das Protokoll beispielsweise wie folgt angezeigt:

Azure Machine Learning Inferencing HTTP server v0.8.0

Server Settings
---------------
Entry Script Name: /home/user-name/azureml-examples/cli/endpoints/online/model-1/onlinescoring/score.py
Model Directory: ./
Worker Count: 1
Worker Timeout (seconds): None
Server Port: 5001
Application Insights Enabled: false
Application Insights Key: None
Inferencing HTTP server version: azmlinfsrv/0.8.0
CORS for the specified origins: 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,977 I [32756] azmlinfsrv - AML_FLASK_ONE_COMPATIBILITY is set, but patching is not necessary.

Verstehen des Protokolldatenformats

Alle Protokolle vom HTTP-Rückschlussserver mit Ausnahme des Startprogrammskripts präsentieren Daten im folgenden Format:

<UTC Time> | <level> [<pid>] <logger name> - <message>

Der Eintrag umfasst die folgenden Komponenten:

• <UTC Time>: Zeitpunkt, zu dem der Eintrag in das Protokoll aufgenommen wurde
• <pid>: ID des Prozesses, der dem Eintrag zugeordnet ist
• <level>: Erstes Zeichen des Protokolliergrads für den Eintrag, z. B. E für ERROR, I für INFO usw.
• <logger name>: Name der Ressource, die dem Protokolleintrag zugeordnet ist
• <message>: Inhalt der Protokollnachricht

Es gibt sechs Ebenen der Protokollierung in Python mit zugewiesenen numerischen Werten gemäß Schweregrad:

Behandeln von Serverproblemen

In den folgenden Abschnitten finden Sie grundlegende Tipps zur Problembehandlung für den HTTP-Rückschlussserver für Azure Machine Learning. Informationen zur Problembehandlung bei Onlineendpunkten finden Sie unter Problembehandlung bei der Bereitstellung von Onlineendpunkten.

Installierte Pakete prüfen

Führen Sie die folgenden Schritte aus, um Probleme mit installierten Paketen zu beheben.

1. Sammeln Sie Informationen zu installierten Paketen und Versionen für Ihre Python-Umgebung.

2. Bestätigen Sie, dass die in der Umgebungsdatei angegebene Version des Python-Pakets azureml-inference-server-http der Version des HTTP-Rückschlussservers für Azure Machine Learning entspricht, die im Startprotokoll angezeigt wird.

   In einigen Fällen installiert der PIP-Abhängigkeitskonfliktlöser unerwartete Paketversionen. Möglicherweise müssen Sie pip ausführen, um installierte Pakete und Versionen zu korrigieren.

3. Wenn Sie Flask oder zugehörige Abhängigkeiten in Ihrer Umgebung angegeben haben, entfernen Sie diese Elemente.

   • Zu den abhängigen Paketen zählen flask, jinja2, itsdangerous, werkzeug, markupsafe und click.
   • flask wird als Abhängigkeit im Serverpaket aufgeführt. Der beste Ansatz besteht darin, dem Rückschlussserver die Installation des Pakets flask zu ermöglichen.
   • Wenn der Rückschlussserver für die Unterstützung neuer Flask-Versionen konfiguriert ist, empfängt der Server die Paketupdates automatisch, sobald diese verfügbar sind.

Überprüfen der Serverversion

Das Serverpaket azureml-inference-server-http wird in PyPI veröffentlicht. Auf der PyPI-Seite werden das Änderungsprotokoll und alle vorherigen Versionen aufgeführt.

Wenn Sie eine frühere Paketversion verwenden, aktualisieren Sie Ihre Konfiguration auf die aktuelle Version. In der folgenden Tabelle sind stabile Versionen, häufige Probleme und empfohlene Anpassungen zusammengefasst:

Überprüfen der Paketabhängigkeiten

Die wichtigsten abhängigen Pakete für das Serverpaket azureml-inference-server-http sind:

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

Wenn Sie in Ihrer Python-Umgebung das Paket azureml-defaults angegeben haben, ist das Paket azureml-inference-server-http ein abhängiges Paket. Die Abhängigkeit wird automatisch installiert.

TypeError während des Serverstarts

Möglicherweise tritt beim Serverstart der folgende TypeError auf:

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

Dieser Fehler tritt auf, wenn Flask 2 in Ihrer Python-Umgebung installiert ist, aber Ihre Version des Pakets azureml-inference-server-http Flask 2 nicht unterstützt. Unterstützung für Flask 2 ist in Version 0.7.0 und höher des Pakets azureml-inference-server-http sowie in Version 1.44 und höher des Pakets azureml-defaults verfügbar.

• Wenn Sie das Flask 2-Paket nicht in einem Azure Machine Learning-Docker-Image verwenden, verwenden Sie die aktuelle Version des Pakets azureml-inference-server-http oder azureml-defaults.

• Wenn Sie das Flask 2-Paket in einem Azure Machine Learning-Docker-Image verwenden, stellen Sie sicher, dass die Version für die Imageerstellung Juli 2022 oder neuer ist.

  Sie können die Imageversion in den Containerprotokollen finden. Zum Beispiel:

  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 | 
  

  Das Builddatum des Images wird nach der Notation Materialization Build angezeigt. Im vorherigen Beispiel ist die Imageversion 20220708 oder der 8. Juli 2022. Das Image in diesem Beispiel ist mit Flask 2 kompatibel.

  Wenn in Ihrem Containerprotokoll keine Meldung dieser Art angezeigt wird, ist Ihr Image veraltet und sollte aktualisiert werden. Wenn Sie ein CUDA (Compute Unified Device Architecture)-Image verwenden und kein neueres Image finden, überprüfen Sie unter AzureML-Containers, ob Ihr Image veraltet ist. Dort finden Sie designierte Ersatzimages für veraltete Images.

  Wenn Sie einen Server mit einem Onlineendpunkt verwenden, können Sie die Protokolle auch unter Protokolle auf der Seite Endpunkte in Azure Machine Learning Studio finden.

Wenn Sie SDK v1 für die Bereitstellung verwenden und in Ihrer Bereitstellungskonfiguration nicht explizit ein Image angeben, wendet der Server das Paket openmpi4.1.0-ubuntu20.04 mit einer Version an, die Ihrem lokalen SDK-Toolset entspricht. Die installierte Version ist jedoch möglicherweise nicht die aktuelle verfügbare Version des Images.

Für die SDK-Version 1.43 installiert der Server standardmäßig die Paketversion openmpi4.1.0-ubuntu20.04:20220616, die jedoch nicht mit SDK 1.43 kompatibel ist. Stellen Sie sicher, dass Sie das neueste SDK für Ihre Bereitstellung verwenden.

Wenn Sie das Image nicht aktualisieren können, können Sie das Problem vorübergehend umgehen, indem Sie die Einträge azureml-defaults==1.43 oder azureml-inference-server-http~=0.4.13 in Ihrer Umgebungsdatei anheften. Diese Einträge weisen den Server an, die ältere Version mit flask 1.0.x zu installieren.

ImportError oder ModuleNotFoundError während des Serverstarts

Während dem Serverstart kann ein Fehler vom Typ ImportError oder ModuleNotFoundError für bestimmte Modulen wie opencensus, jinja2, markupsafe oder click auftreten. Das folgende Beispiel zeigt die Fehlermeldung:

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

Die Import- und Modulfehler treten auf, wenn Sie die Version 0.4.10 oder frühere Versionen des Servers verwenden, welche die Flask-Abhängigkeit nicht an eine kompatible Version anheften. Um das Problem zu verhindern, installieren Sie eine neuere Version des Servers.

Zugehöriger Inhalt

• Bereitstellen eines Modells mit Azure Machine Learning
• Verwenden vordefinierter Docker-Images für Rückschlüsse