Использование модели Машинного обучения Azure, развернутой в качестве веб-службы

При развертывании модели Машинного обучения Azure в качестве веб-службы создается конечная точка REST API. Через эту конечную точку вы можете отправлять данные в модель и получать от нее прогнозы. В этом документе описано, как создать клиенты для работы с веб-службой на языках C#, Go, Java и Python.

При развертывании модели в локальной среде, Экземпляры контейнеров Azure или Служба Azure Kubernetes создается веб-служба. Универсальный код ресурса (URI) для доступа к веб-службе можно получить с помощью пакета SDK для Машинного обучения Azure. Если включена проверка подлинности, с помощью этого пакета SDK вы можете также получить и ключи или маркеры проверки подлинности.

Ниже приведен общий рабочий процесс создания клиента, который использует веб-службу Машинного обучения:

1. Получение сведений о подключении с помощью пакета SDK.
2. Определение типа данных запроса, которые используются моделью.
3. Создание приложения, которое обращается к веб-службе.

Сведения о подключении

Класс azureml.core.Webservice предоставляет необходимые сведения для создания клиента. Следующие свойства Webservice могут быть полезны при создании клиентского приложения:

• auth_enabled — если включена проверка подлинности на основе ключей, имеет значение True, в противном случае — False.
• token_auth_enabled — если включена проверка подлинности на основе маркеров, имеет значение True, в противном случае — False.
• scoring_uri — адрес REST API.
• swagger_uri — адрес спецификации OpenAPI. Этот универсальный код ресурса (URI) доступен, если включено автоматическое создание схем. Дополнительные сведения см. в статье Развертывание моделей в системе Машинного обучения Azure.

Эти сведения для развернутой веб-службы можно получить несколькими способами.

az ml service show -n <service-name>

В следующей таблице показано, как выглядят эти универсальные коды ресурса (URI).

Защищенная веб-служба

Если вы защитили развернутую веб-службу с помощью сертификата TLS/SSL, то вы можете использовать протокол HTTPS для подключения к службе с помощью URI оценки или Swagger. Протокол HTTPS обеспечивает безопасность обмена данными между клиентом и веб-службой путем шифрования обмена данными между ними. Для шифрования используется протокол TLS. Протокол TLS иногда по-прежнему называют протоколом SSL (предшественник TLS).

Дополнительные сведения см. в статье Использование TLS для защиты веб-службы с помощью Машинного обучения Azure.

Проверка подлинности служб

Машинное обучение Azure предоставляет два способа управления доступом к веб-службам.

При отправке запроса к службе, защищенной с помощью ключа или маркера, используйте заголовок Authorization для передачи ключа или маркера. Ключ или маркер должен использовать формат Bearer <key-or-token>, где <key-or-token> — это значение ключа или маркера.

Основное различие между ключами и маркерами состоит в том, что ключи являются статическими и могут быть повторно созданы вручную, а маркеры необходимо обновлять после истечения срока действия. Проверка подлинности на основе ключей поддерживается для веб-служб, развернутых в Экземплярах контейнеров Azure и Службе Azure Kubernetes, а проверка подлинности на основе маркеров доступна только для развертываний Службы Kubernetes Azure. Дополнительные сведения о настройке проверки подлинности см. в разделе Настройка проверки подлинности для моделей, развернутых в виде веб-служб.

Проверка подлинности на основе ключей

При включении проверки подлинности для развертывания автоматически создаются ключи проверки подлинности.

• Проверка подлинности включена по умолчанию при развертывании в Службе Azure Kubernetes.
• Проверка подлинности отключена по умолчанию при развертывании в Экземплярах контейнеров Azure.

Для управления проверкой подлинности используйте параметр auth_enabled при создании или обновлении развертывания.

Если включена проверка подлинности, можно использовать метод get_keys для извлечения первичного и вторичного ключей проверки подлинности:

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

Проверка подлинности на основе маркеров

При активации аутентификации с помощью маркера для веб-службы пользователь должен предоставить веб-службе Azure Machine Learning JWT, чтобы получить доступ к ней.

• Проверка подлинности на основе маркеров отключена по умолчанию при развертывании в Службе Azure Kubernetes.
• Проверка подлинности на основе маркеров не поддерживается при развертывании в Экземплярах контейнеров Azure.

Для управления проверкой подлинности используйте параметр token_auth_enabled при создании или обновлении развертывания.

Если включена проверка подлинности на основе маркеров, можно использовать метод get_token для получения маркера носителя и его срока действия.

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

Если у вас установлены Azure CLI и расширение машинного обучения, то для получения маркера можно использовать следующую команду.

ОБЛАСТЬ ПРИМЕНЕНИЯ: расширение машинного обучения Azure CLI версии 1

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

После истечения срока действия маркера безопасности refresh_by необходимо запрашивать новый маркер.

Данные запроса

REST API ожидает, что текст запроса содержит документ JSON со следующей структурой:

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

Двоичные данные

Чтобы узнать, как включить поддержку двоичных данных в службе, ознакомьтесь с двоичными данными.

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

Общий доступ к ресурсам независимо от источника (CORS)

Чтобы узнать, как включить поддержку CORS в службе, ознакомьтесь с общим доступом к ресурсам независимо от источника.

Вызов службы с помощью C#

В этом примере показано, как использовать C# для вызова веб-службы:

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.

[217.67978776218715, 224.78937091757172]

Вызов службы с помощью Python

В этом примере показано, как использовать Python для вызова веб-службы:

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.

[217.67978776218715, 224.78937091757172]

Схема веб-службы (спецификация OpenAPI)

Если вы использовали автоматическое создание схем в развертывании, то вы можете получить адрес спецификации OpenAPI для службы с помощью свойства swagger_uri. (Например, print(service.swagger_uri).) Используйте запрос GET или откройте универсальный код ресурса (URI) в браузере, чтобы получить эту спецификацию.

Следующий документ JSON является примером схемы (спецификации OpenAPI), созданной для развертывания.

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

Дополнительные сведения см. в спецификации OpenAPI.

Сведения о служебной программе, которая может создавать клиентские библиотеки на основе спецификации, можно получить на странице swagger-codegen.

Следующие шаги

Чтобы просмотреть эталонную архитектуру для оценки в реальном времени моделей Python и глубокого обучения, перейдите в Центр архитектуры Azure.