Sdílet prostřednictvím

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í C#, Go, Java a Pythonu.

Webovou službu vytvoříte, když nasadíte model do místního prostředí, azure Container Instances, Azure Kubernetes Service nebo pole s programovatelnými hradly (FPGA). Pomocí sady Azure Machine Learning SDK načtete identifikátor URI použitý pro přístup k webové službě. 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 jsou ručně vytvořeny bez použití specifikací OpenAPI (Swagger). Pokud jste pro 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) před 30. zářím 2025. Další informace o rozšíření v2 najdete v tématu Rozšíření Azure ML CLI a Python SDK v2.

Informace o připojení

Poznámka:

Informace o webové službě získáte pomocí sady SDK služby Azure Machine Learning. Jedná se o sadu Python SDK. K vytvoření klienta pro službu můžete použít libovolný jazyk.

Třída azureml.core.Webservice poskytuje informace, které potřebujete k vytvoření klienta. Pro vytvoř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í tokenu, Truejinak 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.

Tyto informace pro nasazené webové služby můžete načíst několika způsoby:

PLATÍ PRO: 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)

  • Můžete použít Webservice.list k načtení seznamu nasazených webových služeb pro modely ve vašem pracovním prostoru. Můžete přidat filtry, abyste zúžili seznam vrácených informací. Další informace o tom, co lze filtrovat, naleznete v referenční dokumentaci 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 název pracovního prostoru a 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
Hodnoticí identifikátor 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

Tip

IP adresa se bude pro vaše nasazení lišit. Každý cluster AKS bude mít svou vlastní IP adresu, kterou sdílí nasazení do daného clusteru.

Zabezpečená webová služba

Pokud jste nasadili webovou službu pomocí certifikátu TLS/SSL, můžete se k této službě připojit pomocí hodnoticího identifikátoru URI nebo swaggeru. HTTPS pomáhá zabezpečit komunikaci mezi klientem a webovou službou šifrováním komunikace 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í povoleno
Token Není k dispozici Ve výchozím nastavení zakázaná

Při odesílání žádosti službě, která je zabezpečená pomocí klíče nebo tokenu, použijte autorizační hlavičku k předání klíče nebo tokenu. 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 dají se ručně vygenerovat a tokeny je potřeba aktualizovat po vypršení platnosti. Ověřování založené na klíčích se podporuje pro službu Azure Container Instance a Azure Kubernetes Service nasazené webové služby a ověřování založené na tokenech je k dispozici pouze pro nasazení služby Azure Kubernetes Service. 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.

  • Ověřování je ve výchozím nastavení povolené při nasazování do služby Azure Kubernetes Service.
  • Ověřování je ve výchozím nastavení zakázané při nasazování do služby Azure Container Instances.

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

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

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í tokenů pro webovou službu, musí uživatel poskytnout token JWT služby Azure Machine Learning pro přístup k webové službě.

  • Při nasazování do služby Azure Kubernetes Service je ve výchozím nastavení zakázané ověřování tokenů.
  • Při nasazování do služby Azure Container Instances se ověřování tokenů nepodporuje.

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

Pokud je povolené ověřování tokenů, můžete pomocí get_token metody načíst nosný token a čas 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 k získání tokenu použít následující příkaz:

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 načtení tokenu 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.

Žádost o data

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 očekávanému hodnoticímu skriptu a modelu ve službě. Skript bodování může data před předáním do modelu upravit.

Binární data

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

Tip

Povolení podpory binárních dat probíhá 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 do webové služby:

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 trénování v příkladu poznámkového 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 jsou podobné následujícímu dokumentu JSON:

[217.67978776218715, 224.78937091757172]

Volání služby (Go)

Tento příklad ukazuje, jak pomocí go volat webovou službu vytvořenou z trénování v příkladu poznámkového 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 jsou podobné 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 trénování v příkladu poznámkového 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 jsou podobné 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 trénování v příkladu poznámkového 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 jsou podobné následujícímu dokumentu JSON:

[217.67978776218715, 224.78937091757172]

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

Pokud jste při 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, viz swagger-codegen.

Tip

Dokument JSON schématu můžete načíst po nasazení služby. Pomocí vlastnosti swagger_uri z nasazené webové služby (napříkladservice.swagger_uri) získejte identifikátor URI do souboru 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 podporovanou pro spotřebu v Power BI, musí schéma podporovat formát, který vyžaduje Power BI. 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.