원격 모델 배포 문제 해결

아티클
09/03/2024

Azure Machine Learning을 사용하여 ACI(Azure Container Instances) 및 AKS(Azure Kubernetes Service)에 모델을 배포할 때 발생할 수 있는 일반적인 오류를 해결하거나 방법을 알아봅니다.

참고 항목

AKS(Azure Kubernetes Service)에 모델을 배포하는 경우 해당 클러스터에 대해 Azure Monitor를 사용하도록 설정하는 것이 좋습니다. 이렇게 하면 전반적인 클러스터 상태와 리소스 사용을 해석할 수 있습니다. 다음 리소스도 유용할 수 있습니다.

비정상 또는 오버로드 상태인 클러스터에 모델 배포를 시도하면 문제가 발생하게 됩니다. AKS 클러스터 문제 해결에 도움이 필요한 경우 AKS 고객 지원팀에 문의하세요.

필수 구성 요소

Azure 구독. Azure Machine Learning 평가판 또는 유료 버전을 사용해 보세요.
Azure Machine Learning SDK
Azure CLI
Azure Machine Learning용 CLI 확장 v1

Important

이 문서의 일부 Azure CLI 명령에서는 azure-cli-ml 또는 v1(Azure Machine Learning용 확장)을 사용합니다. v1 확장에 대한 지원은 2025년 9월 30일에 종료됩니다. v1 확장은 이 날짜까지 설치하고 사용할 수 있습니다.

2025년 9월 30일 이전에 ml 또는 v2 확장으로 전환하는 것이 좋습니다. v2 확장에 대한 자세한 내용은 Azure ML CLI 확장 및 Python SDK v2를 참조하세요.

기계 학습 모델의 Docker 배포 단계

Azure Machine Learning에서 로컬이 아닌 컴퓨팅에 모델을 배포하는 경우 다음 작업이 수행됩니다.

InferenceConfig의 환경 개체에서 지정한 Dockerfile은 원본 디렉터리의 내용과 함께 클라우드로 전송됩니다.
이전에 빌드한 이미지를 컨테이너 레지스트리에서 사용할 수 없는 경우 새 Docker 이미지가 클라우드에 빌드되고 작업 영역의 기본 컨테이너 레지스트리에 저장됩니다.
컨테이너 레지스트리의 Docker 이미지가 컴퓨팅 대상에 다운로드됩니다.
작업 영역의 기본 Blob 저장소가 컴퓨팅 대상에 탑재되어 등록된 모델에 대한 액세스 권한을 부여합니다.
웹 서버는 입력 스크립트의 init() 함수를 실행하여 초기화됩니다.
배포된 모델이 요청을 받으면 run() 함수가 해당 요청을 처리합니다.

로컬 배포를 사용할 때의 주요 차이점은 컨테이너 이미지가 로컬 컴퓨터에 빌드된다는 것입니다. 따라서 로컬 배포를 위해 Docker를 설치해야 합니다.

이러한 상위 수준 단계를 이해하면 오류가 발생하는 위치를 이해하는 데 도움이 됩니다.

배포 로그 가져오기

디버깅 오류에 대한 첫 번째 단계는 배포 로그를 가져오는 것입니다. 먼저 여기의 지침에 따라 작업 영역에 연결합니다.

Azure CLI
Python SDK

적용 대상: Azure CLI ml 확장 v1

배포된 웹 서비스에서 로그를 가져오려면 다음을 수행합니다.

az ml service get-logs --verbose --workspace-name <my workspace name> --name <service name>

적용 대상: Python SDK azureml v1

ws라는 azureml.core.Workspace 유형의 개체가 있다고 가정하면 다음을 수행할 수 있습니다.

print(ws.webservices)

# Choose the webservice you are interested in

from azureml.core import Webservice

service = Webservice(ws, '<insert name of webservice>')
print(service.get_logs())

로컬에서 디버그

ACI 또는 AKS에 모델을 배포할 때 문제가 있는 경우 로컬 웹 서비스로 배포합니다. 로컬 웹 서비스를 사용하면 문제를 더 쉽게 해결할 수 있습니다. 로컬 배포 문제를 해결하려면 로컬 문제 해결 문서를 참조하세요.

Azure Machine Learning 유추 HTTP 서버

로컬 유추 서버를 사용하면 항목 스크립트(score.py)를 신속하게 디버그할 수 있습니다. 기본 점수 스크립트에 버그가 있는 경우 서버는 모델을 초기화하거나 제공하지 못합니다. 대신 문제가 발생한 예외 및 위치를 throw합니다. Azure Machine Learning 유추 HTTP 서버에 대한 자세한 정보

pypi 피드에서 azureml-inference-server-http 패키지를 설치합니다.
```
python -m pip install azureml-inference-server-http
```
서버를 시작하고 항목 스크립트로 score.py를 설정합니다.
```
azmlinfsrv --entry_script score.py
```
curl을 사용하여 서버에 점수 매기기 요청을 보냅니다.
```
curl -p 127.0.0.1:5001/score
```

참고 항목

Azure Machine Learning 유추 HTTP 서버에 대한 질문과 대답에 대해 알아봅니다.

컨테이너를 예약할 수 없음

서비스를 Azure Kubernetes Service 컴퓨팅 대상에 배포하는 경우 Azure Machine Learning에서 서비스를 요청된 리소스의 양으로 예약하려고 합니다. 5분 후에 적절한 양의 리소스가 있는 클러스터에서 사용할 수 있는 노드가 없으면 배포가 실패합니다. 실패 메시지는 Couldn't Schedule because the kubernetes cluster didn't have available resources after trying for 00:05:00입니다. 이 오류는 더 많은 노드를 추가하거나 노드의 SKU를 변경하거나 서비스의 리소스 요구 사항을 변경하여 해결할 수 있습니다.

오류 메시지는 일반적으로 더 필요한 리소스를 나타냅니다. 예를 들어 0/3 nodes are available: 3 Insufficient nvidia.com/gpu를 나타내는 오류 메시지가 표시되면 서비스에 GPU가 필요하며 사용 가능한 GPU가 없는 클러스터에 세 개의 노드가 있음을 의미합니다. 이는 GPU SKU를 사용하는 경우 더 많은 노드를 추가하거나, 사용하지 않는 경우 GPU 지원 SKU로 전환하거나, GPU가 필요하지 않도록 환경을 변경하여 해결할 수 있습니다.

서비스 시작 실패

이미지가 성공적으로 빌드되면 시스템에서 배포 구성을 사용하여 컨테이너를 시작하려고 합니다. 컨테이너 시작 프로세스의 일부로, 시스템에서 채점 스크립트의 init() 함수를 호출합니다. init() 함수에 catch되지 않은 예외가 있는 경우 오류 메시지에 CrashLoopBackOff 오류가 표시될 수 있습니다.

Docker 로그 검사 문서의 정보를 사용하세요.

컨테이너 azureml-fe-aci 시작 실패

Azure Container Instance 컴퓨팅 대상에 서비스를 배포할 때 Azure Machine Learning은 유추 요청의 이름이 azureml-fe-aci인 프런트 엔드 컨테이너를 만들려고 시도합니다. azureml-fe-aci가 충돌하는 경우 az container logs --name MyContainerGroup --resource-group MyResourceGroup --subscription MySubscription --container-name azureml-fe-aci를 실행하여 로그를 볼 수 있습니다. 로그의 오류 메시지에 따라 수정할 수 있습니다.

azureml-fe-aci에 대한 가장 일반적인 오류는 제공된 SSL 인증서 또는 키가 잘못되었다는 것입니다.

함수 실패: get_model_path()

채점 스크립트의 init() 함수에서 컨테이너의 모델 파일 또는 모델 파일의 폴더를 찾기 위해 Model.get_model_path() 함수가 호출되는 경우가 많습니다. 모델 파일 또는 폴더를 찾을 수 없으면 함수가 실패합니다. 이 오류를 디버그하는 가장 쉬운 방법은 컨테이너 셸에서 아래의 Python 코드를 실행하는 것입니다.

적용 대상: Python SDK azureml v1

from azureml.core.model import Model
import logging
logging.basicConfig(level=logging.DEBUG)
print(Model.get_model_path(model_name='my-best-model'))

이 예제에서는 채점 스크립트에서 모델 파일 또는 폴더를 찾을 것으로 예상되는 컨테이너의 로컬 경로(/var/azureml-app에 대한 상대 경로)를 출력합니다. 그러면 예상 위치에 파일 또는 폴더가 실제로 있는지 확인할 수 있습니다.

로깅 수준을 DEBUG로 설정하면 추가 정보가 기록될 수 있으며, 이는 오류를 식별하는 데 유용할 수 있습니다.

함수 실패: run(input_data)

서비스가 성공적으로 배포되었지만 채점 엔드포인트에 데이터를 게시할 때 크래시가 발생하는 경우 오류를 catch하는 명령문을 run(input_data) 함수에 추가하면 구체적인 오류 메시지가 반환됩니다. 예시:

def run(input_data):
    try:
        data = json.loads(input_data)['data']
        data = np.array(data)
        result = model.predict(data)
        return json.dumps({"result": result.tolist()})
    except Exception as e:
        result = str(e)
        # return error message back to the client
        return json.dumps({"error": result})

참고: run(input_data) 호출에서 오류 메시지를 반환하는 방법은 디버깅 용도로만 사용해야 합니다. 보안상의 이유로 프로덕션 환경에서는 오류 메시지를 이런 식으로 반환해서는 안 됩니다.

502 HTTP 상태 코드

502 상태 코드는 서비스에서 예외를 throw했거나 score.py 파일의 run() 메서드에서 작동을 중단했음을 나타냅니다. 이 문서의 정보를 사용하여 파일을 디버그하세요.

503 HTTP 상태 코드

Azure Kubernetes Service 배포는 자동 크기 조정을 지원하므로 추가 로드를 지원하기 위해 복제본을 추가할 수 있습니다. 자동 크기 조정기는 점진적 로드 변경을 처리하도록 설계되었습니다. 초당 요청 수가 크게 급증하면 클라이언트에서 503 HTTP 상태 코드를 받을 수 있습니다. 자동 크기 조정기가 빠르게 반응하더라도 AKS는 추가 컨테이너를 만드는 데 상당한 시간이 소요됩니다.

스케일 업/다운 결정은 현재 컨테이너 복제본의 사용률에 기반합니다. 사용 중인(요청을 처리하는) 복제본 수를 현재 복제본의 총 수로 나눈 값이 현재 사용률입니다. 이 수가 autoscale_target_utilization을 초과하면 더 많은 복제본이 생성됩니다. 이보다 낮으면 복제본이 감소됩니다. 복제본 추가에 대한 결정은 열성적이고 빠릅니다(약 1초). 복제본 제거에 대한 결정은 보수적입니다(약 1분). 기본적으로 자동 크기 조정 목표 사용률은 70%로 설정됩니다. 즉 서비스에서 RPS(초당 요청 수)의 급증을 최대 30%까지 처리할 수 있습니다.

503 상태 코드를 방지하는 데 도움이 되는 두 가지 방법이 있습니다.

팁

이러한 두 가지 접근 방식은 개별적으로 또는 함께 사용할 수 있습니다.

자동 크기 조정에서 새 복제본을 만드는 사용률 수준을 변경합니다. autoscale_target_utilization을 더 낮은 값으로 설정하여 사용률 목표를 조정할 수 있습니다.

Important

이 변경으로 인해 복제본이 더 빨리 만들어지지 않습니다. 대신 낮은 사용률 임계값에서 만들어집니다. 서비스 사용률이 70%가 될 때까지 기다리는 대신 값을 30%로 변경하면 30%의 사용률이 발생할 때 복제본이 만들어집니다.

웹 서비스에서 이미 현재 최대 복제본을 사용하고 있고 여전히 503 상태 코드가 표시되면 autoscale_max_replicas 값을 늘려 최대 복제본 수를 늘립니다.
최소 복제본 수를 변경합니다. 최소 복제본 수를 늘리면 들어오는 급증을 처리할 수 있는 더 큰 풀이 제공됩니다.

최소 복제본 수를 늘리려면 autoscale_min_replicas를 더 높은 값으로 설정합니다. 다음 코드를 사용하여 값을 프로젝트와 관련된 값으로 바꿔 필요한 복제본을 계산할 수 있습니다.
```
from math import ceil
# target requests per second
targetRps = 20
# time to process the request (in seconds)
reqTime = 10
# Maximum requests per container
maxReqPerContainer = 1
# target_utilization. 70% in this example
targetUtilization = .7

concurrentRequests = targetRps * reqTime / targetUtilization

# Number of container replicas
replicas = ceil(concurrentRequests / maxReqPerContainer)
```
참고 항목

새 최소 복제본에서 처리할 수 있는 것보다 더 큰 요청 급증을 받으면 503을 다시 받을 수 있습니다. 예를 들어 서비스 트래픽이 증가하면 최소 복제본을 늘려야 할 수 있습니다.

autoscale_target_utilization, autoscale_max_replicas 및 autoscale_min_replicas 설정에 대한 자세한 내용은 AksWebservice 모듈 참조를 참조하세요.

504 HTTP 상태 코드

504 상태 코드는 요청 시간이 초과되었음을 나타냅니다. 기본 시간 제한은 1분입니다.

불필요한 호출을 제거하도록 score.py를 수정하여 시간 제한을 늘리거나 서비스 속도를 높일 수 있습니다. 이러한 작업으로도 문제가 해결되지 않으면 이 문서의 정보를 사용하여 score.py 파일을 디버그합니다. 코드가 응답하지 않는 상태이거나 무한 루프일 수 있습니다.

기타 오류 메시지

다음 오류에 대해 이 작업을 수행합니다.

오류	해결
409 충돌 오류	작업이 이미 진행 중인 경우 동일한 웹 서비스에 대한 모든 새 작업은 409 충돌 오류로 응답합니다. 예를 들어, 웹 서비스 만들기 또는 업데이트 작업이 진행 중인 경우 새 삭제 작업을 트리거하면 오류가 발생합니다.
웹 서비스를 배포할 때 이미지 빌드가 실패했습니다.	이미지 구성을 위해 Conda 파일에 "pynacl == 1.2.1"을 pip 종속성으로 추가합니다.
`['DaskOnBatch:context_managers.DaskOnBatch', 'setup.py']' died with <Signals.SIGKILL: 9>`	배포에 사용되는 VM의 SKU를 메모리를 더 많이 포함하는 SKU로 변경합니다.
FPGA 실패	FPGA 할당량을 요청하고 승인을 받기 전까지는 FPGA에 모델을 배포할 수 없습니다. 액세스를 요청하려면 할당량 요청 양식 https://forms.office.com/Pages/ResponsePage.aspx?id=v4j5cvGGr0GRqy180BHbR2nac9-PZhBDnNSV2ITz0LNUN0U5S0hXRkNITk85QURTWk9ZUUFUWkkyTC4u를 작성합니다.

고급 디버깅

모델 배포에 포함된 Python 코드를 대화형으로 디버그해야 할 수도 있습니다. 예를 들어, 항목 스크립트가 실패하고 추가 로깅으로 이유를 확인할 수 없는 경우입니다. Visual Studio Code 및 debugpy를 사용하여 Docker 컨테이너 내부에서 실행되는 코드에 연결할 수 있습니다.

자세한 내용은 VS Code의 대화형 디버깅 가이드를 참조하세요.

모델 배포 사용자 포럼

다음 단계

배포에 대해 자세히 알아보세요.

다음을 통해 공유