Consumir um modelo do Azure Machine Learning implementado como um serviço webConsume an Azure Machine Learning model deployed as a web service

Implementar um modelo do Azure Machine Learning como um serviço web cria uma API REST.Deploying an Azure Machine Learning model as a web service creates a REST API. Pode enviar dados para esta API e receber a predição devolvida pelo modelo.You can send data to this API and receive the prediction returned by the model. Neste documento, aprenda a criar clientes para o serviço Web usando C#o, o go, o Java e o Python.In this document, learn how to create clients for the web service by using C#, Go, Java, and Python.

Você cria um serviço Web ao implantar uma imagem nas instâncias de contêiner do Azure, no serviço kubernetes do Azure ou em FPGA (matrizes de porta programável por campo).You create a web service when you deploy an image to Azure Container Instances, Azure Kubernetes Service, or field-programmable gate arrays (FPGA). Você cria imagens de modelos registrados e arquivos de pontuação.You create images from registered models and scoring files. Você recupera o URI usado para acessar um serviço Web usando o SDK do Azure Machine Learning.You retrieve the URI used to access a web service by using the Azure Machine Learning SDK. Se a autenticação estiver habilitada, você também poderá usar o SDK para obter as chaves de autenticação ou os tokens.If authentication is enabled, you can also use the SDK to get the authentication keys or tokens.

O fluxo de trabalho geral para criar um cliente que usa um serviço Web do Machine Learning é:The general workflow for creating a client that uses a machine learning web service is:

  1. Use o SDK para obter as informações de conexão.Use the SDK to get the connection information.
  2. Determine o tipo de dados de solicitação usados pelo modelo.Determine the type of request data used by the model.
  3. Crie um aplicativo que chama o serviço Web.Create an application that calls the web service.

Dica

Os exemplos neste documento são criados manualmente sem o uso de especificações de OpenAPI (Swagger).The examples in this document are manually created without the use of OpenAPI (Swagger) specifications. Se você habilitou uma especificação OpenAPI para sua implantação, poderá usar ferramentas como o Swagger-CodeGen para criar bibliotecas de cliente para seu serviço.If you've enabled an OpenAPI specification for your deployment, you can use tools such as swagger-codegen to create client libraries for your service.

Informações da ligaçãoConnection information

Nota

Use o SDK do Azure Machine Learning para obter as informações do serviço Web.Use the Azure Machine Learning SDK to get the web service information. Trata-se de um SDK de Python.This is a Python SDK. Você pode usar qualquer linguagem para criar um cliente para o serviço.You can use any language to create a client for the service.

A classe azureml. Core. WebService fornece as informações necessárias para criar um cliente.The azureml.core.Webservice class provides the information you need to create a client. As propriedades Webservice a seguir são úteis para criar um aplicativo cliente:The following Webservice properties are useful for creating a client application:

  • auth_enabled-Se a autenticação de chave estiver Truehabilitada, Falsecaso contrário,.auth_enabled - If key authentication is enabled, True; otherwise, False.
  • token_auth_enabled-Se a autenticação de token estiver Truehabilitada, Falsecaso contrário,.token_auth_enabled - If token authentication is enabled, True; otherwise, False.
  • scoring_uri -O endereço da REST API.scoring_uri - The REST API address.

Para obter estas informações para os serviços web implementados, há um três formas:There are a three ways to retrieve this information for deployed web services:

  • Quando implementa um modelo, um Webservice objeto é devolvido com informações sobre o serviço:When you deploy a model, a Webservice object is returned with information about the service:

    service = Webservice.deploy_from_model(name='myservice',
                                           deployment_config=myconfig,
                                           models=[model],
                                           image_config=image_config,
                                           workspace=ws)
    print(service.scoring_uri)
    
  • Pode usar Webservice.list obter uma lista de implantados serviços da web para modelos em sua área de trabalho.You can use Webservice.list to retrieve a list of deployed web services for models in your workspace. Pode adicionar filtros para refinar a lista de informações devolvidas.You can add filters to narrow the list of information returned. Para obter mais informações sobre o que pode ser filtrado, consulte a documentação de referência do WebService. List .For more information about what can be filtered on, see the Webservice.list reference documentation.

    services = Webservice.list(ws)
    print(services[0].scoring_uri)
    
  • Se você souber o nome do serviço implantado, poderá criar uma nova instância do Webservicee fornecer o espaço de trabalho e o nome do serviço como parâmetros.If you know the name of the deployed service, you can create a new instance of Webservice, and provide the workspace and service name as parameters. O novo objeto contém informações sobre o serviço implementado.The new object contains information about the deployed service.

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

Autenticação para serviçosAuthentication for services

O Azure Machine Learning fornece duas maneiras de controlar o acesso aos serviços Web.Azure Machine Learning provides two ways to control access to your web services.

Método de AutenticaçãoAuthentication Method ACIACI AKSAKS
ChaveKey Desabilitado por padrãoDisabled by default Habilitado por padrãoEnabled by default
Certificado deToken Não DisponívelNot Available Desabilitado por padrãoDisabled by default

Ao enviar uma solicitação para um serviço protegido com uma chave ou token, use o cabeçalho de autorização para passar a chave ou o token.When sending a request to a service that is secured with a key or token, use the Authorization header to pass the key or token. A chave ou o token devem ser formatados Bearer <key-or-token>como <key-or-token> , em que é o valor da chave ou do token.The key or token must be formatted as Bearer <key-or-token>, where <key-or-token> is your key or token value.

Autenticação com chavesAuthentication with keys

Ao habilitar a autenticação para uma implantação, você cria automaticamente chaves de autenticação.When you enable authentication for a deployment, you automatically create authentication keys.

  • A autenticação é habilitada por padrão quando você está implantando no serviço kubernetes do Azure.Authentication is enabled by default when you are deploying to Azure Kubernetes Service.
  • A autenticação é desabilitada por padrão quando você está implantando em instâncias de contêiner do Azure.Authentication is disabled by default when you are deploying to Azure Container Instances.

Para controlar a autenticação, use auth_enabled o parâmetro ao criar ou atualizar uma implantação.To control authentication, use the auth_enabled parameter when you are creating or updating a deployment.

Se a autenticação estiver ativada, pode utilizar o get_keys método para recuperar uma chave de autenticação primária e secundária:If authentication is enabled, you can use the get_keys method to retrieve a primary and secondary authentication key:

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

Importante

Se precisar de voltar a gerar uma chave, utilize service.regen_key .If you need to regenerate a key, use service.regen_key.

Autenticação com tokensAuthentication with tokens

Quando você habilita a autenticação de token para um serviço Web, um usuário deve fornecer um Azure Machine Learning token JWT para o serviço Web para acessá-lo.When you enable token authentication for a web service, a user must provide an Azure Machine Learning JWT token to the web service to access it.

  • A autenticação de token é desabilitada por padrão quando você está implantando no serviço kubernetes do Azure.Token authentication is disabled by default when you are deploying to Azure Kubernetes Service.
  • Não há suporte para autenticação de token quando você está implantando em instâncias de contêiner do Azure.Token authentication is not supported when you are deploying to Azure Container Instances.

Para controlar a autenticação de token, token_auth_enabled use o parâmetro ao criar ou atualizar uma implantação.To control token authentication, use the token_auth_enabled parameter when you are creating or updating a deployment.

Se a autenticação de token estiver habilitada, você get_token poderá usar o método para recuperar um token de portador e o tempo de expiração dos tokens:If token authentication is enabled, you can use the get_token method to retrieve a bearer token and that tokens expiration time:

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

Importante

Será necessário solicitar um novo token após a hora do refresh_by token.You will need to request a new token after the token's refresh_by time.

Dados de pedidosRequest data

A API REST espera que o corpo da solicitação para ser um documento JSON com a seguinte estrutura:The REST API expects the body of the request to be a JSON document with the following structure:

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

Importante

A estrutura dos dados tem de corresponder ao que a classificação script e o modelo no expect serviço.The structure of the data needs to match what the scoring script and model in the service expect. O script de classificação pode modificar os dados antes de o transmitir para o modelo.The scoring script might modify the data before passing it to the model.

Por exemplo, o modelo no Train dentro do bloco de notas exemplo espera uma matriz de 10 números.For example, the model in the Train within notebook example expects an array of 10 numbers. O script de Pontuação para este exemplo cria uma matriz numpy da solicitação e a passa para o modelo.The scoring script for this example creates a Numpy array from the request, and passes it to the model. O exemplo seguinte mostra os dados que deste serviço de espera:The following example shows the data this service expects:

{
    "data": 
        [
            [
                0.0199132141783263, 
                0.0506801187398187, 
                0.104808689473925, 
                0.0700725447072635, 
                -0.0359677812752396, 
                -0.0266789028311707, 
                -0.0249926566315915, 
                -0.00259226199818282, 
                0.00371173823343597, 
                0.0403433716478807
            ]
        ]
}

O serviço web pode aceitar vários conjuntos de dados numa solicitação.The web service can accept multiple sets of data in one request. Ele retorna um documento JSON que contenha uma matriz de respostas.It returns a JSON document containing an array of responses.

Dados bináriosBinary data

Para obter informações sobre como habilitar o suporte para dados binários em seu serviço, consulte dados binários.For information on how to enable support for binary data in your service, see Binary data.

CORS (compartilhamento de recursos entre origens)Cross-origin resource sharing (CORS)

Para obter informações sobre como habilitar o suporte a CORS em seu serviço, consulte compartilhamento de recursos entre origens.For information on enabling CORS support in your service, see Cross-origin resource sharing.

Chamar o serviço (C#)Call the service (C#)

Este exemplo demonstra como utilizar o C# para chamar o serviço web criado a partir do Train dentro do bloco de notas exemplo:This example demonstrates how to use C# to call the web service created from the Train within notebook example:

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

Os resultados retornados são semelhantes para o documento JSON seguinte:The results returned are similar to the following JSON document:

[217.67978776218715, 224.78937091757172]

Chamar o serviço (Go)Call the service (Go)

Este exemplo demonstra como utilizar o Go para chamar o serviço web criado a partir da Train dentro do bloco de notas exemplo:This example demonstrates how to use Go to call the web service created from the Train within notebook example:

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

Os resultados retornados são semelhantes para o documento JSON seguinte:The results returned are similar to the following JSON document:

[217.67978776218715, 224.78937091757172]

Chamar o serviço (Java)Call the service (Java)

Este exemplo demonstra como utilizar o Java para chamar o serviço web criado a partir da Train dentro do bloco de notas exemplo:This example demonstrates how to use Java to call the web service created from the Train within notebook example:

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

Os resultados retornados são semelhantes para o documento JSON seguinte:The results returned are similar to the following JSON document:

[217.67978776218715, 224.78937091757172]

Chamar o serviço (Python)Call the service (Python)

Este exemplo demonstra como utilizar Python para chamar o web service criado a partir da Train dentro do bloco de notas exemplo:This example demonstrates how to use Python to call the web service created from the Train within notebook example:

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)

Os resultados retornados são semelhantes para o documento JSON seguinte:The results returned are similar to the following JSON document:

[217.67978776218715, 224.78937091757172]

Consumir o serviço de Power BIConsume the service from Power BI

O Power BI dá suporte ao consumo de serviços Web Azure Machine Learning para enriquecer os dados em Power BI com previsões.Power BI supports consumption of Azure Machine Learning web services to enrich the data in Power BI with predictions.

Para gerar um serviço Web com suporte para consumo no Power BI, o esquema deve dar suporte ao formato exigido pelo Power BI.To generate a web service that's supported for consumption in Power BI, the schema must support the format that's required by Power BI. Saiba como criar um esquema com suporte a Power bi.Learn how to create a Power BI-supported schema.

Depois que o serviço Web for implantado, ele será consumível de Power BI fluxos de os.Once the web service is deployed, it's consumable from Power BI dataflows. Saiba como consumir um serviço web Azure Machine Learning do Power bi.Learn how to consume an Azure Machine Learning web service from Power BI.

Passos SeguintesNext steps

Para exibir uma arquitetura de referência para a pontuação em tempo real dos modelos de aprendizado profundo e Python, vá para o centro de arquitetura do Azure.To view a reference architecture for real-time scoring of Python and deep learning models, go to the Azure architecture center.