Korzystanie z modelu usługi Azure Machine Learning wdrożonego jako usługa internetowa

Wdrożenie modelu usługi Azure Machine Learning jako usługi internetowej powoduje utworzenie punktu końcowego interfejsu API REST. Można wysłać dane do tego punktu końcowego i otrzymać prognozę zwróconą przez model. Z tego dokumentu dowiesz się, jak tworzyć klientów dla usługi internetowej przy użyciu języków C#, Go, Java i Python.

Usługa sieci Web jest tworzona podczas wdrażania modelu w środowisku lokalnym, Azure Container Instances, Azure Kubernetes Service lub programowalnych w terenie macierzy bramek (FPGA). Identyfikator URI używany do uzyskiwania dostępu do usługi internetowej jest pobierany przy użyciu zestawu SDK usługi Azure Machine Learning. Jeśli uwierzytelnianie jest włączone, możesz również użyć zestawu SDK, aby uzyskać klucze uwierzytelniania lub tokeny.

Ogólny przepływ pracy tworzenia klienta korzystającego z usługi sieci Web uczenia maszynowego to:

1. Użyj zestawu SDK, aby uzyskać informacje o połączeniu.
2. Ustal typ danych żądania używanych przez model.
3. Utwórz aplikację wywołującą usługę internetową.

Porada

Przykłady w tym dokumencie są tworzone ręcznie bez użycia specyfikacji openAPI (Swagger). Jeśli włączono specyfikację interfejsu OpenAPI dla wdrożenia, możesz użyć narzędzi, takich jak swagger-codegen , aby utworzyć biblioteki klienta dla usługi.

Ważne

Niektóre polecenia interfejsu wiersza polecenia platformy Azure w tym artykule używają azure-cli-mlrozszerzenia , lub v1 dla usługi Azure Machine Learning. Obsługa rozszerzenia w wersji 1 zakończy się 30 września 2025 r. Będzie można zainstalować rozszerzenie v1 i używać go do tej daty.

Zalecamy przejście do mlrozszerzenia , lub v2 przed 30 września 2025 r. Aby uzyskać więcej informacji na temat rozszerzenia w wersji 2, zobacz Rozszerzenie interfejsu wiersza polecenia usługi Azure ML i zestaw Python SDK w wersji 2.

Informacje o połączeniu

Uwaga

Użyj zestawu SDK usługi Azure Machine Learning, aby uzyskać informacje o usłudze internetowej. Jest to zestaw SDK języka Python. Do utworzenia klienta usługi można użyć dowolnego języka.

Klasa azureml.core.Webservice zawiera informacje potrzebne do utworzenia klienta. Webservice Następujące właściwości są przydatne do tworzenia aplikacji klienckiej:

• auth_enabled - Jeśli jest włączone uwierzytelnianie klucza, True; w przeciwnym razie , False.
• token_auth_enabled- Jeśli jest włączone uwierzytelnianie tokenu, True; w przeciwnym razie . False
• scoring_uri — Adres interfejsu API REST.
• swagger_uri - Adres specyfikacji OpenAPI. Ten identyfikator URI jest dostępny, jeśli włączono automatyczne generowanie schematu. Aby uzyskać więcej informacji, zobacz Wdrażanie modeli za pomocą usługi Azure Machine Learning.

Istnieje kilka sposobów pobierania tych informacji dla wdrożonych usług internetowych:

Zestaw SDK dla języka Python

DOTYCZY:Zestaw SDK języka Python w wersji 1

• Podczas wdrażania modelu Webservice obiekt jest zwracany z informacjami o usłudze:

  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)
  

• Webservice.list Służy do pobierania listy wdrożonych usług internetowych dla modeli w obszarze roboczym. Możesz dodać filtry, aby zawęzić listę zwracanych informacji. Aby uzyskać więcej informacji na temat tego, co można filtrować, zobacz dokumentację referencyjną Webservice.list .

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

• Jeśli znasz nazwę wdrożonej usługi, możesz utworzyć nowe wystąpienie Webserviceprogramu i podać nazwę obszaru roboczego i usługi jako parametry. Nowy obiekt zawiera informacje o wdrożonej usłudze.

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

Interfejs wiersza polecenia platformy Azure

DOTYCZY:Rozszerzenie uczenia maszynowego platformy Azure w wersji 1

Jeśli znasz nazwę wdrożonej usługi, użyj polecenia az ml service show :

az ml service show -n <service-name>

Studio

W Azure Machine Learning studio wybierz pozycję Punkty końcowe, Punkty końcowe w czasie rzeczywistym, a następnie nazwę punktu końcowego. W szczegółach punktu końcowego pole punktu końcowego REST zawiera identyfikator URI oceniania. Identyfikator URI struktury Swagger zawiera identyfikator URI struktury Swagger.

W poniższej tabeli przedstawiono, jak wyglądają te identyfikatory URI:

Typ identyfikatora URI	Przykład
Identyfikator URI oceniania	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

Porada

Adres IP będzie inny dla danego wdrożenia. Każdy klaster usługi AKS będzie miał własny adres IP, który jest współużytkowany przez wdrożenia w tym klastrze.

Zabezpieczona usługa internetowa

Jeśli wdrożona usługa internetowa została zabezpieczona przy użyciu certyfikatu TLS/SSL, możesz użyć protokołu HTTPS , aby nawiązać połączenie z usługą przy użyciu identyfikatora URI oceniania lub struktury Swagger. Protokół HTTPS pomaga zabezpieczyć komunikację między klientem a usługą internetową przez szyfrowanie komunikacji między nimi. Szyfrowanie używa protokołu Transport Layer Security (TLS). Protokół TLS jest czasami nazywany protokołem Secure Sockets Layer (SSL), który był poprzednikiem protokołu TLS.

Ważne

Usługi internetowe wdrożone przez usługę Azure Machine Learning obsługują tylko protokół TLS w wersji 1.2. Podczas tworzenia aplikacji klienckiej upewnij się, że obsługuje tę wersję.

Aby uzyskać więcej informacji, zobacz Zabezpieczanie usługi internetowej za pomocą usługi Azure Machine Learning przy użyciu protokołu TLS.

Uwierzytelnianie dla usług

Usługa Azure Machine Learning udostępnia dwa sposoby kontrolowania dostępu do usług internetowych.

Metoda uwierzytelniania	ACI	AKS
Klucz	Domyślnie wyłączone	Domyślnie włączone
Token	Niedostępny	Domyślnie wyłączone

Podczas wysyłania żądania do usługi zabezpieczonej kluczem lub tokenem użyj nagłówka Autoryzacja , aby przekazać klucz lub token. Klucz lub token musi być sformatowany jako Bearer <key-or-token>, gdzie <key-or-token> to Twój klucz lub wartość tokenu.

Podstawową różnicą między kluczami i tokenami jest to, że klucze są statyczne i można je ponownie wygenerować ręcznie, a tokeny należy odświeżyć po wygaśnięciu. Uwierzytelnianie oparte na kluczach jest obsługiwane w przypadku usługi Azure Container Instance i Azure Kubernetes Service wdrożonych usług internetowych, a uwierzytelnianie oparte na tokenach jest dostępne tylko w przypadku wdrożeń Azure Kubernetes Service. Aby uzyskać więcej informacji na temat konfigurowania uwierzytelniania, zobacz Konfigurowanie uwierzytelniania dla modeli wdrożonych jako usługi internetowe.

Uwierzytelnianie za pomocą kluczy

Po włączeniu uwierzytelniania dla wdrożenia automatycznie utworzysz klucze uwierzytelniania.

• Uwierzytelnianie jest domyślnie włączone podczas wdrażania w Azure Kubernetes Service.
• Uwierzytelnianie jest domyślnie wyłączone podczas wdrażania w Azure Container Instances.

Aby kontrolować uwierzytelnianie, użyj parametru auth_enabled podczas tworzenia lub aktualizowania wdrożenia.

Jeśli uwierzytelnianie jest włączone, możesz użyć get_keys metody w celu pobrania podstawowego i pomocniczego klucza uwierzytelniania:

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

Ważne

Jeśli musisz ponownie wygenerować klucz, użyj polecenia service.regen_key.

Uwierzytelnianie za pomocą tokenów

Po włączeniu uwierzytelniania tokenu dla usługi internetowej użytkownik musi podać token JWT usługi Azure Machine Learning do usługi internetowej, aby uzyskać do niej dostęp.

• Uwierzytelnianie tokenu jest domyślnie wyłączone podczas wdrażania w Azure Kubernetes Service.
• Uwierzytelnianie tokenu nie jest obsługiwane podczas wdrażania w Azure Container Instances.

Aby kontrolować uwierzytelnianie tokenu, użyj parametru token_auth_enabled podczas tworzenia lub aktualizowania wdrożenia.

Jeśli uwierzytelnianie tokenu jest włączone, możesz użyć get_token metody , aby pobrać token elementu nośnego i że tokeny wygasają:

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

Jeśli masz interfejs wiersza polecenia platformy Azure i rozszerzenie uczenia maszynowego, możesz użyć następującego polecenia, aby uzyskać token:

DOTYCZY:Rozszerzenie uczenia maszynowego platformy Azure w wersji 1

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

Ważne

Obecnie jedynym sposobem pobrania tokenu jest użycie zestawu SDK usługi Azure Machine Learning lub rozszerzenia uczenia maszynowego interfejsu wiersza polecenia platformy Azure.

Będzie konieczne zażądanie nowego tokenu po upłynięciu czasu odświeżania refresh_by tokenu.

Żądanie danych

Interfejs API REST oczekuje, że treść żądania będzie dokumentem JSON z następującą strukturą:

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

Ważne

Struktura danych musi odpowiadać oczekiwanemu skryptowi oceniania i modelowi w usłudze. Skrypt oceniania może zmodyfikować dane przed przekazaniem ich do modelu.

Dane binarne

Aby uzyskać informacje na temat włączania obsługi danych binarnych w usłudze, zobacz Dane binarne.

Porada

Włączenie obsługi danych binarnych odbywa się w pliku score.py używanym przez wdrożony model. Z poziomu klienta użyj funkcji HTTP języka programowania. Na przykład poniższy fragment kodu wysyła zawartość pliku JPG do usługi internetowej:

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'})

Współużytkowanie zasobów między źródłami (CORS)

Aby uzyskać informacje na temat włączania obsługi mechanizmu CORS w usłudze, zobacz Współużytkowanie zasobów między źródłami.

Wywoływanie usługi (C#)

W tym przykładzie pokazano, jak za pomocą języka C# wywołać usługę internetową utworzoną na podstawie przykładu Trenowanie w notesie :

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);
            }
        }
    }
}

Zwrócone wyniki są podobne do następującego dokumentu JSON:

[217.67978776218715, 224.78937091757172]

Wywoływanie usługi (Go)

W tym przykładzie pokazano, jak za pomocą języka Go wywołać usługę internetową utworzoną na podstawie przykładu Trenowanie w notesie :

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))
}

Zwrócone wyniki są podobne do następującego dokumentu JSON:

[217.67978776218715, 224.78937091757172]

Wywoływanie usługi (Java)

W tym przykładzie pokazano, jak za pomocą języka Java wywołać usługę internetową utworzoną na podstawie przykładu Trenowanie w notesie :

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());
    }
}

Zwrócone wyniki są podobne do następującego dokumentu JSON:

[217.67978776218715, 224.78937091757172]

Wywoływanie usługi (Python)

W tym przykładzie pokazano, jak za pomocą języka Python wywołać usługę internetową utworzoną na podstawie przykładu Trenowanie w notesie :

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)

Zwrócone wyniki są podobne do następującego dokumentu JSON:

[217.67978776218715, 224.78937091757172]

Schemat usługi internetowej (specyfikacja interfejsu OpenAPI)

Jeśli podczas wdrażania użyto automatycznego generowania schematu, możesz uzyskać adres specyfikacji Interfejsu OpenAPI dla usługi przy użyciu właściwości swagger_uri. (Na przykład print(service.swagger_uri).) Użyj żądania GET lub otwórz identyfikator URI w przeglądarce, aby pobrać specyfikację.

Poniższy dokument JSON jest przykładem schematu (specyfikacja interfejsu OpenAPI) wygenerowanego dla wdrożenia:

{
    "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"
                }
            }
        }
    }
}

Aby uzyskać więcej informacji, zobacz Specyfikacja interfejsu OpenAPI.

Aby uzyskać narzędzie, które może tworzyć biblioteki klienckie na podstawie specyfikacji, zobacz swagger-codegen.

Porada

Po wdrożeniu usługi możesz pobrać dokument JSON schematu. Użyj właściwości swagger_uri z wdrożonej usługi internetowej (na przykład service.swagger_uri), aby pobrać identyfikator URI do pliku Swagger lokalnej usługi internetowej.

Korzystanie z usługi z poziomu usługi Power BI

Usługa Power BI obsługuje wzbogacanie danych o przewidywania dzięki korzystaniu z usług internetowych usługi Azure Machine Learning.

Aby wygenerować usługę internetową obsługiwaną do użycia w usłudze Power BI, schemat musi obsługiwać format wymagany przez usługę Power BI. Dowiedz się, jak utworzyć schemat obsługiwany przez usługę Power BI.

Po wdrożeniu usługi internetowej może być ona używana przez przepływy danych usługi Power BI. Dowiedz się, jak korzystać z usługi internetowej Azure Machine Learning za pomocą usługi Power BI.

Następne kroki

Aby wyświetlić architekturę referencyjną oceniania modeli języka Python i uczenia głębokiego w czasie rzeczywistym, przejdź do centrum architektury platformy Azure.