Разработка расширенных сценариев ввода

Статья
10/16/2024

ОБЛАСТЬ ПРИМЕНЕНИЯ: Пакет SDK для Python версии 1

В этой статье объясняется, как писать скрипты записи для специализированных вариантов использования.

Необходимые компоненты

В этой статье предполагается, что у вас уже есть обученная модель машинного обучения, которую планируется развернуть с помощью Машинного обучения Azure. Дополнительные сведения о развертывании моделей см. в статье "Развертывание моделей машинного обучения в Azure".

Автоматическое создание схемы Swagger

Чтобы автоматически создать схему для веб-службы, укажите образец входных и (или) выходных данных в конструкторе для одного из объектов определенного типа. Тип и образец используются для автоматического создания схемы. Машинное обучение Azure затем создает Спецификация OpenAPI (ранее — спецификация Swagger) для веб-службы во время развертывания.

Предупреждение

Для образца ввода или вывода не следует использовать конфиденциальные или закрытые данные. На странице Swagger для вывода на основе AML отображаются образцы данных.

Сейчас поддерживаются следующие типы:

pandas
numpy
pyspark
Стандартный объект Python

Чтобы использовать формирование схемы, включите пакет с открытым исходным кодом inference-schema 1.1.0 или более поздней версии в файл зависимостей. Дополнительные сведения об этом пакете см. в разделе InferenceSchema на GitHub. Чтобы создать соответствие Swagger для автоматического использования веб-служб, функция запуска скрипта оценки должна иметь форму API:

Первый параметр типа StandardPythonParameterType, именованный входными данными и вложенными
Необязательный второй параметр типа StandardPythonParameterTypeс именем GlobalParameters
Возвращает словарь типа StandardPythonParameterType, именованные результаты и вложенные

Определите форматы входных и выходных данных в переменных input_sample и output_sample, которые представляют форматы запросов и ответов для веб-службы. Используйте эти примеры в декораторах входных и выходных функций функции run(). В следующем примере scikit-learn использует создание схемы.

Совместимая с Power BI конечная точка

В следующем примере показано, как определить форму API в соответствии с предыдущей инструкцией. Этот метод поддерживается для использования развернутой веб-службы из Power BI.

import json
import pickle
import numpy as np
import pandas as pd
import azureml.train.automl
from sklearn.externals import joblib
from sklearn.linear_model import Ridge

from inference_schema.schema_decorators import input_schema, output_schema
from inference_schema.parameter_types.standard_py_parameter_type import StandardPythonParameterType
from inference_schema.parameter_types.numpy_parameter_type import NumpyParameterType
from inference_schema.parameter_types.pandas_parameter_type import PandasParameterType


def init():
    global model
    # Replace filename if needed.
    model_path = os.path.join(os.getenv('AZUREML_MODEL_DIR'), 'sklearn_regression_model.pkl')
    # Deserialize the model file back into a sklearn model.
    model = joblib.load(model_path)


# providing 3 sample inputs for schema generation
numpy_sample_input = NumpyParameterType(np.array([[1,2,3,4,5,6,7,8,9,10],[10,9,8,7,6,5,4,3,2,1]],dtype='float64'))
pandas_sample_input = PandasParameterType(pd.DataFrame({'name': ['Sarah', 'John'], 'age': [25, 26]}))
standard_sample_input = StandardPythonParameterType(0.0)

# This is a nested input sample, any item wrapped by `ParameterType` will be described by schema
sample_input = StandardPythonParameterType({'input1': numpy_sample_input, 
                                        'input2': pandas_sample_input, 
                                        'input3': standard_sample_input})

sample_global_parameters = StandardPythonParameterType(1.0) # this is optional
sample_output = StandardPythonParameterType([1.0, 1.0])
outputs = StandardPythonParameterType({'Results':sample_output}) # 'Results' is case sensitive

@input_schema('Inputs', sample_input) 
# 'Inputs' is case sensitive

@input_schema('GlobalParameters', sample_global_parameters) 
# this is optional, 'GlobalParameters' is case sensitive

@output_schema(outputs)

def run(Inputs, GlobalParameters): 
    # the parameters here have to match those in decorator, both 'Inputs' and 
    # 'GlobalParameters' here are case sensitive
    try:
        data = Inputs['input1']
        # data will be convert to target format
        assert isinstance(data, np.ndarray)
        result = model.predict(data)
        return result.tolist()
    except Exception as e:
        error = str(e)
        return error

Совет

Возвращаемым значением из скрипта может быть любой объект Python, сериализуемый в JSON. Например, если модель возвращает таблицу данных Pandas, содержащую несколько столбцов, то можно использовать выходной декоратор, аналогичный приведенному ниже коду:

output_sample = pd.DataFrame(data=[{"a1": 5, "a2": 6}])
@output_schema(PandasParameterType(output_sample))
...
result = model.predict(data)
return result

Двоичные данные (т. е. изображения)

Если модель принимает двоичные данные, например изображение, необходимо изменить файл score.py , используемый для развертывания, чтобы принимать необработанные HTTP-запросы. Чтобы принимать необработанные данные, используйте класс AMLRequest в скрипте записи и добавьте декоратор @rawhttp в функцию run().

Ниже приведен пример score.py, который принимает двоичные данные:

from azureml.contrib.services.aml_request import AMLRequest, rawhttp
from azureml.contrib.services.aml_response import AMLResponse
from PIL import Image
import json


def init():
    print("This is init()")
    

@rawhttp
def run(request):
    print("This is run()")
    
    if request.method == 'GET':
        # For this example, just return the URL for GETs.
        respBody = str.encode(request.full_path)
        return AMLResponse(respBody, 200)
    elif request.method == 'POST':
        file_bytes = request.files["image"]
        image = Image.open(file_bytes).convert('RGB')
        # For a real-world solution, you would load the data from reqBody
        # and send it to the model. Then return the response.

        # For demonstration purposes, this example just returns the size of the image as the response.
        return AMLResponse(json.dumps(image.size), 200)
    else:
        return AMLResponse("bad request", 500)

Внимание

Класс AMLRequest находится в пространстве имен azureml.contrib. Возможности пространства имен быстро изменяются, так как мы работаем над улучшением службы. Поэтому все, что доступно в этом пространстве имен, считается предварительными версиями компонентов, поддержка которых корпорацией Майкрософт ограничена.

Если необходимо протестировать это в локальной среде разработки, можно установить компоненты с помощью следующей команды:

pip install azureml-contrib-services

Примечание.

500 не рекомендуется в качестве пользовательского кода состояния, так как на стороне azureml-fe код состояния будет перезаписан до 502.

Код состояния передается через azureml-fe, а затем отправляется клиенту.
Azureml-fe перезаписывает только 500, возвращенных с стороны модели, на 502, клиент получает 502.
Но если сам azureml-fe возвращает 500, клиентская сторона по-прежнему получает 500.

Класс AMLRequest позволяет получить доступ только к необработанным опубликованным данным в файле score.py , нет клиентского компонента. С клиента данные отводятся как обычные. Например, следующий код Python считывает файл изображения и отправляет данные:

import requests

uri = service.scoring_uri
image_path = 'test.jpg'
files = {'image': open(image_path, 'rb').read()}
response = requests.post(uri, files=files)

print(response.json)

Совместное использование ресурсов в разных источниках позволяет запрашивать ресурсы на веб-странице из другого домена. CORS работает через заголовки HTTP, отправленные с клиентским запросом и возвращаемые с ответом службы. Дополнительные сведения о CORS и допустимых заголовках см. в разделе общий доступ к ресурсам между источниками в Википедии.

Чтобы настроить развертывание модели для поддержки CORS, используйте класс AMLResponse в скрипте записи. Этот класс позволяет задать заголовки для объекта ответа.

В следующем примере задается заголовок Access-Control-Allow-Origin для ответа из скрипта записи:

from azureml.contrib.services.aml_request import AMLRequest, rawhttp
from azureml.contrib.services.aml_response import AMLResponse


def init():
    print("This is init()")

@rawhttp
def run(request):
    print("This is run()")
    print("Request: [{0}]".format(request))
    if request.method == 'GET':
        # For this example, just return the URL for GET.
        # For a real-world solution, you would load the data from URL params or headers
        # and send it to the model. Then return the response.
        respBody = str.encode(request.full_path)
        resp = AMLResponse(respBody, 200)
        resp.headers["Allow"] = "OPTIONS, GET, POST"
        resp.headers["Access-Control-Allow-Methods"] = "OPTIONS, GET, POST"
        resp.headers['Access-Control-Allow-Origin'] = "http://www.example.com"
        resp.headers['Access-Control-Allow-Headers'] = "*"
        return resp
    elif request.method == 'POST':
        reqBody = request.get_data(False)
        # For a real-world solution, you would load the data from reqBody
        # and send it to the model. Then return the response.
        resp = AMLResponse(reqBody, 200)
        resp.headers["Allow"] = "OPTIONS, GET, POST"
        resp.headers["Access-Control-Allow-Methods"] = "OPTIONS, GET, POST"
        resp.headers['Access-Control-Allow-Origin'] = "http://www.example.com"
        resp.headers['Access-Control-Allow-Headers'] = "*"
        return resp
    elif request.method == 'OPTIONS':
        resp = AMLResponse("", 200)
        resp.headers["Allow"] = "OPTIONS, GET, POST"
        resp.headers["Access-Control-Allow-Methods"] = "OPTIONS, GET, POST"
        resp.headers['Access-Control-Allow-Origin'] = "http://www.example.com"
        resp.headers['Access-Control-Allow-Headers'] = "*"
        return resp
    else:
        return AMLResponse("bad request", 400)

Внимание

Класс AMLResponse находится в пространстве имен azureml.contrib. Возможности пространства имен быстро изменяются, так как мы работаем над улучшением службы. Поэтому все, что доступно в этом пространстве имен, считается предварительными версиями компонентов, поддержка которых корпорацией Майкрософт ограничена.

pip install azureml-contrib-services

Предупреждение

Машинное обучение Azure маршрутизирует только запросы POST и GET к контейнерам, на которых выполняется служба оценки. Это может вызвать ошибки из-за браузеров, использующих запросы параметров для предварительного рейса запросов CORS.

Загрузка зарегистрированных моделей

Местоположение моделей в начальном сценарии можно определить двумя способами.

AZUREML_MODEL_DIR: переменная среды, содержащая путь к расположению модели
Model.get_model_path: API, возвращающий путь к файлу модели с использованием имени зарегистрированной модели

AZUREML_MODEL_DIR

AZUREML_MODEL_DIR — это переменная среды, созданная во время развертывания службы. Эту переменную среды можно использовать для поиска расположения развернутых моделей.

В следующей таблице описывается значение AZUREML_MODEL_DIR в зависимости от количества развернутых моделей:

Развертывание	Значение переменной среды
Единая модель	Путь к папке, содержащей модель.
Несколько моделей	Путь к папке, содержащей все модели. Модели расположены по имени и версии в этой папке (`$MODEL_NAME/$VERSION`).

Во время регистрации и развертывания модели помещаются в AZUREML_MODEL_DIR путь, и их исходные имена файлов сохраняются.

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

Пример одной модели

# Example when the model is a file
model_path = os.path.join(os.getenv('AZUREML_MODEL_DIR'), 'sklearn_regression_model.pkl')

# Example when the model is a folder containing a file
file_path = os.path.join(os.getenv('AZUREML_MODEL_DIR'), 'my_model_folder', 'sklearn_regression_model.pkl')

Пример с несколькими моделями

В этом сценарии в рабочей области регистрируются две модели:

my_first_model: содержит один файл (my_first_model.pkl) и существует только одна версия, 1
my_second_model: содержит один файл (my_second_model.pkl) и существует две версии, 1 и 2

При развертывании службы в операции развертывания предоставляются обе модели:

first_model = Model(ws, name="my_first_model", version=1)
second_model = Model(ws, name="my_second_model", version=2)
service = Model.deploy(ws, "myservice", [first_model, second_model], inference_config, deployment_config)

В образе Docker, на котором размещена служба, переменная среды AZUREML_MODEL_DIR содержит каталог, в котором находятся модели. В этом каталоге каждая из моделей находится в каталоге MODEL_NAME/VERSION. Где MODEL_NAME — имя зарегистрированной модели, а VERSION — версия модели. Файлы, составляющие зарегистрированную модель, хранятся в этих каталогах.

В этом примере пути будут выглядеть так $AZUREML_MODEL_DIR/my_first_model/1/my_first_model.pkl и $AZUREML_MODEL_DIR/my_second_model/2/my_second_model.pkl.

# Example when the model is a file, and the deployment contains multiple models
first_model_name = 'my_first_model'
first_model_version = '1'
first_model_path = os.path.join(os.getenv('AZUREML_MODEL_DIR'), first_model_name, first_model_version, 'my_first_model.pkl')
second_model_name = 'my_second_model'
second_model_version = '2'
second_model_path = os.path.join(os.getenv('AZUREML_MODEL_DIR'), second_model_name, second_model_version, 'my_second_model.pkl')

get_model_path

При регистрации модели вы предоставляете имя модели, используемое для управления моделью в реестре. Это имя используется с методом Model.get_model_path () для получения пути к файлу модели или файлам в локальной файловой системе. При регистрации папки или коллекции файлов этот API возвращает путь к каталогу, содержащему эти файлы.

При регистрации модели вы даете ей имя. Имя соответствует месту размещения модели: локально или во время развертывания службы.

Примеры для конкретных платформ

Дополнительные примеры сценариев ввода см. в следующих статьях для конкретных вариантов использования машинного обучения:

Поделиться через

Разработка расширенных сценариев ввода

Необходимые компоненты

Автоматическое создание схемы Swagger

Совместимая с Power BI конечная точка

Двоичные данные (т. е. изображения)

Загрузка зарегистрированных моделей

AZUREML_MODEL_DIR

get_model_path

Примеры для конкретных платформ

Обратная связь

Дополнительные ресурсы

Поделиться через

Разработка расширенных сценариев ввода

Необходимые компоненты

Автоматическое создание схемы Swagger

Совместимая с Power BI конечная точка

Двоичные данные (т. е. изображения)

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

Загрузка зарегистрированных моделей

AZUREML_MODEL_DIR

get_model_path

Примеры для конкретных платформ

Связанный контент

Обратная связь

Дополнительные ресурсы