Consumir um modelo do Azure Machine Learning implementado como serviço Web
A implementação de um modelo do Azure Machine Learning como serviço Web cria um ponto final da API REST. Pode enviar dados para este ponto final e receber a predição devolvida pelo modelo. Neste documento, saiba como criar clientes para o serviço Web usando C#, Go, Java e Python.
Você cria um serviço Web quando implanta um modelo em seu ambiente local, Instâncias de Contêiner do Azure, Serviço Kubernetes do Azure ou FPGA (field-programmable gate arrays). Você recupera o URI usado para acessar o serviço Web usando o SDK do Azure Machine Learning. Se a autenticação estiver habilitada, você também poderá usar o SDK para obter as chaves ou tokens de autenticação.
O fluxo de trabalho geral para criar um cliente que usa um serviço Web de aprendizado de máquina é:
- Utilize o SDK para obter as informações de ligação.
- Determine o tipo de dados de pedido utilizados pelo modelo.
- Crie uma aplicação que chame o serviço Web.
Gorjeta
Os exemplos neste documento são criados manualmente sem o uso de especificações OpenAPI (Swagger). Se você habilitou uma especificação OpenAPI para sua implantação, poderá usar ferramentas como swagger-codegen para criar bibliotecas de cliente para seu serviço.
Importante
Alguns dos comandos da CLI do Azure neste artigo usam a extensão , ou v1, para o azure-cli-mlAzure Machine Learning. O suporte para a extensão v1 terminará em 30 de setembro de 2025. Você poderá instalar e usar a extensão v1 até essa data.
Recomendamos que você faça a transição para a mlextensão , ou v2, antes de 30 de setembro de 2025. Para obter mais informações sobre a extensão v2, consulte Extensão CLI do Azure ML e Python SDK v2.
Informações da ligação
Nota
Use o SDK do Azure Machine Learning para obter as informações do serviço Web. Este é um SDK do Python. Você pode usar qualquer idioma para criar um cliente para o serviço.
A classe azureml.core.Webservice fornece as informações necessárias para criar um cliente. As seguintes Webservice propriedades são úteis para criar um aplicativo cliente:
auth_enabled- Se a autenticação de chave estiver ativada,Truecaso contrário,False.token_auth_enabled- Se a autenticação de token estiver ativada,Truecaso contrário,False.scoring_uri- O endereço da API REST.swagger_uri- O endereço da especificação OpenAPI. Esse URI estará disponível se você tiver habilitado a geração automática de esquema. Para obter mais informações, consulte Implantar modelos com o Azure Machine Learning.
Há várias maneiras de recuperar essas informações para serviços Web implantados:
APLICA-SE A:
Python SDK azureml v1
Quando você implanta um modelo, um
Webserviceobjeto é retornado com informações sobre o serviço: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)Você pode usar
Webservice.listpara recuperar uma lista de serviços Web implantados para modelos em seu espaço de trabalho. Você pode adicionar filtros para restringir a lista de informações retornadas. Para obter mais informações sobre o que pode ser filtrado, consulte a documentação de referência Webservice.list.services = Webservice.list(ws) print(services[0].scoring_uri) print(services[0].swagger_uri)Se você souber o nome do serviço implantado, poderá criar uma nova instância do e fornecer o espaço de trabalho e o nome do
Webserviceserviço como parâmetros. O novo objeto contém informações sobre o serviço implantado.service = Webservice(workspace=ws, name='myservice') print(service.scoring_uri) print(service.swagger_uri)
A tabela a seguir mostra a aparência desses URIs:
| Tipo de URI | Exemplo |
|---|---|
| URI de pontuação | 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 |
Gorjeta
O endereço IP será diferente para sua implantação. Cada cluster AKS terá seu próprio endereço IP que é compartilhado por implantações nesse cluster.
Serviço Web protegido
Se você protegeu o serviço Web implantado usando um certificado TLS/SSL, poderá usar HTTPS para se conectar ao serviço usando a pontuação ou o URI swagger. O HTTPS ajuda a proteger as comunicações entre um cliente e um serviço Web criptografando as comunicações entre os dois. A criptografia usa Transport Layer Security (TLS). TLS às vezes ainda é referido como Secure Sockets Layer (SSL), que foi o antecessor do TLS.
Importante
Os serviços Web implementados pelo Azure Machine Learning suportam apenas TLS versão 1.2. Ao criar um aplicativo cliente, certifique-se de que ele suporta esta versão.
Para obter mais informações, veja Utilizar o TLS para proteger um serviço Web através do Azure Machine Learning.
Autenticação para serviços
O Azure Machine Learning oferece duas formas de controlar o acesso aos serviços Web.
| Método de autenticação | ACI | AKS |
|---|---|---|
| Chave | Desativado por predefinição | Ativado por predefinição |
| Token | Não Disponível | Desativado por predefinição |
Ao enviar uma solicitação para um serviço protegido com uma chave ou token, use o cabeçalho Autorização para passar a chave ou token. A chave ou o token deve ser formatado como Bearer <key-or-token>, em que <key-or-token> é o valor da chave ou do token.
A principal diferença entre chaves e tokens é que as chaves são estáticas e podem ser regeneradas manualmente, e os tokens precisam ser atualizados após a expiração. A autenticação baseada em chave tem suporte para a Instância de Contêiner do Azure e os serviços Web implantados do Serviço Kubernetes do Azure, e a autenticação baseada em token só está disponível para implantações do Serviço Kubernetes do Azure. Para obter mais informações sobre como configurar a autenticação, consulte Configurar a autenticação para modelos implantados como serviços Web.
Autenticação com chaves
Ao habilitar a autenticação para uma implantação, você cria automaticamente chaves de autenticação.
- A autenticação é habilitada por padrão quando você está implantando no Serviço Kubernetes do Azure.
- A autenticação é desabilitada por padrão quando você está implantando em Instâncias de Contêiner do Azure.
Para controlar a autenticação, use o auth_enabled parâmetro quando estiver criando ou atualizando uma implantação.
Se a autenticação estiver habilitada, você poderá usar o get_keys método para recuperar uma chave de autenticação primária e secundária:
primary, secondary = service.get_keys()
print(primary)
Importante
Se precisar regenerar uma chave, use service.regen_key.
Autenticação com tokens
Quando você habilita a autenticação de token para um serviço Web, um usuário deve fornecer um token JWT do Azure Machine Learning ao serviço Web para acessá-lo.
- A autenticação de token é desabilitada por padrão quando você está implantando no Serviço Kubernetes do Azure.
- A autenticação de token não é suportada quando você está implantando em Instâncias de Contêiner do Azure.
Para controlar a autenticação de token, use o token_auth_enabled parâmetro quando estiver criando ou atualizando uma implantação.
Se a autenticação de token estiver habilitada, você poderá usar o get_token método para recuperar um token de portador e esse tempo de expiração de tokens:
token, refresh_by = service.get_token()
print(token)
Se você tiver a CLI do Azure e a extensão de aprendizado de máquina, poderá usar o seguinte comando para obter um token:
APLICA-SE A: Azure CLI ml extension v1
az ml service get-access-token -n <service-name>
Importante
Atualmente, a única maneira de recuperar o token é usando o SDK do Azure Machine Learning ou a extensão de aprendizado de máquina da CLI do Azure.
Precisará de pedir um novo token depois do prazo refresh_by do token.
Solicitar dados
A API REST espera que o corpo da solicitação seja um documento JSON com a seguinte estrutura:
{
"data":
[
<model-specific-data-structure>
]
}
Importante
A estrutura dos dados precisa corresponder ao que o script e o modelo de pontuação no serviço esperam. O script de pontuação pode modificar os dados antes de passá-los para o modelo.
Dados binários
Para obter informações sobre como habilitar o suporte para dados binários em seu serviço, consulte Dados binários.
Gorjeta
A habilitação do suporte para dados binários acontece no arquivo score.py usado pelo modelo implantado. A partir do cliente, use a funcionalidade HTTP da sua linguagem de programação. Por exemplo, o trecho a seguir envia o conteúdo de um arquivo JPG para um serviço Web:
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'})
Partilha de recursos transversais à origem (CORS)
Para obter informações sobre como habilitar o suporte a CORS em seu serviço, consulte Compartilhamento de recursos entre origens.
Chamar o serviço (C#)
Este exemplo demonstra como usar C# para chamar o serviço Web criado a partir do exemplo Train within 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);
}
}
}
}
Os resultados retornados são semelhantes ao seguinte documento JSON:
[217.67978776218715, 224.78937091757172]
Chamar o serviço (Go)
Este exemplo demonstra como usar Go para chamar o serviço Web criado a partir do exemplo Train within 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))
}
Os resultados retornados são semelhantes ao seguinte documento JSON:
[217.67978776218715, 224.78937091757172]
Chamar o serviço (Java)
Este exemplo demonstra como usar Java para chamar o serviço Web criado a partir do exemplo Train within 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());
}
}
Os resultados retornados são semelhantes ao seguinte documento JSON:
[217.67978776218715, 224.78937091757172]
Chamar o serviço (Python)
Este exemplo demonstra como usar Python para chamar o serviço Web criado a partir do exemplo Train within 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)
Os resultados retornados são semelhantes ao seguinte documento JSON:
[217.67978776218715, 224.78937091757172]
Esquema de serviço Web (especificação OpenAPI)
Se você usou a geração automática de esquema com sua implantação, você pode obter o endereço da especificação OpenAPI para o serviço usando a propriedade swagger_uri. (Por exemplo, print(service.swagger_uri).) Use uma solicitação GET ou abra o URI em um navegador para recuperar a especificação.
O documento JSON a seguir é um exemplo de um esquema (especificação OpenAPI) gerado para uma implantação:
{
"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"
}
}
}
}
}
Para obter mais informações, consulte Especificação OpenAPI.
Para obter um utilitário que pode criar bibliotecas de cliente a partir da especificação, consulte swagger-codegen.
Gorjeta
Você pode recuperar o documento JSON do esquema depois de implantar o serviço. Use a propriedade swagger_uri do serviço Web implantado (por exemplo, service.swagger_uri) para obter o URI para o arquivo Swagger do serviço Web local.
Consumir o serviço no Power BI
O Power BI suporta o consumo de serviços Web do Azure Machine Learning para melhorar os dados no Power BI com previsões.
Para gerar um serviço Web com suporte para consumo no Power BI, o esquema deve dar suporte ao formato exigido pelo Power BI. Saiba como criar um esquema suportado pelo Power BI.
Assim que o serviço Web for implementado, poderá ser consumido nos fluxos de dados do Power BI. Saiba como consumir um serviço Web do Azure Machine Learning no Power BI.
Próximos passos
Para exibir uma arquitetura de referência para pontuação em tempo real de Python e modelos de aprendizado profundo, vá para o centro de arquitetura do Azure.
Comentários
Brevemente: Ao longo de 2024, vamos descontinuar progressivamente o GitHub Issues como mecanismo de feedback para conteúdos e substituí-lo por um novo sistema de feedback. Para obter mais informações, veja: https://aka.ms/ContentUserFeedback.
Submeter e ver comentários