Freigeben über

Nutzen eines als Webdienst bereitgestellten Azure Machine Learning-Modells

  • Artikel

Durch die Bereitstellung eines Azure Machine Learning-Modells als Webdienst wird ein REST-API-Endpunkt erstellt. Sie können Daten an diesen Endpunkt senden und die vom Modell zurückgegebene Vorhersage empfangen. In diesem Dokument erfahren Sie, wie Sie Clients für den Webdienst mithilfe von C#, Go, Java und Python erstellen.

Sie erstellen einen Webdienst, wenn Sie ein Modell in Ihrer lokalen Umgebung oder für Azure Container Instances oder Azure Kubernetes Service bereitstellen. Der URI für den Zugriff auf den Webdienst kann über das Azure Machine Learning SDK abgerufen werden. Wenn die Authentifizierung aktiviert ist, können Sie das SDK auch zum Abrufen der Authentifizierungsschlüssel oder -token verwenden.

Dies ist der allgemeine Workflow zum Erstellen eines Clients, der einen Machine Learning-Webdienst verwendet:

  1. Verwenden des SDK zum Abrufen der Verbindungsinformationen
  2. Festlegen des Typs der vom Modell verwendeten Anforderungsdaten
  3. Erstellen einer Anwendung, die den Webdienst aufruft

Tipp

Die Beispiele in diesem Dokument werden ohne Verwendung von OpenAPI-Spezifikationen (Swagger) manuell erstellt. Wenn Sie eine OpenAPI-Spezifikation für Ihre Bereitstellung aktiviert haben, können Sie mit Tools wie swagger-codegen Clientbibliotheken für Ihren Dienst erstellen.

Wichtig

Einige Azure CLI-Befehle in diesem Artikel verwenden die Erweiterung azure-cli-ml oder v1 für Azure Machine Learning. Der Support für die v1-Erweiterung endet am 30. September 2025. Sie können die v1-Erweiterung bis zu diesem Datum installieren und verwenden.

Es wird empfohlen, vor dem 30. September 2025 zur ml- oder v2-Erweiterung zu wechseln. Weitere Informationen zur v2-Erweiterung finden Sie unter Was sind die Azure Machine Learning CLI und das Python SDK v2?.

Verbindungsinformationen

Hinweis

Verwenden Sie das Azure Machine Learning SDK zum Abrufen der Webdienstinformationen. Dies ist ein Python SDK. Sie können eine beliebige Sprache verwenden, um einen Client für den Dienst zu erstellen.

Die azureml.core.Webservice-Klasse stellt die erforderlichen Informationen zum Erstellen eines Clients bereit. Die folgenden Webservice-Eigenschaften sind hilfreich, wenn Sie eine Clientanwendung erstellen:

  • auth_enabled: Wenn Schlüsselauthentifizierung aktiviert ist True, andernfalls False.
  • token_auth_enabled: Wenn Tokenauthentifizierung aktiviert ist True, andernfalls False.
  • scoring_uri: Die REST-API-Adresse.
  • swagger_uri: Die Adresse der OpenAPI-Spezifikation. Dieser URI ist verfügbar, wenn Sie die automatische Schemagenerierung aktiviert haben. Weitere Informationen finden Sie unter Bereitstellen von Modellen mit Azure Machine Learning.

Es gibt mehrere Möglichkeiten, diese Informationen für bereitgestellte Webdienste abzurufen:

GILT FÜR: Python SDK azureml v1

  • Wenn Sie ein Modell bereitstellen, wird ein Webservice-Objekt mit Informationen über den Dienst zurückgegeben:

    service = Model.deploy(ws, "myservice", [model], inference_config, deployment_config)
service.wait_for_deployment(show_output = True)
print(service.scoring_uri)
print(service.swagger_uri)

  • Mit Webservice.list können Sie eine Liste bereitgestellter Webdienste für Modelle in Ihrem Arbeitsbereich abrufen. Sie können Filter hinzufügen, um die Liste der zurückgegebenen Informationen einzugrenzen. Weitere Informationen zu den möglichen Filtern finden Sie in der Referenzdokumentation Webservice.list.

    services = Webservice.list(ws)
print(services[0].scoring_uri)
print(services[0].swagger_uri)

  • Wenn Sie den Namen des bereitgestellten Diensts kennen, können Sie eine neue Instanz von Webservice erstellen und den Arbeitsbereich und den Dienstnamen als Parameter angeben. Dieses neue Objekt enthält Informationen über den bereitgestellten Dienst.

    service = Webservice(workspace=ws, name='myservice')
print(service.scoring_uri)
print(service.swagger_uri)

Die folgende Tabelle zeigt, wie diese URIs aussehen:

URI-Typ Beispiel
Bewertungs-URI http://104.214.29.152:80/api/v1/service/<service-name>/score
Swagger-URI http://104.214.29.152/api/v1/service/<service-name>/swagger.json

Tipp

Die IP-Adresse wird für Ihre Bereitstellung unterschiedlich sein. Jeder AKS-Cluster hat seine eigene IP-Adresse, die von den Bereitstellungen in diesem Cluster gemeinsam genutzt wird.

Geschützter Webdienst

Wenn Sie den bereitgestellten Webdienst mit einem TSL/SSL-Zertifikat geschützt haben, können Sie über HTTPS eine Verbindung mit dem Dienst unter Verwendung des Bewertungs- oder Swagger-URIs herstellen. Mit HTTPS wird die Kommunikation zwischen einem Client und einem Webdienst geschützt, indem sie verschlüsselt wird. Die Verschlüsselung verwendet Transport Layer Security (TLS). In einigen Fällen wird TLS immer noch als Secure Sockets Layer (SSL) bezeichnet, der Vorgänger von TLS.

Wichtig

Über Azure Machine Learning bereitgestellte Webdienste unterstützen nur TLS-Version 1.2. Stellen Sie beim Erstellen einer Clientanwendung sicher, dass diese Version unterstützt wird.

Weitere Informationen finden Sie unter Verwenden von TLS zum Absichern eines Webdiensts mit Azure Machine Learning.

Authentifizierung für Dienste

Azure Machine Learning bietet zwei Möglichkeiten zur Steuerung des Zugriffs auf Ihre Webdienste.

Authentifizierungsmethode ACI AKS
Schlüssel Standardmäßig deaktiviert Standardmäßig aktiviert
Token Nicht verfügbar. Standardmäßig deaktiviert

Verwenden Sie beim Senden einer Anforderung an einen Dienst, der mit einem Schlüssel oder Token gesichert ist, den Authorization-Header, um den Schlüssel oder das Token zu übergeben. Der Schlüssel oder das Token muss als Bearer <key-or-token> formatiert sein, wobei <key-or-token> der Schlüssel- oder Tokenwert ist.

Der primäre Unterschied zwischen Schlüsseln und Token besteht darin, dass Schlüssel statisch sind und manuell neu generiert werden können und Token bei Ablauf aktualisiert werden müssen. Die schlüsselbasierte Authentifizierung wird für Webdienste unterstützt, die über Azure Container Instances und Azure Kubernetes Service bereitgestellt werden. Die tokenbasierte Authentifizierung ist nur für Azure Kubernetes Service-Bereitstellungen verfügbar. Weitere Informationen zum Konfigurieren der Authentifizierung finden Sie unter Konfigurieren der Authentifizierung für Modelle, die als Webdienst bereitgestellt werden.

Authentifizierung mit Schlüsseln

Wenn Sie Authentifizierung für eine Bereitstellung aktivieren, werden automatisch Authentifizierungsschlüssel erstellt.

  • Die Authentifizierung ist standardmäßig aktiviert, wenn Sie Azure Kubernetes Service bereitstellen.
  • Die Authentifizierung ist standardmäßig deaktiviert, wenn Sie Azure Containerinstanz bereitstellen.

Um die Authentifizierung zu steuern, verwenden Sie den auth_enabled Parameter beim Erstellen oder Aktualisieren einer Bereitstellung.

Wenn die Authentifizierung aktiviert ist, können Sie mithilfe der Methode get_keys einen primären und einen sekundären Authentifizierungsschlüssel abrufen:

primary, secondary = service.get_keys()
print(primary)

Wichtig

Wenn Sie einen Schlüssel erneut generieren müssen, verwenden Sie service.regen_key.

Authentifizierung mit Tokens

Wenn Sie die Tokenauthentifizierung für einen Webdienst aktivieren, muss ein Benutzer ein Azure Machine Learning JWT-Token für den Webdienst bereitstellen, um darauf zugreifen zu können.

  • Die Tokenauthentifizierung ist standardmäßig deaktiviert, wenn Sie Azure Kubernetes Service bereitstellen.
  • Die Tokenauthentifizierung wird bei der Bereitstellung in Azure Containerinstanzes nicht unterstützt.

Um die Tokenauthentifizierung zu steuern, verwenden Sie den token_auth_enabled Parameter beim Erstellen oder Aktualisieren einer Bereitstellung.

Wenn die Tokenauthentifizierung aktiviert ist, können Sie mithilfe der Methode get_token ein Bearertoken und dessen Ablaufzeit abrufen:

token, refresh_by = service.get_token()
print(token)

Wenn Sie über die Azure CLI und die Machine-Learning-Erweiterung verfügen, können Sie den folgenden Befehl zum Abrufen eines Tokens verwenden:

GILT FÜR: Azure CLI-ML-Erweiterung v1

az ml service get-access-token -n <service-name>

Wichtig

Aktuell besteht der einzige Weg, das Token abzurufen, darin, das Azure Machine Learning-SDK oder die Azure CLI-Machine-Learning-Erweiterung zu verwenden.

Nach Ablauf der für refresh_by festgelegten Zeit müssen Sie ein neues Token anfordern.

Anforderungsdaten

Die REST-API erwartet als Hauptteil der Anforderung ein JSON-Dokument mit der folgenden Struktur:

{
    "data":
        [
            <model-specific-data-structure>
        ]
}

Wichtig

Die Struktur der Daten muss dem entsprechen, was vom Bewertungsskript und vom Modell im Dienst erwartet wird. Die Daten können vor der Übergabe an das Modell vom Bewertungsskript geändert werden.

Binärdaten

Informationen zum Aktivieren der Unterstützung für Binärdaten in Ihrem Dienst finden Sie unter Binärdaten.

Tipp

Die Aktivierung der Unterstützung für Binärdaten erfolgt in der Datei „score.py“, die vom bereitgestellten Modell verwendet wird. Verwenden Sie über den Client die HTTP-Funktionalität Ihrer Programmiersprache. Mit dem folgenden Codeausschnitt wird der Inhalt einer JPG-Datei beispielsweise an einen Webdienst gesendet:

import requests
# Load image data
data = open('example.jpg', 'rb').read()
# Post raw data to scoring URI
res = request.post(url='<scoring-uri>', data=data, headers={'Content-Type': 'application/> octet-stream'})

Ressourcenfreigabe zwischen verschiedenen Ursprüngen (Cross-Origin Resource Sharing, CORS)

Informationen zum Aktivieren der CORS-Unterstützung in Ihrem Dienst finden Sie unter Ressourcenfreigabe zwischen verschiedenen Ursprüngen (Cross-Origin Resource Sharing).

Aufrufen des Diensts (C#)

In diesem Beispiel wird die Verwendung von C# zum Aufrufen des Webdiensts veranschaulicht, der im Beispiel Train within notebook erstellt wurde:

using System;
using System.Collections.Generic;
using System.IO;
using System.Net.Http;
using System.Net.Http.Headers;
using Newtonsoft.Json;

namespace MLWebServiceClient
{
    // The data structure expected by the service
    internal class InputData
    {
        [JsonProperty("data")]
        // The service used by this example expects an array containing
        //   one or more arrays of doubles
        internal double[,] data;
    }
    class Program
    {
        static void Main(string[] args)
        {
            // Set the scoring URI and authentication key or token
            string scoringUri = "<your web service URI>";
            string authKey = "<your key or token>";

            // Set the data to be sent to the service.
            // In this case, we are sending two sets of data to be scored.
            InputData payload = new InputData();
            payload.data = new double[,] {
                {
                    0.0199132141783263,
                    0.0506801187398187,
                    0.104808689473925,
                    0.0700725447072635,
                    -0.0359677812752396,
                    -0.0266789028311707,
                    -0.0249926566315915,
                    -0.00259226199818282,
                    0.00371173823343597,
                    0.0403433716478807
                },
                {
                    -0.0127796318808497, 
                    -0.044641636506989, 
                    0.0606183944448076, 
                    0.0528581912385822, 
                    0.0479653430750293, 
                    0.0293746718291555, 
                    -0.0176293810234174, 
                    0.0343088588777263, 
                    0.0702112981933102, 
                    0.00720651632920303
                }
            };

            // Create the HTTP client
            HttpClient client = new HttpClient();
            // Set the auth header. Only needed if the web service requires authentication.
            client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", authKey);

            // Make the request
            try {
                var request = new HttpRequestMessage(HttpMethod.Post, new Uri(scoringUri));
                request.Content = new StringContent(JsonConvert.SerializeObject(payload));
                request.Content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
                var response = client.SendAsync(request).Result;
                // Display the response from the web service
                Console.WriteLine(response.Content.ReadAsStringAsync().Result);
            }
            catch (Exception e)
            {
                Console.Out.WriteLine(e.Message);
            }
        }
    }
}

Die zurückgegebenen Ergebnisse ähneln dem folgenden JSON-Dokument:

[217.67978776218715, 224.78937091757172]

Aufrufen des Diensts (Go)

In diesem Beispiel wird die Verwendung von Go zum Aufrufen des Webdiensts veranschaulicht, der im Beispiel Train within notebook erstellt wurde:

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
)

// Features for this model are an array of decimal values
type Features []float64

// The web service input can accept multiple sets of values for scoring
type InputData struct {
    Data []Features `json:"data",omitempty`
}

// Define some example data
var exampleData = []Features{
    []float64{
        0.0199132141783263, 
        0.0506801187398187, 
        0.104808689473925, 
        0.0700725447072635, 
        -0.0359677812752396, 
        -0.0266789028311707, 
        -0.0249926566315915, 
        -0.00259226199818282, 
        0.00371173823343597, 
        0.0403433716478807,
    },
    []float64{
        -0.0127796318808497, 
        -0.044641636506989, 
        0.0606183944448076, 
        0.0528581912385822, 
        0.0479653430750293, 
        0.0293746718291555, 
        -0.0176293810234174, 
        0.0343088588777263, 
        0.0702112981933102, 
        0.00720651632920303,
    },
}

// Set to the URI for your service
var serviceUri string = "<your web service URI>"
// Set to the authentication key or token (if any) for your service
var authKey string = "<your key or token>"

func main() {
    // Create the input data from example data
    jsonData := InputData{
        Data: exampleData,
    }
    // Create JSON from it and create the body for the HTTP request
    jsonValue, _ := json.Marshal(jsonData)
    body := bytes.NewBuffer(jsonValue)

    // Create the HTTP request
    client := &http.Client{}
    request, err := http.NewRequest("POST", serviceUri, body)
    request.Header.Add("Content-Type", "application/json")

    // These next two are only needed if using an authentication key
    bearer := fmt.Sprintf("Bearer %v", authKey)
    request.Header.Add("Authorization", bearer)

    // Send the request to the web service
    resp, err := client.Do(request)
    if err != nil {
        fmt.Println("Failure: ", err)
    }

    // Display the response received
    respBody, _ := ioutil.ReadAll(resp.Body)
    fmt.Println(string(respBody))
}

Die zurückgegebenen Ergebnisse ähneln dem folgenden JSON-Dokument:

[217.67978776218715, 224.78937091757172]

Aufrufen des Diensts (Java)

In diesem Beispiel wird die Verwendung von Java zum Aufrufen des Webdiensts veranschaulicht, der im Beispiel Train within notebook erstellt wurde:

import java.io.IOException;
import org.apache.http.client.fluent.*;
import org.apache.http.entity.ContentType;
import org.json.simple.JSONArray;
import org.json.simple.JSONObject;

public class App {
    // Handle making the request
    public static void sendRequest(String data) {
        // Replace with the scoring_uri of your service
        String uri = "<your web service URI>";
        // If using authentication, replace with the auth key or token
        String key = "<your key or token>";
        try {
            // Create the request
            Content content = Request.Post(uri)
            .addHeader("Content-Type", "application/json")
            // Only needed if using authentication
            .addHeader("Authorization", "Bearer " + key)
            // Set the JSON data as the body
            .bodyString(data, ContentType.APPLICATION_JSON)
            // Make the request and display the response.
            .execute().returnContent();
            System.out.println(content);
        }
        catch (IOException e) {
            System.out.println(e);
        }
    }
    public static void main(String[] args) {
        // Create the data to send to the service
        JSONObject obj = new JSONObject();
        // In this case, it's an array of arrays
        JSONArray dataItems = new JSONArray();
        // Inner array has 10 elements
        JSONArray item1 = new JSONArray();
        item1.add(0.0199132141783263);
        item1.add(0.0506801187398187);
        item1.add(0.104808689473925);
        item1.add(0.0700725447072635);
        item1.add(-0.0359677812752396);
        item1.add(-0.0266789028311707);
        item1.add(-0.0249926566315915);
        item1.add(-0.00259226199818282);
        item1.add(0.00371173823343597);
        item1.add(0.0403433716478807);
        // Add the first set of data to be scored
        dataItems.add(item1);
        // Create and add the second set
        JSONArray item2 = new JSONArray();
        item2.add(-0.0127796318808497);
        item2.add(-0.044641636506989);
        item2.add(0.0606183944448076);
        item2.add(0.0528581912385822);
        item2.add(0.0479653430750293);
        item2.add(0.0293746718291555);
        item2.add(-0.0176293810234174);
        item2.add(0.0343088588777263);
        item2.add(0.0702112981933102);
        item2.add(0.00720651632920303);
        dataItems.add(item2);
        obj.put("data", dataItems);

        // Make the request using the JSON document string
        sendRequest(obj.toJSONString());
    }
}

Die zurückgegebenen Ergebnisse ähneln dem folgenden JSON-Dokument:

[217.67978776218715, 224.78937091757172]

Aufrufen des Diensts (Python)

In diesem Beispiel wird die Verwendung von Python zum Aufrufen des Webdiensts veranschaulicht, der im Beispiel Train within notebook erstellt wurde:

import requests
import json

# URL for the web service
scoring_uri = '<your web service URI>'
# If the service is authenticated, set the key or token
key = '<your key or token>'

# Two sets of data to score, so we get two results back
data = {"data":
        [
            [
                0.0199132141783263,
                0.0506801187398187,
                0.104808689473925,
                0.0700725447072635,
                -0.0359677812752396,
                -0.0266789028311707,
                -0.0249926566315915,
                -0.00259226199818282,
                0.00371173823343597,
                0.0403433716478807
            ],
            [
                -0.0127796318808497,
                -0.044641636506989,
                0.0606183944448076,
                0.0528581912385822,
                0.0479653430750293,
                0.0293746718291555,
                -0.0176293810234174,
                0.0343088588777263,
                0.0702112981933102,
                0.00720651632920303]
        ]
        }
# Convert to JSON string
input_data = json.dumps(data)

# Set the content type
headers = {'Content-Type': 'application/json'}
# If authentication is enabled, set the authorization header
headers['Authorization'] = f'Bearer {key}'

# Make the request and display the response
resp = requests.post(scoring_uri, input_data, headers=headers)
print(resp.text)

Die zurückgegebenen Ergebnisse ähneln dem folgenden JSON-Dokument:

[217.67978776218715, 224.78937091757172]

Webdienst Schema (OpenAPI-Spezifikation)

Wenn Sie automatische Schemagenerierung mit Ihrer Bereitstellung verwendet haben, können Sie die Adresse der OpenAPI-Spezifikation für den Dienst mithilfe der swagger_uri-Eigenschaft abrufen. (Beispiel: print(service.swagger_uri).) Verwenden Sie eine GET-Anforderung, oder öffnen Sie den URI in einem Browser, um die Spezifikation abzurufen.

Das folgende JSON-Dokument ist ein Beispiel für ein Schema (OpenAPI-Spezifikation), das für eine Bereitstellung generiert wurde:

{
    "swagger": "2.0",
    "info": {
        "title": "myservice",
        "description": "API specification for Azure Machine Learning myservice",
        "version": "1.0"
    },
    "schemes": [
        "https"
    ],
    "consumes": [
        "application/json"
    ],
    "produces": [
        "application/json"
    ],
    "securityDefinitions": {
        "Bearer": {
            "type": "apiKey",
            "name": "Authorization",
            "in": "header",
            "description": "For example: Bearer abc123"
        }
    },
    "paths": {
        "/": {
            "get": {
                "operationId": "ServiceHealthCheck",
                "description": "Simple health check endpoint to ensure the service is up at any given point.",
                "responses": {
                    "200": {
                        "description": "If service is up and running, this response will be returned with the content 'Healthy'",
                        "schema": {
                            "type": "string"
                        },
                        "examples": {
                            "application/json": "Healthy"
                        }
                    },
                    "default": {
                        "description": "The service failed to execute due to an error.",
                        "schema": {
                            "$ref": "#/definitions/ErrorResponse"
                        }
                    }
                }
            }
        },
        "/score": {
            "post": {
                "operationId": "RunMLService",
                "description": "Run web service's model and get the prediction output",
                "security": [
                    {
                        "Bearer": []
                    }
                ],
                "parameters": [
                    {
                        "name": "serviceInputPayload",
                        "in": "body",
                        "description": "The input payload for executing the real-time machine learning service.",
                        "schema": {
                            "$ref": "#/definitions/ServiceInput"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "The service processed the input correctly and provided a result prediction, if applicable.",
                        "schema": {
                            "$ref": "#/definitions/ServiceOutput"
                        }
                    },
                    "default": {
                        "description": "The service failed to execute due to an error.",
                        "schema": {
                            "$ref": "#/definitions/ErrorResponse"
                        }
                    }
                }
            }
        }
    },
    "definitions": {
        "ServiceInput": {
            "type": "object",
            "properties": {
                "data": {
                    "type": "array",
                    "items": {
                        "type": "array",
                        "items": {
                            "type": "integer",
                            "format": "int64"
                        }
                    }
                }
            },
            "example": {
                "data": [
                    [ 10, 9, 8, 7, 6, 5, 4, 3, 2, 1 ]
                ]
            }
        },
        "ServiceOutput": {
            "type": "array",
            "items": {
                "type": "number",
                "format": "double"
            },
            "example": [
                3726.995
            ]
        },
        "ErrorResponse": {
            "type": "object",
            "properties": {
                "status_code": {
                    "type": "integer",
                    "format": "int32"
                },
                "message": {
                    "type": "string"
                }
            }
        }
    }
}

Weitere Informationen finden Sie in der OpenAPI-Spezifikation.

Ein Hilfsprogramm, das Clientbibliotheken aus der Spezifikation erstellen kann, finden Sie unter swagger-codegen.

Tipp

Sie können das JSON-Schemadokument abrufen, nachdem Sie den Dienst bereitgestellt haben. Verwenden Sie die swagger_uri-Eigenschaft des bereitgestellten Webdiensts (beispielsweise service.swagger_uri), um den URI für die Swagger-Datei des lokalen Webdiensts abzurufen.

Nutzen des Diensts aus Power BI

Power BI unterstützt die Nutzung von Azure Machine Learning-Webdiensten, um die Daten in Power BI um Vorhersagen zu erweitern.

Zum Generieren eines Webdiensts, der für die Nutzung in Power BI unterstützt wird, muss das Schema das für Power BI benötigte Format unterstützen. Informieren Sie sich über die Erstellung eines von Power BI unterstützten Schemas.

Nachdem der Webdienst bereitgestellt wurde, kann er über Power BI-Dataflows genutzt werden. Informieren Sie sich über die Integration von Azure Machine Learning in Power BI (Vorschau).

Nächste Schritte

Eine Referenzarchitektur für die Echtzeitbewertung von Python und Deep Learning-Modellen finden Sie im Azure Architecture Center.