Erstellen von Aufträgen und Eingabedaten für Batchendpunkte

  • Artikel

Batchendpunkte können verwendet werden, um lange Batchvorgänge über große Mengen von Daten durchzuführen. Diese Daten können an verschiedenen Standorten platziert werden. Einige Arten von Batchendpunkten können auch Literalparameter als Eingaben empfangen. In diesem Tutorial erfahren Sie, wie Sie diese Eingaben und die verschiedenen unterstützten Typen oder Speicherorte angeben können.

Vor dem Aufrufen eines Endpunkts

Um einen Batch-Endpunkt erfolgreich aufzurufen und Aufträge zu erstellen, müssen Sie die folgenden Voraussetzungen erfüllen:

  • Sie haben die Berechtigung, eine Batch-Endpunktbereitstellung durchzuführen. Für die Ausführung einer Bereitstellung können die Rollen AzureML – Wissenschaftliche Fachkraft für Daten, Mitwirkender und Besitzer verwendet werden. Weitere Informationen zu den erforderlichen Berechtigungen für benutzerdefinierte Rollendefinitionen finden Sie unter Autorisierung auf Batchendpunkten.

  • Sie haben ein gültiges Microsoft Entra ID-Token, das einen Sicherheitsprinzipal darstellt, um den Endpunkt aufzurufen. Dieser Prinzipal kann ein Benutzerprinzipal oder ein Dienstprinzipal sein. In beiden Fällen wird nach dem Aufruf eines Endpunkts ein Batchbereitstellungsauftrag unter Verwendung der Identität erstellt, die mit dem Token verknüpft ist. Zu Testzwecken können Sie Ihre eigenen Anmeldedaten für den Aufruf verwenden, wie unten beschrieben.

    Verwenden Sie die Azure-Befehlszeilenschnittstelle, um sich entweder mit interaktiver oder Gerätecode-Authentifizierung anzumelden:

    az login

    Weitere Informationen über die Authentifizierung mit mehreren Arten von Berechtigungsnachweisen finden Sie unter Autorisierung auf Batch-Endpunkten.

  • Der Rechencluster, auf dem der Endpunkt eingerichtet ist, hat Zugriff auf die Eingabedaten.

    Tipp

    Wenn Sie einen Datenspeicher ohne Anmeldeinformationen oder ein externes Azure-Speicherkonto als Dateneingabe verwenden, stellen Sie sicher, dass Sie Compute-Cluster für den Datenzugriff konfigurieren. Die verwaltete Identität des Rechenclusters wird für die Einbindung des Speicherkontos verwendet. Die Identität des Auftrags (Aufrufer) wird weiterhin zum Lesen der zugrunde liegenden Daten verwendet, so dass Sie eine granulare Zugriffskontrolle erreichen können.

Grundlagen zum Erstellen von Aufträgen

Um einen Auftrag aus einem Batchendpunkt zu erstellen, müssen Sie ihn aufrufen. Aufrufe können mithilfe der Azure CLI, des Azure Machine Learning SDK für Python oder eines REST-API-Aufrufs erfolgen. Die folgenden Beispiele zeigen die Grundlagen des Aufrufs für einen Batchendpunkt, der einen einzelnen Eingabedatenordner zur Verarbeitung empfängt. Beispiele mit unterschiedlichen Eingaben und Ausgaben finden Sie unter Eingaben und Ausgaben verstehen.

Verwenden Sie den invoke-Vorgang unter Batchendpunkten:

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                            --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data

Aufrufen einer bestimmten Bereitstellung

Batch-Endpunkte können mehrere Bereitstellungen unter demselben Endpunkt hosten. Der Standardendpunkt wird verwendet, sofern der Benutzer nichts anderes angibt. Sie können den verwendeten Einsatz wie folgt ändern:

Verwenden Sie das Argument --deployment-name oder -d, um den Namen der Bereitstellung anzugeben:

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                            --deployment-name $DEPLOYMENT_NAME \
                            --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data

Konfigurieren der Jobeigenschaften

Sie können einige der Eigenschaften im erstellten Auftrag zum Aufruf konfigurieren.

Hinweis

Das Konfigurieren von Auftragseigenschaften ist nur in Batchendpunkten mit Pipelinekomponentenbereitstellungen im Moment verfügbar.

Konfigurieren des Experimentnamens

Verwenden Sie das Argument --experiment-name, um den Namen des Experiments anzugeben:

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
                            --experiment-name "my-batch-job-experiment" \
                            --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data

Verstehen von Eingaben und Ausgaben

Batchendpunkte bieten eine dauerhafte API, die Consumer zum Erstellen von Batchaufträgen verwenden können. Dieselbe Schnittstelle kann verwendet werden, um die Eingaben und Ausgaben anzugeben, die Ihre Bereitstellung erwartet. Verwenden Sie Eingaben, um alle Informationen zu übergeben, die Ihr Endpunkt zum Ausführen des Auftrags benötigt.

Diagramm der Verwendung von In- und Outputs in Batch-Endpunkten.

Batch-Endpunkte unterstützen zwei Arten von Eingaben:

  • Dateneingaben, die Zeiger auf einen bestimmten Speicherort oder ein Azure Machine Learning-Asset sind.
  • Literale Eingaben, d.h. literale Werte (wie Zahlen oder Zeichenketten), die Sie an den Auftrag übergeben wollen.

Anzahl und Typ der Eingaben und Ausgaben hängen vom Typ der Batchbereitstellung ab. Modellimplementierungen erfordern immer eine Dateneingabe und erzeugen eine Datenausgabe. Literaleingaben werden nicht unterstützt. Die Bereitstellung von Pipelinekomponenten bietet jedoch ein allgemeineres Konstrukt zum Erstellen von Endpunkten und ermöglichen es Ihnen, eine beliebige Anzahl von Eingaben (Daten und Literal) und Ausgaben anzugeben.

In der folgenden Tabelle sind die Eingaben und Ausgaben für Batch-Bereitstellungen zusammengefasst:

Bereitstellungstyp Nummer der Eingabe Unterstützte Typen der Eingabe Nummer der Ausgabe Unterstützte Typen der Ausgabe
Modellimplementierung 1 Dateneingaben 1 Datenausgaben
Einsatz von Pipeline-Komponenten [0..N] Dateneingaben und Literaleingaben [0..N] Datenausgaben

Tipp

Eingaben und Ausgaben sind immer benannt. Diese Namen dienen als Schlüssel, um sie zu identifizieren und den tatsächlichen Wert während des Aufrufs zu übergeben. Da bei Modellimplementierungen immer eine Eingabe und eine Ausgabe erforderlich sind, wird der Name während des Aufrufs ignoriert. Sie können einen Namen vergeben, der Ihren Anwendungsfall am besten beschreibt, z. B. „sales_estimation“.

Dateneingaben

Dateneingaben beziehen sich auf Eingaben, die auf einen Speicherort verweisen, an dem Daten platziert sind. Da Batchendpunkte in der Regel große Datenmengen verbrauchen, können Sie die Eingabedaten nicht als Teil der Aufrufanforderung übergeben. Stattdessen geben Sie den Speicherort an, an dem der Batch-Endpunkt nach den Daten suchen soll. Eingabedaten werden eingebunden und auf der Zielcompute gestreamt, um die Leistung zu verbessern.

Batchendpunkte unterstützen das Lesen von Dateien in den folgenden Speicheroptionen:

  • Azure Machine Learning Data Assets, einschließlich Ordner (uri_folder) und Datei (uri_file).
  • Azure Machine Learning Data Stores, einschließlich Azure Blob Storage, Azure Data Lake Storage Gen1 und Azure Data Lake Storage Gen2.
  • Azure Storage Accounts, einschließlich Azure Data Lake Storage Gen1, Azure Data Lake Storage Gen2 und Azure Blob Storage.
  • Lokale Datenordner/Dateien (Azure Machine Learning CLI oder Azure Machine Learning SDK für Python). Dieser Vorgang führt jedoch dazu, dass die lokalen Daten in den standardmäßigen Azure Machine Learning-Datenspeicher des Arbeitsbereichs hochgeladen werden, an dem Sie gerade arbeiten.

Wichtig

Hinweis zu veralteten Funktionen: Datasets des Typs FileDataset (V1) wurden als veraltet eingestuft und werden in Zukunft eingestellt. Vorhandene Batchendpunkte, die auf diese Funktionalität angewiesen sind, funktionieren weiterhin, aber Batchendpunkte, die mit GA CLIv2 (2.4.0 und höher) oder der GA-REST-API (2022-05-01 und höher) erstellt wurden, unterstützen keine V1-Datasets.

Literaleingaben

Literaleingaben beziehen sich auf Eingaben, die zur Aufrufzeit dargestellt und aufgelöst werden können, z. B. Zeichenfolgen, Zahlen und boolesche Werte. In der Regel verwenden Sie Literaleingaben, um Parameter als Teil der Bereitstellung einer Pipelinekomponente an Ihren Endpunkt zu übergeben. Batchendpunkte unterstützen die folgenden Literaltypen:

  • string
  • boolean
  • float
  • integer

Wörtliche Eingaben werden nur bei der Bereitstellung von Pipelinekomponenten unterstützt. Siehe Erstellen von Aufträgen mit literalen Eingaben, um zu erfahren, wie man sie angibt.

Datenausgaben

Datenausgaben beziehen sich auf den Speicherort, an dem die Ergebnisse eines Batchauftrags platziert werden sollen. Ausgaben werden anhand des Namens identifiziert, und Azure Machine Learning weist jeder benannten Ausgabe automatisch einen eindeutigen Pfad zu. Sie können jedoch bei Bedarf einen anderen Pfad angeben.

Wichtig

Batchendpunkte unterstützen nur das Schreiben von Ausgaben in Azure Blob Storage-Datenspeichern. Wenn Sie in ein Speicherkonto schreiben müssen, für das hierarchische Namespaces aktiviert sind (auch als Azure Datalake Gen2 oder ADLS Gen2 bezeichnet), beachten Sie, dass dieser Speicherdienst als Azure Blob Storage-Datenspeicher registriert werden kann, da die Dienste vollständig kompatibel sind. Auf diese Weise können Sie Ausgaben von Batchendpunkten in ADLS Gen2 schreiben.

Aufträge mit Dateneingabe erstellen

Die folgenden Beispiele zeigen, wie Aufträge erstellt werden, die Dateneingaben von Datenbeständen, Datenspeichern und Azure Storage Accounts übernehmen.

Eingangsdaten aus einer Datenressource

Azure Machine Learning-Datenressourcen (ehemals als Datasets bezeichnet) werden als Eingaben für Aufträge unterstützt. Führen Sie die folgenden Schritte aus, um einen Batchendpunktauftrag mit Daten auszuführen, die in einer registrierten Datenressource in Azure Machine Learning gespeichert sind:

Warnung

Datenressourcen des Typs „Tabelle“ (MLTable) werden derzeit nicht unterstützt.

  1. Erstellen Sie zunächst die Datenressource: Diese Datenressource besteht aus einem Ordner mit mehreren CSV-Dateien, die Sie mithilfe von Batch-Endpunkten parallel verarbeiten werden. Sie können diesen Schritt überspringen, wenn Ihre Daten bereits als Datenressource registriert sind.

    Erstellen Sie eine Datenressourcendefinition in YAML:

    heart-dataset-unlabeled.yml

    $schema: https://azuremlschemas.azureedge.net/latest/data.schema.json
name: heart-dataset-unlabeled
description: An unlabeled dataset for heart classification.
type: uri_folder
path: heart-classifier-mlflow/data

    Erstellen Sie dann die Datenressource:

    az ml data create -f heart-dataset-unlabeled.yml

  2. Erstellen Sie die Eingabe oder Anfrage:

    DATASET_ID=$(az ml data show -n heart-dataset-unlabeled --label latest | jq -r .id)

    Hinweis

    Die Datenressourcen-ID würde wie /subscriptions/<subscription>/resourcegroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace>/data/<data-asset>/versions/<version> aussehen. Sie können auch azureml:/<datasset_name>@latest als Möglichkeit zur Angabe der Eingabe verwenden.

  3. Führen Sie den Endpunkt aus:

    Verwenden Sie das --set-Argument, um die Eingabe anzugeben:

    az ml batch-endpoint invoke --name $ENDPOINT_NAME \
    --set inputs.heart_dataset.type="uri_folder" inputs.heart_dataset.path=$DATASET_ID

    Für einen Endpunkt, der einer Modellbereitstellung dient, können Sie das --input-Argument verwenden, um die Dateneingabe anzugeben, da für eine Modellbereitstellung immer nur eine Dateneingabe erforderlich ist.

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --input $DATASET_ID

    Das Argument --set neigt dazu, lange Befehle zu erzeugen, wenn mehrere Eingaben angegeben werden. Platzieren Sie in solchen Fällen Ihre Eingaben in einer YAML-Datei und verwenden Sie --file, um die Eingaben anzugeben, die Sie für Ihren Endpunktaufruf benötigen.

    inputs.yml

    inputs:
  heart_dataset: azureml:/<datasset_name>@latest

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --file inputs.yml

Eingangsdaten aus Datenspeichern

Auf Daten aus in Azure Machine Learning registrierten Datenspeichern kann direkt von Batchbereitstellungsaufträgen verwiesen werden. In diesem Beispiel laden Sie zunächst einige Daten in den Standarddatenspeicher im Azure Machine Learning-Arbeitsbereich hoch und führen dann eine Batch-Bereitstellung für diese Daten aus. Führen Sie die folgenden Schritte aus, um einen Batch-Endpunktauftrag mithilfe von Daten auszuführen, die in einem Datenspeicher gespeichert sind.

  1. Greifen Sie auf den Standard-Datenspeicher im Azure Machine Learning-Arbeitsbereich zu. Wenn sich Ihre Daten in einem anderen Speicher befinden, können Sie stattdessen diesen Speicher verwenden. Sie müssen den Standarddatenspeicher nicht verwenden.

    DATASTORE_ID=$(az ml datastore show -n workspaceblobstore | jq -r '.id')

    Hinweis

    Die ID des Datenspeichers würde so aussehen: /subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace>/datastores/<data-store>.

    Tipp

    Der standardmäßige Blobdatenspeicher in einem Arbeitsbereich lautet workspaceblobstore. Sie können diesen Schritt überspringen, wenn Sie die Ressourcen-ID des Standarddatenspeichers in Ihrem Arbeitsbereich bereits kennen.

  2. Sie müssen einige Beispieldaten in den Datenspeicher hochladen. In diesem Beispiel wird davon ausgegangen, dass Sie die Beispieldaten aus dem Repository im Ordner sdk/python/endpoints/batch/deploy-models/heart-classifier-mlflow/data in den Ordner heart-disease-uci-unlabeled im Blob-Speicherkonto hochgeladen haben. Vergewissern Sie sich, dass Sie dies erledigt haben, bevor Sie weitermachen.

  3. Erstellen Sie die Eingabe oder Anfrage:

    Geben Sie den Dateipfad in die folgende Variable ein:

    DATA_PATH="heart-disease-uci-unlabeled"
INPUT_PATH="$DATASTORE_ID/paths/$DATA_PATH"

    Hinweis

    Sehen Sie sich an, wie der Pfad paths an die Ressourcen-ID des Datenspeichers angefügt wird, um anzugeben, dass im Folgenden ein Pfad darin enthalten ist.

    Tipp

    Sie können auch azureml://datastores/<data-store>/paths/<data-path> als Möglichkeit zur Angabe der Eingabe verwenden.

  4. Führen Sie den Endpunkt aus:

    Verwenden Sie das --set-Argument, um die Eingabe anzugeben:

    az ml batch-endpoint invoke --name $ENDPOINT_NAME \
    --set inputs.heart_dataset.type="uri_folder" inputs.heart_dataset.path=$INPUT_PATH

    Für einen Endpunkt, der einer Modellbereitstellung dient, können Sie das --input-Argument verwenden, um die Dateneingabe anzugeben, da für eine Modellbereitstellung immer nur eine Dateneingabe erforderlich ist.

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --input $INPUT_PATH --input-type uri_folder

    Das Argument --set neigt dazu, lange Befehle zu erzeugen, wenn mehrere Eingaben angegeben werden. Platzieren Sie in solchen Fällen Ihre Eingaben in einer YAML-Datei und verwenden Sie --file, um die Eingaben anzugeben, die Sie für Ihren Endpunktaufruf benötigen.

    inputs.yml

    inputs:
  heart_dataset:
    type: uri_folder
    path: azureml://datastores/<data-store>/paths/<data-path>

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --file inputs.yml

    Wenn es sich bei Ihren Daten um eine Datei handelt, verwenden Sie stattdessen uri_file als Typ.

Eingangsdaten aus Azure Storage-Konten

Azure Machine Learning-Batchendpunkte können Daten aus Cloudstandorten in Azure Storage-Konten lesen, sowohl öffentliche als auch private. Führen Sie die folgenden Schritte aus, um einen Batchendpunktauftrag mit Daten auszuführen, die in einem Speicherkonto gespeichert sind:

Hinweis

Im Abschnitt Konfiguration von Compute-Clustern für den Datenzugriff erfahren Sie mehr über die zusätzliche Konfiguration, die für das erfolgreiche Lesen von Daten aus Speicherkonten erforderlich ist.

  1. Erstellen Sie die Eingabe oder Anfrage:

    INPUT_DATA = "https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data"

    Wenn Ihre Daten als Datei vorliegen:

    INPUT_DATA = "https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data/heart.csv"

  2. Führen Sie den Endpunkt aus:

    Verwenden Sie das --set-Argument, um die Eingabe anzugeben:

    az ml batch-endpoint invoke --name $ENDPOINT_NAME \
    --set inputs.heart_dataset.type="uri_folder" inputs.heart_dataset.path=$INPUT_DATA

    Für einen Endpunkt, der einer Modellbereitstellung dient, können Sie das --input-Argument verwenden, um die Dateneingabe anzugeben, da für eine Modellbereitstellung immer nur eine Dateneingabe erforderlich ist.

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --input $INPUT_DATA --input-type uri_folder

    Das Argument --set neigt dazu, lange Befehle zu erzeugen, wenn mehrere Eingaben angegeben werden. Platzieren Sie in solchen Fällen Ihre Eingaben in einer YAML-Datei und verwenden Sie --file, um die Eingaben anzugeben, die Sie für Ihren Endpunktaufruf benötigen.

    inputs.yml

    inputs:
  heart_dataset:
    type: uri_folder
    path: https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data

    az ml batch-endpoint invoke --name $ENDPOINT_NAME --file inputs.yml

    Wenn es sich bei Ihren Daten um eine Datei handelt, verwenden Sie stattdessen uri_file als Typ.

Arbeitsplätze mit wörtlichen Eingaben schaffen

Für die Bereitstellung von Pipeline-Komponenten können wörtliche Eingaben verwendet werden. Das folgende Beispiel zeigt, wie eine Eingabe namens score_mode, vom Typ string und mit einem Wert von append angegeben wird:

Platzieren Sie Ihre Eingaben in einer YAML-Datei, und verwenden Sie --file, um die Eingaben zu spezifizieren, die Sie für Ihren Endpunktaufruf benötigen.

inputs.yml

inputs:
  score_mode:
    type: string
    default: append

az ml batch-endpoint invoke --name $ENDPOINT_NAME --file inputs.yml

Sie können das Argument --set auch verwenden, um den Wert anzugeben. Allerdings neigt es dazu, lange Befehle zu erzeugen, wenn mehrere Eingaben gemacht werden:

az ml batch-endpoint invoke --name $ENDPOINT_NAME \
    --set inputs.score_mode.type="string" inputs.score_mode.default="append"

Aufträge mit Datenausgaben erstellen

Das folgende Beispiel zeigt, wie Sie den Speicherort für eine Ausgabe mit dem Namen score ändern können. Der Vollständigkeit halber konfigurieren diese Beispiele auch eine Eingabe mit dem Namen heart_dataset.

  1. Verwenden Sie den Standarddatenspeicher im Azure Machine Learning-Arbeitsbereich verwenden, um die Ausgaben zu speichern. Sie können jeden anderen Datenspeicher in Ihrem Arbeitsbereich verwenden, solange es sich um ein Blobspeicherkonto handelt.

    DATASTORE_ID=$(az ml datastore show -n workspaceblobstore | jq -r '.id')

    Hinweis

    Die ID des Datenspeichers würde so aussehen: /subscriptions/<subscription>/resourceGroups/<resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<workspace>/datastores/<data-store>.

  2. Erstellen Sie eine Datenausgabe:

    DATA_PATH="batch-jobs/my-unique-path"
OUTPUT_PATH="$DATASTORE_ID/paths/$DATA_PATH"

    Erstellen Sie der Vollständigkeit halber auch eine Dateneingabe:

    INPUT_PATH="https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data"

    Hinweis

    Sehen Sie sich an, wie der Pfad paths an die Ressourcen-ID des Datenspeichers angefügt wird, um anzugeben, dass im Folgenden ein Pfad darin enthalten ist.

  3. Führen Sie die Bereitstellung aus:

    Verwenden Sie das Argument --set , um die Eingabe zu spezifizieren:

    az ml batch-endpoint invoke --name $ENDPOINT_NAME \
    --set inputs.heart_dataset.path=$INPUT_PATH \
    --set outputs.score.path=$OUTPUT_PATH

Nächste Schritte