Megosztás a következőn keresztül:

Azure Machine Learning-modell felhasználása webszolgáltatásként

  • Cikk

Ha egy Azure Machine Learning-modellt webszolgáltatásként helyez üzembe, létrejön egy REST API-végpont. Adatokat küldhet ennek a végpontnak, és megkaphatja a modell által visszaküldött előrejelzést. Ebben a dokumentumban megtudhatja, hogyan hozhat létre ügyfeleket a webszolgáltatáshoz a C#, a Go, a Java és a Python használatával.

Webszolgáltatást akkor hoz létre, ha modellt helyez üzembe a helyi környezetben, az Azure Container Instancesben vagy az Azure Kubernetes Service-ben. Az Azure Machine Learning SDK-val lekérheti a webszolgáltatás eléréséhez használt URI-t. Ha a hitelesítés engedélyezve van, az SDK-val is lekérheti a hitelesítési kulcsokat vagy jogkivonatokat.

A gépi tanulási webszolgáltatást használó ügyfelek létrehozásának általános munkafolyamata a következő:

  1. Kérdezze le a kapcsolati adatokat az SDK-val.
  2. Határozza meg a modell által használt kérelemadatok típusát.
  3. Hozza létre a webszolgáltatást meghívó alkalmazást.

Tipp.

A dokumentumban szereplő példák manuálisan jönnek létre az OpenAPI (Swagger) specifikációinak használata nélkül. Ha engedélyezte az üzemelő példány OpenAPI-specifikációját, az olyan eszközökkel, mint a swagger-codegen , ügyfélkódtárakat hozhat létre a szolgáltatáshoz.

Fontos

A cikkben szereplő Azure CLI-parancsok némelyike az azure-cli-mlAzure Machine Learning bővítményét vagy v1-et használja. A v1-bővítmény támogatása 2025. szeptember 30-án megszűnik. Addig a dátumig telepítheti és használhatja a v1-bővítményt.

Javasoljuk, hogy 2025. szeptember 30-a előtt váltsa át a ml(vagy v2) bővítményt. További információ a v2-es bővítményről: Azure ML CLI-bővítmény és Python SDK v2.

Kapcsolati információk

Feljegyzés

A webszolgáltatás adatainak lekéréséhez használja az Azure Machine Learning SDK-t. Ez egy Python SDK. A szolgáltatáshoz bármilyen nyelven létrehozhat ügyfelet.

Az azureml.core.Webservice osztály az ügyfél létrehozásához szükséges információkat tartalmazza. Az ügyfélalkalmazások létrehozásához az alábbi Webservice tulajdonságok hasznosak:

  • auth_enabled - Ha a kulcshitelesítés engedélyezve van, Trueellenkező esetben False.
  • token_auth_enabled - Ha a jogkivonat-hitelesítés engedélyezve van, Trueellenkező esetben False.
  • scoring_uri - A REST API-cím.
  • swagger_uri - Az OpenAPI specifikációjának címe. Ez az URI akkor érhető el, ha engedélyezte az automatikus sémagenerálást. További információ: Modellek üzembe helyezése az Azure Machine Learning használatával.

Ezeket az információkat többféleképpen is lekérheti az üzembe helyezett webszolgáltatások esetében:

A KÖVETKEZŐKRE VONATKOZIK: Python SDK azureml v1

  • Modell üzembe helyezésekor a rendszer visszaad egy Webservice objektumot a szolgáltatással kapcsolatos információkkal:

    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)

  • A munkaterületen lévő modellekhez telepített webszolgáltatások listájának lekérésére használható Webservice.list . Szűrők hozzáadásával szűkítheti a visszaadott információk listáját. A szűréssel kapcsolatos további információkért tekintse meg a Webservice.list referenciadokumentációját.

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

  • Ha ismeri az üzembe helyezett szolgáltatás nevét, létrehozhat egy új példányt Webservice, és paraméterekként megadhatja a munkaterület és a szolgáltatás nevét. Az új objektum információkat tartalmaz az üzembe helyezett szolgáltatásról.

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

Az alábbi táblázat az alábbi URI-k megjelenését mutatja be:

URI-típus Példa
Pontozási 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

Tipp.

Az IP-cím eltérő lesz az üzembe helyezéshez. Minden AKS-fürtnek saját IP-címe lesz, amelyet az adott fürtön üzemelő példányok osztanak meg.

Biztonságos webszolgáltatás

Ha az üzembe helyezett webszolgáltatást TLS/SSL-tanúsítvánnyal védte, https használatával csatlakozhat a szolgáltatáshoz a pontozó vagy a swagger URI használatával. A HTTPS a kettő közötti kommunikáció titkosításával segíti az ügyfél és a webszolgáltatás közötti kommunikáció védelmét. A titkosítás a Transport Layer Security (TLS) protokollt használja. A TLS-t néha még mindig biztonságos szoftvercsatornák rétegének (SSL) nevezik, amely a TLS elődje volt.

Fontos

Az Azure Machine Learning által üzembe helyezett webszolgáltatások csak a TLS 1.2-es verzióját támogatják. Ügyfélalkalmazás létrehozásakor győződjön meg arról, hogy támogatja ezt a verziót.

További információért lásd: TLS használata webszolgáltatás védelméhez az Azure Machine Learning szolgáltatás segítségével.

Szolgáltatások hitelesítése

Az Azure Machine Learning két módszert kínál a webszolgáltatásokhoz való hozzáférés szabályozására.

Hitelesítési módszer ACI AKS
Kulcs Alapértelmezés szerint le van tiltva Alapértelmezés szerint engedélyezett
Jogkivonat Nem elérhető Alapértelmezés szerint le van tiltva

Amikor egy kulccsal vagy jogkivonattal védett szolgáltatásnak küld kérést, az Engedélyezési fejléc használatával adja át a kulcsot vagy a jogkivonatot. A kulcsot vagy jogkivonatot Bearer <key-or-token> formátumban kell megadni, amelyben a <key-or-token> a kulcs vagy jogkivonat értéke.

A kulcsok és a jogkivonatok közötti elsődleges különbség az, hogy a kulcsok statikusak, és manuálisan újragenerálhatók, és a jogkivonatokat a lejáratkor frissíteni kell. A kulcsalapú hitelesítés az Azure Container Instance és az Azure Kubernetes Service által üzembe helyezett webszolgáltatások esetében támogatott, a tokenalapú hitelesítés pedig csak az Azure Kubernetes Service üzemelő példányaihoz érhető el. A hitelesítés konfigurálásáról további információt a webszolgáltatásként üzembe helyezett modellek hitelesítésének konfigurálása című témakörben talál.

Hitelesítés kulcsokkal

Amikor engedélyezi a hitelesítést egy központi telepítéshez, automatikusan létrehozza a hitelesítési kulcsokat.

  • A hitelesítés alapértelmezés szerint engedélyezve van az Azure Kubernetes Service-ben való üzembe helyezéskor.
  • A hitelesítés alapértelmezés szerint le van tiltva az Azure Container Instancesben való üzembe helyezéskor.

A hitelesítés szabályozásához használja a paramétert az auth_enabled üzembe helyezés létrehozásakor vagy frissítésekor.

Ha a hitelesítés engedélyezve van, a get_keys metódussal lekérhet egy elsődleges és másodlagos hitelesítési kulcsot:

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

Fontos

Ha újra kell létrehoznia egy kulcsot, használja a következőt service.regen_key: .

Hitelesítés jogkivonatokkal

Amikor engedélyezi a jogkivonat-hitelesítést egy webszolgáltatáshoz, a felhasználónak meg kell adnia egy Azure Machine Learning JWT-jogkivonatot a webszolgáltatásnak a hozzáféréshez.

  • A jogkivonat-hitelesítés alapértelmezés szerint le van tiltva az Azure Kubernetes Service-ben való üzembe helyezéskor.
  • A jogkivonat-hitelesítés nem támogatott az Azure Container Instancesben való üzembe helyezéskor.

A jogkivonat-hitelesítés szabályozásához használja a token_auth_enabled paramétert az üzembe helyezés létrehozásakor vagy frissítésekor.

Ha a jogkivonat-hitelesítés engedélyezve van, a metódussal lekérheti a get_token tulajdonosi jogkivonatot és a jogkivonatok lejárati idejét:

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

Ha rendelkezik az Azure CLI-vel és a gépi tanulási bővítményrel, a következő paranccsal szerezhet be egy jogkivonatot:

A KÖVETKEZŐRE VONATKOZIK: Azure CLI ml-bővítmény 1-es verzió 

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

Fontos

A jogkivonat lekérésének jelenleg csak az Azure Machine Learning SDK vagy az Azure CLI machine learning bővítmény használatával lehet lekérni.

Új jogkivonatot kell kérnie a jogkivonat refresh_by ideje után.

Adatok kérése

A REST API elvárja, hogy a kérés törzse egy JSON-dokumentum legyen, amely a következő struktúrával rendelkezik:

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

Fontos

Az adatok struktúrájának meg kell egyeznie a szolgáltatásban elvárt pontozási szkripttel és modellel. A pontozási szkript módosíthatja az adatokat, mielőtt továbbítaná azokat a modellnek.

Bináris adatok

A bináris adatok szolgáltatásbeli támogatásának engedélyezéséről további információt a Bináris adatok című témakörben talál.

Tipp.

A bináris adatok támogatásának engedélyezése az üzembe helyezett modell által használt score.py fájlban történik. Az ügyféltől használja a programozási nyelv HTTP-funkcióit. A következő kódrészlet például egy JPG-fájl tartalmát küldi el egy webszolgáltatásnak:

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

Eltérő eredetű erőforrások megosztása (CORS)

A CORS-támogatás szolgáltatásban való engedélyezéséről további információt a Forrásközi erőforrás-megosztás című témakörben talál.

Szolgáltatás meghívása (C#)

Ez a példa bemutatja, hogyan hívhatja meg a C#-ot a Betanított jegyzetfüzet példában létrehozott webszolgáltatás meghívásához:

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

A visszaadott eredmények a következő JSON-dokumentumhoz hasonlóak:

[217.67978776218715, 224.78937091757172]

Szolgáltatás meghívása (Go)

Ez a példa bemutatja, hogyan hívhatja meg a betanított jegyzetfüzetben létrehozott webszolgáltatást a Go használatával:

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

A visszaadott eredmények a következő JSON-dokumentumhoz hasonlóak:

[217.67978776218715, 224.78937091757172]

Szolgáltatás meghívása (Java)

Ez a példa bemutatja, hogyan hívhatja meg a Java használatával a Betanított jegyzetfüzetben létrehozott webszolgáltatást:

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

A visszaadott eredmények a következő JSON-dokumentumhoz hasonlóak:

[217.67978776218715, 224.78937091757172]

Szolgáltatás meghívása (Python)

Ez a példa bemutatja, hogyan hívhatja meg a Pythont a Betanítása jegyzetfüzetben példaként létrehozott webszolgáltatás meghívására:

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)

A visszaadott eredmények a következő JSON-dokumentumhoz hasonlóak:

[217.67978776218715, 224.78937091757172]

Webszolgáltatás-séma (OpenAPI-specifikáció)

Ha automatikus sémalétrehozást használt az üzembe helyezés során, a swagger_uri tulajdonság használatával lekérheti a szolgáltatás OpenAPI-specifikációjának címét. (Például. print(service.swagger_uri)) Használjon GET kérést, vagy nyissa meg az URI-t egy böngészőben a specifikáció lekéréséhez.

Az alábbi JSON-dokumentum egy példa egy üzembe helyezéshez létrehozott sémára (OpenAPI-specifikációra):

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

További információ: OpenAPI-specifikáció.

Az ügyfélkódtárakat a specifikációból létrehozó segédprogramért lásd a swagger-codegen című témakört.

Tipp.

A szolgáltatás üzembe helyezése után lekérheti a séma JSON-dokumentumát. Az üzembe helyezett webszolgáltatás swagger_uri tulajdonságával (például service.swagger_uri) lekérheti az URI-t a helyi webszolgáltatás Swagger-fájljához.

Szolgáltatás felhasználása a Power BI-ból

A Power BI támogatja az Azure Machine Learning webszolgáltatások felhasználását a Power BI-adatok előrejelzésekkel való bővítéséhez.

A Power BI-ban használathoz támogatott webszolgáltatás létrehozásához a sémának támogatnia kell a Power BI által megkövetelt formátumot. Megtudhatja, hogyan hozhat létre Power BI által támogatott sémát.

A webszolgáltatás az üzembe helyezése után a Power BI-adatfolyamokból használható. Ismerje meg, hogyan használható Azure Machine Learning webszolgáltatás a Power BI-ból.

Következő lépések

A Python- és mélytanulási modellek valós idejű pontozásához használható referenciaarchitektúrát az Azure Architektúraközpontban tekintheti meg.