Azure Machine Learning 유추 HTTP 서버를 사용하여 점수 매기기 스크립트 디버그

Azure Machine Learning 유추 HTTP 서버는 채점 함수를 HTTP 엔드포인트로 노출하고 Flask 서버 코드 및 종속성을 단일 패키지로 래핑하는 Python 패키지입니다. 유추 서버는 Azure Machine Learning에서 모델을 배포할 때 사용되는 유추를 위해 미리 빌드된 Docker 이미지 에 포함됩니다. 패키지만 사용하는 경우 프로덕션을 위해 모델을 로컬로 배포할 수 있습니다. 로컬 개발 환경에서 점수 매기기(항목) 스크립트의 유효성을 쉽게 검사할 수도 있습니다. 점수 매기기 스크립트에 문제가 있는 경우 유추 서버는 오류 및 오류의 위치를 반환합니다.

유추 서버를 사용하여 연속 통합 및 배포 파이프라인에서 유효성 검사 게이트를 만들 수도 있습니다. 예를 들어 후보 스크립트를 사용하여 유추 서버를 시작하고 로컬 엔드포인트에 대해 테스트 도구 모음을 실행할 수 있습니다.

이 문서에서는 유추 서버를 사용하여 로컬로 디버그하려는 개발자를 지원합니다. 이 문서에서는 온라인 엔드포인트에서 유추 서버를 사용하는 방법을 알아보세요.

필수 조건

• Python 3.8 이상
• 아나콘다

유추 서버는 Windows 및 Linux 기반 운영 체제에서 실행됩니다.

온라인 엔드포인트에 대한 로컬 디버깅 옵션 탐색

클라우드에 배포하기 전에 엔드포인트를 로컬로 디버깅하면 코드 및 구성에서 오류를 초기에 catch할 수 있습니다. 엔드포인트를 로컬로 디버깅하려면 다음을 포함한 여러 옵션이 있습니다.

• Azure Machine Learning 유추 HTTP 서버입니다.
• 로컬 엔드포인트입니다.

다음 표에서는 각 옵션이 다양한 디버깅 시나리오에 대해 제공하는 지원에 대한 개요를 제공합니다.

이 문서에서는 유추 서버를 사용하는 방법을 설명합니다.

유추 서버를 로컬로 실행하는 경우 배포 컨테이너 구성에 대한 우려 없이 점수 매기기 스크립트를 디버깅하는 데 집중할 수 있습니다.

로컬로 채점 스크립트 디버그

점수 매기기 스크립트를 로컬로 디버그하려면 유추 서버 동작을 테스트하기 위한 몇 가지 옵션이 있습니다.

• 점수 계산 더미 스크립트를 사용합니다.
• VS Code를 사용하여 azureml-inference-server-http 패키지로 디버그합니다.
• 예제 리포지토리에서 실제 채점 스크립트, 모델 파일 및 환경 파일을 실행합니다.

다음 섹션에서는 각 옵션에 대한 정보를 제공합니다.

더미 점수 매기기 스크립트를 사용하여 유추 서버 동작 테스트

1. 파일을 저장할 server_quickstart 디렉터리를 만듭니다.

   mkdir server_quickstart
   cd server_quickstart
   

2. 패키지 충돌을 방지하려면 다음과 같은 myenv가상 환경을 만들고 활성화합니다.

   python -m virtualenv myenv
   

   참고 항목

   Linux에서는 source myenv/bin/activate 명령을 실행하여 가상 환경을 활성화합니다.

   유추 서버를 테스트한 후 명령을 실행 deactivate 하여 Python 가상 환경을 비활성화할 수 있습니다.

3. azureml-inference-server-http PyPI(Python 패키지 인덱스) 피드에서 패키지를 설치합니다.

   python -m pip install azureml-inference-server-http
   

4. 항목 스크립트를 만듭니다. 다음 예제에서는 기본 항목 스크립트를 만들고 score.py 파일에 저장합니다.

   echo -e 'import time\ndef init(): \n\ttime.sleep(1) \n\ndef run(input_data): \n\treturn {"message":"Hello, World!"}' > score.py
   

5. 명령을 azmlinfsrv 사용하여 유추 서버를 시작하고 score.py 파일을 항목 스크립트로 설정합니다.

   azmlinfsrv --entry_script score.py
   

   참고 항목

   유추 서버는 0.0.0.0에서 호스트됩니다. 즉, 호스팅 컴퓨터의 모든 IP 주소를 수신 대기합니다.

6. 유틸리티를 curl 사용하여 추론 서버에 점수 매기기 요청을 보냅니다.

   curl -p 127.0.0.1:5001/score
   

   유추 서버는 다음 응답을 게시합니다.

   {"message": "Hello, World!"}
   

7. 테스트를 마치면 Ctrl+C 를 선택하여 유추 서버를 중지합니다.

score.py 채점 스크립트 파일을 수정할 수 있습니다. 그런 다음 명령을 사용하여 azmlinfsrv --entry_script score.py 유추 서버를 다시 실행하여 변경 내용을 테스트할 수 있습니다.

VS Code와 통합

VS Code에서는 azureml-inference-server-http 패키지로 디버깅을 위해 Python 확장을 사용할 수 있습니다. VS Code는 디버깅을 위한 두 가지 모드인 시작 및 연결을 제공합니다.

두 모드 중 하나를 사용하기 전에 다음 명령을 실행하여 패키지를 설치 azureml-inference-server-http 합니다.

python -m pip install azureml-inference-server-http

시작 모드

시작 모드의 경우 다음 단계를 수행하여 VS Code launch.json 구성 파일을 설정하고 VS Code 내에서 유추 서버를 시작합니다.

1. VS Code를 시작하고 score.py 스크립트가 포함된 폴더를 엽니다.

2. VS Code의 해당 작업 영역에 대해 launch.json 파일에 다음 구성을 추가합니다.

   {
       "version": "0.2.0",
       "configurations": [
           {
               "name": "Debug score.py",
               "type": "debugpy",
               "request": "launch",
               "module": "azureml_inference_server_http.amlserver",
               "args": [
                   "--entry_script",
                   "score.py"
               ]
           }
       ]
     }
   

3. VS Code에서 실행>디버깅 시작을 선택하거나 F5 키를 눌러 디버깅 세션을 시작합니다.

연결 모드

연결 모드의 경우 Python 확장과 함께 VS Code를 사용하여 유추 서버 프로세스에 연결하려면 다음 단계를 수행합니다.

1. VS Code를 시작하고 score.py 스크립트가 포함된 폴더를 엽니다.

2. VS Code의 해당 작업 영역에 대해 launch.json 파일에 다음 구성을 추가합니다.

   {
       "version": "0.2.0",
       "configurations": [
           {
               "name": "Python: Attach using Process ID",
               "type": "debugpy",
               "request": "attach",
               "processId": "${command:pickProcess}",
               "justMyCode": true
           }
       ]
     }
   

3. 명령 창에서 명령을 실행하여 유추 서버를 시작합니다 azmlinfsrv --entry_script score.py .

4. VS Code에서 디버깅 세션을 시작하려면 다음 단계를 수행합니다.

   1. 실행>시작 디버깅을 선택하거나 F5 키를 선택합니다.

   2. 명령 창에서 유추 서버에서 로그를 검색하여 프로세스의 프로세스 ID를 azmlinfsrv 찾습니다.

      

      azmlinfsrv 프로세스의 ID를 찾아야 하며, gunicorn 프로세스의 ID는 찾으면 안 됩니다.

   3. VS Code 디버거에서 프로세스의 ID를 입력합니다 azmlinfsrv .

      VS Code 프로세스 선택기가 표시되지 않으면 작업 영역에 대한 launch.json 파일 필드에 프로세스 ID processId 를 수동으로 입력합니다.

시작 및 연결 모드의 경우 중단점을 설정하고 스크립트를 단계별로 디버그할 수 있습니다.

엔드투엔드 예 사용

다음 절차에서는 Azure Machine Learning 예제 리포지토리의 샘플 파일을 사용하여 유추 서버를 로컬로 실행합니다. 샘플 파일에는 채점 스크립트, 모델 파일 및 환경 파일이 포함됩니다. 이러한 샘플 파일을 사용하는 방법에 대한 자세한 내용은 온라인 엔드포인트를 사용하여 기계 학습 모델 배포 및 점수 매기기를 참조하세요.

1. 샘플 리포지토리를 복제하고 관련 샘플 파일이 포함된 폴더로 이동합니다.

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

2. conda를 사용하여 가상 환경을 만들고 활성화합니다.

   이 예에서는 azureml-inference-server-http 패키지가 자동으로 설치됩니다. 패키지는 conda.yaml 파일에 나열된 패키지의 azureml-defaults 종속 라이브러리로 포함됩니다.

   # Create the environment from the YAML file.
   conda env create --name model-env -f ./environment/conda.yaml
   # Activate the new environment.
   conda activate model-env
   

3. 점수 매기기 스크립트, 온라인 점수 매기기/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()
   

4. 점수 매기기 스크립트와 모델 폴더의 경로를 지정하여 유추 서버를 실행합니다.

   배포하는 동안 AZUREML_MODEL_DIR 변수가 모델 폴더의 경로를 저장하도록 정의합니다. 매개 변수에 해당 값을 지정합니다 model_dir . 점수 매기기 스크립트가 실행되면 변수에서 AZUREML_MODEL_DIR 값을 검색합니다.

   이 경우 점수 매기기 스크립트가 하위 디렉터리를 ./model_dir 로 지정하기 때문에 현재 디렉터리를 값으로 model/sklearn_regression_model.pkl사용합니다.

   azmlinfsrv --entry_script ./onlinescoring/score.py --model_dir ./
   

   유추 서버가 시작되고 점수 매기기 스크립트를 성공적으로 호출하면 예제 시작 로그 가 열립니다. 그렇지 않으면 로그에 오류 메시지가 표시됩니다.

5. 다음 단계를 수행하여 샘플 데이터로 점수 매기기 스크립트를 테스트합니다.

   1. 다른 명령 창을 열고 명령을 실행한 것과 동일한 작업 디렉터리로 azmlinfsrv 이동합니다.

   2. 다음 curl 유틸리티를 사용하여 예제 요청을 유추 서버로 보내고 점수 매기기 결과를 받습니다.

      curl --request POST "127.0.0.1:5001/score" --header "Content-Type:application/json" --data @sample-request.json
      

      채점 스크립트에 문제가 없으면 스크립트는 채점 결과를 반환합니다. 문제가 발생하면 점수 매기기 스크립트를 업데이트한 다음 유추 서버를 다시 시작하여 업데이트된 스크립트를 테스트할 수 있습니다.

유추 서버 경로 검토

유추 서버는 기본적으로 다음 경로에서 포트 5001에서 수신 대기합니다.

유추 서버 매개 변수 검토

유추 서버는 다음 매개 변수를 허용합니다.

추론 서버 요청 처리 탐구

다음 단계에서는 유추 서버 azmlinfsrv가 들어오는 요청을 처리하는 방법을 보여 줍니다.

1. Python CLI 래퍼는 유추 서버의 네트워크 스택 주위에 있으며 유추 서버를 시작하는 데 사용됩니다.

2. 클라이언트는 유추 서버에 요청을 보냅니다.

3. 유추 서버는 WSGI(웹 서버 게이트웨이 인터페이스) 서버를 통해 요청을 전송하며, 이 서버는 다음 Flask 작업자 애플리케이션 중 하나에 요청을 디스패치합니다.

   • Windows에서: 웨이트리스 실행
   • Linux: gunicorn

4. Flask ​​작업자 앱은 항목 스크립트와 모든 종속성을 로드하는 것을 포함한 요청을 처리합니다.

5. 사용자의 항목 스크립트가 요청을 수신합니다. 항목 스크립트는 로드된 모델에 대한 유추 호출을 수행하고 응답을 반환합니다.

유추 서버 로그 탐색

유추 서버 테스트에 대한 로그 데이터를 가져오는 방법에는 두 가지가 있습니다.

• 패키지를 로컬로 azureml-inference-server-http 실행하고 로그 출력을 봅니다.
• 온라인 엔드포인트를 사용하고 컨테이너 로그를 확인합니다. 유추 서버의 로그 이름은 Azure Machine Learning 유추 HTTP 서버 <버전>입니다.

시작 로그 보기

유추 서버가 시작되면 로그에 다음과 같은 초기 서버 설정이 표시됩니다.

Azure ML Inferencing HTTP server <version>


Server Settings
---------------
Entry Script Name: <entry-script>
Model Directory: <model-directory>
Config File: <configuration-file>
Worker Count: <worker-count>
Worker Timeout (seconds): None
Server Port: <port>
Health Port: <port>
Application Insights Enabled: false
Application Insights Key: <Application-Insights-instrumentation-key>
Inferencing HTTP server version: azmlinfsrv/<version>
CORS for the specified origins: <access-control-allow-origins>
Create dedicated endpoint for health: <health-check-endpoint>


Server Routes
---------------
Liveness Probe: GET   127.0.0.1:<port>/
Score:          POST  127.0.0.1:<port>/score

<logs>

예를 들어 엔드 투 엔드 예제 단계를 수행하여 유추 서버를 실행하는 경우 로그에는 다음 정보가 포함됩니다.

Azure ML Inferencing HTTP server v1.2.2


Server Settings
---------------
Entry Script Name: /home/user-name/azureml-examples/cli/endpoints/online/model-1/onlinescoring/score.py
Model Directory: ./
Config File: None
Worker Count: 1
Worker Timeout (seconds): None
Server Port: 5001
Health Port: 5001
Application Insights Enabled: false
Application Insights Key: None
Inferencing HTTP server version: azmlinfsrv/1.2.2
CORS for the specified origins: None
Create dedicated endpoint for health: None

Server Routes
---------------
Liveness Probe: GET   127.0.0.1:5001/
Score:          POST  127.0.0.1:5001/score

2022-12-24 07:37:53,318 I [32726] gunicorn.error - Starting gunicorn 20.1.0
2022-12-24 07:37:53,319 I [32726] gunicorn.error - Listening at: http://0.0.0.0:5001 (32726)
2022-12-24 07:37:53,319 I [32726] gunicorn.error - Using worker: sync
2022-12-24 07:37:53,322 I [32756] gunicorn.error - Booting worker with pid: 32756
Initializing logger
2022-12-24 07:37:53,779 I [32756] azmlinfsrv - Starting up app insights client
2022-12-24 07:37:54,518 I [32756] azmlinfsrv.user_script - Found user script at /home/user-name/azureml-examples/cli/endpoints/online/model-1/onlinescoring/score.py
2022-12-24 07:37:54,518 I [32756] azmlinfsrv.user_script - run() is not decorated. Server will invoke it with the input in JSON string.
2022-12-24 07:37:54,518 I [32756] azmlinfsrv.user_script - Invoking user's init function
2022-12-24 07:37:55,974 I [32756] azmlinfsrv.user_script - Users's init has completed successfully
2022-12-24 07:37:55,976 I [32756] azmlinfsrv.swagger - Swaggers are prepared for the following versions: [2, 3, 3.1].
2022-12-24 07:37:55,976 I [32756] azmlinfsrv - Scoring timeout is set to 3600000
2022-12-24 07:37:55,976 I [32756] azmlinfsrv - Worker with pid 32756 ready for serving traffic

로그 데이터 서식 이해

시작 관리자 스크립트를 제외한 유추 서버의 모든 로그는 다음 형식으로 데이터를 제공합니다.

<UTC-time> <level> [<process-ID>] <logger-name> - <message>

각 항목은 다음 구성 요소로 구성됩니다.

• <UTC-time>: 로그에 항목을 입력한 시간입니다.
• <level>: 항목에 대한 로깅 수준의 첫 번째 문자(예: E ERROR, I INFO 등)
• <process-ID>: 항목과 연결된 프로세스의 ID입니다.
• <logger-name>: 로그 항목과 연결된 리소스의 이름입니다.
• <message>: 로그 메시지의 내용

Python에는 6가지 수준의 로깅이 있습니다. 각 수준에는 심각도에 따라 할당된 숫자 값이 있습니다.

유추 서버 문제 해결

다음 섹션에서는 유추 서버에 대한 기본 문제 해결 팁을 제공합니다. 온라인 엔드포인트 문제를 해결하려면 온라인 엔드포인트 배포 및 점수 매기기 문제를 참조하세요.

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

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

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

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

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

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

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

유추 서버 버전 확인

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

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

패키지 종속성 확인

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

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

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

유추 서버 시작 중 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 패키지를 사용하는 경우, 이미지 빌드 버전이 c0 버전 이상인지 확인하십시오.

  컨테이너 로그에서 이미지 버전을 찾을 수 있습니다. 예를 들어 다음 로그 문을 참조하세요.

  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 표기 뒤에 나타납니다. 앞의 예제에서 이미지 버전은 2022년 7월 8일입니다 20220708. 이 예제의 이미지는 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 발생

추론 서버를 시작하는 동안 ImportError 또는 ModuleNotFoundError가 특정 모듈(예: opencensus, jinja2, markupsafe 또는 click)에서 발생할 수 있습니다. 다음 예제에서는 오류 메시지를 보여 줍니다.

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

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

관련 콘텐츠

• 온라인 엔드포인트를 사용하여 기계 학습 모델 배포 및 점수 매기기
• 유추를 위해 미리 빌드된 Docker 이미지