Scripts de entrada avançados

APLICA-SE A:SDK do Azure Machine Learning 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 aprendizado de máquina 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 aprendizado de máquina no Azure.

Gere automaticamente um esquema do Swagger

Para gerar automaticamente um esquema para seu serviço Web, forneça uma amostra 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 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 código inference-schema aberto versão 1.1.0 ou posterior em seu arquivo de dependências. Para obter mais informações sobre este pacote, consulte InferenceSchema no GitHub. Para gerar Swagger em conformidade para o consumo automatizado de serviços Web, a run função no seu script de pontuação deve atender às seguintes condições:

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

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

Endpoint compatível com 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 este script quando consumir o seu serviço web implantado a partir 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 seu modelo aceita dados binários, como uma imagem, você deve modificar o arquivo de score.py que sua implantação usa para que ele aceite solicitações HTTP brutas. Para aceitar dados brutos, use a AMLRequest classe em seu script de entrada e adicione o @rawhttp decorador à run função.

O seguinte script score.py 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

Quando você usa 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 como de costume. 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)

Partilha de recursos de várias origens

O compartilhamento de recursos entre origens (CORS) fornece uma maneira de recursos em uma página da Web serem solicitados 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 Compartilhamento de recursos entre origens.

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

O exemplo a seguir define o Access-Control-Allow-Origin cabeçalho para a resposta do 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 registados

Existem duas formas 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 valores possíveis de AZUREML_MODEL_DIR para um número variável de modelos implantados:

Durante o registo e a implementação dos modelos, os modelos são colocados no caminho AZUREML_MODEL_DIR e os seus nomes de ficheiro originais são preservados.

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

Modelo único

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 com o 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 onde os modelos estão localizados. Nesta pasta, cada modelo está localizado em um caminho de pasta de <model-name>/<version>. Neste 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')

obter_caminho_modelo

Quando regista um modelo, fornece um nome de modelo que é utilizado para gerir o modelo no registo. Use esse nome com o Model.get_model_path método para recuperar o caminho do arquivo de modelo ou arquivos 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 regista um modelo, dá-lhe um nome. O nome corresponde ao local onde o modelo é colocado, localmente ou durante a implantação do serviço.

Exemplos específicos do quadro

Para obter mais exemplos de script de entrada para casos de uso específicos de aprendizado de máquina, consulte os seguintes artigos:

• PyTorch
• TensorFlow
• Keras
• Aprendizagem automática de máquina

Conteúdos relacionados

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