您现在访问的是微软AZURE全球版技术文档网站,若需要访问由世纪互联运营的MICROSOFT AZURE中国区技术文档网站,请访问 https://docs.azure.cn.

使用部署为 Web 服务的 Azure 机器学习模型Consume an Azure Machine Learning model deployed as a web service

将 Azure 机器学习模型部署为 Web 服务可创建 REST API。Deploying an Azure Machine Learning model as a web service creates a REST API. 可将数据发送到此 API,并接收模型返回的预测。You can send data to this API and receive the prediction returned by the model. 本文档介绍了如何使用 C#、Go、Java 和 Python 为 Web 服务创建客户端。In this document, learn how to create clients for the web service by using C#, Go, Java, and Python.

将映像部署到 Azure 容器实例、Azure Kubernetes 服务或现场可编程入口阵列(FPGA)时,可以创建 web 服务。You create a web service when you deploy an image to Azure Container Instances, Azure Kubernetes Service, or field-programmable gate arrays (FPGA). 你将基于已注册的模型和评分文件创建映像。You create images from registered models and scoring files. 你将使用 Azure 机器学习 SDK 检索用来访问 Web 服务的 URI。You retrieve the URI used to access a web service by using the Azure Machine Learning SDK. 如果启用了身份验证,则还可以使用 SDK 获取身份验证密钥或令牌。If authentication is enabled, you can also use the SDK to get the authentication keys or tokens.

用于创建使用机器学习 Web 服务的客户端的常规工作流为:The general workflow for creating a client that uses a machine learning web service is:

  1. 使用 SDK 获取连接信息。Use the SDK to get the connection information.
  2. 确定模型使用的请求数据的类型。Determine the type of request data used by the model.
  3. 创建调用 Web 服务的应用程序。Create an application that calls the web service.

提示

本文档中的示例是手动创建的,而无需使用 OpenAPI (Swagger)规范。The examples in this document are manually created without the use of OpenAPI (Swagger) specifications. 如果已为部署启用了 OpenAPI 规范,则可以使用codegen等工具为你的服务创建客户端库。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.

连接信息Connection information

备注

使用 Azure 机器学习 SDK 获取 Web 服务信息。Use the Azure Machine Learning SDK to get the web service information. 这是一个 Python SDK。This is a Python SDK. 可以使用任何语言来为服务创建客户端。You can use any language to create a client for the service.

azureml.core.Webservice 类提供了创建客户端所需的信息。The azureml.core.Webservice class provides the information you need to create a client. 创建客户端应用程序时,以下 Webservice 属性非常有用:The following Webservice properties are useful for creating a client application:

  • auth_enabled-如果启用密钥身份验证, True则为; False否则为。auth_enabled - If key authentication is enabled, True; otherwise, False.
  • token_auth_enabled-如果启用令牌身份验证, True则为; False否则为。token_auth_enabled - If token authentication is enabled, True; otherwise, False.
  • scoring_uri - REST API 地址。scoring_uri - The REST API address.
  • swagger_uri-OpenAPI 规范的地址。swagger_uri - The address of the OpenAPI specification. 如果已启用自动生成架构,则可以使用此 URI。This URI is available if you enabled automatic schema generation. 有关详细信息,请参阅部署模型与 Azure 机器学习For more information, see Deploy models with Azure Machine Learning.

可通过三种方式检索已部署的 Web 服务的此信息:There are a three ways to retrieve this information for deployed web services:

  • 部署模型时,会返回包含有关服务的信息的 Webservice 对象: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)
    print(service.swagger_uri)
    
  • 可以使用 Webservice.list 检索工作区中为模型部署的 Web 服务列表。You can use Webservice.list to retrieve a list of deployed web services for models in your workspace. 可以添加筛选器,以缩小返回的信息列表范围。You can add filters to narrow the list of information returned. 有关可以筛选的对象的详细信息,请参阅 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)
    print(services[0].swagger_uri)
    
  • 如果知道已部署的服务的名称,可以创建 Webservice 的新实例,并以参数的形式提供工作区和服务名称。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. 新对象包含有关已部署的服务的信息。The new object contains information about the deployed service.

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

服务身份验证Authentication for services

Azure 机器学习提供了两种方法来控制对 web 服务的访问。Azure Machine Learning provides two ways to control access to your web services.

身份验证方法Authentication Method ACIACI AKSAKS
KeyKey 默认情况下禁用Disabled by default 默认情况下启用Enabled by default
令牌Token 不可用Not Available 默认情况下禁用Disabled by default

将请求发送到使用密钥或令牌保护的服务时,请使用__Authorization__标头传递密钥或令牌。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. 密钥或令牌的格式必须为Bearer <key-or-token>,其中<key-or-token>是密钥或令牌值。The key or token must be formatted as Bearer <key-or-token>, where <key-or-token> is your key or token value.

密钥身份验证Authentication with keys

为部署启用身份验证时,会自动创建身份验证密钥。When you enable authentication for a deployment, you automatically create authentication keys.

  • 部署到 Azure Kubernetes 服务时,会默认启用身份验证。Authentication is enabled by default when you are deploying to Azure Kubernetes Service.
  • 部署到 Azure 容器实例时,会默认禁用身份验证。Authentication is disabled by default when you are deploying to Azure Container Instances.

若要控制身份验证,请在创建或更新部署时使用 auth_enabled 参数。To control authentication, use the auth_enabled parameter when you are creating or updating a deployment.

如果已启用身份验证,可以使用 get_keys 方法来检索主要和辅助身份验证密钥: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)

重要

如需重新生成密钥,请使用 service.regen_keyIf you need to regenerate a key, use service.regen_key.

带令牌的身份验证Authentication with tokens

为 web 服务启用令牌身份验证时,用户必须向 web 服务提供 Azure 机器学习 JWT 令牌才能访问该令牌。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.

  • 在部署到 Azure Kubernetes 服务时,令牌身份验证默认情况下处于禁用状态。Token authentication is disabled by default when you are deploying to Azure Kubernetes Service.
  • 在部署到 Azure 容器实例时,令牌身份验证不受支持。Token authentication is not supported when you are deploying to Azure Container Instances.

若要控制令牌身份验证, token_auth_enabled请在创建或更新部署时使用参数。To control token authentication, use the token_auth_enabled parameter when you are creating or updating a deployment.

如果启用了令牌身份验证,则可以使用get_token方法来检索持有者令牌,并确保令牌过期时间: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)

重要

需要在令牌refresh_by时间之后请求新令牌。You will need to request a new token after the token's refresh_by time.

请求数据Request data

REST API 预期请求正文是采用以下结构的 JSON 文档:The REST API expects the body of the request to be a JSON document with the following structure:

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

重要

数据结构需要符合服务中评分脚本和模型的预期。The structure of the data needs to match what the scoring script and model in the service expect. 评分脚本在将数据传递到模型之前可以修改数据。The scoring script might modify the data before passing it to the model.

例如,在笔记本中训练示例中的模型预期存在由 10 个数字构成的数组。For example, the model in the Train within notebook example expects an array of 10 numbers. 此示例的评分脚本从请求创建一个 Numpy 数组,并将其传递给模型。The scoring script for this example creates a Numpy array from the request, and passes it to the model. 以下示例演示此服务预期的数据: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
            ]
        ]
}

Web 服务可以接受一个请求中的多个数据集。The web service can accept multiple sets of data in one request. 它会返回包含响应数组的 JSON 文档。It returns a JSON document containing an array of responses.

二进制数据Binary data

有关如何在服务中启用对二进制数据的支持的信息,请参阅二进制数据For information on how to enable support for binary data in your service, see Binary data.

跨域资源共享 (CORS)Cross-origin resource sharing (CORS)

有关在服务中启用 CORS 支持的信息,请参阅跨域资源共享For information on enabling CORS support in your service, see Cross-origin resource sharing.

调用服务 (C#)Call the service (C#)

此示例演示如何使用 C# 调用在笔记本中训练示例创建的 Web 服务: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);
            }
        }
    }
}

返回的结果类似于以下 JSON 文档:The results returned are similar to the following JSON document:

[217.67978776218715, 224.78937091757172]

调用服务 (Go)Call the service (Go)

此示例演示如何使用 Go 调用在笔记本中训练示例创建的 Web 服务: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))
}

返回的结果类似于以下 JSON 文档:The results returned are similar to the following JSON document:

[217.67978776218715, 224.78937091757172]

调用服务 (Java)Call the service (Java)

此示例演示如何使用 Java 调用在笔记本中训练示例创建的 Web 服务: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());
    }
}

返回的结果类似于以下 JSON 文档:The results returned are similar to the following JSON document:

[217.67978776218715, 224.78937091757172]

调用服务 (Python)Call the service (Python)

此示例演示如何使用 Python 调用在笔记本中训练示例创建的 Web 服务: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)

返回的结果类似于以下 JSON 文档:The results returned are similar to the following JSON document:

[217.67978776218715, 224.78937091757172]

从 Power BI 使用服务Consume the service from Power BI

Power BI 支持 Azure 机器学习 web 服务的使用,使用预测来丰富 Power BI 数据。Power BI supports consumption of Azure Machine Learning web services to enrich the data in Power BI with predictions.

若要生成 Power BI 中使用的 web 服务,架构必须支持 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. 了解如何创建 Power BI 支持的架构Learn how to create a Power BI-supported schema.

部署 web 服务后,可通过 Power BI 数据流来利用它。Once the web service is deployed, it's consumable from Power BI dataflows. 了解如何从 Power BI 使用 Azure 机器学习 web 服务Learn how to consume an Azure Machine Learning web service from Power BI.

后续步骤Next steps

若要查看 Python 和深度学习模型的实时评分的参考体系结构,请参阅Azure 体系结构中心To view a reference architecture for real-time scoring of Python and deep learning models, go to the Azure architecture center.