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

  • 아티클

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

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

이 문서는 문제 해결에 접근하는 방식으로 구성됩니다.

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

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

필수 구성 요소

로컬로 배포

로컬 배포는 로컬 Docker 환경에 모델을 배포합니다. 로컬 배포는 클라우드에 배포하기 전에 테스트 및 디버깅하는 데 유용합니다.

팁

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

로컬 배포는 로컬 엔드포인트의 생성, 업데이트 및 삭제를 지원합니다. 또한 엔드포인트에서 로그를 호출하고 얻을 수 있습니다.

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

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

로컬 배포의 일부로 다음 단계가 수행됩니다.

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

자세한 내용은 배포에서 로컬로 배포 및 기계 학습 모델 채점을 참조하세요.

팁

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

Conda 설치

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

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

  1. conda 설치에 대한 로그를 확인합니다. 컨테이너가 충돌하거나 시작하는 데 너무 오래 걸리는 경우 conda 환경 업데이트가 올바르게 해결되지 않았을 수 있습니다.

  2. conda env create -n userenv -f <CONDA_ENV_FILENAME> 명령을 사용하여 로컬로 mlflow conda 파일을 설치합니다.

  3. 로컬로 오류가 있는 경우 다시 배포하기 전에 conda 환경을 확인하고 기능 환경을 만들어 보세요.

  4. 컨테이너가 로컬로 확인되더라도 충돌하는 경우 배포에 사용되는 SKU 크기가 너무 작을 수 있습니다.

    1. Conda 패키지 설치는 런타임에 발생하므로 SKU 크기가 너무 작아서 conda.yaml 환경 파일에 자세히 설명된 모든 패키지를 수용할 수 없으면 컨테이너가 충돌할 수 있습니다.
    2. Standard_F4s_v2 VM은 시작 SKU 크기가 좋지만 conda 파일에 지정된 종속성에 따라 더 큰 크기가 필요할 수 있습니다.
    3. Kubernetes 온라인 엔드포인트의 경우 클러스터에 4개 이상의 vCPU 코어와 8GB의 메모리가 있어야 합니다.

컨테이너 로그 가져오기

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

로그를 가져올 수 있는 컨테이너 유형은 두 가지가 있습니다.

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

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

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

az configure를 통해 이러한 매개 변수를 아직 설정하지 않은 경우 이러한 명령에 --resource-group 및 --workspace-name을 추가합니다.

이러한 매개 변수를 설정하는 방법에 대한 정보를 보려는 경우 해당 값을 이미 설정했으면 다음을 실행합니다.

az ml online-deployment get-logs -h

기본적으로 로그는 유추 서버에서 풀됩니다.

참고 항목

Python 로깅을 사용하는 경우 메시지가 로그에 게시되도록 하려면 올바른 로깅 수준 순서를 사용해야 합니다. 예를 들면 INFO입니다.

–-container storage-initializer를 전달하여 스토리지 이니셜라이저 컨테이너에서 로그를 가져올 수도 있습니다.

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

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

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

요청 추적

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

  • x-request-id는 서버 추적을 위해 예약되어 있습니다. 이 헤더가 유효한 GUID인지 확인하기 위해 이 헤더를 재정의합니다.

    참고 항목

    실패한 요청에 대한 지원 티켓을 만들 때 실패한 요청 ID를 첨부하여 조사를 더 신속하게 처리합니다.

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

일반적인 배포 오류

다음은 배포 작업 상태의 일부로 보고되는 일반적인 배포 오류 목록입니다.

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]'".

다음 목록에는 일반적인 이미지 빌드 실패 시나리오가 포함되어 있습니다.

또한 ImageBuild 시간 제한의 경우 기본 프로브 설정을 검토하는 것이 좋습니다.

컨테이너 레지스트리 권한 부여 실패

오류 메시지에 "container registry authorization failure"가 언급되어 있으면 현재 자격 증명으로 컨테이너 레지스트리에 액세스할 수 없음을 의미합니다. 작업 영역 리소스 키의 비동기화로 인해 이 오류가 발생할 수 있으며 자동으로 동기화하는 데 시간이 걸립니다. 그러나 키 동기화를 수동으로 호출하여 권한 부여 실패를 해결할 수 있습니다.

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

VNet을 사용하는 프라이빗 작업 영역에 이미지 빌드 컴퓨팅이 설정되지 않았습니다.

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

일반 이미지 빌드 실패

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

또한 클라우드에 배포하기 전에 로컬 배포를 통해 모델을 로컬에서 테스트하고 디버그하는 것이 좋습니다.

오류: OutOfQuota

다음은 Azure 서비스를 사용할 때 할당량이 부족해질 수 있는 일반적인 리소스 목록입니다.

또한 다음은 Kubernetes 온라인 엔드포인트에 한해 할당량이 부족해질 수 있는 일반적인 리소스 목록입니다.

CPU 할당량

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

완화할 수 있는 한 가지 방법은 사용되지 않은 배포를 삭제할 수 있는지 확인하는 것입니다. 또는 할당량 증가 요청을 제출할 수 있습니다.

클러스터 할당량

이 문제는 Azure Machine Learning 컴퓨팅 클러스터 할당량이 충분하지 않은 경우에 발생합니다. 이 할당량은 Azure Cloud에 CPU 또는 GPU 노드를 배포하기 위해 구독당 한 번에 사용할 수 있는 총 클러스터 수를 정의합니다.

완화할 수 있는 한 가지 방법은 사용되지 않은 배포를 삭제할 수 있는지 확인하는 것입니다. 또는 할당량 증가 요청을 제출할 수 있습니다. 이 할당량 증가 요청에 대한 할당량 유형으로 Machine Learning Service: Cluster Quota를 선택해야 합니다.

디스크 할당량

이 문제는 모델의 크기가 사용 가능한 디스크 공간보다 크고 모델을 다운로드할 수 없는 경우에 발생합니다. 디스크 공간이 더 많은 SKU를 사용해 보거나 이미지 및 모델 크기를 줄입니다.

메모리 할당량

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

역할 할당 할당량

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

엔드포인트 할당량

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

Kubernetes 할당량

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

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

다음 마이그레이션을 시도하여 이 문제를 해결할 수 있습니다.

  • Kubernetes 클러스터를 유지 관리하는 IT 운영자의 경우 노드를 더 추가하거나 클러스터에서 사용되지 않는 일부 Pod를 지워 일부 리소스를 해제할 수 있습니다.
  • 모델을 배포하는 기계 학습 엔지니어의 경우 배포의 리소스 요청을 줄여 볼 수 있습니다.
    • 리소스 섹션을 통해 배포 구성에서 리소스 요청을 직접 정의하는 경우 리소스 요청을 줄여 볼 수 있습니다.
    • instance type을 사용하여 모델 배포용 리소스를 정의하는 경우 IT 운영자에게 문의하여 인스턴스 유형의 리소스 구성을 조정할 수 있습니다. 자세한 내용은 Kubernetes 인스턴스 유형을 관리하는 방법을 참조하세요.

지역 전체 VM 용량

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

기타 할당량

배포의 일부로 제공된 score.py를 실행하기 위해 Azure는 score.py에 필요한 모든 리소스를 포함하는 컨테이너를 만들고 해당 컨테이너에서 채점 스크립트를 실행합니다.

컨테이너를 시작할 수 없는 경우 채점이 발생하지 않음을 의미합니다. 컨테이너가 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가 올바르게 입력되었고 현재 활성화되어 있는지 다시 확인하세요.

Azure 구독에 대한 자세한 내용은 필수 구성 요소 섹션을 참조하세요.

권한 부여 오류

컴퓨팅 리소스를 프로비전한 후(배포를 만드는 동안) Azure는 작업 영역 ACR(Azure Container Registry)에서 사용자 컨테이너 이미지를 끌어오려고 합니다. 작업 영역 스토리지 계정의 사용자 컨테이너에 사용자 모델 및 코드 아티팩트를 탑재하려 합니다.

이러한 작업을 수행하기 위해 Azure는 관리 ID를 사용하여 스토리지 계정과 컨테이너 레지스트리에 액세스합니다.

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

  • 사용자 할당 ID를 사용하여 연결된 엔드포인트를 만든 경우 사용자의 관리 ID에는 작업 영역의 스토리지 계정에 대한 Storage Blob 데이터 읽기 권한자 권한이 있어야 하고 작업 영역의 ACR(Azure Container Registry)에 대한 AcrPull 권한이 있어야 합니다. 사용자 할당 ID에 올바른 권한이 있는지 확인합니다.

자세한 내용은 Container Registry 권한 부여 오류를 참조하세요.

잘못된 템플릿 함수 사양

이 오류는 템플릿 함수가 잘못 지정되었을 때 발생합니다. 정책을 수정하거나 차단을 해제할 정책 할당을 제거합니다. 오류 메시지에는 이 오류를 디버깅하는 데 도움이 되는 정책 할당 이름과 정책 정의뿐만 아니라 템플릿 오류를 방지하기 위한 팁을 설명하는 Azure Policy 정의 구조 문서도 포함될 수 있습니다.

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

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

작업 영역 ACR에서 컨테이너 이미지를 사용할 수 있는지 확인합니다.

예를 들어 이미지가 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>

Warning

모델의 정보를 가져오려면 버전 또는 레이블을 지정해야 합니다.

작업 영역 스토리지 계정에 Blob이 있는지 확인할 수도 있습니다.

  • 예를 들어 Blob이 https://foobar.blob.core.windows.net/210212154504-1517266419/WebUpload/210212154504-1517266419/GaussianNB.pkl인 경우 이 명령을 사용하여 존재 여부를 확인할 수 있습니다.

    az storage blob exists --account-name foobar --container-name 210212154504-1517266419 --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 모델 형식과 함께 사용할 수 없습니다. 코드 없는 배포 방법을 사용하여 MLflow 모델을 배포해야 하는 경우 작업 영역 관리형 VNet 을 사용해 보세요.

제한보다 큰 리소스 요청

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

azureml-fe 준비 안 됨

들어오는 유추 요청을 배포된 서비스로 라우팅하는 프런트 엔드 구성 요소(azureml-fe)는 필요에 따라 자동으로 스케일링됩니다. k8s 확장 설치 중에 설치됩니다.

이 구성 요소는 클러스터에서 정상 상태여야 하며 하나 이상의 정상 복제본이어야 합니다. kubernetes 온라인 엔드포인트 및 배포 만들기/업데이트 요청을 트리거할 때 사용할 수 없는 경우 이 오류 메시지가 표시됩니다.

이 문제를 해결하려면 Pod 상태 및 로그를 확인하세요. 클러스터에 설치된 k8s 확장을 업데이트할 수도 있습니다.

오류: ResourceNotReady

배포의 일부로 제공된 score.py를 실행하기 위해 Azure는 score.py에 필요한 모든 리소스를 포함하는 컨테이너를 만들고 해당 컨테이너에서 채점 스크립트를 실행합니다. 이 시나리오의 오류는 이 컨테이너를 실행할 때 충돌이 발생하여 채점할 수 없음을 의미합니다. 이 오류는 다음과 같은 경우에 발생합니다.

  • score.py에 오류가 있습니다. get-logs를 사용하여 일반적인 문제를 진단합니다.
    • score.py에서 가져오기를 시도하는 패키지는 conda 환경에 포함되지 않습니다.
    • 구문 오류입니다.
    • init() 메서드의 실패.
  • get-logs에서 로그를 생성하지 않는 경우 일반적으로 컨테이너를 시작하지 못했음을 의미합니다. 이 문제를 디버그하려면 로컬로 배포해 보세요.
  • 준비 상태 또는 활동성 프로브가 올바르게 설정되지 않았습니다.
  • 컨테이너 초기화가 너무 오래 걸려서 준비 상태 또는 활동성 프로브가 실패 임계값을 초과하여 실패합니다. 이 경우 프로브 설정을 조정하여 컨테이너를 초기화하는 데 더 오랜 시간을 허용합니다. 또는 지원되는 VM SKU 중에서 더 큰 VM SKU를 사용하여 초기화를 가속화합니다.
  • 종속성 누락 등 컨테이너의 환경 설정에 오류가 있습니다.
  • TypeError: register() takes 3 positional arguments but 4 were given 오류가 표시되면 Flask v2와 azureml-inference-server-http 간의 종속성을 확인하세요. 자세한 내용은 유추 HTTP 서버에 대한 FAQ를 참조하세요.

오류: ResourceNotFound

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

Resource Manager가 리소스를 찾을 수 없음

이 오류는 Azure Resource Manager가 필요한 리소스를 찾을 수 없을 때 발생합니다. 예를 들어 스토리지 계정을 참조하지만 지정된 경로에서 찾을 수 없는 경우 이 오류가 표시될 수 있습니다. 정확한 경로 또는 이름 철자에서 제공했을 수 있는 리소스를 두 번 확인해야 합니다.

자세한 내용은 리소스를 찾을 수 없음 오류 해결을 참조하세요.

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

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

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

  1. 온라인 엔드포인트의 시스템 ID에 프라이빗 레지스트리의 acrPull 역할을 부여합니다.
  2. 환경 정의에서 프라이빗 이미지의 주소와 이미지를 수정(빌드)하지 말라는 지침을 지정합니다.

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

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

오류: OperationCanceled

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

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

Azure 작업은 우선 순위 수준이 있으며 가장 높은 수준에서 가장 낮은 수준으로 실행됩니다. 이 오류는 우선 순위가 높은 다른 작업에 의해 작업이 재정의된 경우에 발생합니다.

작업을 다시 시도하면 취소하지 않고 작업을 수행할 수 있습니다.

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

Azure 작업에는 제출된 후 짧은 대기 기간이 있으며, 이 기간 동안 잠금을 검색하여 경합 상태가 발생하지 않도록 합니다. 이 오류는 제출한 작업이 다른 작업과 동일한 경우에 발생합니다. 다른 작업은 진행되기 위해 현재 잠금을 받았다는 확인을 기다리고 있습니다. 초기 요청 후 너무 빨리 매우 비슷한 요청을 제출했음을 나타낼 수 있습니다.

몇 초에서 최대 1분까지 기다렸다가 작업을 다시 시도하면 해당 작업이 취소되지 않고 수행될 수 있습니다.

오류: SecretsInjectionError

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

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

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

오류: InternalServerError

안정적이고 신뢰할 수 있는 서비스를 제공하기 위해 최선을 다하고 있지만, 계획대로 되지 않는 경우도 있습니다. 이 오류가 발생하면 당사 측에 문제가 있는 것이므로 당사가 해결해야 합니다. 모든 관련 정보를 포함하여 고객 지원 티켓을 제출하면 문제를 해결할 수 있습니다.

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

ID 및 인증 관련 오류:

crashloopbackoff 관련 오류:

채점 스크립트 관련 오류:

기타:

오류: ACRSecretError

다음은 Kubernetes 온라인 배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있는 이유 목록입니다.

  • 역할 할당이 완료되지 않았습니다. 이 경우 몇 초 동안 기다렸다가 나중에 다시 시도하세요.
  • Azure ARC(Azure Arc Kubernetes 클러스터용) 또는 Azure Machine Learning 확장(AKS용)이 제대로 설치되거나 구성되지 않았습니다. Azure ARC 또는 Azure Machine Learning 확장 구성과 상태를 확인해 보세요.
  • Kubernetes 클러스터에 잘못된 네트워크 구성이 있습니다. 프록시, 네트워크 정책 또는 인증서를 확인하세요.
    • 프라이빗 AKS 클러스터를 사용하는 경우 AKS vnet의 작업 영역, 스토리지 계정, ACR에 대한 프라이빗 엔드포인트를 설정해야 합니다.
  • Azure Machine Learning 확장 버전이 v1.1.25보다 높은지 확인합니다.

오류: TokenRefreshFailed

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

오류: GetAADTokenFailed

이 오류는 Kubernetes 클러스터 요청 Azure AD 토큰이 실패했거나 시간 제한되었기 때문입니다. 네트워크 접근성을 확인한 후 다시 시도하세요.

  • 필요한 네트워크 트래픽 구성에 따라 아웃바운드 프록시를 확인하고 클러스터가 작업 영역에 연결할 수 있는지 확인할 수 있습니다.
  • 작업 영역 엔드포인트 URL은 클러스터의 온라인 엔드포인트 CRD에서 찾을 수 있습니다.

작업 영역이 공용 네트워크 액세스를 사용하지 않도록 설정한 프라이빗 작업 영역인 경우 Kubernetes 클러스터는 프라이빗 링크를 통해서만 해당 프라이빗 작업 영역과 통신해야 합니다.

  • 작업 영역 액세스가 공용 액세스를 허용하는지 확인할 수 있습니다. AKS 클러스터 자체가 공용인지 프라이빗인지에 관계없이 프라이빗 작업 영역에 액세스할 수 없습니다.
  • 자세한 내용은 보안 Azure Kubernetes Service 유추 환경을 참조하세요.

오류: ACRAuthenticationChallengeFailed

이 오류는 Kubernetes 클러스터가 인증 질문을 수행하기 위해 작업 영역의 ACR 서비스에 연결할 수 없기 때문입니다. 네트워크, 특히 ACR 공용 네트워크 액세스를 확인한 후 다시 시도하세요.

GetAADTokenFailed의 문제 해결 단계에 따라 네트워크를 확인할 수 있습니다.

오류: ACRTokenExchangeFailed

이 오류는 Azure AD 토큰이 아직 권한이 없기 때문에 Kubernetes 클러스터 교환 ACR 토큰이 실패했기 때문입니다. 역할 할당에 시간이 걸리기 때문에 잠시 기다렸다가 다시 시도하면 됩니다.

이 실패는 당시 ACR 서비스에 대한 요청이 너무 많아서일 수도 있습니다. 이는 일시적인 오류이므로 나중에 다시 시도할 수 있습니다.

오류: KubernetesUnaccessible

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

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

이 오류를 완화하려면 다음을 수행할 수 있습니다.

  • 클러스터에 대한 AKS 인증서를 회전합니다. 자세한 내용은 AKS(Azure Kubernetes Service)의 인증서 순환을 참조하세요.
  • 새 인증서는 5시간 이후로 업데이트되어야 하므로 5시간 정도 기다렸다가 다시 배포하면 됩니다.

오류: ImagePullLoopBackOff

Kubernetes 온라인 배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있는 이유는 컨테이너 레지스트리의 이미지를 다운로드할 수 없어 이미지를 풀하지 못하기 때문입니다.

이 경우 클러스터에서 컨테이너 레지스트리의 이미지를 풀할 수 있다면 클러스터 네트워크 정책 및 작업 영역 컨테이너 레지스트리를 확인하면 됩니다.

오류: DeploymentCrashLoopBackOff

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

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

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

오류: KubernetesCrashLoopBackOff

다음은 Kubernetes 온라인 엔드포인트/배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있는 이유 목록입니다.

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

오류: NamespaceNotFound

Kubernetes 온라인 엔드포인트를 만들거나 업데이트할 때 이 오류가 발생할 수 있는 이유는 Kubernetes 컴퓨팅에서 사용된 네임스페이스를 클러스터에서 사용할 수 없기 때문입니다.

작업 영역 포털에서 Kubernetes 컴퓨팅을 확인하고, Kubernetes 클러스터의 네임스페이스를 확인하면 됩니다. 네임스페이스를 사용할 수 없는 경우 레거시 컴퓨팅을 분리했다가 다시 연결해 클러스터에 이미 존재하는 네임스페이스를 지정하여 새 컴퓨팅을 만들면 됩니다.

오류: UserScriptInitFailed

Kubernetes 온라인 배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있는 이유는 업로드된 score.py 파일의 init 함수에서 예외가 발생했기 때문입니다.

배포 로그를 확인하여 예외 메시지를 자세히 살펴보고 예외를 수정하면 됩니다.

오류: UserScriptImportError

Kubernetes 온라인 배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있는 이유는 업로드한 score.py 파일이 사용할 수 없는 패키지를 가져왔기 때문입니다.

배포 로그를 확인하여 예외 메시지를 자세히 살펴보고 예외를 수정하면 됩니다.

오류: UserScriptFunctionNotFound

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

오류: EndpointNotFound

Kubernetes 온라인 배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있는 이유는 시스템이 클러스터에서 배포용 엔드포인트 리소스를 찾을 수 없기 때문입니다. 기존 엔드포인트에서 배포를 만들거나, 클러스터에서 먼저 이 엔드포인트를 만들어야 합니다.

오류: EndpointAlreadyExists

Kubernetes 온라인 엔드포인트를 만들 때 이 오류가 발생할 수 있는 이유는 만드는 엔드포인트가 클러스터에 이미 있기 때문입니다.

엔드포인트 이름은 작업 영역별, 클러스터별로 고유해야 하므로 이 경우 다른 이름으로 엔드포인트를 만들어야 합니다.

오류: ScoringFeUnhealthy

Kubernetes 온라인 엔드포인트/배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있는 이유는 클러스터에서 실행되는 시스템 서비스인 Azureml-fe가 찾을 수 없거나 비정상이기 때문입니다.

이 문제를 해결하려면 클러스터에서 Azure Machine Learning 확장을 다시 설치하거나 업데이트하면 됩니다.

오류: ValidateScoringFailed

Kubernetes 온라인 배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있는 이유는 모델 배포를 처리할 때 채점 요청 URL의 유효성을 검사하지 못했기 때문입니다.

이 경우 먼저 엔드포인트 URL을 확인한 후 배포를 재배포해 보면 됩니다.

오류: InvalidDeploymentSpec

Kubernetes 온라인 배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있는 이유는 배포 사양이 잘못되었기 때문입니다.

이 경우 오류 메시지를 확인하면 됩니다.

  • instance count가 유효한지 확인합니다.
  • 자동 스케일링을 사용하도록 설정한 경우 minimum instance count와 maximum instance count가 모두 유효한지 확인합니다.

오류: PodUnschedulable

다음은 Kubernetes 온라인 엔드포인트/배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있는 이유 목록입니다.

  • 클러스터의 리소스가 부족해서 노드에 Pod를 예약할 수 없습니다.
  • 노드 일치 노드 선호도/선택기가 없습니다.

이 오류를 완화하려면 다음 단계를 수행하면 됩니다.

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

오류: PodOutOfMemory

온라인 배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있는 이유는 배포에 제공하는 메모리 제한이 충분하지 않기 때문입니다. 이 오류를 완화하려면 메모리 제한을 더 큰 값으로 설정하거나 더 큰 인스턴스 유형을 사용하면 됩니다.

오류: InferencingClientCallFailed

Kubernetes 온라인 엔드포인트/배포를 만들거나 업데이트할 때 이 오류가 발생할 수 있는 이유는 Kubernetes 클러스터의 k8s 확장을 연결할 수 없기 때문입니다.

이 경우 컴퓨팅을 분리했다가 다시 연결하면 됩니다.

참고 항목

다시 연결하여 오류를 해결하려면 동일한 컴퓨팅 이름과 네임스페이스 등 이전에 분리된 컴퓨팅과 정확히 동일한 구성으로 다시 연결해야 합니다. 그렇지 않으면 다른 오류가 발생할 수 있습니다.

여전히 작동하지 않는 경우 클러스터에 액세스할 수 있는 관리자에게 kubectl get po -n azureml을 사용하여 릴레이 서버 Pod가 실행 중인지 여부를 확인해 달라고 요청하면 됩니다.

자동 크기 조정 문제

자동 크기 조정에 문제가 있는 경우 Azure 자동 크기 조정 문제 해결을 참조하세요.

Kubernetes 온라인 엔드포인트의 경우 Kubernetes 클러스터에서 모든 모델 배포에 대한 자동 크기 조정을 처리하는 프런트 엔드 구성 요소인 Azure Machine Learning 유추 라우터가 있습니다. Kubernetes 유추 라우팅의 자동 크기 조정에서 자세한 내용을 찾을 수 있습니다.

일반적인 모델 사용 오류

다음은 엔드포인트 invoke 작업 상태로 인해 발생하는 일반적인 모델 사용 오류 목록입니다.

대역폭 제한 문제

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

  • 메트릭 "네트워크 바이트"를 사용하여 현재 대역폭 사용량을 파악합니다. 자세한 내용은 관리형 온라인 엔드포인트 모니터링을 참조하세요.
  • 대역폭 제한이 적용되는 경우 두 개의 응답 트레일러가 반환됩니다.
    • ms-azureml-bandwidth-request-delay-ms: 요청 스트림 전송에 소요된 지연 시간(밀리초)입니다.
    • ms-azureml-bandwidth-response-delay-ms: 응답 스트림 전송에 소요된 지연 시간(밀리초)입니다.

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에 실패한 활동성 또는 준비 상태 프로브가 함께 제공되는 경우 컨테이너의 활동성 또는 준비 상태를 더 오래 검색할 수 있도록 프로브 설정을 조정하는 것이 좋습니다.
429 보류 중인 요청이 너무 많음 현재 모델이 처리할 수 있는 것보다 더 많은 요청을 가져오고 있습니다. Azure Machine Learning은 원활한 작동을 보장하기 위해 언제든지 최대 2 * max_concurrent_requests_per_instance * instance_count requests개를 병렬로 처리할 수 있는 시스템을 구현했습니다. 이 최댓값을 초과하는 다른 요청은 거부됩니다. request_settings 및 scale_settings 섹션에서 모델 배포 구성을 검토하여 이러한 설정을 확인하고 조정할 수 있습니다. 또한 RequestSettings에 대한 YAML 정의에 설명된 대로 환경 변수 WORKER_COUNT가 올바르게 전달되었는지 확인해야 합니다.

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

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

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

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

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

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

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

팁

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

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

    Important

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

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

  • 최소 복제본 수를 변경합니다. 최소 복제본 수를 늘리면 들어오는 급증을 처리할 수 있는 더 큰 풀이 제공됩니다.

    인스턴스 수를 늘리려면 다음 코드에 따라 필요한 복제본을 계산하면 됩니다.

    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을 다시 받을 수 있습니다. 예를 들어 엔드포인트 트래픽이 증가하면 최소 복제본을 늘려야 할 수 있습니다.

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

인스턴스 수를 늘리려면 다음 코드를 사용하여 필요한 복제본을 계산하면 됩니다.

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)

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.

CORS 실행 전 요청을 처리하기 위한 중간 계층으로 Azure Functions, Azure Application Gateway 또는 모든 서비스를 사용하는 것이 좋습니다.

일반적인 네트워크 격리 문제

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

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

Important

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

v1_legacy_mode를 사용하지 않도록 설정하는 방법에 대한 자세한 내용은 v2를 사용한 네트워크 격리를 참조하세요.

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

다음 명령을 사용하여 작업 영역에 대한 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 플래그가 사용하지 않도록 설정되었는지 확인합니다. 이 플래그가 사용하도록 설정되고 컨테이너 레지스트리의 표시 유형이 프라이빗 경우 이 실패가 예상됩니다.

  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 엔드포인트인 경우 Studio UI에서 직접 가져올 수 있는 엔드포인트 URI에 IP 주소가 포함됩니다. 엔드포인트의 IP 주소를 가져오는 다른 방법은 보안 Kubernetes 온라인 엔드포인트에서 찾을 수 있습니다.

  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 서버로 작업 영역을 사용하는 방법을 사용하여 설정된 경우 다음 명령을 사용하여 사용자 지정 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"

    curl HTTPs가 실패하지만(예: 시간 제한) HTTP가 작동하는 경우 인증서가 유효한지 확인하세요.

    이것이 A 레코드로 확인되지 않으면 Azure DNS(168.63.129.16)에서 확인이 작동하는지 확인합니다.

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

    이 작업이 성공하면 사용자 지정 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>

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

유추 서버 문제 해결

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

기본 단계

기본적인 문제 해결 단계는 다음과 같습니다.

  1. Python 환경에 대한 버전 정보를 수집합니다.
  2. 환경 파일에 지정된 azureml-inference-server-http python 패키지 버전이 시작 로그에 표시된 AzureML 유추 HTTP 서버 버전과 일치하는지 확인합니다. 경우에 따라 pip의 종속성 확인자가 예기치 않은 버전의 패키지를 설치하도록 합니다.
  3. 사용자 환경에서 Flask(및 해당 종속성)를 지정하는 경우 이를 제거합니다. 종속성에는 Flask, Jinja2, itsdangerous, Werkzeug, MarkupSafe 및 click이 포함됩니다. Flask는 서버 패키지에 종속성으로 나열되며, 서버에서 설치하도록 하는 것이 가장 좋습니다. 이렇게 하면 서버에서 새 버전의 Flask를 지원할 때 자동으로 가져옵니다.

서버 버전

서버 패키지 azureml-inference-server-http가 PyPI에 게시됩니다. PyPI 페이지에서 변경 로그와 이전의 모든 버전을 찾을 수 있습니다. 이전 버전을 사용하는 경우 최신 버전으로 업데이트합니다.

  • 0.4.x: 학습 이미지 ≤ 20220601 및 azureml-defaults>=1.34,<=1.43에 번들로 제공되는 버전입니다. 0.4.13은 안정적인 마지막 버전입니다. 버전 0.4.11 이전의 서버를 사용하는 경우 jinja2에서 이름 Markup을 가져올 수 없는 것과 같은 Flask 종속성 문제가 나타날 수 있습니다. 가능한 경우 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인 경우 환경의 pip 요구 사항에 azureml-defaults==1.38.0이 추가됩니다.

자주 묻는 질문

1. 서버를 시작하는 동안 다음 오류가 발생했습니다.


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가 설치되어 있지만 Flask 2를 지원하지 않는 azureml-inference-server-http 버전을 실행하고 있습니다. Flask 2에 대한 지원은 azureml-defaults>=1.44에도 있는 azureml-inference-server-http>=0.7.0에 추가되었습니다.

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

  • AzureML Docker 이미지와 함께 이 패키지를 사용하는 경우 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, Materializaton Build:20220708.v2
2022-08-22T17:05:02,188930082+00:00 | gunicorn/run | 
2022-08-22T17:05:02,190557998+00:00 | gunicorn/run |

    이미지의 빌드 날짜는 위의 예에서 20220708 또는 2022년 7월 8일인 "구체화 빌드" 뒤에 나타납니다. 이 이미지는 Flask 2와 호환됩니다. 컨테이너 로그에 이와 같은 배너가 표시되지 않으면 이미지가 오래된 것이므로 업데이트해야 합니다. CUDA 이미지를 사용 중이고 최신 이미지를 찾을 수 없는 경우 AzureML-Containers에서 이미지가 더 이상 사용되지 않는지 확인합니다. 그렇다면 대체 이미지를 찾을 수 있어야 합니다.

  • 온라인 엔드포인트가 있는 서버를 사용 중인 경우 Azure Machine Learning 스튜디오의 온라인 엔드포인트 페이지에 있는 '배포 로그'에서 로그를 찾을 수도 있습니다. SDK v1을 사용하여 배포하고 배포 구성에 이미지를 명시적으로 지정하지 않으면 기본적으로 로컬 SDK 도구 집합과 일치하는 openmpi4.1.0-ubuntu20.04 버전이 사용됩니다. 이 버전은 이미지의 최신 버전이 아닐 수 있습니다. 예를 들어 SDK 1.43은 기본적으로 호환되지 않는 openmpi4.1.0-ubuntu20.04:20220616을 사용합니다. 배포에 최신 SDK를 사용하고 있는지 확인합니다.

  • 어떤 이유로 이미지를 업데이트할 수 없는 경우 azureml-defaults==1.43 또는 azureml-inference-server-http~=0.4.13을 고정하여 일시적으로 문제를 피할 수 있습니다. 그러면 이전 버전 서버가 Flask 1.0.x로 설치됩니다.

2. 다음 메시지와 같이 시작하는 동안 모듈 opencensus, jinja2, MarkupSafe 또는 click에서 ImportError 또는 ModuleNotFoundError가 발생했습니다.

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

이전 버전(<= 0.4.10)의 서버는 Flask의 종속성을 호환 가능한 버전에 고정하지 않았습니다. 이 문제는 최신 버전의 서버에서 수정되었습니다.

다음 단계