다음을 통해 공유

온라인 엔드포인트 배포 및 채점 문제 해결

  • 아티클

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

이 문서에서는 일반적인 Azure Machine Learning 온라인 엔드포인트 배포 및 채점 문제를 해결하는 방법을 설명합니다.

문서 구조는 문제 해결에 접근해야 하는 방식을 반영합니다.

  1. 클라우드에 배포하기 전에 로컬 배포 를 사용하여 모델을 로컬에서 테스트하고 디버그합니다.
  2. 컨테이너 로그 를 사용하여 문제를 디버그합니다.
  3. 발생할 수 있는 일반적인 배포 오류 와 이를 해결하는 방법을 이해합니다.

HTTP 상태 코드 섹션에서는 REST 요청으로 엔드포인트를 채점할 때 호출 및 예측 오류가 HTTP 상태 코드에 매핑되는 방법을 설명합니다.

필수 조건

요청 추적

지원되는 추적 헤더는 다음의 두 가지가 있습니다.

  • x-request-id는 서버 추적을 위해 예약되어 있습니다. Azure Machine Learning은 이 헤더를 재정의하여 유효한 GUID인지 확인합니다. 실패한 요청에 대한 지원 티켓을 만들 때 실패한 요청 ID를 첨부하여 조사를 더 신속하게 처리합니다. 아니면 지역 이름과 엔드포인트 이름을 제공합니다.

  • x-ms-client-request-id는 클라이언트 추적 시나리오에 사용할 수 있습니다. 이 헤더는 영숫자 문자, 하이픈, 밑줄만 허용하며 최대 40자 길이로 잘립니다.

로컬로 배포

로컬 배포는 로컬 Docker 환경에 모델을 배포하는 것을 의미합니다. 로컬 배포는 로컬 엔드포인트의 생성, 업데이트, 삭제를 지원하며 엔드포인트에서 로그를 호출하고 가져올 수 있습니다. 로컬 배포는 클라우드에 배포하기 전에 테스트 및 디버깅하는 데 유용합니다.

팁

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

Azure CLI 또는 Python SDK를 사용하여 로컬로 배포할 수 있습니다. Azure Machine Learning 스튜디오는 로컬 배포 또는 로컬 엔드포인트를 지원하지 않습니다.

로컬 배포를 사용하려면 --local을 적절한 명령에 추가합니다.

az ml online-deployment create --endpoint-name <endpoint-name> -n <deployment-name> -f <spec_file.yaml> --local

다음 단계는 로컬 배포 중에 발생합니다.

  1. Docker는 새 컨테이너 이미지를 빌드하거나 로컬 Docker 캐시에서 기존 이미지를 풀합니다. Docker는 사양 파일의 환경 부분과 일치하는 경우 기존 이미지를 사용합니다.
  2. Docker는 모델 및 코드 파일과 같은 탑재된 로컬 아티팩트로 새 컨테이너를 시작합니다.

자세한 내용은 로컬 엔드포인트를 사용하여 로컬로 배포 및 디버그를 참조하세요.

팁

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

컨테이너 로그 가져오기

모델이 배포되는 VM(가상 머신)에 직접 액세스할 수는 없지만 VM에서 실행되는 일부 컨테이너에서 로그를 가져올 수 있습니다. 얻는 정보의 양은 배포의 프로비전 상태에 따라 달라집니다. 지정된 컨테이너가 실행 중이면 콘솔 출력이 표시됩니다. 그렇지 않으면 나중에 다시 시도하라는 메시지가 표시됩니다.

다음 유형의 컨테이너에서 로그를 가져올 수 있습니다.

  • 유추 서버 콘솔 로그에는 채점 스크립트 score.py 코드의 인쇄 및 로깅 함수 출력이 포함됩니다.
  • 스토리지 이니셜라이저 로그에는 코드 및 모델 데이터가 컨테이너에 성공적으로 다운로드되었는지 여부에 대한 정보가 포함됩니다. 유추 서버 컨테이너가 실행되기 전에 컨테이너가 실행됩니다.

Kubernetes 온라인 엔드포인트의 경우 관리자는 모델을 배포하는 클러스터에 직접 액세스하고 Kubernetes에서 로그를 확인할 수 있습니다. 예시:

kubectl -n <compute-namespace> logs <container-name>

참고 항목

Python 로깅을 사용하는 경우 로그에 게시할 메시지에 대해 올바른 로깅 수준(예: INFO)을 사용해야 합니다.

컨테이너의 로그 출력 보기

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

az ml online-deployment get-logs -e <endpoint-name> -n <deployment-name> -l 100

또는

az ml online-deployment get-logs --endpoint-name <endpoint-name> --name <deployment-name> --lines 100

기본적으로 로그는 유추 서버에서 풀합니다. –-container storage-initializer를 전달하여 스토리지 이니셜라이저 컨테이너에서 로그를 가져올 수 있습니다.

az configure를 통해 이러한 매개 변수를 아직 설정하지 않은 경우 명령에 --resource-group 및 --workspace-name을 추가합니다. 이러한 매개 변수를 설정하는 방법에 대한 정보를 보려는 경우 또는 해당 값을 이미 설정한 경우 다음 명령을 실행합니다.

az ml online-deployment get-logs -h

자세한 정보를 보려면 명령에 --help 또는 --debug를 추가합니다.

일반적인 배포 오류

배포 작업 상태는 다음과 같은 일반적인 배포 오류를 보고할 수 있습니다.

Kubernetes 온라인 배포를 만들거나 업데이트하는 경우 Kubernetes 배포와 관련된 일반적인 오류도 참조하세요.

ERROR: ImageBuildFailure

이 오류는 Docker 이미지 환경을 빌드하는 동안 반환됩니다. 실패에 대한 자세한 내용은 빌드 로그를 확인할 수 있습니다. 빌드 로그는 Azure Machine Learning 작업 영역의 기본 스토리지에 있습니다.

오류의 일부로 정확한 위치가 반환될 수 있습니다(예: "the build log under the storage account '[storage-account-name]' in the container '[container-name]' at the path '[path-to-the-log]'").

다음 섹션에서는 일반적인 이미지 빌드 실패 시나리오에 대해 설명합니다.

Azure Container Registry 권한 부여 실패

현재 자격 증명으로 컨테이너 레지스트리에 액세스할 수 없는 경우 오류 메시지에 "container registry authorization failure"가 표시됩니다. 작업 영역 리소스 키의 비동기화로 인해 이 오류가 발생할 수 있으며 자동으로 동기화하는 데 시간이 걸립니다. 그러나 권한 부여 실패를 해결할 수 있는 az ml workspace sync-keys를 사용하여 키 동기화를 수동으로 호출할 수 있습니다.

가상 네트워크 뒤에 있는 컨테이너 레지스트리가 잘못 설정된 경우에도 이 오류가 발생할 수 있습니다. 가상 네트워크가 제대로 설정되었는지 확인합니다.

가상 네트워크를 사용하는 프라이빗 작업 영역에 이미지 빌드 컴퓨팅이 설정되지 않음

오류 메시지에 "failed to communicate with the workspace's container registry"가 언급되고 가상 네트워크를 사용하고 있으며 작업 영역의 컨테이너 레지스트리가 프라이빗이고 프라이빗 엔드포인트로 구성된 경우 Container Registry가 가상 네트워크에서 이미지를 빌드하도록 허용해야 합니다.

이미지 빌드 시간 초과

이미지 빌드 시간 제한은 이미지가 너무 커서 배포 생성 기간 내에 빌드를 완료할 수 없을 때 발생하는 경우가 많습니다. 오류가 지정하는 위치에서 이미지 빌드 로그를 확인합니다. 이미지 빌드 시간이 초과된 지점에서 로그가 잘립니다.

이 문제를 해결하려면 배포를 만드는 동안 이미지를 끌어오기만 하면 되도록 이미지를 별도로 빌드합니다. 또한 ImageBuild 시간 제한이 있는 경우 기본 프로브 설정을 검토합니다.

일반 이미지 빌드 실패

실패에 대한 자세한 내용은 빌드 로그를 확인합니다. 빌드 로그에서 명백한 오류가 없고 마지막 줄이 Installing pip dependencies: ...working...인 경우 종속성으로 인해 오류가 발생할 수 있습니다. conda 파일에 버전 종속성을 고정하면 이 문제를 해결할 수 있습니다.

클라우드에 배포하기 전에 로컬로 배포하여 모델을 테스트하고 디버그해 보세요.

오류: OutOfQuota

Azure 서비스를 사용할 때 다음 리소스의 할당량이 부족할 수 있습니다.

Kubernetes 온라인 엔드포인트의 경우에만 Kubernetes 리소스의 할당량이 부족할 수 있습니다.

CPU 할당량

모델을 배포하려면 컴퓨팅 할당량이 충분해야 합니다. CPU 할당량은 구독당, 작업 영역당, SKU당, 지역당 사용할 수 있는 가상 코어 수를 정의합니다. 각 배포는 사용 가능한 할당량에서 차감하고 SKU 유형에 따라 삭제 후 다시 추가합니다.

삭제할 수 있는 사용되지 않는 배포가 있는지 확인하거나 할당량 증가에 대한 요청을 제출할 수 있습니다.

클러스터 할당량

OutOfQuota 오류는 Azure Machine Learning 컴퓨팅 클러스터 할당량이 충분하지 않은 경우에 발생합니다. 할당량은 Azure 클라우드에서 CPU 또는 GPU 노드를 배포하는 데 동시에 사용할 수 있는 구독당 총 클러스터 수를 정의합니다.

디스크 할당량

OutOfQuota 오류는 모델 크기가 사용 가능한 디스크 공간보다 크고 모델을 다운로드할 수 없는 경우에 발생합니다. 디스크 공간이 더 많은 SKU를 사용하거나 이미지와 모델 크기를 줄여 보세요.

메모리 할당량

OutOfQuota 오류는 모델의 메모리 공간이 사용 가능한 메모리보다 클 때 발생합니다. 디스크 공간이 더 많은 SKU를 사용해 보세요.

역할 할당 할당량

관리형 온라인 엔드포인트를 만들 때 관리형 ID가 작업 영역 리소스에 액세스하려면 역할 할당이 필요합니다. 역할 할당 한도에 도달한 경우 이 구독에서 사용되지 않는 역할 할당을 삭제해 봅니다. Azure Portal에서 Azure 구독에 대한 액세스 제어를 선택하여 모든 역할 할당을 확인할 수 있습니다.

엔드포인트 할당량

이 구독에서 사용되지 않는 엔드포인트를 삭제해 보세요. 모든 엔드포인트가 활발하게 사용되고 있는 경우 엔드포인트 제한 증가를 요청해 봅니다. 엔드포인트 제한에 대한 자세한 내용은 Azure Machine Learning 온라인 엔드포인트 및 일괄 처리 엔드포인트를 사용한 엔드포인트 할당량을 참조하세요.

Kubernetes 할당량

OutOfQuota 오류는 이 배포에 대해 예약할 수 없는 노드로 인해 요청된 CPU 또는 메모리를 제공할 수 없는 경우에 발생합니다. 예를 들어 노드를 통제해야 하며 그렇지 못할 경우 사용하지 못할 수 있습니다.

오류 메시지는 일반적으로 클러스터의 리소스 부족을 나타냅니다(예: OutOfQuota: Kubernetes unschedulable. Details:0/1 nodes are available: 1 Too many pods...). 이 메시지는 클러스터에 너무 많은 Pod가 있고 요청에 따라 새 모델을 배포하기에 충분한 리소스가 없다는 것을 의미합니다.

이 문제를 해결하려면 다음 해결 방법을 시도하세요.

  • Kubernetes 클러스터를 유지 관리하는 IT 운영자는 노드를 더 추가하거나 클러스터에서 사용되지 않는 일부 Pod를 지워 일부 리소스를 해제할 수 있습니다.

  • 모델을 배포하는 기계 학습 엔지니어는 배포의 리소스 요청을 줄일 수 있습니다.

    • 리소스 섹션을 통해 배포 구성에서 리소스 요청을 직접 정의하는 경우 리소스 요청을 줄여보세요.
    • 모델 배포에 대한 리소스를 정의하는 데 instance_type을 사용하는 경우 IT 운영자에게 문의하여 인스턴스 유형 리소스 구성을 조정합니다. 자세한 내용은 인스턴스 유형 만들기 및 관리를 참조하세요.

지역 전체 VM 용량

이 지역의 Azure Machine Learning 용량이 부족하여 서비스에서 지정된 VM 크기를 프로비전하지 못했습니다. 나중에 다시 시도하거나 다른 지역에 배포해 보세요.

기타 할당량

배포의 일부로 제공하는 score.py 파일을 실행하기 위해 Azure는 score.py에 필요한 모든 리소스를 포함하는 컨테이너를 만듭니다. 그런 다음, Azure Machine Learning은 해당 컨테이너에서 채점 스크립트를 실행합니다. 컨테이너를 시작할 수 없는 경우 채점을 수행할 수 없습니다. 컨테이너는 instance_type에서 지원할 수 있는 것보다 더 많은 리소스를 요청할 수 있습니다. 온라인 배포의 instance_type을 업데이트하는 것이 좋습니다.

오류의 정확한 이유를 확인하려면 다음 작업을 수행합니다.

다음 명령 실행:

az ml online-deployment get-logs -e <endpoint-name> -n <deployment-name> -l 100

오류: BadArgument

다음과 같은 이유로 관리형 온라인 엔드포인트 또는 Kubernetes 온라인 엔드포인트를 사용할 때 이 오류가 발생할 수 있습니다.

다음과 같은 이유로 Kubernetes 온라인 엔드포인트만 사용할 때 이 오류가 발생할 수 있습니다.

구독이 없음

참조된 Azure 구독은 기존 및 활성 상태여야 합니다. 이 오류는 Azure에서 입력한 구독 ID를 찾을 수 없을 때 발생합니다. 이 오류는 구독 ID의 오타 때문일 수 있습니다. 구독 ID가 올바르게 입력되었으며 현재 활성화되어 있는지 다시 확인합니다.

권한 부여 오류

배포를 만들 때 컴퓨팅 리소스를 프로비전한 후 Azure는 작업 영역 컨테이너 레지스트리에서 사용자 컨테이너 이미지를 가져와서 사용자 모델 및 코드 아티팩트를 작업 영역 스토리지 계정의 사용자 컨테이너에 탑재합니다. Azure는 관리형 ID를 사용하여 스토리지 계정 및 컨테이너 레지스트리에 액세스합니다.

사용자 할당 ID를 사용하여 연결된 엔드포인트를 만드는 경우 사용자의 관리형 ID에는 작업 영역 스토리지 계정에 대한 Storage Blob 데이터 읽기 권한자 권한과 작업 영역 컨테이너 레지스트리에 대한 AcrPull 권한이 있어야 합니다. 사용자 할당 ID에 올바른 권한이 있는지 확인합니다.

시스템 할당 ID를 사용하여 연결된 엔드포인트를 만든 경우 Azure RBAC(역할 기반 액세스 제어) 권한이 자동으로 부여되며 추가 권한이 필요하지 않습니다. 자세한 내용은 컨테이너 레지스트리 권한 부여 오류를 참조하세요.

잘못된 템플릿 함수 사양

이 오류는 템플릿 함수가 잘못 지정되었을 때 발생합니다. 정책을 수정하거나 차단을 해제할 정책 할당을 제거합니다. 오류 메시지에는 이 오류를 디버그하는 데 도움이 되는 정책 할당 이름 및 정책 정의가 포함될 수 있습니다. 템플릿 오류를 방지하기 위한 팁은 Azure 정책 정의 구조를 참조하세요.

사용자 컨테이너 이미지를 다운로드할 수 없음

사용자 컨테이너를 찾을 수 없습니다. 자세한 내용을 보려면 컨테이너 로그를 확인합니다.

컨테이너 이미지를 작업 영역 컨테이너 레지스트리에서 사용할 수 있는지 확인합니다. 예를 들어 이미지가 testacr.azurecr.io/azureml/azureml_92a029f831ce58d2ed011c3c42d35acb:latest인 경우 다음 명령을 사용하여 리포지토리를 확인할 수 있습니다.

az acr repository show-tags -n testacr --repository azureml/azureml_92a029f831ce58d2ed011c3c42d35acb --orderby time_desc --output table`

사용자 모델을 다운로드할 수 없음

사용자 모델을 찾을 수 없습니다. 자세한 내용을 보려면 컨테이너 로그를 확인합니다. 배포와 동일한 작업 영역에 모델을 등록했는지 확인합니다.

작업 영역에서 모델에 대한 세부 정보를 표시하려면 다음 작업을 수행합니다. 모델 정보를 가져오려면 버전 또는 레이블을 지정해야 합니다.

다음 명령 실행:

az ml model show --name <model-name> --version <version>

또한 Blob이 작업 영역 스토리지 계정에 있는지 확인합니다. 예를 들어 Blob이 https://foobar.blob.core.windows.net/210212154504-1517266419/WebUpload/210212154504-1517266419/GaussianNB.pkl인 경우 다음 명령을 사용하여 Blob이 있는지 확인할 수 있습니다.

az storage blob exists --account-name <storage-account-name> --container-name <container-name> --name WebUpload/210212154504-1517266419/GaussianNB.pkl --subscription <sub-name>

Blob이 있는 경우 다음 명령을 사용하여 스토리지 이니셜라이저에서 로그를 가져올 수 있습니다.

az ml online-deployment get-logs --endpoint-name <endpoint-name> --name <deployment-name> –-container storage-initializer`

프라이빗 네트워크를 사용하는 MLflow 모델 형식은 지원되지 않음

관리형 온라인 엔드포인트에 레거시 네트워크 격리 방법을 사용하는 경우 MLflow 모델 형식으로 프라이빗 네트워크 기능을 사용할 수 없습니다. 코드 없는 배포 방법을 사용하여 MLflow 모델을 배포해야 하는 경우 작업 영역 관리형 가상 네트워크를 사용해 보세요.

제한보다 큰 리소스 요청

리소스에 대한 요청은 제한보다 작거나 같아야 합니다. 제한을 설정하지 않으면 컴퓨팅을 작업 영역에 연결할 때 Azure Machine Learning에서 기본값을 설정합니다. Azure Portal에서 또는 az ml compute show 명령을 사용하여 제한을 확인할 수 있습니다.

Azureml-fe 준비 안 됨

들어오는 유추 요청을 배포된 서비스로 라우팅하는 프런트 엔드 azureml-fe 구성 요소는 k8s-extension 설치 중에 설치되고 필요에 따라 자동으로 확장됩니다. 이 구성 요소에는 클러스터에 하나 이상의 정상 복제본이 있어야 합니다.

Kubernetes 온라인 엔드포인트 또는 배포 만들기 또는 업데이트 요청을 트리거할 때 구성 요소를 사용할 수 없는 경우 이 오류가 발생합니다. Pod 상태 및 로그를 확인하여 이 문제를 해결합니다. 클러스터에 설치된 k8s-extension을 업데이트할 수도 있습니다.

오류: ResourceNotReady

배포의 일부로 제공된 score.py 파일을 실행하기 위해 Azure는 score.py에 필요한 모든 리소스를 포함하는 컨테이너를 만들고 해당 컨테이너에서 채점 스크립트를 실행합니다. 이 시나리오의 오류는 실행할 때 이 컨테이너가 충돌하므로 채점을 수행할 수 없다는 것입니다. 이 오류는 다음 조건 중 하나에서 발생할 수 있습니다.

  • score.py에 오류가 있습니다. 다음과 같은 경우 get-logs를 사용하여 일반적인 문제를 진단합니다.

    • score.py에서 가져오기를 시도하는 패키지는 conda 환경에 포함되지 않음
    • 구문 오류
    • init() 메서드의 실패

    get-logs에서 로그를 생성하지 않는 경우 일반적으로 컨테이너를 시작하지 못했음을 의미합니다. 이 문제를 디버그하려면 로컬로 배포해 보세요.

  • 준비 상태 또는 활동성 프로브가 올바르게 설정되지 않았습니다.

  • 컨테이너 초기화가 너무 오래 걸리므로 준비 상태 또는 활동성 프로브가 실패 임계값을 초과하여 실패합니다. 이 경우 프로브 설정을 조정하여 컨테이너를 초기화하는 데 더 오랜 시간을 허용합니다. 또는 더 큰 지원되는 VM SKU를 사용하여 초기화를 가속화합니다.

  • 컨테이너 환경 설정에 누락된 종속성과 같은 오류가 있습니다.

    TypeError: register() takes 3 positional arguments but 4 were given 오류가 발생하면 flask v2와 azureml-inference-server-http 간의 종속성을 확인하세요. 자세한 내용은 HTTP 서버 문제 해결을 참조하세요.

오류: ResourceNotFound

다음과 같은 이유로 관리형 온라인 엔드포인트 또는 Kubernetes 온라인 엔드포인트를 사용할 때 이 오류가 발생할 수 있습니다.

리소스 관리자가 리소스를 찾을 수 없음

이 오류는 Azure Resource Manager가 필요한 리소스를 찾을 수 없을 때 발생합니다. 예를 들어 지정된 경로에서 스토리지 계정을 찾을 수 없는 경우 이 오류가 발생할 수 있습니다. 정확도 및 맞춤법 검사에 대한 경로 또는 이름 사양을 다시 확인합니다. 자세한 내용은 리소스를 찾을 수 없는 오류 해결을 참조하세요.

컨테이너 레지스트리 권한 부여 오류

이 오류는 배포를 위해 프라이빗 또는 기타 액세스할 수 없는 컨테이너 레지스트리에 속한 이미지를 배포용으로 제공한 경우에 발생합니다. Azure Machine Learning API는 프라이빗 레지스트리 자격 증명을 수락할 수 없습니다.

이 오류를 해결하려면 컨테이너 레지스트리가 프라이빗이 아닌지 확인하거나 다음 단계를 수행합니다.

  1. 프라이빗 레지스트리의 acrPull 역할을 온라인 엔드포인트의 시스템 ID에 부여합니다.
  2. 환경 정의에서 프라이빗 이미지의 주소를 지정하고 이미지를 수정하거나 빌드하지 않도록 지침을 제공합니다.

이 해결 방법이 성공하면 이미지를 빌드할 필요가 없으며 최종 이미지 주소는 지정된 이미지 주소입니다. 배포 시 온라인 엔드포인트의 시스템 ID는 프라이빗 레지스트리에서 이미지를 가져옵니다.

자세한 진단 정보는 작업 영역 진단을 사용하는 방법을 참조하세요.

오류: WorkspaceManagedNetworkNotReady

이 오류는 작업 영역 관리형 가상 네트워크를 사용하도록 설정하는 온라인 배포를 만들려고 하지만 관리형 가상 네트워크가 아직 프로비전되지 않은 경우에 발생합니다. 온라인 배포를 만들기 전에 작업 영역 관리형 가상 네트워크를 프로비전합니다.

작업 영역 관리형 가상 네트워크를 수동으로 프로비전하려면 관리형 VNet 수동 프로비전 지침을 따릅니다. 그런 다음, 온라인 배포 만들기를 시작할 수 있습니다. 자세한 내용은 관리형 온라인 엔드포인트를 사용하여 네트워크 격리 및 네트워크 격리를 통해 관리형 온라인 엔드포인트 보호를 참조하세요.

오류: OperationCanceled

다음과 같은 이유로 관리형 온라인 엔드포인트 또는 Kubernetes 온라인 엔드포인트를 사용할 때 이 오류가 발생할 수 있습니다.

우선 순위가 높은 다른 작업에 의해 취소된 작업

Azure 작업은 특정 우선 순위 수준을 가지며 가장 높은 수준에서 가장 낮은 수준으로 실행됩니다. 이 오류는 우선 순위가 높은 다른 작업이 작업을 재정의할 때 발생합니다. 작업을 다시 시도하면 취소 없이 작업을 수행할 수 있습니다.

잠금 확인을 기다리는 중에 취소된 작업

Azure 작업에는 제출된 후 짧은 대기 기간이 있으며, 이 기간 동안 잠금을 검색하여 경합 상태가 발생하지 않도록 합니다. 이 오류는 제출한 작업이 다른 작업과 동일한 경우에 발생합니다. 현재 다른 작업은 진행되기 전에 잠금을 받았다는 확인을 기다리고 있습니다.

초기 요청 후 너무 빨리 비슷한 요청을 제출했을 수 있습니다. 최대 1분 동안 기다린 후 작업을 다시 시도하면 취소 없이 작업을 수행할 수 있습니다.

오류: SecretsInjectionError

온라인 배포를 만드는 동안 비밀을 검색 및 삽입할 경우 온라인 엔드포인트와 연결된 ID를 사용하여 작업 영역 연결 또는 키 자격 증명 모음에서 비밀이 검색됩니다. 이 오류는 다음 이유 중 하나로 발생합니다.

  • 배포 정의가 환경 변수에 매핑된 참조로 비밀을 지정했더라도 엔드포인트 ID에는 작업 영역 연결 또는 키 자격 증명 모음에서 비밀을 읽을 수 있는 Azure RBAC 권한이 없습니다. 역할 할당은 변경 내용을 적용하는 데 시간이 걸릴 수 있습니다.

  • 비밀 참조의 형식이 잘못되었거나 지정된 비밀이 작업 영역 연결 또는 키 자격 증명 모음에 존재하지 않습니다.

자세한 내용은 온라인 엔드포인트의 비밀 주입(미리 보기) 및 비밀 주입을 사용하여 온라인 배포에서 비밀에 액세스(미리 보기)를 참조하세요.

오류: InternalServerError

이 오류는 수정해야 하는 Azure Machine Learning 서비스에 문제가 있음을 의미합니다. 문제를 해결하는 데 필요한 모든 정보가 포함된 고객 지원 티켓을 제출합니다.

Kubernetes 배포와 관련된 일반적인 오류

ID 및 인증 오류:

Crashloopbackoff 오류:

채점 스크립트 오류:

기타 오류:

오류: ACRSecretError

Kubernetes 온라인 배포를 만들거나 업데이트할 때 다음 이유 중 하나로 인해 이 오류가 발생할 수 있습니다.

  • 역할 할당이 완료되지 않았습니다. 몇 초 정도 기다렸다가 다시 시도하세요.

  • Azure Arc 지원 Kubernetes 클러스터 또는 AKS Azure Machine Learning 확장이 제대로 설치되거나 구성되지 않았습니다. Azure Arc 지원 Kubernetes 또는 Azure Machine Learning 확장 구성 및 상태를 확인합니다.

  • Kubernetes 클러스터에 잘못된 네트워크 구성이 있습니다. 프록시, 네트워크 정책 또는 인증서를 확인합니다.

  • 프라이빗 AKS 클러스터에 적절한 엔드포인트가 없습니다. AKS 가상 네트워크에서 Container Registry, 스토리지 계정, 작업 영역에 대한 프라이빗 엔드포인트를 설정해야 합니다.

  • Azure Machine Learning 확장 버전이 v1.1.25 이하입니다. 확장 버전이 v1.1.25보다 큰지 확인합니다.

오류: TokenRefreshFailed

이 오류는 Kubernetes 클러스터 ID가 제대로 설정되지 않아 확장이 Azure에서 보안 주체 자격 증명을 가져올 수 없기 때문에 발생합니다. Azure Machine Learning 확장을 다시 설치하고 다시 시도하세요.

오류: GetAADTokenFailed

이 오류는 Kubernetes 클러스터 요청 Microsoft Entra ID 토큰이 실패하거나 시간이 초과되었기 때문에 발생합니다. 네트워크 액세스를 확인한 다음, 다시 시도하세요.

  • Kubernetes 컴퓨팅 사용의 지침에 따라 아웃바운드 프록시를 확인하고 클러스터가 작업 영역에 연결할 수 있는지 확인합니다. 클러스터의 온라인 엔드포인트 CRD(사용자 지정 리소스 정의)에서 작업 영역 엔드포인트 URL을 찾을 수 있습니다.

  • 작업 영역에서 공용 액세스를 허용하는지 여부를 확인합니다. AKS 클러스터 자체가 퍼블릭인지 프라이빗인지에 관계없이 프라이빗 작업 영역에서 공용 네트워크 액세스를 사용하지 않도록 설정하는 경우 Kubernetes 클러스터는 프라이빗 링크를 통해서만 해당 작업 영역과 통신할 수 있습니다. 자세한 내용은 안전한 AKS 추론 환경이란?을 참조하세요.

오류: ACRAuthenticationChallengeFailed

이 오류는 Kubernetes 클러스터가 인증 문제를 해결하기 위해 작업 영역 Container Registry 서비스에 연결할 수 없기 때문에 발생합니다. 네트워크, 특히 Container Registry 공용 네트워크 액세스를 확인한 다음, 다시 시도하세요. GetAADTokenFailed의 문제 해결 단계에 따라 네트워크를 확인할 수 있습니다.

오류: ACRTokenExchangeFailed

이 오류는 Microsoft Entra ID 토큰에 아직 권한이 없기 때문에 발생하므로 Kubernetes 클러스터 교환 Container Registry 토큰이 실패합니다. 역할 할당에는 다소 시간이 걸리므로 잠시 기다렸다가 다시 시도하세요.

이 오류는 Container Registry 서비스에 대한 동시 요청이 너무 많기 때문일 수도 있습니다. 이 오류는 일시적이어야 하며 나중에 다시 시도할 수 있습니다.

오류: KubernetesUnaccessible

Kubernetes 모델 배포 중에 다음 오류가 발생할 수 있습니다.

{"code":"BadRequest","statusCode":400,"message":"The request is invalid.","details":[{"code":"KubernetesUnaccessible","message":"Kubernetes error: AuthenticationException. Reason: InvalidCertificate"}],...}

이 오류를 해결하기 위해 클러스터에 대한 AKS 인증서를 회전할 수 있습니다. 새 인증서는 5시간 후에 업데이트해야 하므로 5시간 동안 기다렸다가 다시 배포할 수 있습니다. 자세한 내용은 AKS(Azure Kubernetes Service)의 인증서 회전을 참조하세요.

오류: ImagePullLoopBackOff

컨테이너 레지스트리에서 이미지를 다운로드할 수 없어 이미지 끌어오기 실패가 발생하므로 Kubernetes 온라인 배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있습니다. 클러스터 네트워크 정책 및 작업 영역 컨테이너 레지스트리를 확인하여 클러스터가 컨테이너 레지스트리에서 이미지를 끌어올 수 있는지 확인합니다.

오류: DeploymentCrashLoopBackOff

초기화할 때 사용자 컨테이너가 충돌하여 Kubernetes 온라인 배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있습니다. 이 오류의 경우 두 가지 가능한 이유가 있습니다.

  • 사용자 스크립트 score.py에 초기화 시 예외를 발생시키는 구문 오류 또는 가져오기 오류가 있습니다.
  • 배포 Pod에는 해당 제한보다 더 많은 메모리가 필요합니다.

이 오류를 완화하려면 먼저 배포 로그에서 사용자 스크립트의 예외를 확인합니다. 오류가 지속되면 리소스/인스턴스 유형 메모리 제한을 확장해 봅니다.

오류: KubernetesCrashLoopBackOff

다음 이유 중 하나로 Kubernetes 온라인 엔드포인트 또는 배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있습니다.

  • 하나 이상의 Pod가 CrashLoopBackoff 상태에서 중단되었습니다. 배포 로그가 있고 로그에 오류 메시지가 있는지 확인합니다.
  • score.py에 오류가 발생하여 점수 코드를 초기화할 때 컨테이너가 충돌했습니다. ERROR: ResourceNotReady 의 지침을 따릅니다.
  • 채점 프로세스에는 배포 구성 제한보다 더 많은 메모리가 필요합니다. 더 큰 메모리 제한으로 배포를 업데이트할 수 있습니다.

오류: NamespaceNotFound

Kubernetes 컴퓨팅에서 사용된 네임스페이스를 클러스터에서 사용할 수 없으므로 Kubernetes 온라인 엔드포인트를 만들거나 업데이트할 때 이 오류가 발생할 수 있습니다. 작업 영역 포털에서 Kubernetes 컴퓨팅을 확인하고 Kubernetes 클러스터의 네임스페이스를 확인합니다. 네임스페이스를 사용할 수 없는 경우 레거시 컴퓨팅을 분리했다가 다시 연결해 클러스터에 이미 존재하는 네임스페이스를 지정하여 새 컴퓨팅을 만듭니다.

오류: UserScriptInitFailed

업로드된 score.py 파일의 init 함수에서 예외가 발생했기 때문에 Kubernetes 온라인 배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있습니다. 배포 로그를 확인하여 예외 메시지를 자세히 확인하고 예외를 수정합니다.

오류: UserScriptImportError

업로드한 score.py 파일이 사용할 수 없는 패키지를 가져오기 때문에 Kubernetes 온라인 배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있습니다. 배포 로그를 확인하여 예외 메시지를 자세히 확인하고 예외를 수정합니다.

오류: UserScriptFunctionNotFound

업로드한 score.py 파일에 이름이 init() 또는 run()인 함수가 없으므로 Kubernetes 온라인 배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있습니다. 코드를 확인하고 함수를 추가합니다.

오류: EndpointNotFound

시스템에서 클러스터에서 배포에 대한 엔드포인트 리소스를 찾을 수 없기 때문에 Kubernetes 온라인 배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있습니다. 기존 엔드포인트에서 배포를 만들거나 클러스터에서 먼저 엔드포인트를 만듭니다.

오류: EndpointAlreadyExists

클러스터에 엔드포인트가 이미 있으므로 Kubernetes 온라인 엔드포인트를 만들 때 이 오류가 발생할 수 있습니다. 엔드포인트 이름은 작업 영역 및 클러스터별로 고유해야 하므로 다른 이름으로 엔드포인트를 만듭니다.

오류: ScoringFeUnhealthy

클러스터에서 실행되는 azureml-fe 시스템 서비스는 찾을 수 없거나 비정상이므로 Kubernetes 온라인 엔드포인트 또는 배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있습니다. 이 문제를 해결하려면 클러스터에서 Azure Machine Learning 확장을 다시 설치하거나 업데이트합니다.

오류: ValidateScoringFailed

모델을 처리할 때 채점 요청 URL 유효성 검사가 실패했기 때문에 Kubernetes 온라인 배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있습니다. 엔드포인트 URL을 확인한 다음, 다시 배포합니다.

오류: InvalidDeploymentSpec

배포 사양이 잘못되었으므로 Kubernetes 온라인 배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있습니다. 오류 메시지를 확인하여 instance count가 유효한지 확인합니다. 자동 스케일링을 사용하도록 설정한 경우 minimum instance count 및 maximum instance count가 둘 다 유효한지 확인합니다.

오류: PodUnschedulable

다음 이유 중 하나로 Kubernetes 온라인 엔드포인트 또는 배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있습니다.

  • 클러스터의 리소스 부족으로 인해 시스템에서 노드에 Pod를 예약할 수 없습니다.
  • 노드 선호도 선택기와 일치하는 노드가 없습니다.

이 오류를 해결하려면 다음 단계를 수행합니다.

  1. 사용한 instance_type의 node selector 정의와 클러스터 노드의 node label 구성을 확인합니다.
  2. AKS 클러스터의 instance_type 및 노드 SKU 크기 또는 Azure Arc 지원 Kubernetes 클러스터의 노드 리소스를 확인합니다.
  3. 클러스터의 리소스가 부족한 경우 인스턴스 유형 리소스 요구 사항을 줄이거나 리소스 요구 사항이 더 작은 다른 인스턴스 형식을 사용합니다.
  4. 클러스터에 배포 요구 사항을 충족할 리소스가 더 이상 없는 경우 일부 배포를 삭제하여 리소스를 해제합니다.

오류: PodOutOfMemory

배포에 대해 지정한 메모리 제한이 부족하기 때문에 온라인 배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있습니다. 이 오류를 해결하려면 메모리 제한을 더 큰 값으로 설정하거나 더 큰 인스턴스 유형을 사용할 수 있습니다.

오류: InferencingClientCallFailed

Kubernetes 클러스터의 k8s-extension을 연결할 수 없으므로 Kubernetes 온라인 엔드포인트 또는 배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있습니다. 이 경우 컴퓨팅을 분리한 다음, 다시 연결합니다.

다시 연결하여 오류를 해결하려면 다른 오류를 방지하기 위해 컴퓨팅 이름 및 네임스페이스와 같은 분리된 컴퓨팅과 동일한 구성으로 다시 연결해야 합니다. 그래도 작동하지 않는 경우 클러스터에 액세스할 수 있는 관리자에게 kubectl get po -n azureml을 사용하여 릴레이 서버 Pod가 실행 중인지 확인하도록 요청합니다.

모델 사용량 문제

엔드포인트 invoke 작업 상태로 인해 발생하는 공통 모델 사용량 오류에는 대역폭 제한 문제, CORS 정책, 다양한HTTP 상태 코드가 포함됩니다.

대역폭 제한 문제

관리되는 온라인 엔드포인트에는 각 엔드포인트에 대한 대역폭 제한이 있습니다. 온라인 엔드포인트에 대한 제한에서 제한 구성을 찾을 수 있습니다. 대역폭 사용량이 제한을 초과하는 경우 요청이 지연됩니다.

대역폭 지연을 모니터링하려면 메트릭 네트워크 바이트를 사용하여 현재 대역폭 사용량을 파악합니다. 자세한 내용은 관리형 온라인 엔드포인트 모니터링을 참조하세요.

대역폭 제한이 적용되는 경우 두 개의 응답 트레일러가 반환됩니다.

  • ms-azureml-bandwidth-request-delay-ms는 요청 스트림 전송에 걸린 지연 시간(밀리초)입니다.
  • ms-azureml-bandwidth-response-delay-ms는 응답 스트림 전송에 걸린 지연 시간(밀리초)입니다.

CORS 정책에 따라 차단됨

V2 온라인 엔드포인트는 기본적으로 CORS(원본 간 리소스 공유)를 지원하지 않습니다. 웹 애플리케이션이 CORS 실행 전 요청을 제대로 처리하지 않고 엔드포인트를 호출하려고 하면 다음 오류 메시지를 받을 수 있습니다.

Access to fetch at 'https://{your-endpoint-name}.{your-region}.inference.ml.azure.com/score' from origin http://{your-url} has been blocked by CORS policy: Response to preflight request doesn't pass access control check. No 'Access-control-allow-origin' header is present on the request resource. If an opaque response serves your needs, set the request's mode to 'no-cors' to fetch the resource with the CORS disabled.

Azure Functions, Azure Application Gateway 또는 다른 서비스를 중간 계층으로 사용하여 CORS 실행 전 요청을 처리할 수 있습니다.

HTTP 상태 코드

REST 요청으로 온라인 엔드포인트에 액세스할 때 반환된 상태 코드는 HTTP 상태 코드에 대한 표준을 준수합니다. 다음 섹션에서는 엔드포인트 호출 및 예측 오류가 HTTP 상태 코드에 매핑되는 방법에 대해 자세히 설명합니다.

관리되는 온라인 엔드포인트에 대한 일반적인 오류 코드

다음 표에는 REST 요청에서 관리형 온라인 엔드포인트를 사용할 때 발생하는 일반적인 오류 코드가 포함되어 있습니다.

상태 코드 이유 설명
200 OK 모델이 대기 시간 범위 내에서 성공적으로 실행되었습니다.
401 Unauthorized 점수와 같은 요청된 작업을 수행할 수 있는 권한이 없습니다. 또는 토큰이 만료되었거나 토큰의 형식이 잘못되었습니다. 자세한 내용은 관리형 온라인 엔드포인트에 대한 인증 및 온라인 엔드포인트에 대한 클라이언트 인증을 참조하세요.
404 없습니다. 엔드포인트에 양수 가중치가 있는 유효한 배포가 없습니다.
408 요청 시간 초과 모델 실행이 모델 배포 구성의 request_settings에 있는 request_timeout_ms에 제공된 제한 시간보다 오래 걸렸습니다.
424 모델 오류 모델 컨테이너가 200이 아닌 응답을 반환하면 Azure는 424를 반환합니다. 엔드포인트의 Azure Monitor 메트릭 탐색기에서 Requests Per Minute 메트릭 아래의 Model Status Code 차원을 확인합니다. 또는 자세한 내용은 응답 헤더 ms-azureml-model-error-statuscode 및 ms-azureml-model-error-reason을 확인하세요. 424에 활동성 또는 준비 상태 프로브가 실패하는 경우, 컨테이너 활동성 또는 준비 상태를 더 오래 조사하도록 ProbeSettings를 조정하는 것이 좋습니다.
429 보류 중인 요청이 너무 많음 현재 모델이 처리할 수 있는 것보다 더 많은 요청을 가져오고 있습니다. 원활한 작업을 보장하기 위해 Azure Machine Learning은 지정된 시간에 병렬로 최대 2 * max_concurrent_requests_per_instance * instance_count requests를 처리할 수 있도록 허용합니다. 이 최댓값을 초과하는 요청은 거부됩니다.

모델 배포 구성을 request_settings 섹션 및 scale_settings 섹션에서 검토하여 이러한 설정을 확인하고 조정할 수 있습니다. 또한 RequestSettings에 설명된 대로 환경 변수 WORKER_COUNT가 올바르게 전달되었는지 확인합니다.

자동 스케일링을 사용할 때 이 오류가 발생하면 모델이 시스템을 스케일 업할 수 있는 것보다 더 빠르게 요청을 받고 있는 것입니다. 시스템에 조정할 시간을 주기 위해 지수 백오프를 사용하여 요청을 다시 보내는 것을 고려해 보세요. 인스턴스 수를 계산하는 코드를 사용하여 인스턴스 수를 늘릴 수도 있습니다. 이러한 단계를 자동 스케일링 설정과 결합하여 모델이 요청 유입을 처리할 준비가 되었는지 확인합니다.
429 속도가 제한됨 초당 요청 수가 관리형 온라인 엔드포인트 제한에 도달했습니다.
500 내부 서버 오류 Azure Machine Learning 프로비저닝된 인프라가 실패합니다.

Kubernetes 온라인 엔드포인트에 대한 일반적인 오류 코드

다음 표에는 REST 요청이 Kubernetes 온라인 엔드포인트를 사용하는 경우의 일반적인 오류 코드가 포함되어 있습니다.

상태 코드 오류 설명
409 충돌 오류 작업이 이미 진행 중이면 동일한 온라인 엔드포인트의 모든 새 작업이 409 충돌 오류로 응답합니다. 예를 들어 온라인 엔드포인트 만들기 또는 업데이트 작업이 진행 중인 경우 새 삭제 작업을 트리거하면 오류가 발생합니다.
502 score.py 파일의 run() 메서드에서 예외 또는 충돌 score.py에 오류가 있는 경우(예: 가져온 패키지가 conda 환경에 존재하지 않거나, 구문 오류가 발생하거나, init() 메서드에서 실패하는 경우)가 있는 경우 ERROR: ResourceNotReady를 참조하여 파일을 디버그합니다.
503 초당 요청 급증 자동 크기 조정기는 점진적 로드 변경을 처리하도록 설계되었습니다. 초당 요청 수가 크게 급증하면 클라이언트에서 503 HTTP 상태 코드를 받을 수 있습니다. 자동 크기 조정기가 빠르게 반응하더라도 AKS는 추가 컨테이너를 만드는 데 상당한 시간이 소요됩니다. 503 상태 코드 오류를 방지하는 방법을 참조하세요.
504 요청 시간 초과 504 상태 코드는 요청 시간이 초과되었음을 나타냅니다. 기본 제한 시간 설정은 5초입니다. 불필요한 호출을 제거하도록 score.py를 수정하여 시간 제한을 늘리거나 엔드포인트의 속도를 높일 수 있습니다. 이러한 작업이 문제를 수정하지 않으면 코드가 응답하지 않는 상태 또는 무한 루프에 있는 것일 수 있습니다. ERROR: ResourceNotReady를 따라score.py 파일을 디버그합니다.
500 내부 서버 오류 Azure Machine Learning 프로비저닝된 인프라가 실패합니다.

503 상태 코드 오류를 방지하는 방법

Kubernetes 온라인 배포는 추가 로드를 지원하기 위해 복제본을 추가할 수 있는 자동 스케일링을 지원합니다. 자세한 내용은 Azure Machine Learning 유추 라우터를 참조하세요. 스케일 업 또는 다운 결정은 현재 컨테이너 복제본의 사용률에 기반합니다.

두 가지 작업을 통해 503 상태 코드 오류를 방지할 수 있는데, 새 복제본을 만들기 위한 사용률 수준을 변경하거나 최소 복제본 수를 변경하는 것입니다. 이러한 접근 방식을 개별적으로 또는 조합하여 사용할 수 있습니다.

  • 자동 스케일링에서 새 복제본을 만드는 사용률 대상을 더 낮은 값의 autoscale_target_utilization으로 설정하여 변경합니다. 이렇게 변경해도 복제본이 더 빠르게 만들어지는 것은 아니지만 사용률 임계값은 낮아집니다. 예를 들어 값을 30%로 변경하면 서비스가 70% 활용될 때까지 기다리지 않고 30% 사용률이 발생할 때 복제본이 만들어집니다.

  • 수신 급증을 처리할 수 있는 더 큰 풀을 제공하도록 최소 복제본 수를 변경합니다.

인스턴스 수를 계산하는 방법

인스턴스 수를 늘리려면 필요한 복제본을 다음과 같이 계산할 수 있습니다.

from math import ceil
# target requests per second
target_rps = 20
# time to process the request (in seconds, choose appropriate percentile)
request_process_time = 10
# Maximum concurrent requests per instance
max_concurrent_requests_per_instance = 1
# The target CPU usage of the model container. 70% in this example
target_utilization = .7

concurrent_requests = target_rps * request_process_time / target_utilization

# Number of instance count
instance_count = ceil(concurrent_requests / max_concurrent_requests_per_instance)

참고 항목

새 최소 복제본이 처리할 수 있는 것보다 큰 요청 급증이 수신되면 503을 다시 받을 수 있습니다. 예를 들어 엔드포인트 트래픽이 증가하면 최소 복제본을 늘려야 할 수 있습니다.

Kubernetes 온라인 엔드포인트에서 이미 현재 최대 복제본을 사용하고 있는데도 503 상태 코드가 표시되는 경우 autoscale_max_replicas 값을 늘려 최대 복제본 수를 늘립니다.

네트워크 격리 문제

이 섹션에서는 일반적인 네트워크 격리 문제에 대한 정보를 제공합니다.

V1LegacyMode == true 메시지와 함께 온라인 엔드포인트 만들기 실패

v1_legacy_mode에 대한 Azure Machine Learning 작업 영역을 구성하여 v2 API를 비활성화할 수 있습니다. 관리형 온라인 엔드포인트는 v2 API 플랫폼의 기능이며 작업 영역에 v1_legacy_mode가 사용하도록 설정된 경우 작동하지 않습니다.

v1_legacy_mode를 사용하지 않도록 설정하려면 v2를 사용하여 네트워크 격리를 참조하세요.

Important

v1_legacy_mode를 사용하지 않도록 설정하기 전에 네트워크 보안 팀에 문의하세요. 네트워크 보안 팀이 어떤 이유로 이를 사용하도록 설정했을 수 있기 때문입니다.

키 기반 인증을 사용한 온라인 엔드포인트 만들기 실패

다음 명령을 사용하여 작업 영역에 대한 Azure Key Vault의 네트워크 규칙을 나열합니다. <keyvault-name>을 키 자격 증명 모음의 이름으로 바꿉니다.

az keyvault network-rule list -n <keyvault-name>

이 명령에 대한 응답은 다음 JSON 코드와 유사합니다.

{
    "bypass": "AzureServices",
    "defaultAction": "Deny",
    "ipRules": [],
    "virtualNetworkRules": []
}

bypass 값이 AzureServices가 아니면 키 자격 증명 모음 네트워크 설정 구성의 지침에 따라 AzureServices로 설정합니다.

이미지 다운로드 오류와 함께 온라인 배포 실패

참고 항목

이 문제는 Azure Machine Learning이 엔드포인트 아래의 각 배포에 대해 관리되는 가상 네트워크를 만드는 관리되는 온라인 엔드포인트에 대한 레거시 네트워크 격리 방법을 사용할 때 발생합니다.

  1. 배포에 대해 egress-public-network-access 플래그가 disabled인지 확인합니다. 이 플래그가 사용하도록 설정되고 컨테이너 레지스트리의 표시 유형이 프라이빗인 경우 이 실패가 예상됩니다.

  2. 다음 명령을 사용하여 프라이빗 엔드포인트 연결 상태를 확인합니다. <registry-name>을 작업 영역의 Azure Container Registry 이름으로 바꿉니다.

    az acr private-endpoint-connection list -r <registry-name> --query "[?privateLinkServiceConnectionState.description=='Egress for Microsoft.MachineLearningServices/workspaces/onlineEndpoints'].{Name:name, status:privateLinkServiceConnectionState.status}"

    응답 코드에서 status 필드가 Approved로 설정되어 있는지 확인합니다. 그렇지 않은 경우 다음 명령을 사용하여 승인합니다. <private-endpoint-name>을 이전 명령에서 반환된 이름으로 바꿉니다.

    az network private-endpoint-connection approve -n <private-endpoint-name>

점수 엔드포인트를 확인할 수 없습니다.

  1. 채점 요청을 실행하는 클라이언트가 Azure Machine Learning 작업 영역에 액세스할 수 있는 가상 네트워크인지 확인합니다.

  2. 엔드포인트 호스트 이름에서 nslookup 명령을 사용하여 IP 주소 정보를 검색합니다. 예를 들면 다음과 같습니다.

    nslookup endpointname.westcentralus.inference.ml.azure.com

    응답에는 가상 네트워크에서 제공하는 범위에 있어야 하는 주소가 포함됩니다.

    참고 항목

    • Kubernetes 온라인 엔드포인트의 경우 엔드포인트 호스트 이름은 Kubernetes 클러스터에 지정된 CName(도메인 이름)이어야 합니다.
    • 엔드포인트가 HTTP인 경우 IP 주소는 스튜디오 UI에서 가져올 수 있는 엔드포인트 URI에 포함됩니다.
    • 보안 Kubernetes 온라인 엔드포인트에서 엔드포인트의 IP 주소를 가져오는 다른 방법을 찾을 수 있습니다.

  3. nslookup 명령이 호스트 이름을 확인하지 않는 경우 다음 작업을 수행합니다.

관리형 온라인 엔드포인트

  1. 다음 명령을 사용하여 가상 네트워크의 프라이빗 DNS(도메인 이름 서버) 영역에 A 레코드가 있는지 확인합니다.

    az network private-dns record-set list -z privatelink.api.azureml.ms -o tsv --query [].name

    결과에는 *.<GUID>.inference.<region>과 유사한 항목이 포함되어야 합니다.

  2. 유추 값이 반환되지 않으면 작업 영역에 대한 프라이빗 엔드포인트를 삭제한 다음, 다시 만듭니다. 자세한 내용은 프라이빗 엔드포인트를 구성하는 방법을 참조하세요.

  3. 프라이빗 엔드포인트가 있는 작업 영역에서 사용자 지정 DNS 서버를 사용하는 경우 다음 명령을 실행하여 사용자 지정 DNS의 확인이 제대로 작동하는지 확인합니다.

dig endpointname.westcentralus.inference.ml.azure.com

Kubernetes 온라인 엔드포인트

  1. Kubernetes 클러스터에서 DNS 구성을 확인합니다.

  2. 또한 다음 명령을 사용하여 azureml-fe가 예상대로 작동하는지 확인합니다.

    kubectl exec -it deploy/azureml-fe -- /bin/bash
(Run in azureml-fe pod)

curl -vi -k https://localhost:<port>/api/v1/endpoint/<endpoint-name>/swagger.json
"Swagger not found"

    HTTP의 경우 다음 명령을 사용합니다.

     curl https://localhost:<port>/api/v1/endpoint/<endpoint-name>/swagger.json
"Swagger not found"

  3. curl HTTP가 실패하거나 시간이 초과되었지만 HTTP가 작동하는 경우 인증서가 유효한지 확인합니다.

  4. 이전 프로세스가 A 레코드로 확인되지 않는 경우 Azure DNS(168.63.129.16)에서 확인이 작동하는지 확인합니다.

    dig @168.63.129.16 endpointname.westcentralus.inference.ml.azure.com

  5. 이전 명령이 성공하면 사용자 지정 DNS의 프라이빗 링크에 대한 조건부 전달자 문제를 해결합니다.

온라인 배포는 점수를 매길 수 없습니다.

  1. 다음 명령을 실행하여 배포가 성공했는지 확인합니다.

    az ml online-deployment show -e <endpointname> -n <deploymentname> --query '{name:name,state:provisioning_state}'

    배포가 성공적으로 완료되면 state의 값은 Succeeded입니다.

  2. 배포에 성공했다면 다음 명령을 사용하여 트래픽이 배포에 할당되었는지 확인합니다. <endpointname>을 사용자의 엔드포인트 이름으로 바꿉니다.

    az ml online-endpoint show -n <endpointname>  --query traffic

    이 명령의 응답에는 배포에 할당된 트래픽의 백분율이 나열되어야 합니다.

    팁

    이 배포를 대상으로 하기 위해 요청에서 azureml-model-deployment 헤더를 사용하는 경우 이 단계가 필요하지 않습니다.

  3. 트래픽 할당 또는 배포 헤더가 올바르게 설정된 경우 다음 명령을 사용하여 엔드포인트에 대한 로그를 가져옵니다. <endpointname>을 엔드포인트 이름으로 바꾸고 <deploymentname>을 배포로 바꿉니다.

    az ml online-deployment get-logs  -e <endpointname> -n <deploymentname>

  4. 배포에 요청을 제출할 때 채점 코드를 실행하는 데 문제가 있는지 로그를 검토합니다.

유추 서버 문제

이 섹션에서는 Azure Machine Learning 유추 HTTP 서버에 대한 기본적인 문제 해결 팁을 제공합니다.

설치된 패키지를 확인합니다

설치된 패키지의 문제를 해결하려면 다음 단계를 따릅니다.

  1. Python 환경에 설치된 패키지와 버전에 대한 정보를 수집합니다.

  2. 환경 파일에 지정된 azureml-inference-server-http Python 패키지 버전이 시작 로그에 표시된 Azure Machine Learning 유추 HTTP 서버 버전과 일치하는지 확인합니다.

    어떤 경우에는 pip 종속성 확인자가 예기치 못한 패키지 버전을 설치합니다. 설치된 패키지와 버전을 수정하려면 pip를 실행해야 할 수도 있습니다.

  3. 환경에서 Flask나 해당 종속성을 지정하는 경우 이러한 항목을 제거합니다.

    • 종속 패키지에는 flask, jinja2, itsdangerous, werkzeug, markupsafe, click이 포함됩니다.
    • flask는 서버 패키지의 종속성으로 나열되어 있습니다. 가장 좋은 방법은 유추 서버가 flask 패키지를 설치하도록 허용하는 것입니다.
    • 유추 서버가 Flask의 새로운 버전을 지원하도록 구성된 경우, 서버는 패키지 업데이트가 제공되면 자동으로 해당 업데이트를 수신합니다.

서버 버전 확인

서버 패키지 azureml-inference-server-http가 PyPI에 게시됩니다. PyPI 페이지에는 변경 로그 및 모든 이전 버전이 나열됩니다.

이전 패키지 버전을 사용하는 경우 구성을 최신 버전으로 업데이트합니다. 다음 표는 안정적인 버전, 일반적인 문제 및 권장 조정 사항을 요약한 것입니다.

패키지 버전 설명 문제 해결 방법
0.4.x 20220601 또는 이전 날짜의 학습 이미지와 azureml-defaults 패키지 버전 .1.34부터 1.43까지 번들로 제공됩니다. 안정적인 최신 버전은 0.4.13입니다. 0.4.11 이전 서버 버전의 경우 Flask 종속성 문제가 발생할 수 있습니다(예: "can't import name Markup from jinja2"). 가능하면 0.4.13 또는 0.8.x(최신 버전)으로 업그레이드합니다.
0.6.x 20220516 이전의 유추 이미지에 사전 설치되어 있습니다. 안정적인 최신 버전은 0.6.1입니다. 해당 없음 해당 없음
0.7.x Flask 2를 지원합니다. 안정적인 최신 버전은 0.7.7입니다. 해당 없음 해당 없음
0.8.x 로그 형식이 변경되었습니다. Python 3.6 지원이 종료되었습니다. 해당 없음 해당 없음

패키지 종속성 확인

azureml-inference-server-http 서버 패키지에 가장 관련성 있는 종속 패키지는 다음과 같습니다.

  • flask
  • opencensus-ext-azure
  • inference-schema

Python 환경에서 azureml-defaults 패키지를 지정한 경우 azureml-inference-server-http 패키지는 종속 패키지입니다. 종속성은 자동으로 설치됩니다.

팁

Python SDK v1을 사용하고 Python 환경에서 azureml-defaults 패키지를 명시적으로 지정하지 않으면 SDK가 자동으로 패키지를 추가할 수 있습니다. 하지만 패키저 버전은 SDK 버전에 비해 잠겨 있습니다. 예를 들어, SDK 버전이 1.38.0이면 azureml-defaults==1.38.0 항목이 환경의 pip 요구 사항에 추가됩니다.

서버 시작 중 TypeError 발생

서버를 시작하는 동안 다음 TypeError가 발생할 수 있습니다.

TypeError: register() takes 3 positional arguments but 4 were given

  File "/var/azureml-server/aml_blueprint.py", line 251, in register

    super(AMLBlueprint, self).register(app, options, first_registration)

TypeError: register() takes 3 positional arguments but 4 were given

이 오류는 Python 환경에 Flask 2가 설치되어 있지만 azureml-inference-server-http 패키지 버전이 Flask 2를 지원하지 않는 경우 발생합니다. Flask 2에 대한 지원은 azureml-inference-server-http 패키지 버전 0.7.0 이상 및 azureml-defaults 패키지 버전 1.44 이상에서 사용할 수 있습니다.

  • Azure Machine Learning Docker 이미지에서 Flask 2 패키지를 사용하지 않는 경우 최신 버전의 azureml-inference-server-http 또는 azureml-defaults 패키지를 사용합니다.

  • Azure Machine Learning Docker 이미지에서 Flask 2 패키지를 사용하는 경우 이미지 빌드 버전이 2022년 7월 이후인지 확인합니다.

    컨테이너 로그에서 이미지 버전을 찾을 수 있습니다. 예시:

    2022-08-22T17:05:02,147738763+00:00 | gunicorn/run | AzureML Container Runtime Information
2022-08-22T17:05:02,161963207+00:00 | gunicorn/run | ###############################################
2022-08-22T17:05:02,168970479+00:00 | gunicorn/run | 
2022-08-22T17:05:02,174364834+00:00 | gunicorn/run | 
2022-08-22T17:05:02,187280665+00:00 | gunicorn/run | AzureML image information: openmpi4.1.0-ubuntu20.04, Materialization Build:20220708.v2
2022-08-22T17:05:02,188930082+00:00 | gunicorn/run | 
2022-08-22T17:05:02,190557998+00:00 | gunicorn/run |

    이미지의 빌드 날짜는 Materialization Build 표기 뒤에 나타납니다. 앞의 예제에서 이미지 버전은 20220708 또는 2022년 7월 8일입니다. 이 예제의 이미지는 Flask 2와 호환됩니다.

    컨테이너 로그에 유사한 메시지가 표시되지 않으면 이미지가 오래되었으므로 업데이트해야 합니다. CUDA(Compute Unified Device Architecture) 이미지를 사용하고 최신 이미지를 찾을 수 없는 경우 AzureML-Containers에서 해당 이미지가 더 이상 사용되지 않는지 확인합니다. 더 이상 사용되지 않는 이미지에 대한 지정된 대체 이미지를 찾을 수 있습니다.

    온라인 엔드포인트에서 서버를 사용하는 경우 Azure Machine Learning 스튜디오의 엔드포인트 페이지에 있는 로그에서 로그를 찾을 수도 있습니다.

SDK v1을 사용하여 배포하고 배포 구성에서 이미지를 명시적으로 지정하지 않으면 서버는 로컬 SDK 툴셋과 일치하는 버전으로 openmpi4.1.0-ubuntu20.04 패키지를 적용합니다. 그러나 설치된 버전이 이미지의 최신 버전이 아닐 수 있습니다.

SDK 버전 1.43의 경우 서버는 기본적으로 openmpi4.1.0-ubuntu20.04:20220616 패키지 버전을 설치하지만 이 패키지 버전은 SDK 1.43과 호환되지 않습니다. 배포에 최신 SDK를 사용하고 있는지 확인합니다.

이미지를 업데이트할 수 없는 경우 환경 파일에 azureml-defaults==1.43 또는 azureml-inference-server-http~=0.4.13 항목을 고정하면 일시적으로 문제를 방지할 수 있습니다. 이 항목은 서버가 flask 1.0.x를 사용하여 이전 버전을 설치하도록 지시합니다.

서버 시작 중 ImportError 또는 ModuleNotFoundError 발생

서버 시작 중에 opencensus, jinja2, markupsafe 또는 click과 같은 특정 모듈에서 ImportError 또는 ModuleNotFoundError가 발생할 수 있습니다. 다음 예제에서는 오류 메시지를 보여 줍니다.

ImportError: cannot import name 'Markup' from 'jinja2'

Flask 종속성을 호환되는 버전에 고정하지 않는 서버의 버전 0.4.10 또는 이전 버전을 사용하는 경우 가져오기 및 모듈 오류가 발생합니다. 문제를 방지하려면 최신 버전의 서버를 설치합니다.

기타 일반적인 문제

다른 일반적인 온라인 엔드포인트 문제는 conda 설치 및 자동 스케일링과 관련이 있습니다.

Conda 설치 문제

MLflow 배포 문제는 일반적으로 conda.yml 파일에 지정된 사용자 환경 설치와 관련된 문제에서 비롯됩니다.

conda 설치 문제를 디버그하려면 다음 단계를 사용해 보세요.

  1. conda 설치 로그를 확인합니다. 컨테이너가 충돌하거나 시작하는 데 너무 오래 걸리는 경우 conda 환경 업데이트가 올바르게 확인되지 않았을 수 있습니다.
  2. conda env create -n userenv -f <CONDA_ENV_FILENAME> 명령을 사용하여 로컬로 mlflow conda 파일을 설치합니다.
  3. 로컬로 오류가 있는 경우 다시 배포하기 전에 conda 환경을 확인하고 기능 환경을 만들어 보세요.
  4. 컨테이너가 로컬로 확인되더라도 충돌하는 경우 배포에 사용되는 SKU 크기가 너무 작을 수 있습니다.
    • Conda 패키지 설치는 런타임에 발생하므로 SKU 크기가 너무 작아서 conda.yml 환경 파일의 모든 패키지를 수용할 수 없으면 컨테이너가 충돌할 수 있습니다.
    • Standard_F4s_v2 VM은 시작 SKU 크기가 좋지만 conda 파일이 지정하는 종속성에 따라 더 큰 VM이 필요할 수 있습니다.
    • Kubernetes 온라인 엔드포인트의 경우 Kubernetes 클러스터에는 최소 4개의 vCPU 코어와 8GB의 메모리가 있어야 합니다.

자동 크기 조정 문제

자동 스케일링에 문제가 있는 경우 Azure Monitor 자동 스케일링 문제 해결을 참조하세요.

Kubernetes 온라인 엔드포인트의 경우 Azure Machine Learning 유추 라우터는 Kubernetes 클러스터의 모든 모델 배포에 대한 자동 스케일링을 처리하는 프런트 엔드 구성 요소입니다. 자세한 내용은 Kubernetes 유추 라우팅 자동 스케일링을 참조하세요.

관련 콘텐츠