일괄 처리 엔드포인트 문제 해결

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

이 문서에서는 Azure Machine Learning에서 일괄 처리 채점에 일괄 처리 엔드포인트를 사용할 때 일반적인 오류를 해결하기 위한 지침을 제공합니다. 다음 섹션에서는 일괄 처리 채점 로그를 분석하여 발생 가능한 문제와 지원되지 않는 시나리오를 식별하는 방법을 설명합니다. 일반적인 오류를 해결하기 위해 권장되는 솔루션을 검토할 수도 있습니다.

일괄 처리 채점 작업에 대한 로그 가져오기

Azure CLI 또는 REST API를 사용하여 일괄 처리 엔드포인트를 호출하면 일괄 처리 채점 작업이 비동기식으로 실행됩니다. 일괄 처리 채점 작업에 대한 로그를 가져오기 위한 두 가지 옵션이 있습니다.

• 옵션 1: 작업 로그를 로컬 콘솔로 스트리밍합니다. azureml-logs 폴더에 있는 로그만 스트리밍됩니다.

  다음 명령을 실행하여 시스템 생성 로그를 콘솔로 스트리밍합니다. <job_name> 매개 변수를 일괄 처리 채점 작업의 이름으로 바꿉니다.

  az ml job stream --name <job_name>
  

• 옵션 2: Azure Machine Learning 스튜디오에서 작업 로그를 확인합니다.

  스튜디오에서 사용할 작업 링크를 가져오려면 다음 명령을 실행합니다. <job_name> 매개 변수를 일괄 처리 채점 작업의 이름으로 바꿉니다.

  az ml job show --name <job_name> --query services.Studio.endpoint -o tsv
  

  1. 스튜디오에서 작업 링크를 엽니다.

  2. 작업 그래프에서 batchscoring 단계를 선택합니다.

  3. 출력 + 로그 탭에서 검토할 로그를 하나 이상 선택합니다.

로그 파일 검토

Azure Machine Learning은 일괄 처리 채점 작업의 문제를 해결하는 데 도움이 되는 여러 형식의 로그 파일 및 기타 데이터 파일을 제공합니다.

일괄 처리 채점 로그의 최상위 두 폴더는 azureml-logs와 logs입니다. 채점 스크립트를 시작하는 컨트롤러의 정보는 ~/azureml-logs/70_driver_log.txt 파일에 저장됩니다.

개략적인 정보 검사

일괄 처리 채점 작업의 분산된 특성으로 인해 다양한 원본의 로그가 생성되지만 두 개의 결합된 파일은 고급 정보를 제공합니다.

스택 추적 데이터에서 오류 검사

다른 파일은 스크립트에서 발생할 수 있는 오류에 대한 정보를 제공합니다.

노드당 프로세스 로그 검사

각 노드가 점수 스크립트를 실행하는 방식을 완전히 이해하려면 각 노드의 개별 프로세스 로그를 살펴봅니다. 프로세스 로그는 ~/logs/sys/node 폴더에 저장되고 작업자 노드별로 그룹화됩니다.

폴더에는 각 미니 일괄 처리에 대한 자세한 정보가 포함된 <process_name>.txt 파일이 포함된 <ip_address>/ 하위 폴더가 있습니다. 작업자가 미니 일괄 처리를 선택하거나 완료하면 폴더 콘텐츠가 업데이트됩니다. 각 미니 일괄 처리에 대한 로그 파일에는 다음이 포함됩니다.

• 작업자 프로세스의 IP 주소와 PID(프로세스 ID)
• 총 항목 수, 성공적으로 처리된 항목 수 및 실패한 항목 수입니다.
• 시작 시간, 기간, 처리 시간 및 실행 메서드 시간입니다.

노드당 주기적인 검사

또한 각 노드의 리소스 사용량에 대한 정기 확인 결과를 볼 수 있습니다. 로그 파일과 설치 파일은 ~/logs/perf 폴더에 저장됩니다.

--resource_monitor_interval 매개 변수를 사용하여 확인 간격을 초 단위로 변경합니다.

• 기본값 사용: 기본 간격은 600초(10분)입니다.
• 검사 중지: 노드에서 실행 중인 검사를 중지하려면 값을 0으로 설정합니다.

폴더에는 각 미니 일괄 처리에 대한 <ip_address>/ 하위 폴더가 포함되어 있습니다. 작업자가 미니 일괄 처리를 선택하거나 완료하면 폴더 콘텐츠가 업데이트됩니다. 각 미니 일괄 처리의 폴더에는 다음 항목이 포함됩니다.

채점 스크립트에 로깅 추가

채점 스크립트에서 Python 로깅을 사용할 수 있습니다. 이러한 로그는 logs/user/stdout/<node_id>/process<number>.stdout.txt 파일에 저장됩니다.

다음 코드는 스크립트에 로깅을 추가하는 방법을 보여 줍니다.

import argparse
import logging

# Get logging_level
arg_parser = argparse.ArgumentParser(description="Argument parser.")
arg_parser.add_argument("--logging_level", type=str, help="logging level")
args, unknown_args = arg_parser.parse_known_args()
print(args.logging_level)

# Initialize Python logger
logger = logging.getLogger(__name__)
logger.setLevel(args.logging_level.upper())
logger.info("Info log statement")
logger.debug("Debug log statement")

일반적인 오류 해결

다음 섹션에서는 일괄 처리 엔드포인트 개발 및 사용량 중에 발생할 수 있는 일반적인 오류와 해결 단계를 설명합니다.

azureml이라는 모듈이 없음

Azure Machine Learning 일괄 처리 배포에는 설치에 azureml-core 패키지가 필요합니다.

메시지가 기록됨: "[이름이 azureml인 모듈이 없습니다."

이유: 설치에서 azureml-core 패키지가 누락된 것 같습니다.

솔루션: conda 종속성 파일에 azureml-core 패키지를 추가합니다.

예측 파일에 출력이 없음

일괄 처리 배포에서는 predictions.csv 파일을 저장할 빈 폴더가 필요합니다. 배포 과정에서 지정된 폴더에 기존 파일이 있는 경우, 프로세스는 해당 파일 콘텐츠를 새 출력으로 바꾸거나 결과를 사용하여 새 파일을 만들지 않습니다.

메시지가 기록됨: 구체적으로 기록된 메시지가 없습니다.

이유: 일괄 처리 배포에서는 기존 predictions.csv 파일을 덮어쓸 수 없습니다.

솔루션: 프로세스에서 예측에 대한 출력 폴더 위치를 지정하는 경우 해당 폴더에 기존 predictions.csv 파일이 없는지 확인합니다.

일괄 처리 프로세스 시간 초과

일괄 처리 배포는 timeout 값을 사용하여 각 일괄 처리 프로세스가 완료될 때까지 배포가 기다려야 하는 시간을 결정합니다. 일괄 처리 실행이 지정된 시간 제한을 초과하면 일괄 처리 배포 프로세스가 중단됩니다.

중단된 프로세스는 max_retries 값에 지정된 최대 시도 횟수까지 다시 시도됩니다. 다시 시도할 때마다 시간 제한 오류가 발생하면 배포 작업이 실패합니다.

retry_settings 매개 변수를 사용하여 각 배포에 대한 timeout 및 max_retries 속성을 구성할 수 있습니다.

메시지가 기록됨: "[숫자]초 동안 진행률이 업데이트되지 않았습니다. 이번 점검에서는 진행률 업데이트가 없습니다. 마지막 업데이트 이후 [숫자]초 동안 기다립니다."

이유: 일괄 처리 실행이 지정된 시간 제한 및 최대 다시 시도 횟수를 초과했습니다. 이 작업은 항목 스크립트의 run() 함수가 실패한 것과 같습니다.

솔루션: 배포에 대한 timeout 값을 늘립니다. 기본적으로 timeout 값은 30이고 max_retries 값은 3입니다. 배포에 적합한 timeout 값을 결정하려면 각 일괄 처리에서 처리할 파일 수와 파일 크기를 고려합니다. 처리할 파일 수를 줄이고 더 작은 크기의 미니 일괄 처리를 생성할 수 있습니다. 이런 접근방식을 사용하면 실행 속도가 더 빨라집니다.

ScriptExecution.StreamAccess.Authentication에서 예외가 발생했습니다.

일괄 처리 배포를 성공시키려면 컴퓨팅 클러스터의 관리 ID에 데이터 자산 스토리지를 탑재할 수 있는 권한이 있어야 합니다. 관리 ID에 권한이 충분하지 않으면 스크립트에서 예외가 발생합니다. 이 실패로 인해 데이터 자산 스토리지가 탑재되지 않음이 발생할 수도 있습니다.

기록된 메시지: "StreamAccessException으로 인해 ScriptExecutionException이 발생했습니다. StreamAccessException은 AuthenticationException으로 인해 발생했습니다."

이유: 배포가 실행 중인 컴퓨팅 클러스터는 데이터 자산이 있는 스토리지를 탑재할 수 없습니다. 컴퓨팅의 관리 ID에 탑재를 수행할 수 있는 권한이 없습니다.

솔루션: 배포가 실행 중인 컴퓨팅 클러스터와 연결된 관리 ID에 최소한 스토리지 계정에 대한 Storage Blob 데이터 읽기 권한자 액세스 권한이 있는지 확인합니다. Azure Storage 계정 소유자만 Azure Portal에서 액세스 수준을 변경할 수 있습니다.

데이터 세트 초기화에 실패하여 데이터 세트를 탑재할 수 없습니다.

일괄 처리 배포 프로세스에는 데이터 자산을 위한 탑재된 스토리지가 필요합니다. 스토리지가 탑재되지 않으면 데이터 세트를 초기화할 수 없습니다.

기록된 메시지: "데이터 세트 초기화 실패: UserErrorException: 메시지: 데이터 세트를 탑재할 수 없습니다(id='xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', 이름='없음', 버전=없음). 데이터 세트의 원본에 액세스할 수 없거나 데이터가 포함되어 있지 않습니다."

이유: 배포가 실행 중인 컴퓨팅 클러스터는 데이터 자산이 있는 스토리지를 탑재할 수 없습니다. 컴퓨팅의 관리 ID에 탑재를 수행할 수 있는 권한이 없습니다.

솔루션: 배포가 실행 중인 컴퓨팅 클러스터와 연결된 관리 ID에 최소한 스토리지 계정에 대한 Storage Blob 데이터 읽기 권한자 액세스 권한이 있는지 확인합니다. Azure Storage 계정 소유자만 Azure Portal에서 액세스 수준을 변경할 수 있습니다.

dataset_param에 지정된 값이나 기본값이 없음

일괄 처리 배포 중에 데이터 세트 노드는 dataset_param 매개 변수를 참조합니다. 배포를 진행하려면 매개 변수에 할당된 값이나 지정된 기본값이 있어야 합니다.

기록된 메시지: "데이터 세트 노드 [코드]가 지정된 값이나 기본값이 없는 매개 변수 dataset_param을 참조하세요."

이유: 일괄 처리 엔드포인트에 제공된 입력 데이터 자산이 지원되지 않습니다.

솔루션: 배포 스크립트가 일괄 처리 엔드포인트에 지원되는 데이터 입력을 제공하는지 확인합니다.

사용자 프로그램 실패, 실행 실패

일괄 처리 배포를 위한 스크립트 실행 중 init() 또는 run() 함수에서 오류가 발생하면 사용자 프로그램이나 실행이 실패할 수 있습니다. 생성된 로그 파일에서 오류 세부 정보를 검토할 수 있습니다.

기록된 메시지: "사용자 프로그램이 다음 예외로 인해 실패했습니다. 실행 실패. 자세한 내용은 로그를 확인하세요. 로그 레이아웃은 logs/readme.txt에서 확인할 수 있습니다."

이유: init() 또는 run() 함수는 채점 스크립트를 실행하는 동안 발생하는 오류를 생성합니다.

솔루션: 다음 단계에 따라 함수 오류에 대한 세부 정보를 찾습니다.

1. Azure Machine Learning 스튜디오에서 실패한 일괄 처리 배포 작업 실행으로 이동하여 출력 + 로그 탭을 선택합니다.

2. logs>user>error><node_identifier>>process<number>.txt 파일을 엽니다.

3. init() 또는 run() 함수에서 생성된 오류 메시지를 찾습니다.

ValueError: 연결할 개체가 없습니다.

일괄 처리 배포가 성공하려면 미니 일괄 처리의 각 파일이 유효해야 하며 지원되는 파일 형식을 구현해야 합니다. MLflow 모델은 일부 파일 형식만 지원한다는 점에 유의해야 합니다. 자세한 내용은 일괄 처리 유추를 배포할 때의 고려 사항을 참조하세요.

기록된 메시지: "ValueError: 연결할 개체가 없습니다."

이유: 생성된 미니 일괄 처리의 파일이 모두 손상되었거나 지원되지 않는 파일 형식입니다.

솔루션: 실패한 파일에 대한 세부 정보를 찾으려면 다음 단계를 따릅니다.

1. Azure Machine Learning 스튜디오에서 실패한 일괄 처리 배포 작업 실행으로 이동하여 출력 + 로그 탭을 선택합니다.

2. logs>user>stdout><node_identifier>>process<number>.txt 파일을 엽니다.

3. "ERROR:azureml:입력 파일 처리 오류"와 같이 파일 입력 실패를 설명하는 항목을 찾습니다.

파일 형식이 지원되지 않는 경우 지원되는 파일 목록을 검토합니다. 입력 데이터의 파일 형식을 변경하거나, 채점 스크립트를 제공하여 배포를 사용자 지정해야 할 수도 있습니다. 자세한 내용은 채점 스크립트와 함께 MLflow 모델 사용을 참조하세요.

성공한 미니 일괄 처리가 없음

일괄 처리 배포 프로세스에서는 일괄 처리 엔드포인트가 run() 함수에서 예상하는 형식으로 데이터를 제공해야 합니다. 입력 파일이 손상된 파일이거나 모델 서명과 호환되지 않는 경우 run() 함수는 성공적인 미니 일괄 처리를 반환하지 못합니다.

기록된 메시지: "run()에서 반환된 성공적인 미니 일괄 처리 항목이 없습니다. https://aka.ms/batch-inference-documentation에서 'response: run()'을 확인하세요."

이유: 일괄 처리 엔드포인트가 예상 형식의 데이터를 run() 함수에 제공하지 못했습니다. 이 문제는 손상된 파일을 읽거나 입력 데이터가 모델(MLflow)의 서명과 호환되지 않는 것으로 인해 발생할 수 있습니다.

솔루션: 실패한 미니 일괄 처리에 대한 세부 정보를 찾으려면 다음 단계를 따릅니다.

1. Azure Machine Learning 스튜디오에서 실패한 일괄 처리 배포 작업 실행으로 이동하여 출력 + 로그 탭을 선택합니다.

2. logs>user>stdout><node_identifier>>process<number>.txt 파일을 엽니다.

3. "입력 파일 처리 오류"와 같이 미니 일괄 처리의 입력 파일 오류를 설명하는 항목을 찾습니다. 세부 정보에는 입력 파일을 올바르게 읽을 수 없는 이유를 설명해야 합니다.

대상 그룹 또는 서비스가 허용되지 않음

Microsoft Entra 토큰은 허용된 사용자(대상 그룹), 서비스 및 리소스를 식별하는 특정 작업에 대해 발급됩니다. 일괄 처리 엔드포인트 REST API에 대한 인증 토큰은 resource 매개 변수를 https://ml.azure.com으로 설정해야 합니다.

메시지가 기록됨: 구체적으로 기록된 메시지가 없습니다.

이유: 다른 대상 그룹 또는 서비스에 대해 발급된 토큰으로 일괄 처리 엔드포인트 및 배포에 대한 REST API를 호출하려고 합니다.

솔루션: 이 인증 문제를 해결하려면 다음 단계를 따릅니다.

1. 일괄 처리 엔드포인트 REST API에 대한 인증 토큰을 생성할 때 resource 매개 변수를 https://ml.azure.com으로 설정합니다.

   이 리소스는 REST API에서 엔드포인트를 관리하는 데 사용하는 리소스와 다릅니다. 모든 Azure 리소스(일괄 처리 엔드포인트 포함)는 관리를 위해 리소스 https://management.azure.com을 사용합니다.

2. 일괄 처리 엔드포인트 및 배포를 위해 REST API를 호출하는 경우, 다른 대상 그룹이나 서비스를 위해 발급된 토큰이 아닌 일괄 처리 엔드포인트 REST API를 위해 발급된 토큰을 사용해야 합니다. 각각의 경우에 올바른 리소스 URI를 사용하고 있는지 확인합니다.

관리 API와 작업 호출 API를 동시에 사용하려면 토큰 두 개가 필요합니다. 자세한 내용은 일괄 처리 엔드포인트의 인증(REST)을 참조하세요.

라우팅할 유효한 배포가 없음

일괄 처리 배포가 성공하려면 일괄 처리 엔드포인트에 적어도 하나 이상의 유효한 배포 경로가 있어야 합니다. 표준 방법은 defaults.deployment_name 매개 변수를 사용하여 기본 일괄 처리 배포를 정의하는 것입니다.

기록된 메시지: "라우팅할 유효한 배포가 없습니다. 엔드포인트에 가중치 값이 양수인 배포가 하나 이상 있는지 확인하거나 배포별 헤더를 사용하여 라우팅하세요."

이유: 기본 일괄 처리 배포가 올바르게 설정되지 않았습니다.

솔루션: 다음 방법 중 하나를 사용하여 라우팅 문제를 해결합니다.

• defaults.deployment_name 매개 변수가 올바른 기본 일괄 처리 배포를 정의하는지 확인합니다. 자세한 내용은 기본 일괄 처리 배포 업데이트를 참조하세요.

• 배포별 헤더로 경로를 정의합니다.

제한 사항 및 지원되지 않는 시나리오

일괄 처리 엔드포인트에 따라 다른 기계 학습 배포 솔루션을 설계하는 경우 일부 구성 및 시나리오가 지원되지 않는다는 점을 유념해야 합니다. 다음 섹션에서는 지원되지 않는 작업 영역 및 컴퓨팅 리소스와 입력 파일에 대한 잘못된 형식을 식별합니다.

지원되지 않는 작업 영역 구성

다음 작업 영역 구성은 일괄 처리 배포에 지원되지 않습니다.

• 격리 기능이 사용하도록 설정된 Azure Container Registries로 구성된 작업 영역
• 고객 관리형 키가 있는 작업 영역

지원되지 않는 컴퓨팅 구성

다음 컴퓨팅 구성은 일괄 처리 배포에 지원되지 않습니다.

• Azure ARC Kubernetes 클러스터
• Azure Kubernetes 클러스터에 대한 세분화된 리소스 요청(메모리, vCPU, GPU)(인스턴스 수만 요청할 수 있음)

지원되지 않는 입력 파일 형식

다음 입력 파일 형식은 일괄 처리 배포에 지원되지 않습니다.

• 표 형식 데이터 세트(V1)
• 폴더 및 파일 데이터 세트(V1)
• MLtable(V2)

관련 콘텐츠

• 일괄 처리 배포를 위한 작성자 채점 스크립트
• 일괄 처리 엔드포인트에 대한 권한 부여
• 일괄 처리 엔드포인트에서 네트워크 격리