Využívání modelu služby Azure Machine Learning nasazeného jako webová služba

  • Článek

Nasazením modelu služby Azure Machine Learning jako webové služby se vytvoří koncový bod rozhraní REST API. Do tohoto koncového bodu můžete odesílat data a přijímat z něj predikce vrácené modelem. V tomto dokumentu se dozvíte, jak vytvářet klienty pro webovou službu pomocí jazyků C#, Go, Java a Python.

Webovou službu vytvoříte při nasazení modelu do místního prostředí, Azure Container Instances, Azure Kubernetes Service nebo programovatelných hradlových polí (FPGA). Identifikátor URI použitý pro přístup k webové službě načtete pomocí sady SDK služby Azure Machine Learning. Pokud je ověřování povolené, můžete k získání ověřovacích klíčů nebo tokenů použít také sadu SDK.

Obecný pracovní postup pro vytvoření klienta, který používá webovou službu strojového učení, je:

  1. Získání informací o připojení pomocí sady SDK
  2. Určení typu dat požadavků používaných modelem
  3. Vytvoření aplikace, která volá webovou službu

Tip

Příklady v tomto dokumentu se vytvářejí ručně bez použití specifikací OpenAPI (Swagger). Pokud jste pro své nasazení povolili specifikaci OpenAPI, můžete k vytvoření klientských knihoven pro vaši službu použít nástroje, jako je swagger-codegen .

Důležité

Některé příkazy Azure CLI v tomto článku používají azure-cli-mlrozšíření , nebo v1 pro Azure Machine Learning. Podpora rozšíření v1 skončí 30. září 2025. Do tohoto data budete moct nainstalovat a používat rozšíření v1.

Doporučujeme přejít na mlrozšíření , nebo v2 do 30. září 2025. Další informace o rozšíření v2 najdete v tématech Rozšíření Azure ML CLI a Python SDK v2.

Informace o připojení

Poznámka

K získání informací o webové službě použijte sadu Azure Machine Learning SDK. Toto je sada Python SDK. K vytvoření klienta služby můžete použít libovolný jazyk.

Třída azureml.core.Webservice poskytuje informace, které potřebujete k vytvoření klienta. Při vytváření klientské aplikace jsou užitečné následující Webservice vlastnosti:

  • auth_enabled– Pokud je povolené ověřování pomocí klíče, Truev opačném případě . False
  • token_auth_enabled – Pokud je povolené ověřování tokenem, Truev opačném případě hodnota False.
  • scoring_uri – Adresa rozhraní REST API.
  • swagger_uri – Adresa specifikace OpenAPI. Tento identifikátor URI je k dispozici, pokud jste povolili automatické generování schématu. Další informace najdete v tématu Nasazení modelů pomocí služby Azure Machine Learning.

Existuje několik způsobů, jak tyto informace načíst pro nasazené webové služby:

PLATÍ PRO:Sada Python SDK azureml v1

  • Když nasadíte model, Webservice vrátí se objekt s informacemi o službě:

    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)

  • Pomocí příkazu Webservice.list můžete načíst seznam nasazených webových služeb pro modely ve vašem pracovním prostoru. Seznam vrácených informací můžete zúžit přidáním filtrů. Další informace o tom, co se dá filtrovat, najdete v referenční dokumentaci k webservice.list .

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

  • Pokud znáte název nasazené služby, můžete vytvořit novou instanci Webservicea zadat pracovní prostor a název služby jako parametry. Nový objekt obsahuje informace o nasazené službě.

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

Následující tabulka ukazuje, jak tyto identifikátory URI vypadají:

Typ identifikátoru URI Příklad
Identifikátor URI bodování http://104.214.29.152:80/api/v1/service/<service-name>/score
Identifikátor URI Swaggeru http://104.214.29.152/api/v1/service/<service-name>/swagger.json

Tip

IP adresa se pro vaše nasazení bude lišit. Každý cluster AKS bude mít vlastní IP adresu, kterou nasazení sdílí s tímto clusterem.

Zabezpečená webová služba

Pokud jste zabezpečili nasazenou webovou službu pomocí certifikátu TLS/SSL, můžete se ke službě připojit pomocí protokolu HTTPS pomocí hodnoticího identifikátoru URI nebo swaggeru. HTTPS pomáhá zabezpečit komunikaci mezi klientem a webovou službou tím, že šifruje komunikaci mezi těmito dvěma službami. Šifrování používá protokol TLS (Transport Layer Security). Protokol TLS se někdy stále označuje jako SSL (Secure Sockets Layer ), který byl předchůdcem protokolu TLS.

Důležité

Webové služby nasazené službou Azure Machine Learning podporují pouze protokol TLS verze 1.2. Při vytváření klientské aplikace se ujistěte, že podporuje tuto verzi.

Další informace najdete v tématu Zabezpečení webové služby prostřednictvím služby Azure Machine Learning s využitím protokolu TLS.

Ověřování pro služby

Azure Machine Learning nabízí dva způsoby řízení přístupu k webovým službám.

Metoda ověřování ACI AKS
Klíč Ve výchozím nastavení zakázaná Ve výchozím nastavení povolená
Token Není k dispozici Ve výchozím nastavení zakázaná

Při odesílání požadavku do služby, která je zabezpečená pomocí klíče nebo tokenu, použijte k předání klíče nebo tokenu hlavičku Authorization . Klíč nebo token musí být ve formátu Bearer <key-or-token>, kde <key-or-token> je hodnota klíče nebo tokenu.

Hlavní rozdíl mezi klíči a tokeny spočívá v tom, že klíče jsou statické a je možné je znovu vygenerovat ručně a tokeny je potřeba po vypršení platnosti aktualizovat. Ověřování na základě klíčů je podporováno pro službu Azure Container Instance a Azure Kubernetes Service nasazené webové služby a ověřování na základě tokenů je k dispozici pouze pro Azure Kubernetes Service nasazení. Další informace o konfiguraci ověřování najdete v tématu Konfigurace ověřování pro modely nasazené jako webové služby.

Ověřování pomocí klíčů

Když povolíte ověřování pro nasazení, automaticky vytvoříte ověřovací klíče.

  • Když nasazujete do Azure Kubernetes Service, ověřování je ve výchozím nastavení povolené.
  • Když nasazujete do Azure Container Instances, ověřování je ve výchozím nastavení zakázané.

K řízení ověřování použijte auth_enabled parametr při vytváření nebo aktualizaci nasazení.

Pokud je ověřování povolené, můžete k načtení primárního a sekundárního ověřovacího klíče použít metodu get_keys :

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

Důležité

Pokud potřebujete klíč znovu vygenerovat, použijte service.regen_key.

Ověřování pomocí tokenů

Když povolíte ověřování pomocí tokenu pro webovou službu, musí uživatel webové službě poskytnout token JWT služby Azure Machine Learning, aby k němu měl přístup.

  • Ověřování pomocí tokenu je při nasazování do Azure Kubernetes Service ve výchozím nastavení zakázané.
  • Ověřování pomocí tokenu se nepodporuje, když nasazujete do Azure Container Instances.

Pokud chcete řídit ověřování pomocí tokenu token_auth_enabled , při vytváření nebo aktualizaci nasazení použijte parametr .

Pokud je povolené ověřování tokenu, můžete použít metodu get_token k načtení nosné tokeny a doby vypršení platnosti tokenů:

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

Pokud máte Azure CLI a rozšíření strojového učení, můžete token získat pomocí následujícího příkazu:

PLATÍ PRO:Rozšíření Azure CLI ml v1

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

Důležité

V současné době je jediným způsobem, jak načíst token, pomocí sady Azure Machine Learning SDK nebo rozšíření azure CLI pro strojové učení.

Po uplynutí doby refresh_by tokenu je potřeba vyžádat si nový token.

Vyžádání dat

Rozhraní REST API očekává, že text požadavku bude dokument JSON s následující strukturou:

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

Důležité

Struktura dat musí odpovídat tomu, co hodnoticí skript a model ve službě očekávají. Hodnoticí skript může data před předáním modelu upravit.

Binární data

Informace o tom, jak povolit podporu binárních dat ve vaší službě, najdete v tématu Binární data.

Tip

Podpora binárních dat se povolí v souboru score.py používaném nasazeným modelem. Z klienta použijte funkci HTTP vašeho programovacího jazyka. Například následující fragment kódu odešle obsah souboru JPG webové službě:

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

Sdílení prostředků mezi zdroji (CORS)

Informace o povolení podpory CORS ve vaší službě najdete v tématu Sdílení prostředků mezi zdroji.

Volání služby (C#)

Tento příklad ukazuje, jak pomocí jazyka C# volat webovou službu vytvořenou z příkladu vytrénovat v poznámkovém bloku :

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

Vrácené výsledky se podobají následujícímu dokumentu JSON:

[217.67978776218715, 224.78937091757172]

Volání služby (Go)

Tento příklad ukazuje, jak pomocí funkce Go zavolat webovou službu vytvořenou z příkladu vytrénovat v poznámkovém bloku :

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

Vrácené výsledky se podobají následujícímu dokumentu JSON:

[217.67978776218715, 224.78937091757172]

Volání služby (Java)

Tento příklad ukazuje, jak pomocí Javy volat webovou službu vytvořenou z příkladu vytrénovat v poznámkovém bloku :

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

Vrácené výsledky se podobají následujícímu dokumentu JSON:

[217.67978776218715, 224.78937091757172]

Volání služby (Python)

Tento příklad ukazuje, jak pomocí Pythonu volat webovou službu vytvořenou z příkladu vytrénovat v poznámkovém bloku :

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)

Vrácené výsledky se podobají následujícímu dokumentu JSON:

[217.67978776218715, 224.78937091757172]

Schéma webové služby (specifikace OpenAPI)

Pokud jste ve svém nasazení použili automatické generování schématu, můžete získat adresu specifikace OpenAPI pro službu pomocí vlastnosti swagger_uri. (Například print(service.swagger_uri).) K načtení specifikace použijte požadavek GET nebo otevřete identifikátor URI v prohlížeči.

Následující dokument JSON je příkladem schématu (specifikace OpenAPI) vygenerovaného pro nasazení:

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

Další informace najdete ve specifikaci OpenAPI.

Nástroj, který může vytvářet klientské knihovny ze specifikace, najdete v tématu swagger-codegen.

Tip

Po nasazení služby můžete načíst dokument JSON schématu. Pomocí vlastnosti swagger_uri z nasazené webové služby (například service.swagger_uri) získejte identifikátor URI pro soubor Swagger místní webové služby.

Využívání služby v Power BI

Power BI podporuje využívání webových služeb Azure Machine Learning za účelem rozšiřování dat v Power BI o predikce.

Pokud chcete vygenerovat webovou službu, která je v Power BI podporovaná, musí schéma podporovat formát, který Power BI vyžaduje. Zjistěte, jak vytvořit schéma podporované v Power BI.

Po nasazení webové služby je možné ji využívat v tocích dat Power BI. Zjistěte, jak v Power BI využívat webovou službu Azure Machine Learning.

Další kroky

Pokud chcete zobrazit referenční architekturu pro bodování modelů Pythonu a hlubokého učení v reálném čase, přejděte do centra architektury Azure.