온라인 엔드포인트를 사용하여 기계 학습 모델 배포 및 점수 매기기

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

이 문서에서는 실시간 유추에 사용하기 위해 모델을 온라인 엔드포인트에 배포하는 방법을 알아봅니다. 오류를 디버그하기 위해 로컬 컴퓨터에 모델을 배포하는 것부터 시작합니다. 그런 다음 Azure에서 모델을 배포하고 테스트합니다. 또한 배포 로그를 보고 SLA(서비스 수준 계약)를 모니터링하는 방법도 알아봅니다. 이 문서가 끝나면 실시간 유추에 사용할 수 있는 확장 가능한 HTTPS/REST 엔드포인트를 갖게 됩니다.

온라인 엔드포인트란 실시간 유추에 사용되는 엔드포인트입니다. 온라인 엔드포인트에는 관리형 온라인 엔드포인트Kubernetes 온라인 엔드포인트의 두 가지 유형이 있습니다. 엔드포인트 및 관리형 온라인 엔드포인트와 Kubernetes 온라인 엔드포인트 간의 차이점에 대한 자세한 내용은 Azure Machine Learning 엔드포인트란?을 참조하세요.

관리형 온라인 엔드포인트는 턴키 방식으로 ML 모델을 배포하는 데 도움이 됩니다. 관리형 온라인 엔드포인트는 확장성 있는 완전 관리형 방식으로 Azure의 강력한 CPU 및 GPU 머신에서 작동합니다. 관리형 온라인 엔드포인트는 모델 제공, 크기 조정, 보안 및 모니터링을 처리하여 기본 인프라를 설정하고 관리하는 오버헤드로부터 벗어날 수 있습니다.

이 문서의 주요 예제에서는 배포에 관리형 온라인 엔드포인트를 사용합니다. Kubernetes를 대신 사용하려면 이 문서의 참고 사항을 관리형 온라인 엔드포인트에 대한 설명과 함께 참조하세요.

필수 조건

적용 대상:Azure CLI ml 확장 v2(현재)

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

  • Azure RBAC(Azure 역할 기반 액세스 제어)는 Azure Machine Learning의 작업에 대한 액세스 권한을 부여하는 데 사용됩니다. 이 문서의 단계를 수행하려면 사용자 계정에 Azure Machine Learning 작업 영역에 대한 소유자 또는 기여자 역할이 할당되거나 Microsoft.MachineLearningServices/workspaces/onlineEndpoints/*를 허용하는 사용자 지정 역할이 할당되어야 합니다. Studio를 사용하여 온라인 엔드포인트/배포를 만들기/관리하는 경우 리소스 그룹 소유자로부터 "Microsoft.Resources/deployments/write" 권한이 추가로 필요합니다. 자세한 내용은 Azure Machine Learning 작업 영역 액세스 관리를 참조하세요.

  • (선택 사항) 로컬로 배포하려면 로컬 컴퓨터에 Docker 엔진을 설치해야 합니다. 문제를 더 쉽게 디버그할 수 있도록 이 옵션을 권장합니다.

배포를 위한 가상 머신 할당량 할당

관리형 온라인 엔드포인트의 경우 Azure Machine Learning은 일부 VM SKU에서 업그레이드를 수행하기 위해 컴퓨팅 리소스의 20%를 예약합니다. 배포에서 지정된 수의 인스턴스를 요청하는 경우 오류가 발생하지 않도록 사용할 수 있는 ceil(1.2 * number of instances requested for deployment) * number of cores for the VM SKU 할당량이 있어야 합니다. 예를 들어, 배포에서 Standard_DS3_v2 VM 인스턴스 10개(코어 4개 포함)를 요청하는 경우 48개 코어(12 instances * 4 cores)에 대한 할당량을 사용할 수 있어야 합니다. 사용량을 확인하고 할당량 증가를 요청하려면 Azure Portal에서 사용량 및 할당량 보기를 참조하세요.

추가 할당량 예약에서 제외되는 특정 VM SKU가 있습니다. 전체 목록을 보려면 관리형 온라인 엔드포인트 SKU 목록을 참조하세요.

Azure Machine Learning은 모든 사용자가 할당량에 액세스하여 제한된 시간 동안 테스트를 수행할 수 있는 공유 할당량 풀을 제공합니다. 스튜디오를 사용하여 모델 카탈로그에서 관리되는 온라인 엔드포인트로 Llama-2, Phi, Nemotron, Mistral, Dolly 및 Deci-DeciLM 모델을 배포하는 경우 Azure Machine Learning을 사용하면 이 공유 할당량에 잠시 액세스할 수 있습니다.

온라인 엔드포인트 배포에 공유 할당량을 사용하는 방법에 대한 자세한 내용은 스튜디오를 사용하여 기본 모델을 배포하는 방법을 참조하세요.

시스템 준비

환경 변수 설정

Azure CLI에 대한 기본값을 아직 설정하지 않은 경우 기본 설정을 저장합니다. 구독, 작업 영역 및 리소스 그룹에 대한 값을 여러 번 전달하지 않으려면 다음 코드를 실행하세요.

az account set --subscription <subscription ID>
az configure --defaults workspace=<Azure Machine Learning workspace name> group=<resource group>

예제 리포지토리 복제

이 문서를 따르려면 먼저 예제 리포지토리(azureml-examples)를 복제합니다. 그런 후 다음 코드를 실행하여 리포지토리의 cli/ 디렉터리로 이동합니다.

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

--depth 1을 사용하여 최신 커밋만 리포지토리에 복제하여 작업을 완료하는 데 걸리는 시간을 줄입니다.

이 자습서의 명령은 cli 디렉터리의 deploy-local-endpoint.shdeploy-managed-online-endpoint.sh에 있고 YAML 구성 파일은 endpoints/online/managed/sample/ 하위 디렉터리에 있습니다.

참고 항목

Kubernetes 온라인 엔드포인트에 대한 YAML 구성 파일은 endpoints/online/kubernetes/ 하위 디렉터리에 있습니다.

엔드포인트 정의

엔드포인트를 정의하려면 다음을 지정해야 합니다.

  • 엔드포인트 이름: 엔드포인트의 이름입니다. Azure 지역에서 고유해야 합니다. 명명 규칙에 대한 자세한 내용은 엔드포인트 제한을 참조하세요.
  • 인증 모드: 엔드포인트에 대한 인증 방법입니다. 키 기반 인증과 Azure Machine Learning 토큰 기반 인증 중에서 선택합니다. 키는 만료되지 않지만 토큰은 만료됩니다. 인증에 대한 자세한 내용은 온라인 엔드포인트에 대한 인증을 참조하세요.
  • 필요에 따라 엔드포인트에 설명과 태그를 추가할 수 있습니다.

엔드포인트 이름 설정

엔드포인트 이름을 설정하려면 다음 명령을 실행합니다(YOUR_ENDPOINT_NAME를 그유한 이름으로 바꿈).

Linux의 경우 다음 명령을 실행합니다.

export ENDPOINT_NAME="<YOUR_ENDPOINT_NAME>"

엔드포인트 구성:

다음 코드 조각은 endpoints/online/managed/sample/endpoint.yml 파일을 보여줍니다.

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: my-endpoint
auth_mode: key

엔드포인트 YAML 형식에 대한 참조는 다음 표에 설명되어 있습니다. 이러한 특성을 지정하는 방법을 알아보려면 온라인 엔드포인트 YAML 참조를 참조하세요. 관리형 엔드포인트 관련 한도에 대한 자세한 내용은 온라인 엔드포인트에 대한 한도를 참조하세요.

설명
$schema (선택 사항) YAML 스키마입니다. YAML 파일에서 사용 가능한 모든 옵션을 보려면 브라우저에서 이전 코드 조각의 스키마를 볼 수 있습니다.
name 엔드포인트의 이름입니다.
auth_mode 키 기반 인증의 경우 key를 사용합니다. Azure Machine Learning 토큰 기반 인증에 대해 aml_token을 사용합니다. 최신 토큰을 가져오려면 az ml online-endpoint get-credentials 명령을 사용합니다.

배포 정의

배포는 실제 유추를 수행하는 모델을 호스팅하는 데 필요한 리소스의 세트입니다. 모델을 배포하려면 다음이 있어야 합니다.

  • 모델 파일(또는 작업 영역에 이미 등록된 모델의 이름 및 버전). 이 예에는 회귀를 수행하는 scikit-learn 모델이 있습니다.
  • 채점 스크립트, 즉 지정된 입력 요청에서 모델을 실행하는 코드입니다. 채점 스크립트는 배포된 웹 서비스에 제출된 데이터를 수신하여 모델에 전달합니다. 그런 다음 스크립트는 모델을 실행하고 응답을 클라이언트에 반환합니다. 채점 스크립트는 모델에 따라 다르며 모델이 입력으로 예상하고 출력으로 반환하는 데이터를 이해해야 합니다. 이 예제에는 score.py 파일이 있습니다.
  • 모델이 실행되는 환경입니다. 환경은 Conda 종속성이 있는 Docker 이미지 또는 Dockerfile일 수 있습니다.
  • 인스턴스 유형 및 크기 조정 용량을 지정하는 설정.

다음 표에서는 배포의 주요 특성을 설명합니다.

attribute Description
이름 배포의 이름입니다.
엔드포인트 이름 배포를 만들 엔드포인트의 이름입니다.
모델 배포에 사용할 모델입니다. 이 값은 작업 영역에서 기존 버전의 모델에 대한 참조 또는 인라인 모델 사양일 수 있습니다.
코드 경로 모델 채점을 위한 모든 Python 소스 코드가 포함된 로컬 개발 환경의 디렉터리 경로입니다. 중첩된 디렉터리 및 패키지를 사용할 수 있습니다.
채점 스크립트 소스 코드 디렉터리에 있는 채점 파일의 상대 경로입니다. 이 Python 코드에는 init() 함수와 run() 함수가 있어야 합니다. init() 함수는 모델을 만들거나 업데이트한 후에 호출됩니다(모델을 메모리에 캐시하는 등의 용도로 사용할 수 있음). run() 함수는 실제 채점/예측을 수행하도록 엔드포인트를 호출할 때마다 호출됩니다.
환경 모델 및 코드를 호스팅할 환경입니다. 이 값은 작업 영역에서 기존 버전의 환경에 대한 참조 또는 인라인 환경 사양일 수 있습니다.
인스턴스 유형 배포에 사용할 VM 크기입니다. 지원되는 크기 목록은 관리되는 온라인 엔드포인트 SKU 목록을 참조하세요.
인스턴트 수 배포에 사용할 인스턴스 수입니다. 예상되는 워크로드 값을 기준으로 합니다. 고가용성을 위해 값을 3 이상으로 설정하는 것이 좋습니다. 업그레이드 수행을 위해 추가 20%를 예약합니다. 자세한 내용은 배포에 대한 가상 머신 할당량 할당을 참조하세요.

참고 항목

  • 배포 뒤의 인스턴스가 보안 패치 및/또는 기타 복구 작업을 거칠 때 배포에서 언제든지 모델 및 컨테이너 이미지(환경에 정의됨)를 다시 참조할 수 있습니다. 배포를 위해 Azure Container Registry에 등록된 모델 또는 컨테이너 이미지를 사용하고 모델 또는 컨테이너 이미지를 제거한 경우 이미지를 다시 설치하면 이러한 자산을 사용하는 배포가 실패할 수 있습니다. 모델 또는 컨테이너 이미지를 제거한 경우 종속 배포가 대체 모델 또는 컨테이너 이미지로 다시 만들어지거나 업데이트되었는지 확인합니다.
  • 환경이 참조하는 컨테이너 레지스트리는 엔드포인트 ID에 Microsoft Entra 인증 및 Azure RBAC를 통해 액세스할 수 있는 권한이 있는 경우에만 프라이빗일 수 있습니다. 같은 이유로 Azure Container Registry 이외의 프라이빗 Docker 레지스트리는 지원되지 않습니다.

배포 구성

다음 코드 조각은 endpoints/online/managed/sample/blue-deployment.yml 파일을 배포를 구성하는 데 필요한 모든 입력과 함께 보여줍니다.

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: my-endpoint
model:
  path: ../../model-1/model/
code_configuration:
  code: ../../model-1/onlinescoring/
  scoring_script: score.py
environment: 
  conda_file: ../../model-1/environment/conda.yaml
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest
instance_type: Standard_DS3_v2
instance_count: 1

참고 항목

blue-deployment.yml 파일에서 다음 배포 특성을 지정했습니다.

  • model - 이 예제에서는 path를 사용하여 모델 속성 인라인을 지정합니다. 모델 파일은 자동으로 업로드되고 자동 생성된 이름으로 등록됩니다.
  • environment - 이 예제에는 path가 포함된 인라인 정의가 있습니다. 이미지에 environment.docker.image를 사용합니다. conda_file 종속성은 이미지 위에 설치됩니다.

배포하는 동안 채점 모델의 Python 원본과 같은 로컬 파일이 개발 환경에서 업로드됩니다.

YAML 스키마에 대한 자세한 내용은 온라인 엔드포인트 YAML 참조를 참조하세요.

참고 항목

관리형 엔드포인트 대신 Kubernetes를 컴퓨팅 대상으로 사용하려면

  1. Azure Machine Learning 스튜디오를 사용하여 Kubernetes 클러스터를 만들고 Azure Machine Learning 작업 영역에 컴퓨팅 대상으로 연결합니다.
  2. 관리형 엔드포인트 YAML 대신 엔드포인트 YAML을 사용하여 Kubernetes를 대상으로 지정합니다. target의 값을 등록된 컴퓨팅 대상의 이름으로 변경하려면 YAML을 편집해야 합니다. Kubernetes 배포에 적용할 수 있는 추가 속성이 있는 이 deployment.yaml을 사용할 수 있습니다.

이 문서에서 사용되는 모든 명령(선택 사항인 SLA 모니터링 및 Azure Log Analytics 통합 제외)은 관리형 엔드포인트 또는 Kubernetes 엔드포인트와 함께 사용할 수 있습니다.

모델 및 환경을 별도로 등록

이 예제에서는 path(업로드할 파일의 위치)를 인라인으로 지정합니다. CLI는 자동으로 파일을 업로드하고 모델과 환경을 등록합니다. 프로덕션 환경에서는 모델 및 환경을 등록하고 YAML에 별도로 등록된 이름 및 버전을 지정하는 것이 모범 사례입니다. model: azureml:my-model:1 또는 environment: azureml:my-env:1 형식을 사용합니다.

등록을 수행하려면 modelenvironment의 YAML 정의를 별도의 YAML 파일에 추출하고 az ml model createaz ml environment create 명령을 사용할 수 있습니다. 이러한 명령에 대해 자세히 알아보려면 az ml model create -haz ml environment create -h를 실행합니다.

모델을 자산으로 등록하는 방법에 대한 자세한 내용은 CLI를 사용하여 Machine Learning에서 모델을 자산으로 등록을 참조하세요. 환경을 만드는 방법에 대한 자세한 내용은 CLI & SDK(v2)를 통해 Azure Machine Learning 환경 관리를 참조하세요.

다른 CPU 및 GPU 인스턴스 유형과 이미지 사용

blue-deployment.yml 파일의 앞의 정의는 범용 형식 Standard_DS3_v2 인스턴스 및 비 GPU Docker 이미지 mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest를 사용합니다. GPU 컴퓨팅의 경우 GPU 컴퓨팅 유형 SKU 및 GPU Docker 이미지를 선택합니다.

지원되는 범용 및 GPU 인스턴스 유형을 보려면 관리형 온라인 엔드포인트에서 지원되는 VM SKU를 참조하세요. Azure Machine Learning CPU 및 GPU 기본 이미지 목록은 Azure Machine Learning 기본 이미지를 참조하세요.

참고 항목

관리 엔드포인트 대신 Kubernetes를 컴퓨팅 대상으로 사용하려면 Kubernetes 컴퓨팅 대상 소개를 참조하세요.

AZUREML_MODEL_DIR 관련 모델 경로 식별

Azure Machine Learning에 모델을 배포할 때 배포 구성의 일부로 배포하려는 모델의 위치를 지정해야 합니다. Azure Machine Learning에서 모델의 경로는 AZUREML_MODEL_DIR 환경 변수를 사용하여 추적됩니다. AZUREML_MODEL_DIR과 관련하여 모델 경로를 식별하여 컴퓨터에 로컬로 저장된 하나 이상의 모델을 배포하거나 Azure Machine Learning 작업 영역에 등록된 모델을 배포할 수 있습니다.

예를 들어 단일 모델을 배포하거나 로컬에 저장된 여러 모델을 배포하는 처음 두 사례에 대해 다음 로컬 폴더 구조를 참조합니다.

A screenshot showing a folder structure containing multiple models.

배포에서 단일 로컬 모델 사용

배포의 로컬 컴퓨터에 있는 단일 모델을 사용하려면 배포 YAML의 model에 대한 path를 지정합니다. 경로가 /Downloads/multi-models-sample/models/model_1/v1/sample_m1.pkl인 배포 YAML의 예는 다음과 같습니다.

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json 
name: blue 
endpoint_name: my-endpoint 
model: 
  path: /Downloads/multi-models-sample/models/model_1/v1/sample_m1.pkl 
code_configuration: 
  code: ../../model-1/onlinescoring/ 
  scoring_script: score.py 
environment:  
  conda_file: ../../model-1/environment/conda.yml 
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest 
instance_type: Standard_DS3_v2 
instance_count: 1 

배포를 만든 후 환경 변수 AZUREML_MODEL_DIR은 모델이 저장된 Azure 내의 스토리지 위치를 가리킵니다. 예를 들어 /var/azureml-app/azureml-models/81b3c48bbf62360c7edbbe9b280b9025/1에는 모델 sample_m1.pkl이 포함됩니다.

채점 스크립트(score.py) 내에서 init() 함수에 모델(이 예제에서는 sample_m1.pkl)을 로드할 수 있습니다.

def init(): 
    model_path = os.path.join(str(os.getenv("AZUREML_MODEL_DIR")), "sample_m1.pkl") 
    model = joblib.load(model_path) 

배포에서 여러 로컬 모델 사용

Azure CLI, Python SDK 및 기타 클라이언트 도구를 사용하면 배포 정의에서 배포당 하나의 모델만 지정할 수 있지만 모든 모델을 포함하는 모델 폴더를 파일 또는 하위 디렉터리로 등록하여 배포에서 여러 모델을 계속 사용할 수 있습니다.

이전 예제 폴더 구조에서는 models 폴더에 여러 모델이 있음을 알 수 있습니다. 배포 YAML에서 다음과 같이 models 폴더의 경로를 지정할 수 있습니다.

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json 
name: blue 
endpoint_name: my-endpoint 
model: 
  path: /Downloads/multi-models-sample/models/ 
code_configuration: 
  code: ../../model-1/onlinescoring/ 
  scoring_script: score.py 
environment:  
  conda_file: ../../model-1/environment/conda.yml 
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest 
instance_type: Standard_DS3_v2 
instance_count: 1 

배포를 만든 후 환경 변수 AZUREML_MODEL_DIR은 모델이 저장된 Azure 내의 스토리지 위치를 가리킵니다. 예를 들어 /var/azureml-app/azureml-models/81b3c48bbf62360c7edbbe9b280b9025/1은 모델과 파일 구조를 포함합니다.

이 예제에서는 AZUREML_MODEL_DIR 폴더의 내용이 다음과 같이 표시됩니다.

A screenshot of the folder structure of the storage location for multiple models.

채점 스크립트(score.py) 내에서 init() 함수에 모델을 로드할 수 있습니다. 다음 코드는 sample_m1.pkl 모델을 로드합니다.

def init(): 
    model_path = os.path.join(str(os.getenv("AZUREML_MODEL_DIR")), "models","model_1","v1", "sample_m1.pkl ") 
    model = joblib.load(model_path) 

여러 모델을 하나의 배포에 배포하는 방법의 예제는 하나의 배포에 여러 모델 배포(CLI 예제)여러 모델을 하나의 배포에 배포(SDK 예제)를 참조하세요.

등록할 파일이 1500개 이상인 경우 모델을 등록할 때 파일 또는 하위 디렉터리를 .tar.gz로 압축하는 것이 좋습니다. 모델을 사용하려면 채점 스크립트에서 init() 함수의 파일 또는 하위 디렉터리를 압축 해제할 수 있습니다. 또는 모델을 등록할 때 azureml.unpack 속성을 True로 설정하여 파일 또는 하위 디렉터리의 압축을 자동으로 해제합니다. 두 경우 모두 압축 해제는 초기화 단계에서 한 번 발생합니다.

배포에서 Azure Machine Learning 서비스 작업 영역에 등록된 모델 사용

Azure Machine Learning 작업 영역에 등록된 하나 이상의 모델을 사용하려면 배포에서 배포 YAML에 등록된 모델의 이름을 지정합니다. 예를 들어 다음 배포 YAML 구성은 등록된 model 이름을 azureml:local-multimodel:3로 지정합니다.

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json 
name: blue 
endpoint_name: my-endpoint 
model: azureml:local-multimodel:3 
code_configuration: 
  code: ../../model-1/onlinescoring/ 
  scoring_script: score.py 
environment:  
  conda_file: ../../model-1/environment/conda.yml 
  image: mcr.microsoft.com/azureml/openmpi4.1.0-ubuntu20.04:latest 
instance_type: Standard_DS3_v2 
instance_count: 1 

이 예제에서는 local-multimodel:3 Azure Machine Learning 스튜디오의 모델 탭에서 볼 수 있는 다음 모델 아티팩트가 포함되어 있음을 고려합니다.

A screenshot of the folder structure showing the model artifacts of the registered model.

배포를 만든 후 환경 변수 AZUREML_MODEL_DIR은 모델이 저장된 Azure 내의 스토리지 위치를 가리킵니다. 예를 들어 /var/azureml-app/azureml-models/local-multimodel/3은 모델과 파일 구조를 포함합니다. AZUREML_MODEL_DIR은 모델 아티팩트의 루트가 포함된 폴더를 가리킵니다. 이 예제에서는 AZUREML_MODEL_DIR 폴더의 콘텐츠가 다음과 같이 표시됩니다.

A screenshot of the folder structure showing multiple models.

채점 스크립트(score.py) 내에서 init() 함수에 모델을 로드할 수 있습니다. 예를 들어 diabetes.sav 모델을 로드합니다.

def init(): 
    model_path = os.path.join(str(os.getenv("AZUREML_MODEL_DIR"), "models", "diabetes", "1", "diabetes.sav") 
    model = joblib.load(model_path) 

채점 스크립트 이해

온라인 엔드포인트의 점수 매기기 스크립트의 형식은 이전 버전의 CLI 및 Python SDK에서 사용된 것과 동일한 형식입니다.

앞서 설명했듯이 code_configuration.scoring_script에 지정된 채점 스크립트에는 init() 함수와 run() 함수가 있어야 합니다.

이 예제에서는 이 score.py 파일: score.py를 사용합니다.

import os
import logging
import json
import numpy
import joblib


def init():
    """
    This function is called when the container is initialized/started, typically after create/update of the deployment.
    You can write the logic here to perform init operations like caching the model in memory
    """
    global model
    # AZUREML_MODEL_DIR is an environment variable created during deployment.
    # It is the path to the model folder (./azureml-models/$MODEL_NAME/$VERSION)
    # Please provide your model's folder name if there is one
    model_path = os.path.join(
        os.getenv("AZUREML_MODEL_DIR"), "model/sklearn_regression_model.pkl"
    )
    # deserialize the model file back into a sklearn model
    model = joblib.load(model_path)
    logging.info("Init complete")


def run(raw_data):
    """
    This function is called for every invocation of the endpoint to perform the actual scoring/prediction.
    In the example we extract the data from the json input and call the scikit-learn model's predict()
    method and return the result back
    """
    logging.info("model 1: request received")
    data = json.loads(raw_data)["data"]
    data = numpy.array(data)
    result = model.predict(data)
    logging.info("Request processed")
    return result.tolist()

컨테이너가 초기화/시작되면 init() 함수가 호출됩니다. 초기화는 일반적으로 배포를 만들거나 업데이트한 직후에 발생합니다. init 함수는 이 예제에서와 같이 메모리에 모델을 캐시하는 것과 같은 글로벌 초기화 작업을 위한 논리를 작성하는 곳입니다.

run() 함수는 엔드포인트를 호출할 때마다 호출되며, 실제 채점 및 예측을 수행합니다. 이 예제에서는 JSON 입력에서 데이터를 추출하고, scikit-learn 모델의 predict() 메서드를 호출하며, 결과를 반환합니다.

로컬 엔드포인트를 사용하여 로컬로 배포 및 디버그

Azure에 배포하기 전에 코드 및 구성의 유효성을 검사하고 디버깅하여 엔드포인트를 로컬로 테스트 실행하는 것이 좋습니다. Azure CLI 및 Python SDK는 로컬 엔드포인트 및 배포를 지원하지만 Azure Machine Learning 스튜디오 및 ARM 템플릿은 지원하지 않습니다.

로컬로 배포하려면 Docker 엔진 을 설치하고 실행해야 합니다. Docker 엔진은 일반적으로 컴퓨터가 시작될 때 시작됩니다. 그렇지 않은 경우 Docker 엔진 문제를 해결할 수 있습니다.

Azure Machine Learning 유추 HTTP 서버 Python 패키지를 사용하여 Docker 엔진 없이 로컬로 채점 스크립트를 디버그할 수 있습니다. 유추 서버를 사용하여 디버깅하면 로컬 엔드포인트에 배포하기 전에 채점 스크립트를 디버그하여 배포 컨테이너 구성의 영향을 받지 않고 디버그할 수 있습니다.

참고 항목

로컬 엔드포인트에 대한 제한 사항은 다음과 같습니다.

  • 로컬 엔드포인트는 트래픽 규칙, 인증 또는 프로브 설정을 지원하지 않습니다.
  • 로컬 엔드포인트는 엔드포인트당 하나의 배포만 지원합니다.
  • 로컬 conda 파일을 통해서만 로컬 모델 파일 및 환경을 지원합니다. 등록된 모델을 테스트하려면 먼저 CLI 또는 SDK를 사용하여 모델을 다운로드한 다음 배포 정의에서 path를 사용하여 부모 폴더를 참조합니다. 등록된 환경을 테스트하려면 Azure Machine Learning 스튜디오에서 환경의 컨텍스트를 확인하고 사용할 로컬 conda 파일을 준비합니다. 이 문서의 예제에서는 로컬 배포를 지원하는 로컬 conda 파일과 함께 로컬 모델 및 환경을 사용하는 방법을 보여 줍니다.

Azure에 배포하기 전에 온라인 엔드포인트를 로컬로 디버깅하는 방법에 대한 자세한 내용은 Visual Studio Code에서 로컬로 온라인 엔드포인트 디버그를 참조하세요.

로컬에서 모델 배포

먼저 엔드포인트를 만듭니다. 선택적으로, 로컬 엔드포인트의 경우 이 단계를 건너뛰고 다음 단계에서 배포를 만들 수 있습니다. 그러면 필요한 메타데이터가 만들어집니다. 모델을 로컬로 배포하는 것은 개발 및 테스트 목적으로 유용합니다.

az ml online-endpoint create --local -n $ENDPOINT_NAME -f endpoints/online/managed/sample/endpoint.yml

이제 엔드포인트 아래에 blue라는 배포를 만듭니다.

az ml online-deployment create --local -n blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml

--local 플래그는 Docker 환경에 엔드포인트를 배포하도록 CLI에 지시합니다.

Visual Studio Code를 사용하여 로컬로 엔드포인트를 테스트하고 디버그합니다. 자세한 내용은 Visual Studio Code에서 로컬로 온라인 엔드포인트 디버그를 참조하세요.

로컬 배포에 성공했는지 확인

상태를 확인하여 모델이 오류 없이 배포되었는지 확인합니다.

az ml online-endpoint show -n $ENDPOINT_NAME --local

출력은 다음 JSON과 비슷합니다. provisioning_stateSucceeded인 경우

{
  "auth_mode": "key",
  "location": "local",
  "name": "docs-endpoint",
  "properties": {},
  "provisioning_state": "Succeeded",
  "scoring_uri": "http://localhost:49158/score",
  "tags": {},
  "traffic": {}
}

다음 표에는 provisioning_state에 대해 가능한 값이 포함되어 있습니다.

시스템 상태 설명
만드는 중 리소스를 만드는 중입니다.
업데이트 중 리소스를 업데이트 중입니다.
삭제 중 리소스를 삭제하는 중입니다.
성공함 만들기/업데이트 작업이 성공했습니다.
실패함 만들기/업데이트/삭제 작업이 실패했습니다.

로컬 엔드포인트를 호출하여 모델로 데이터 채점

엔드포인트를 호출하여 편리한 명령 invoke를 사용하고 JSON 파일에 저장된 쿼리 매개 변수를 전달하여 모델을 채점합니다.

az ml online-endpoint invoke --local --name $ENDPOINT_NAME --request-file endpoints/online/model-1/sample-request.json

REST 클라이언트(예: curl)를 사용하려면 채점 URI가 있어야 합니다. 채점 URI를 얻으려면 az ml online-endpoint show --local -n $ENDPOINT_NAME을 실행합니다. 반환된 데이터에서 scoring_uri 특성을 찾습니다. 샘플 curl 기반 명령은 이 문서의 뒷부분에서 사용할 수 있습니다.

호출 작업의 출력에 대한 로그를 검토합니다.

예제 score.py 파일에서 run() 메서드는 콘솔에 일부 출력을 로그합니다.

get-logs 명령을 사용하여 이 출력을 볼 수 있습니다.

az ml online-deployment get-logs --local -n blue --endpoint $ENDPOINT_NAME

Azure에 온라인 엔드포인트 배포

다음으로, Azure에 온라인 엔드포인트를 배포합니다.

Azure에 배포

클라우드에서 엔드포인트를 만들려면 다음 코드를 실행합니다.

az ml online-endpoint create --name $ENDPOINT_NAME -f endpoints/online/managed/sample/endpoint.yml

엔드포인트 아래에 blue라는 배포를 만들려면 다음 코드를 실행합니다.

az ml online-deployment create --name blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml --all-traffic

이 배포는 기본 환경/이미지가 처음으로 빌드되는지 여부에 따라 최대 15분 정도 걸릴 수 있습니다. 동일한 환경을 사용하는 후속 배포는 더 빨리 처리를 완료합니다.

  • CLI 콘솔을 차단하지 않으려는 경우 명령에 --no-wait 플래그를 추가할 수 있습니다. 그러나 이렇게 하면 배포 상태의 대화형 표시가 중지됩니다.

Important

az ml online-deployment create--all-traffic 플래그는 새로 만든 파란색 배포의 엔드포인트에 트래픽의 100%를 할당합니다. 이는 개발 및 테스트 목적으로 유용하지만 프로덕션의 경우 명시적 명령을 통해 새 배포로 트래픽을 여는 것이 좋습니다. 예: az ml online-endpoint update -n $ENDPOINT_NAME --traffic "blue=100".

클러스터의 상태를 확인합니다.

show 명령에는 엔드포인트 및 배포에 대한 정보가 provisioning_state에 포함되어 있습니다.

az ml online-endpoint show -n $ENDPOINT_NAME

list 명령을 사용하여 작업 영역의 모든 엔드포인트를 테이블 형식으로 나열할 수 있습니다.

az ml online-endpoint list --output table

온라인 배포 상태 확인

로그를 확인하여 모델이 오류 없이 배포되었는지 확인합니다.

컨테이너에서 로그 출력을 보려면 다음 CLI 명령을 사용합니다.

az ml online-deployment get-logs --name blue --endpoint $ENDPOINT_NAME

기본적으로 로그는 유추 서버에서 풀합니다. 스토리지 이니셜라이저 컨테이너에서 로그를 보려면 --container storage-initializer 플래그를 추가합니다. 배포 로그에 대한 자세한 내용은 컨테이너 로그 가져오기를 참조하세요.

엔드포인트를 호출하여 모델을 사용하여 데이터 채점

선택한 invoke 명령 또는 REST 클라이언트를 사용하여 엔드포인트를 호출하고 일부 데이터를 채점할 수 있습니다.

az ml online-endpoint invoke --name $ENDPOINT_NAME --request-file endpoints/online/model-1/sample-request.json

다음 예제에서는 엔드포인트에 인증하는 데 사용되는 키를 얻는 방법을 보여줍니다.

Microsoft.MachineLearningServices/workspaces/onlineEndpoints/token/actionMicrosoft.MachineLearningServices/workspaces/onlineEndpoints/listkeys/action을 허용하는 사용자 지정 역할에 할당하여 인증 키를 가져올 수 있는 Microsoft Entra 보안 주체를 제어할 수 있습니다. 자세한 내용은 Azure Machine Learning 작업 영역 액세스 관리를 참조하세요.

ENDPOINT_KEY=$(az ml online-endpoint get-credentials -n $ENDPOINT_NAME -o tsv --query primaryKey)

다음으로 curl을 사용하여 데이터의 점수를 매깁니다.

SCORING_URI=$(az ml online-endpoint show -n $ENDPOINT_NAME -o tsv --query scoring_uri)

curl --request POST "$SCORING_URI" --header "Authorization: Bearer $ENDPOINT_KEY" --header 'Content-Type: application/json' --data @endpoints/online/model-1/sample-request.json

여기서는 showget-credentials 명령을 사용하여 인증 자격 증명을 얻습니다. 또한 --query 플래그를 사용하여 필요한 특성만 필터링하고 있습니다. --query에 대한 자세한 내용은 Azure CLI 명령 출력 쿼리를 참조하세요.

호출 로그를 보려면 get-logs를 다시 실행합니다.

토큰을 사용한 인증에 대한 자세한 내용은 온라인 엔드포인트에 인증을 참조하세요.

(선택 사항) 배포 업데이트

코드, 모델 또는 환경을 업데이트하려면 YAML 파일을 업데이트한 다음 az ml online-endpoint update 명령을 실행합니다.

참고 항목

배포 확장을 위해 단일 update 명령에서 인스턴스 수를 다른 모델 설정(코드, 모델 또는 환경)과 함께 업데이트하는 경우 먼저 크기 조정 작업이 수행된 후에 다른 업데이트가 적용됩니다. 프로덕션 환경에서는 이러한 작업을 별도로 수행하는 것이 좋습니다.

update의 작동 방식을 이해하려면 다음을 수행합니다.

  1. online/model-1/onlinescoring/score.py 파일을 엽니다.

  2. init() 함수의 마지막 줄을 변경합니다. logging.info("Init complete") 다음에 logging.info("Updated successfully")를 추가합니다.

  3. 파일을 저장합니다.

  4. 다음 명령을 실행합니다.

    az ml online-deployment update -n blue --endpoint $ENDPOINT_NAME -f endpoints/online/managed/sample/blue-deployment.yml
    

    참고 항목

    YAML을 사용한 업데이트는 선언적입니다. 즉, YAML의 변경 내용이 기본 Azure Resource Manager 리소스(엔드포인트 및 배포)에 반영됩니다. 선언적 접근 방식은 GitOps를 용이하게 합니다. 엔드포인트 및 배포에 대한 모든 변경 사항(instance_count 포함)은 YAML을 거칩니다.

    • --setCLI 명령을 사용하여 매개 변수update와 같은 일반 업데이트 매개 변수를 사용하여 YAML의 특성을 재정의하거 YAML 파일에 전달하지 않고 특정 특성을 설정할 수 있습니다. 단일 특성에 --set를 사용하는 것은 개발 및 테스트 시나리오에서 특히 중요합니다. 예를 들어 첫 번째 배포의 instance_count 값을 스케일 업하려면 --set instance_count=2 플래그를 사용하면 됩니다. 그러나 YAML이 업데이트되지 않으므로 이 기법을 사용하면 GitOps가 용이하지 않습니다.
    • YAML 파일 지정은 필수가 아닙니다. 예를 들어, 특정 배포에 대해 다양한 동시성 설정을 테스트하려는 경우 az ml online-deployment update -n blue -e my-endpoint --set request_settings.max_concurrent_requests_per_instance=4 environment_variables.WORKER_COUNT=4와 같은 것을 시도해 볼 수 있습니다. 이렇게 하면 기존 구성이 모두 유지되지만 지정된 매개 변수만 업데이트됩니다.
  5. 엔드포인트가 생성되거나 업데이트될 때 실행되는 init() 함수를 수정했으므로 로그에 Updated successfully 메시지가 표시됩니다. 다음을 실행하여 로그를 검색합니다.

    az ml online-deployment get-logs --name blue --endpoint $ENDPOINT_NAME
    

update 명령은 로컬 배포에서도 작동합니다. 동일한 az ml online-deployment update 명령에 --local 플래그를 사용합니다.

참고 항목

배포에 대한 이전 업데이트는 내부 롤링 업데이트의 예제입니다.

  • 관리형 온라인 엔드포인트의 경우 배포가 한 번에 20%의 노드가 있는 새 구성으로 업데이트됩니다. 배포에 10개의 노드가 있는 경우 한 번에 2개의 노드가 업데이트됩니다.
  • Kubernetes 온라인 엔드포인트의 경우 시스템이 새 구성을 사용하여 새 배포 인스턴스를 반복적으로 만들고 이전 배포 인스턴스를 삭제합니다.
  • 프로덕션 사용량의 경우 웹 서비스를 업데이트하기 위한 보다 안전한 대안을 제공하는 파란색-녹색 배포를 고려해야 합니다.

(선택 사항) 자동 크기 조정 구성

자동 크기 조정은 애플리케이션의 로드를 처리하기 위해 적절한 양의 리소스를 자동으로 실행합니다. 관리되는 온라인 엔드포인트는 Azure Monitor 자동 크기 조정 기능과의 통합을 통해 자동 크기 조정을 지원합니다. 자동 크기 조정을 구성하려면 온라인 엔드포인트를 자동 크기 조정하는 방법을 참조하세요.

(선택 사항) Azure Monitor를 사용하여 SLA 모니터링

SLA에 따라 메트릭을 보고 알림을 설정하려면 온라인 엔드포인트 모니터링에 설명된 단계를 완료하세요.

(선택 사항) Log Analytics와 통합

CLI용 get-logs 명령 또는 SDK용 get_logs 메서드는 자동으로 선택된 인스턴스에서 로그의 마지막 수백 줄만 제공합니다. 그러나 Log Analytics는 지속적으로 로그를 저장하고 분석하는 방법을 제공합니다. 로깅 사용에 대한 자세한 내용은 온라인 엔드포인트 모니터링을 참조하세요.

엔드포인트 및 배포 삭제

배포를 사용하지 않을 경우 다음 코드를 실행하여 배포를 삭제해야 합니다(엔드포인트 및 모든 기본 배포 삭제).

az ml online-endpoint delete --name $ENDPOINT_NAME --yes --no-wait