Share via

Een Azure Machine Learning-model gebruiken dat als een webservice is geïmplementeerd

  • Artikel

Als u een Azure Machine Learning-model implementeert als webservice, wordt een REST API-eindpunt gemaakt. U kunt gegevens naar dit eindpunt verzenden en de voorspelling ontvangen die door het model wordt geretourneerd. In dit document leert u hoe u clients voor de webservice maakt met behulp van C#, Go, Java en Python.

U maakt een webservice wanneer u een model implementeert in uw lokale omgeving, Azure Container Instances, Azure Kubernetes Service of FPGA (field-programmeble gate arrays). U haalt de URI op die wordt gebruikt voor toegang tot de webservice met behulp van de Azure Machine Learning SDK. Als verificatie is ingeschakeld, kunt u ook de SDK gebruiken om de verificatiesleutels of tokens op te halen.

De algemene werkstroom voor het maken van een client die gebruikmaakt van een machine learning-webservice is:

  1. Gebruik de SDK om de verbindingsgegevens op te halen.
  2. Bepaal het type aanvraaggegevens dat door het model wordt gebruikt.
  3. Maak een toepassing die de webservice aanroept.

Tip

De voorbeelden in dit document worden handmatig gemaakt zonder het gebruik van OpenAPI-specificaties (Swagger). Als u een OpenAPI-specificatie hebt ingeschakeld voor uw implementatie, kunt u hulpprogramma's zoals swagger-codegen gebruiken om clientbibliotheken voor uw service te maken.

Belangrijk

Sommige Azure CLI-opdrachten in dit artikel maken gebruik van de azure-cli-mlextensie , of v1 voor Azure Machine Learning. Ondersteuning voor de v1-extensie eindigt op 30 september 2025. Tot die datum kunt u de extensie v1 installeren en gebruiken.

U wordt aangeraden vóór 30 september 2025 over te stappen op de mlextensie , of v2. Zie Azure ML CLI-extensie en Python SDK v2 voor meer informatie over de v2-extensie.

Verbindingsgegevens

Notitie

Gebruik de Azure Machine Learning SDK om de webservicegegevens op te halen. Dit is een Python SDK. U kunt elke taal gebruiken om een client voor de service te maken.

De klasse azureml.core.Webservice biedt de informatie die u nodig hebt om een client te maken. De volgende Webservice eigenschappen zijn handig voor het maken van een clienttoepassing:

  • auth_enabled - Als sleutelverificatie is ingeschakeld, anders True, False.
  • token_auth_enabled - Als tokenverificatie is ingeschakeld, Trueanders, False.
  • scoring_uri - Het REST API-adres.
  • swagger_uri - Het adres van de OpenAPI-specificatie. Deze URI is beschikbaar als u het automatisch genereren van schema's hebt ingeschakeld. Zie Modellen implementeren met Azure Machine Learning voor meer informatie.

Er zijn verschillende manieren om deze informatie op te halen voor geïmplementeerde webservices:

VAN TOEPASSING OP:Python SDK azureml v1

  • Wanneer u een model implementeert, wordt een Webservice object geretourneerd met informatie over de service:

    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)

  • U kunt gebruiken Webservice.list om een lijst met geïmplementeerde webservices op te halen voor modellen in uw werkruimte. U kunt filters toevoegen om de lijst met geretourneerde gegevens te beperken. Zie de referentiedocumentatie voor Webservice.list voor meer informatie over waarop kan worden gefilterd.

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

  • Als u de naam van de geïmplementeerde service weet, kunt u een nieuw exemplaar van maken en de naam van Webservicede werkruimte en service opgeven als parameters. Het nieuwe object bevat informatie over de geïmplementeerde service.

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

In de volgende tabel ziet u hoe deze URI's eruitzien:

URI-type Voorbeeld
Score-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

Het IP-adres is anders voor uw implementatie. Elk AKS-cluster heeft een eigen IP-adres dat wordt gedeeld door implementaties naar dat cluster.

Beveiligde webservice

Als u de geïmplementeerde webservice hebt beveiligd met een TLS/SSL-certificaat, kunt u HTTPS gebruiken om verbinding te maken met de service met behulp van de score- of swagger-URI. HTTPS helpt de communicatie tussen een client en een webservice te beveiligen door de communicatie tussen de twee te versleutelen. Versleuteling maakt gebruik van Tls (Transport Layer Security). TLS wordt soms nog steeds aangeduid als Secure Sockets Layer (SSL), wat de voorloper van TLS was.

Belangrijk

Webservices die zijn geïmplementeerd door Azure Machine Learning ondersteunen alleen TLS versie 1.2. Wanneer u een clienttoepassing maakt, moet u ervoor zorgen dat deze deze versie ondersteunt.

Zie TLS gebruiken om een webservice te beveiligen via Azure Machine Learning voor meer informatie.

Verificatie voor services

Azure Machine Learning biedt twee manieren om de toegang tot uw webservices te beheren.

Verificatiemethode ACI AKS
Sleutel Standaard uitgeschakeld Standaard ingeschakeld
Token Niet beschikbaar Standaard uitgeschakeld

Wanneer u een aanvraag verzendt naar een service die is beveiligd met een sleutel of token, gebruikt u de autorisatieheader om de sleutel of het token door te geven. De sleutel of het token moet worden opgemaakt als Bearer <key-or-token>, waarbij de waarde van <key-or-token> uw sleutel of token is.

Het belangrijkste verschil tussen sleutels en tokens is dat sleutels statisch zijn en handmatig opnieuw kunnen worden gegenereerd, en dat tokens moeten worden vernieuwd wanneer ze verlopen. Verificatie op basis van sleutels wordt ondersteund voor Azure Container Instance en Azure Kubernetes Service geïmplementeerde webservices. Verificatie op basis van tokens is alleen beschikbaar voor Azure Kubernetes Service implementaties. Zie Verificatie configureren voor modellen die zijn geïmplementeerd als webservices voor meer informatie over het configureren van verificatie.

Verificatie met sleutels

Wanneer u verificatie inschakelt voor een implementatie, maakt u automatisch verificatiesleutels.

  • Verificatie is standaard ingeschakeld wanneer u implementeert in Azure Kubernetes Service.
  • Verificatie is standaard uitgeschakeld wanneer u implementeert in Azure Container Instances.

Als u verificatie wilt beheren, gebruikt u de auth_enabled parameter wanneer u een implementatie maakt of bijwerkt.

Als verificatie is ingeschakeld, kunt u de get_keys methode gebruiken om een primaire en secundaire verificatiesleutel op te halen:

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

Belangrijk

Als u een sleutel opnieuw wilt genereren, gebruikt service.regen_keyu .

Verificatie met tokens

Wanneer u tokenverificatie inschakelt voor een webservice, moet een gebruiker een Azure Machine Learning JWT-token opgeven voor toegang tot de webservice.

  • Tokenverificatie is standaard uitgeschakeld wanneer u implementeert in Azure Kubernetes Service.
  • Tokenverificatie wordt niet ondersteund wanneer u implementeert in Azure Container Instances.

Als u tokenverificatie wilt beheren, gebruikt u de token_auth_enabled parameter wanneer u een implementatie maakt of bijwerkt.

Als tokenverificatie is ingeschakeld, kunt u de get_token methode gebruiken om een Bearer-token en de verlooptijd van die tokens op te halen:

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

Als u de Azure CLI en de machine learning-extensie hebt, kunt u de volgende opdracht gebruiken om een token op te halen:

VAN TOEPASSING OP:Azure CLI ml-extensie v1

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

Belangrijk

Op dit moment kunt u het token alleen ophalen met behulp van de Azure Machine Learning SDK of de Azure CLI-extensie voor machine learning.

U moet een nieuw token aanvragen nadat de refresh_by-tijd van het token is verstreken.

Gegevens aanvragen

De REST API verwacht dat de hoofdtekst van de aanvraag een JSON-document is met de volgende structuur:

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

Belangrijk

De structuur van de gegevens moet overeenkomen met wat het scorescript en model in de service verwacht. Het scorescript kan de gegevens wijzigen voordat deze worden doorgegeven aan het model.

Binaire gegevens

Zie Binaire gegevens voor informatie over het inschakelen van ondersteuning voor binaire gegevens in uw service.

Tip

Het inschakelen van ondersteuning voor binaire gegevens vindt plaats in het score.py-bestand dat wordt gebruikt door het geïmplementeerde model. Gebruik vanuit de client de HTTP-functionaliteit van uw programmeertaal. Met het volgende fragment wordt bijvoorbeeld de inhoud van een JPG-bestand naar een webservice verzonden:

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

CORS (Cross-Origin Resource Sharing, cross-origin-resource delen)

Zie Cross-origin resource sharing (Cross-origin resource sharing) voor informatie over het inschakelen van CORS-ondersteuning in uw service.

De service aanroepen (C#)

In dit voorbeeld ziet u hoe u C# gebruikt om de webservice aan te roepen die is gemaakt op basis van het voorbeeld Trainen in notebook :

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

De geretourneerde resultaten zijn vergelijkbaar met het volgende JSON-document:

[217.67978776218715, 224.78937091757172]

De service aanroepen (Go)

In dit voorbeeld ziet u hoe u Go gebruikt om de webservice aan te roepen die is gemaakt op basis van het voorbeeld Trainen in notebook :

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

De geretourneerde resultaten zijn vergelijkbaar met het volgende JSON-document:

[217.67978776218715, 224.78937091757172]

De service aanroepen (Java)

In dit voorbeeld ziet u hoe u Java gebruikt om de webservice aan te roepen die is gemaakt op basis van het voorbeeld Trainen in notebook :

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

De geretourneerde resultaten zijn vergelijkbaar met het volgende JSON-document:

[217.67978776218715, 224.78937091757172]

De service aanroepen (Python)

In dit voorbeeld ziet u hoe u Python gebruikt om de webservice aan te roepen die is gemaakt op basis van het voorbeeld Trainen in notebook :

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)

De geretourneerde resultaten zijn vergelijkbaar met het volgende JSON-document:

[217.67978776218715, 224.78937091757172]

Webserviceschema (OpenAPI-specificatie)

Als u automatische schemageneratie hebt gebruikt bij uw implementatie, kunt u het adres van de OpenAPI-specificatie voor de service ophalen met behulp van de eigenschap swagger_uri. (Bijvoorbeeld print(service.swagger_uri).) Gebruik een GET-aanvraag of open de URI in een browser om de specificatie op te halen.

Het volgende JSON-document is een voorbeeld van een schema (OpenAPI-specificatie) dat is gegenereerd voor een implementatie:

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

Zie OpenAPI-specificatie voor meer informatie.

Zie swagger-codegen voor een hulpprogramma dat clientbibliotheken kan maken op basis van de specificatie.

Tip

U kunt het JSON-schemadocument ophalen nadat u de service hebt geïmplementeerd. Gebruik de eigenschap swagger_uri van de geïmplementeerde webservice (bijvoorbeeld service.swagger_uri) om de URI naar het Swagger-bestand van de lokale webservice op te halen.

De service gebruiken vanuit Power BI

Power BI ondersteunt het gebruik van Azure Machine Learning-webservices om de gegevens in Power BI te verrijken met voorspellingen.

Als u een webservice wilt genereren die wordt ondersteund voor gebruik in Power BI, moet het schema de indeling ondersteunen die is vereist voor Power BI. Meer informatie over het maken van een schema dat door Power BI wordt ondersteund.

Zodra de webservice is geïmplementeerd, kan deze worden gebruikt vanuit Power BI-gegevensstromen. Een Azure Machine Learning-webservice gebruiken vanuit Power BI.

Volgende stappen

Als u een referentiearchitectuur wilt weergeven voor realtime scoren van Python- en Deep Learning-modellen, gaat u naar het Azure Architecture Center.