Konsumera en Azure Machine Learning-modell som distribuerats som en webbtjänst

Om du distribuerar en Azure Machine Learning-modell som en webbtjänst skapas en REST API-slutpunkt. Du kan skicka data till den här slutpunkten så returnerar modellen förutsägelsen. I det här dokumentet lär du dig hur du skapar klienter för webbtjänsten med hjälp av C#, Go, Java och Python.

Du skapar en webbtjänst när du distribuerar en modell till din lokala miljö, Azure Container Instances eller Azure Kubernetes Service. Du hämtar den URI som används för att komma åt webbtjänsten med hjälp av Azure Machine Learning SDK. Om autentisering är aktiverat kan du också använda SDK:t för att hämta autentiseringsnycklarna eller token.

Det allmänna arbetsflödet för att skapa en klient som använder en maskininlärningswebbtjänst är:

1. Använd SDK:et för att hämta anslutningsinformationen.
2. Fastställ vilken typ av begärandedata som används av modellen.
3. Skapa ett program som anropar webbtjänsten.

Anslutningsinformation

Klassen azureml.core.Webservice innehåller den information du behöver för att skapa en klient. Följande Webservice egenskaper är användbara för att skapa ett klientprogram:

• auth_enabled– Om nyckelautentisering är aktiverat, True; annars . False
• token_auth_enabled– Om tokenautentisering är aktiverat, True; annars . False
• scoring_uri – REST API-adressen.
• swagger_uri – Adressen till OpenAPI-specifikationen. Den här URI:n är tillgänglig om du har aktiverat automatisk schemagenerering. Mer information finns i Distribuera modeller med Azure Machine Learning.

Det finns flera sätt att hämta den här informationen för distribuerade webbtjänster:

az ml service show -n <service-name>

I följande tabell visas hur dessa URI:er ser ut:

Skyddad webbtjänst

Om du har skyddat den distribuerade webbtjänsten med ett TLS/SSL-certifikat kan du använda HTTPS för att ansluta till tjänsten med hjälp av bedömnings- eller swagger-URI:n. HTTPS hjälper till att skydda kommunikationen mellan en klient och en webbtjänst genom att kryptera kommunikationen mellan de två. Kryptering använder TLS (Transport Layer Security). TLS kallas ibland fortfarande secure sockets layer (SSL), som var föregångaren till TLS.

Mer information finns i Använda TLS för att skydda en webbtjänst via Azure Machine Learning.

Autentisering för tjänster

Azure Machine Learning tillhandahåller två sätt att styra åtkomsten till dina webbtjänster.

När du skickar en begäran till en tjänst som skyddas med en nyckel eller token använder du auktoriseringshuvudet för att skicka nyckeln eller token. Nyckeln eller token måste formateras som Bearer <key-or-token>, där <key-or-token> är ditt nyckel- eller tokenvärde.

Den primära skillnaden mellan nycklar och token är att nycklar är statiska och kan återskapas manuellt, och token måste uppdateras när de upphör att gälla. Nyckelbaserad autentisering stöds för Azure Container Instance och Azure Kubernetes Service distribuerade webbtjänster, och tokenbaserad autentisering är endast tillgänglig för Azure Kubernetes Service-distributioner. Mer information om hur du konfigurerar autentisering finns i Konfigurera autentisering för modeller som distribueras som webbtjänster.

Autentisering med nycklar

När du aktiverar autentisering för en distribution skapar du automatiskt autentiseringsnycklar.

• Autentisering är aktiverat som standard när du distribuerar till Azure Kubernetes Service.
• Autentisering är inaktiverad som standard när du distribuerar till Azure Container Instances.

Om du vill styra autentiseringen använder du parametern auth_enabled när du skapar eller uppdaterar en distribution.

Om autentisering är aktiverat kan du använda get_keys metoden för att hämta en primär och sekundär autentiseringsnyckel:

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

Autentisering med token

När du aktiverar tokenautentisering för en webbtjänst måste en användare tillhandahålla en Azure Machine Learning JWT till webbtjänsten för att få åtkomst till den.

• Tokenautentisering inaktiveras som standard när du distribuerar till Azure Kubernetes Service.
• Tokenautentisering stöds inte när du distribuerar till Azure Container Instances.

Om du vill styra tokenautentisering använder du parametern token_auth_enabled när du skapar eller uppdaterar en distribution.

Om tokenautentisering är aktiverat kan du använda get_token metoden för att hämta en ägartoken och tokens förfallotid:

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

Om du har Azure CLI och maskininlärningstillägget kan du använda följande kommando för att hämta en token:

GÄLLER FÖR: Azure CLI ml-tillägget v1

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

Du behöver begära en ny token efter tokens refresh_by-tid.

Begär data

REST-API:et förväntar sig att brödtexten i begäran är ett JSON-dokument med följande struktur:

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

Binära data

Information om hur du aktiverar stöd för binära data i din tjänst finns i Binära data.

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

Resursdelning för korsande ursprung (CORS)

Information om hur du aktiverar CORS-stöd i din tjänst finns i Resursdelning mellan ursprung.

Anropa tjänsten (C#)

Det här exemplet visar hur du använder C# för att anropa en webbtjänst:

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

Resultaten som returneras liknar följande JSON-dokument:

[217.67978776218715, 224.78937091757172]

Anropa tjänsten (Python)

Det här exemplet visar hur du använder Python för att anropa en webbtjänst:

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)

Resultaten som returneras liknar följande JSON-dokument:

[217.67978776218715, 224.78937091757172]

Webbtjänstschema (OpenAPI-specifikation)

Om du använde automatisk schemagenerering med distributionen kan du hämta adressen till OpenAPI-specifikationen för tjänsten med hjälp av egenskapen swagger_uri. (Till exempel print(service.swagger_uri).) Använd en GET-begäran eller öppna URI:n i en webbläsare för att hämta specifikationen.

Följande JSON-dokument är ett exempel på ett schema (OpenAPI-specifikation) som genererats för en distribution:

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

Mer information finns i OpenAPI-specifikation.

Ett verktyg som kan skapa klientbibliotek från specifikationen finns i swagger-codegen.

Nästa steg

Om du vill visa en referensarkitektur för realtidsbedömning av Python- och djupinlärningsmodeller går du till Azure Architecture Center.