Scripts de entrada avançados

APLICA-SE A:Azure Machine Learning SDK v1 para Python

Este artigo explica como escrever scripts de entrada para casos de uso especializados no Azure Machine Learning. Um script de entrada, que também é chamado de script de pontuação, aceita solicitações, usa um modelo para pontuar dados e retorna uma resposta.

Pré-requisitos

Um modelo de machine learning treinado que você pretende implantar com o Azure Machine Learning. Para obter mais informações sobre a implantação de modelos, consulte Implantar modelos de machine learning no Azure.

Gerar automaticamente um esquema Swagger

Para gerar automaticamente um esquema para seu serviço Web, forneça um exemplo da entrada ou saída no construtor para um dos objetos de tipo definidos. O tipo e o exemplo são usados para criar automaticamente o esquema. Em seguida, o Azure Machine Learning cria uma especificação OpenAPI (anteriormente, uma especificação do Swagger) para o serviço Web durante a implantação.

Atualmente, há suporte para os seguintes tipos:

• pandas
• numpy
• pyspark
• Objeto Python padrão

Para usar a geração de esquema, inclua o pacote de inference-schema software livre versão 1.1.0 ou posterior no arquivo de dependências. Para obter mais informações sobre esse pacote, consulte InferenceSchema no GitHub. Para gerar Swagger em conformidade para consumo automatizado de serviços Web, a função run no script de pontuação deve atender às seguintes condições:

• O primeiro parâmetro deve ter o tipo StandardPythonParameterType, ser nomeado Inputs e ser aninhado.
• Deve haver um segundo parâmetro opcional do tipo StandardPythonParameterType chamado GlobalParameters.
• A função deve retornar um dicionário do tipo StandardPythonParameterType, nomeado Results e aninhado.

Defina os formatos de exemplo de entrada e saída nas variáveis sample_input e sample_output, que representam os formatos de solicitação e resposta para o serviço Web. Use esses exemplos nos decoradores da função de entrada e saída na função run. O scikit-learn exemplo na seção a seguir usa a geração de esquema.

Endpoint compatível com o Power BI

O exemplo a seguir demonstra como definir a run função de acordo com as instruções na seção anterior. Você pode usar esse script ao consumir seu serviço Web implantado do Power BI.

import os
import json
import pickle
import numpy as np
import pandas as pd
import azureml.train.automl
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 the file name 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)


# Provide three 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)

# The following sample is a nested input sample. Any item wrapped by `ParameterType` is described by the schema.
sample_input = StandardPythonParameterType({'input1': numpy_sample_input, 
                                        'input2': pandas_sample_input, 
                                        'input3': standard_sample_input})

sample_global_parameters = StandardPythonParameterType(1.0) # This line 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) 
# The preceding line is optional. "GlobalParameters" is case sensitive.

@output_schema(outputs)

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

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

Dados binários (imagem)

Se o modelo aceitar dados binários, como uma imagem, você deverá modificar o arquivo score.py que sua implantação usa para que ele aceite solicitações HTTP brutas. Para aceitar dados brutos, use a classe AMLRequest no script de entrada e adicione o decorador @rawhttp à função run.

O script de score.py a seguir aceita dados binários:

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, return the URL for GET requests.
        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, load the data from the request body
        # and send it to the model. Then return the response.

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

pip install azureml-contrib-services

Ao usar a AMLRequest classe, você pode acessar apenas os dados brutos postados no arquivo score.py. Não há nenhum componente do lado do cliente. A partir de um cliente, você pode postar dados normalmente. Por exemplo, o código Python a seguir lê um arquivo de imagem e posta os dados:

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)

Compartilhamento de recursos entre origens

O CORS (compartilhamento de recursos entre origens) fornece uma maneira de solicitar recursos em uma página da Web de outro domínio. O CORS funciona por meio de cabeçalhos HTTP que são enviados com a solicitação do cliente e retornados com a resposta do serviço. Para obter mais informações sobre CORS e cabeçalhos válidos, consulte o compartilhamento de recursos entre origens.

Para configurar a implantação de modelo para dar suporte a CORS, use a classe AMLResponse no script de entrada. Ao usar essa classe, você pode definir os cabeçalhos no objeto de resposta.

O exemplo a seguir define o cabeçalho Access-Control-Allow-Origin para a resposta com base no script de entrada:

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)

pip install azureml-contrib-services

Carregar modelos registrados

Existem duas maneiras de localizar modelos no script de entrada:

• AZUREML_MODEL_DIR: uma variável de ambiente que contém o caminho para o local do modelo
• Model.get_model_path: uma API que retorna o caminho para o arquivo de modelo usando o nome do modelo registrado

AZUREML_MODEL_DIR

AZUREML_MODEL_DIR é uma variável de ambiente criada durante a implantação do serviço. Você pode usar essa variável de ambiente para localizar o local dos modelos implantados.

A tabela a seguir descreve os possíveis valores de AZUREML_MODEL_DIR para um número variante de modelos implantados.

Durante o registro e a implantação do modelo, os modelos são colocados no caminho AZUREML_MODEL_DIR e seus nomes de arquivo originais são preservados.

Para obter o caminho para um arquivo de modelo no script de entrada, combine a variável de ambiente com o caminho de arquivo que você está procurando.

Um único modelo

O exemplo a seguir mostra como localizar o caminho quando você tem um único modelo:

import os

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

# In the following example, the model is a folder that contains a file.
file_path = os.path.join(os.getenv('AZUREML_MODEL_DIR'), 'my_model_folder', 'sklearn_regression_model.pkl')

Vários modelos

O exemplo a seguir mostra como encontrar o caminho quando você tem vários modelos. Nesse cenário, dois modelos são registrados no espaço de trabalho:

• my_first_model: este modelo contém um arquivo, my_first_model.pkl e tem uma versão. 1
• my_second_model: este modelo contém um arquivo, my_second_model.pkl e tem duas versões 1 e 2.

Ao implantar o serviço, você fornece os dois modelos na operação de implantação:

from azureml.core import Workspace, Model

# Get a handle to the workspace.
ws = Workspace.from_config()

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)

Na imagem do Docker que hospeda o serviço, a AZUREML_MODEL_DIR variável de ambiente contém a pasta em que os modelos estão localizados. Nesta pasta, cada modelo está localizado em um caminho de pasta de <model-name>/<version>. Nesse caminho, <model-name> é o nome do modelo registrado e <version> é a versão do modelo. Os arquivos que compõem o modelo registrado são armazenados nessas pastas.

Neste exemplo, o caminho do primeiro modelo é $AZUREML_MODEL_DIR/my_first_model/1/my_first_model.pkl. O caminho do segundo modelo é $AZUREML_MODEL_DIR/my_second_model/2/my_second_model.pkl.

# In the following example, 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

Quando você registra um modelo, fornece um nome de modelo que é usado para gerenciar o modelo no registro. Use esse nome com o método Model.get_model_path para recuperar o caminho do arquivo ou arquivos do modelo no sistema de arquivos local. Se você registrar uma pasta ou uma coleção de arquivos, essa API retornará o caminho da pasta que contém esses arquivos.

Quando você registra um modelo, atribui um nome a ele. O nome corresponde ao local em que o modelo foi colocado, seja localmente ou durante a implantação do serviço.

Exemplos específicos de estrutura

Para obter mais exemplos de script de entrada para casos específicos de uso de machine learning, consulte os seguintes artigos:

• PyTorch
• TensorFlow
• Keras
• Machine learning automatizado

Conteúdo relacionado

• Solucionar problemas de implantação de modelo remoto
• Consumir um modelo de Azure Machine Learning implantado como um serviço Web
• Atualizar um serviço Web implantado (v1)