다음을 통해 공유

일괄 처리 배포에서 출력 사용자 지정

  • 아티클

적용 대상:Azure CLI ml 확장 v2(현재)Python SDK azure-ai-ml v2(현재)

이 가이드에서는 사용자 지정 출력 및 파일을 만드는 배포를 만드는 방법을 설명합니다. 일괄 처리 유추 작업의 출력으로 기록되는 내용을 더 세밀하게 제어해야 하는 경우가 있습니다. 이러한 경우에는 다음과 같은 상황이 포함됩니다.

  • 출력에 예측이 기록되는 방식을 제어해야 합니다. 예를 들어 원래 데이터에 예측을 추가하려고 합니다(데이터가 테이블 형식인 경우).
  • 일괄 처리 배포에서 지원되는 기본 제공 파일 형식과는 다른 파일 형식으로 예측을 작성해야 합니다.
  • 모델은 출력을 테이블 형식으로 작성할 수 없는 생성 모델입니다. 이미지를 출력으로 생성하는 모델을 예로 들 수 있습니다.
  • 모델은 단일 파일 대신 여러 테이블 형식 파일을 생성합니다. 예를 들어, 여러 시나리오를 고려하여 예측을 수행하는 모델입니다.

Batch 배포를 사용하면 일괄 처리 배포 작업의 출력에 직접 쓸 수 있어 작업 출력을 제어할 수 있습니다. 이 자습서에서는 모델을 배포하여 일괄 처리 유추를 수행하고 원본 입력 데이터에 예측을 추가하여 parquet 형식으로 출력을 작성하는 방법을 알아봅니다.

이 샘플 정보

이 예제에서는 모델을 배포하여 일괄 처리 유추를 수행하고 예측이 출력에 기록되는 방식을 사용자 지정하는 방법을 보여 줍니다. 이 모델은 UCI 심장 질환 데이터 세트를 기반으로 합니다. 데이터베이스에는 76개의 특성이 포함되어 있지만 이 예에서는 그중 14개의 하위 집합을 사용합니다. 이 모델은 환자의 심장병 유무를 예측하려고 시도합니다. 값은 0(심장병 없음)에서 1(심장병 있음) 사이의 정수입니다.

모델은 XGBBoost 분류자를 사용하여 학습되었으며 필요한 모든 전처리가 scikit-learn 파이프라인으로 패키지되어 이 모델을 원시 데이터에서 예측으로 이동하는 엔드투엔드 파이프라인으로 만들었습니다.

이 문서의 예는 azureml-examples 리포지토리에 포함된 코드 샘플을 기반으로 합니다. YAML 및 기타 파일을 복사/붙여넣기하지 않고 로컬로 명령을 실행하려면 먼저 리포지토리를 복제한 후 디렉터리를 폴더로 변경합니다.

git clone https://github.com/Azure/azureml-examples --depth 1
cd azureml-examples/cli

이 예의 파일은 다음 위치에 있습니다.

cd endpoints/batch/deploy-models/custom-outputs-parquet

Jupyter Notebook에서 따라 하기

이 예를 수행하는 데 사용할 수 있는 Jupyter Notebook이 있습니다. 복제된 리포지토리에서 custom-output-batch.ipynb라는 Notebook을 엽니다.

필수 조건

이 문서의 단계를 수행하기 전에 다음과 같은 필수 구성 요소가 있는지 확인합니다.

  • Azure 구독 Azure 구독이 아직 없는 경우 시작하기 전에 체험 계정을 만듭니다. Azure Machine Learning 평가판 또는 유료 버전을 사용해 보세요.

  • Azure Machine Learning 작업 영역 작업 영역이 없으면 Azure Machine Learning 작업 영역 관리 문서의 단계에서 새로 만듭니다.

  • 작업 영역에 다음 권한이 있는지 확인합니다.

    • 일괄 처리 엔드포인트 및 배포 만들기 또는 관리: Microsoft.MachineLearningServices/workspaces/batchEndpoints/*를 허용하는 소유자, 기여자 또는 사용자 지정 역할을 사용합니다.

    • 작업 영역 리소스 그룹에서 ARM 배포 만들기: 작업 영역이 배포된 리소스 그룹에서 Microsoft.Resources/deployments/write를 허용하는 소유자, 기여자 또는 사용자 지정 역할을 사용합니다.

  • Azure Machine Learning을 사용하려면 다음 소프트웨어를 설치해야 합니다.

    Azure CLI 및 mlAzure Machine Learning용 확장.

    az extension add -n ml

    참고 항목

    일괄 처리 엔드포인트에 대한 파이프라인 구성 요소 배포는 Azure CLI용 ml 확장 버전 2.7에 도입되었습니다. 최신 버전을 가져오려면 az extension update --name ml을 사용합니다.

작업 영역에 연결

작업 영역은 Azure Machine Learning의 최상위 리소스로, Azure Machine Learning을 사용할 때 만든 모든 아티팩트를 사용할 수 있는 중앙 집중식 환경을 제공합니다. 이 섹션에서는 배포 작업을 수행할 작업 영역에 연결합니다.

다음 코드에서 구독 ID, 작업 영역, 위치 및 리소스 그룹에 대한 값을 전달합니다.

az account set --subscription <subscription>
az configure --defaults workspace=<workspace> group=<resource-group> location=<location>

사용자 지정 출력을 사용하여 일괄 처리 배포 만들기

이 예에서는 일괄 처리 배포 작업의 출력 폴더에 직접 쓸 수 있는 배포를 만듭니다. 배포에서는 이 기능을 사용하여 사용자 지정 parquet 파일을 작성합니다.

모델 등록

일괄 처리 엔드포인트를 사용하여 등록된 모델만 배포할 수 있습니다. 이 예제의 경우 리포지토리에 모델의 로컬 복사본이 이미 있으므로 작업 영역의 레지스트리에만 모델을 게시하면 됩니다. 배포하려는 모델이 이미 등록된 경우 이 단계를 건너뛸 수 있습니다.

MODEL_NAME='heart-classifier-sklpipe'
az ml model create --name $MODEL_NAME --type "custom_model" --path "model"

채점 스크립트 생성

일괄 처리 배포에서 제공하는 입력 데이터를 읽고 모델의 점수를 반환할 수 있는 채점 스크립트를 만들어야 합니다. 또한 작업의 출력 폴더에 직접 쓰려고 합니다. 요약하면 제안된 채점 스크립트는 다음과 같이 작동합니다.

  1. 입력 데이터를 CSV 파일로 읽습니다.
  2. 입력 데이터에 대해 MLflow 모델 predict 함수를 실행합니다.
  3. 입력 데이터와 함께 pandas.DataFrame에 예측을 추가합니다.
  4. 명명된 파일의 데이터를 parquet 형식의 입력 파일로 씁니다.

code/batch_driver.py

import os
import pickle
import glob
import pandas as pd
from pathlib import Path
from typing import List


def init():
    global model
    global output_path

    # AZUREML_MODEL_DIR is an environment variable created during deployment
    # It is the path to the model folder
    # Please provide your model's folder name if there's one:
    output_path = os.environ["AZUREML_BI_OUTPUT_PATH"]
    model_path = os.environ["AZUREML_MODEL_DIR"]
    model_file = glob.glob(f"{model_path}/*/*.pkl")[-1]

    with open(model_file, "rb") as file:
        model = pickle.load(file)


def run(mini_batch: List[str]):
    for file_path in mini_batch:
        data = pd.read_csv(file_path)
        pred = model.predict(data)

        data["prediction"] = pred

        output_file_name = Path(file_path).stem
        output_file_path = os.path.join(output_path, output_file_name + ".parquet")
        data.to_parquet(output_file_path)

    return mini_batch

설명:

  • 환경 변수 AZUREML_BI_OUTPUT_PATH를 사용하여 배포 작업의 출력 경로에 액세스하는 방법을 확인합니다.
  • init() 함수는 나중에 작성할 위치를 파악하는 데 사용할 수 있는 output_path라는 전역 변수를 채웁니다.
  • run 메서드는 처리된 파일의 목록을 반환합니다. run 함수가 list 또는 pandas.DataFrame 개체를 반환하는 데 필요합니다.

Warning

모든 일괄 처리 실행기가 동시에 이 경로에 대한 쓰기 권한을 갖는다는 점을 고려합니다. 즉, 동시성을 고려해야 합니다. 이 경우 각 실행기가 입력 파일 이름을 출력 폴더 이름으로 사용하여 자체 파일을 작성하는지 확인합니다.

엔드포인트 만들기

이제 모델이 배포되는 heart-classifier-batch라는 일괄 처리 엔드포인트를 만듭니다.

  1. 엔드포인트의 이름을 결정합니다. 엔드포인트 이름은 엔드포인트와 연결된 URI에 표시되므로 일괄 처리 엔드포인트 이름은 Azure 지역 내에서 고유해야 합니다. 예를 들어, westus2에는 이름이 mybatchendpoint인 일괄 처리 엔드포인트가 하나만 있을 수 있습니다.

    이 경우 나중에 쉽게 참조할 수 있도록 엔드포인트 이름을 변수에 배치합니다.

    ENDPOINT_NAME="heart-classifier-custom"

  2. 일괄 처리 엔드포인트를 구성합니다.

    다음 YAML 파일은 일괄 처리 엔드포인트를 정의합니다.

    endpoint.yml

    $schema: https://azuremlschemas.azureedge.net/latest/batchEndpoint.schema.json
name: heart-classifier-batch
description: A heart condition classifier for batch inference
auth_mode: aad_token

  3. 엔드포인트 만들기:

    az ml batch-endpoint create -n $ENDPOINT_NAME -f endpoint.yml

배포 만들기

다음 단계에 따라 이전 채점 스크립트를 사용하여 배포를 만듭니다.

  1. 먼저 채점 스크립트를 실행할 수 있는 환경을 만듭니다.

    Azure Machine Learning CLI의 경우 추가 단계가 필요하지 않습니다. 환경 정의는 배포 파일에 포함됩니다.

    environment:
  name: batch-mlflow-xgboost
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
  conda_file: environment/conda.yaml

  2. 배포를 만듭니다. 이제 output_action이 SUMMARY_ONLY로 설정되어 있습니다.

    참고 항목

    이 예에서는 이름이 batch-cluster인 컴퓨팅 클러스터가 있다고 가정합니다. 그에 따라 이름을 변경합니다.

    만들어진 엔드포인트에서 새 배포를 만들려면 다음과 같이 YAML 구성을 만듭니다. 추가 속성은 전체 일괄 처리 엔드포인트 YAML 스키마를 확인합니다.

    $schema: https://azuremlschemas.azureedge.net/latest/modelBatchDeployment.schema.json
endpoint_name: heart-classifier-batch
name: classifier-xgboost-custom
description: A heart condition classifier based on XGBoost and Scikit-Learn pipelines that append predictions on parquet files.
type: model
model: azureml:heart-classifier-sklpipe@latest
environment:
  name: batch-mlflow-xgboost
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
  conda_file: environment/conda.yaml
code_configuration:
  code: code
  scoring_script: batch_driver.py
compute: azureml:batch-cluster
resources:
  instance_count: 2
settings:
  max_concurrency_per_instance: 2
  mini_batch_size: 2
  output_action: summary_only
  retry_settings:
    max_retries: 3
    timeout: 300
  error_threshold: -1
  logging_level: info

    그런 후 다음 명령을 사용하여 배포를 만듭니다.

    az ml batch-deployment create --file deployment.yml --endpoint-name $ENDPOINT_NAME --set-default

  3. 이제 일괄 처리 엔드포인트를 사용할 준비가 되었습니다.

배포 테스트

엔드포인트를 테스트하려면 모델과 함께 사용할 수 있는 이 리포지토리에 있는 레이블이 지정되지 않은 데이터 샘플을 사용합니다. Batch 엔드포인트는 클라우드에 있고 Azure Machine Learning 작업 영역에서 액세스할 수 있는 데이터만 처리할 수 있습니다. 이 예에서는 Azure Machine Learning 데이터 저장소에 업로드합니다. 채점을 위해 엔드포인트를 호출하는 데 사용할 수 있는 데이터 자산을 만들 예정입니다. 그러나 일괄 처리 엔드포인트는 여러 형식의 위치에 일괄 처리할 수 있는 데이터를 허용합니다.

  1. 스토리지 계정의 데이터로 엔드포인트를 호출합니다.

    JOB_NAME = $(az ml batch-endpoint invoke --name $ENDPOINT_NAME --input https://azuremlexampledata.blob.core.windows.net/data/heart-disease-uci/data --query name -o tsv)

    참고 항목

    모든 설치에 jq 유틸리티가 설치되지 않을 수도 있습니다. GitHub에서 지침을 가져올 수 있습니다.

  2. 명령이 반환되는 즉시 일괄 작업이 시작됩니다. 완료될 때까지 작업 상태를 모니터링할 수 있습니다.

    az ml job show -n $JOB_NAME --web

출력을 분석합니다.

작업은 생성된 모든 파일이 배치되는 score라는 명명된 출력을 생성합니다. 각 입력 파일당 하나의 파일을 디렉터리에 직접 썼으므로 동일한 수의 파일이 있을 것으로 예상할 수 있습니다. 이 특정 예에서는 출력 파일의 이름을 입력과 동일하게 지정하지만 파일 확장명은 parquet으로 지정됩니다.

참고 항목

predictions.csv 파일도 출력 폴더에 포함되어 있습니다. 이 파일에는 처리된 파일의 요약이 포함되어 있습니다.

다음과 같이 작업 이름을 사용하여 작업 결과를 다운로드할 수 있습니다.

예측을 다운로드하려면 다음 명령을 사용합니다.

az ml job download --name $JOB_NAME --output-name score --download-path ./

파일이 다운로드되면 선호하는 도구를 사용하여 파일을 열 수 있습니다. 다음 예제에서는 Pandas 데이터 프레임을 사용하여 예측을 로드합니다.

import pandas as pd
import glob

output_files = glob.glob("named-outputs/score/*.parquet")
score = pd.concat((pd.read_parquet(f) for f in output_files))
score

출력은 다음과 같습니다.

연령 sex ... thal 예측
63 1 ... fixed 0
67 1 ... 노멀 1
67 1 ... reversible 0
37 1 ... 노멀 0

리소스 정리

일괄 처리 엔드포인트와 모든 기본 배포를 삭제하려면 다음 코드를 실행합니다. Batch 채점 작업은 삭제되지 않습니다.

az ml batch-endpoint delete --name $ENDPOINT_NAME --yes

관련 콘텐츠