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

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 maakt voor de webservice 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 field-programmable gate arrays (FPGA). U haalt de URI op die wordt gebruikt voor toegang tot de webservice met behulp van 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 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 voor uw implementatie hebt ingeschakeld, kunt u hulpprogramma's zoals swagger-codegen gebruiken om clientbibliotheken voor uw service te maken.

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:

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

  • Wanneer u een model implementeert, Webservice wordt een -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 voor modellen in uw werkruimte op te halen. U kunt filters toevoegen om de lijst met geretourneerde gegevens te beperken. Zie de naslagdocumentatie voor Webservice.list voor meer informatie over waar op 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 werkruimte en servicenaam opgeven Webservice 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 eruit zien:

URI-type Voorbeeld
Scoring-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 scoring- of swagger-URI. HTTPS helpt de communicatie tussen een client en een webservice te beveiligen door communicatie tussen de twee te versleutelen. Voor versleuteling Transport Layer Security (TLS) gebruikt. TLS wordt soms nog steeds aangeduid als Secure Sockets Layer (SSL), de voorloper van TLS.

Belangrijk

Webservices die zijn geïmplementeerd door Azure Machine Learning bieden alleen ondersteuning voor TLS-versie 1.2. Wanneer u een clienttoepassing maakt, moet u ervoor zorgen dat deze versie wordt ondersteund.

Zie Use TLS to secure a web service through Azure Machine Learning (TLSgebruiken om een webservice te beveiligen via Azure Machine Learning).

Verificatie voor services

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

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

Bij het verzenden van een aanvraag 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 token moet worden opgemaakt als Bearer <key-or-token> , waarbij de waarde van uw sleutel of <key-or-token> token is.

Het belangrijkste verschil tussen sleutels en tokens is dat sleutels statisch zijn en handmatig opnieuw kunnen worden ge regenereerd en dat tokens na verloop van verloop moeten worden vernieuwd. Op sleutels gebaseerde auth wordt ondersteund voor Azure Container Instance en Azure Kubernetes Service geïmplementeerde webservices en op token gebaseerde auth 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 inschakelen 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 controleren, gebruikt auth_enabled u de parameter bij het maken of bijwerken van een implementatie.

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

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

Belangrijk

Als u een sleutel opnieuw wilt maken, gebruikt u service.regen_key .

Verificatie met tokens

Wanneer u tokenverificatie inschakelen voor een webservice, moet een gebruiker een Azure Machine Learning JWT-token aan de webservice om toegang te krijgen.

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

Als u de verificatie van het token wilt controleren, gebruikt u token_auth_enabled de parameter bij het maken of bijwerken van een implementatie.

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

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

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

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

Belangrijk

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

U moet na de tijd van het token een nieuw token refresh_by aanvragen.

Gegevens aanvragen

De REST API verwacht dat 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 verwachten. Het scoring-script kan de gegevens wijzigen voordat deze aan het model worden doorgeven.

Binaire gegevens

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

Tip

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

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 sharingvoor meer informatie over het inschakelen van CORS-ondersteuning in uw service.

De service aanroepen (C#)

In dit voorbeeld wordt gedemonstreerd hoe u C# gebruikt om de webservice aan te roepen die is gemaakt vanuit 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 wordt gedemonstreerd hoe u Go gebruikt om de webservice aan te roepen die is gemaakt vanuit 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 wordt gedemonstreerd hoe u Java gebruikt om de webservice aan te roepen die is gemaakt vanuit 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 vanuit 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 voor uw implementatie, kunt u het adres van de OpenAPI-specificatie voor de service op halen met behulp van swagger_uri eigenschap. (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 wordt 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-codegenvoor een hulpprogramma dat clientbibliotheken op de specificatie kan maken.

Tip

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

De service gebruiken vanuit Power BI

Power BI ondersteunt het gebruik van Azure Machine Learning webservices om de gegevens in de 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 door Power BI. Informatie over het maken van een Power BI ondersteund schema.

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 het in realtime scoren van Python- en Deep Learning-modellen, gaat u naar het Azure Architecture Center.