고급 항목 스크립트

적용 대상:Python용 Azure Machine Learning SDK v1

이 문서에서는 Azure Machine Learning에서 특수한 사용 사례에 대한 항목 스크립트를 작성하는 방법을 설명합니다. 점수 매기기 스크립트라고도 하는 항목 스크립트는 요청을 수락하고 모델을 사용하여 데이터를 채점하고 응답을 반환합니다.

필수 구성 요소

Azure Machine Learning을 사용하여 배포하려는 학습된 기계 학습 모델입니다. 모델 배포에 대한 자세한 내용은 Azure에 기계 학습 모델 배포를 참조하세요.

Swagger 스키마 자동 생성

웹 서비스에 대한 스키마를 자동으로 생성하려면 정의된 형식 개체 중 하나에 대한 생성자의 입력 또는 출력 샘플을 제공합니다. 형식 및 샘플은 스키마를 자동으로 만드는 데 사용됩니다. 그런 다음 Azure Machine Learning은 배포 중에 웹 서비스에 대한 OpenAPI 사양 (이전의 Swagger 사양)을 만듭니다.

현재 지원되는 형식은 다음과 같습니다.

• pandas
• numpy
• pyspark
• 표준 Python 개체

스키마 생성을 사용하려면 종속성 파일에 오픈 소스 inference-schema 패키지 버전 1.1.0 이상을 포함합니다. 이 패키지에 대한 자세한 내용은 GitHub의 InferenceSchema를 참조하세요. 자동화된 웹 서비스 사용을 위해 준수 Swagger를 생성하려면 점수 매기기 스크립트의 run 함수가 다음 조건을 충족해야 합니다.

• 첫 번째 매개 변수는 StandardPythonParameterType 형식을 가져야 하고, 이름은 Inputs여야 하며, 중첩되어야 합니다.
• 이름이 지정된 StandardPythonParameterType형식 GlobalParameters 의 선택적 두 번째 매개 변수가 있어야 합니다.
• 함수는 이름이 Results이고 중첩된 StandardPythonParameterType 형식의 사전을 반환해야 합니다.

sample_input 및 sample_output 변수에서 웹 서비스의 요청 및 응답 형식을 나타내는 입력 및 출력 샘플 형식을 정의합니다. run 함수에 대한 입력 및 출력 함수 데코레이터에서 이러한 샘플을 사용합니다. scikit-learn 다음 섹션의 예제에서는 스키마 생성을 사용합니다.

Power BI 호환 엔드포인트

다음 예제에서는 이전 섹션의 run 지침에 따라 함수를 정의하는 방법을 보여 줍니다. 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

이진(이미지) 데이터

모델에서 이미지와 같은 이진 데이터를 허용하는 경우 배포에서 사용하는 score.py 파일을 수정하여 원시 HTTP 요청을 수락해야 합니다. 원시 데이터를 수락하려면 항목 스크립트에서 AMLRequest 클래스를 사용하고 run 함수에 @rawhttp 데코레이터를 추가합니다.

다음 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, 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

클래스를 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(원본 간 리소스 공유)는 웹 페이지의 리소스를 다른 도메인에서 요청할 수 있는 방법을 제공합니다. 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)

pip install azureml-contrib-services

등록된 모델 로드

항목 스크립트에서 모델을 찾는 방법에는 두 가지가 있습니다.

• AZUREML_MODEL_DIR: 모델 위치에 대한 경로를 포함하는 환경 변수
• Model.get_model_path: 등록된 모델 이름을 사용하여 모델 파일의 경로를 반환하는 API입니다.

AZUREML_MODEL_DIR

AZUREML_MODEL_DIR 는 서비스 배포 중에 생성되는 환경 변수입니다. 이 환경 변수를 사용하여 배포된 모델의 위치를 찾을 수 있습니다.

다음 표에서는 다양한 수의 AZUREML_MODEL_DIR 배포된 모델에 대해 가능한 값을 설명합니다.

모델 등록 및 배포 중에 모델이 경로에 AZUREML_MODEL_DIR 배치되고 원래 파일 이름이 유지됩니다.

항목 스크립트의 모델 파일에 대한 경로를 가져오려면 환경 변수를 찾고 있는 파일 경로와 결합합니다.

단일 모델

다음 예제에서는 단일 모델이 있을 때 경로를 찾는 방법을 보여줍니다.

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

다중 모델

다음 예제에서는 여러 모델이 있을 때 경로를 찾는 방법을 보여 줍니다. 이 시나리오에서는 두 개의 모델이 작업 영역에 등록됩니다.

• my_first_model: 이 모델에는 하나의 파일 my_first_model.pkl이 포함되며 하나의 버전이 1있습니다.
• my_second_model: 이 모델에는 my_second_model.pkl이라는 하나의 파일이 포함되어 있으며 두 가지 버전 1 이 있습니다 2.

서비스를 배포할 때 배포 작업에서 두 모델을 모두 제공합니다.

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)

서비스를 AZUREML_MODEL_DIR 호스트하는 Docker 이미지에서 환경 변수에는 모델이 있는 폴더가 포함됩니다. 이 폴더에서 각 모델은 .의 <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.

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

모델 경로 얻기

모델을 등록할 때 레지스트리에서 모델을 관리하는 데 사용되는 모델 이름을 제공합니다. 이 이름을 메서드와 함께 Model.get_model_path 사용하여 로컬 파일 시스템에서 모델 파일 또는 파일의 경로를 검색합니다. 폴더 또는 파일 컬렉션을 등록하는 경우 이 API는 해당 파일이 포함된 폴더의 경로를 반환합니다.

모델을 등록할 때 이름을 지정합니다. 이름은 모델을 로컬 또는 서비스 배포 중에 배치하는 위치에 해당합니다.

프레임워크 관련 예제

특정 기계 학습 사용 사례에 대한 추가 항목 스크립트 예제는 다음 문서를 참조하세요.

• PyTorch
• Tensorflow
• Keras
• 자동화된 기계 학습

관련 콘텐츠

• 원격 모델 배포 문제 해결
• 웹 서비스로 배포된 Azure Machine Learning 모델 사용
• 배포된 웹 서비스 업데이트(v1)