CLI를 사용하여 실시간 유추를 위해 온라인 엔드포인트에 흐름 배포

이 문서에서는 Azure Machine Learning v2 CLI를 활용하여 실시간 추론에 사용하기 위해 관리형 온라인 엔드포인트 또는 Kubernetes 온라인 엔드포인트에 흐름을 배포하는 방법을 알아봅니다.

시작하기 전에 흐름을 제대로 테스트하여 프로덕션에 배포할 준비가 되었음을 확신할 수 있어야 합니다. 흐름 테스트에 대한 자세한 내용은 흐름 테스트를 참조하세요. 흐름을 테스트한 후에는 관리형 온라인 엔드포인트 및 배포를 만드는 방법과 실시간 추론을 위해 엔드포인트를 사용하는 방법을 알아봅니다.

• 이 문서에서는 CLI 환경을 사용하는 방법을 설명합니다.
• Python SDK는 이 문서에서 다루지 않습니다. 대신 GitHub 샘플 Notebook을 참조하세요. Python SDK를 사용하려면 Azure Machine Learning용 Python SDK v2가 있어야 합니다. 자세한 내용은 Azure Machine Learning용 Python SDK v2 설치를 참조하세요.

필수 조건

• Azure CLI 및 Azure CLI에 대한 Azure Machine Learning 확장. 자세한 내용은 CLI(v2) 설치, 설정 및 사용을 참조하세요.
• Azure Machine Learning 작업 영역 리소스가 없으면 빠른 시작: 작업 영역 리소스 만들기 문서의 단계에서 리소스를 만듭니다.
• Azure RBAC(Azure 역할 기반 액세스 제어)는 Azure Machine Learning의 작업에 대한 액세스 권한을 부여하는 데 사용됩니다. 이 문서의 단계를 수행하려면 사용자 계정에 Azure Machine Learning 작업 영역에 대한 소유자 또는 기여자 역할 또는 "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/"를 허용하는 사용자 지정 역할이 할당되어야 합니다. Studio를 사용하여 온라인 엔드포인트/배포를 만들기/관리하는 경우 리소스 그룹 소유자로부터 "Microsoft.Resources/deployments/write" 권한이 추가로 필요합니다. 자세한 내용은 Azure Machine Learning 작업 영역 액세스 관리를 참조하세요.

배포를 위한 가상 머신 할당량 할당

관리형 온라인 엔드포인트의 경우 Azure Machine Learning은 업그레이드를 수행하기 위해 컴퓨팅 리소스의 20%를 예약합니다. 따라서 배포에서 지정된 수의 인스턴스를 요청하는 경우 오류가 발생하지 않도록 사용할 수 있는 ceil(1.2 * number of instances requested for deployment) * number of cores for the VM SKU 할당량이 있어야 합니다. 예를 들어 배포에서 10개의 Standard_DS3_v2 VM 인스턴스(4개 코어 탑재)를 요청하는 경우 48개 코어(12개 인스턴스 x 4개 코어)에 대한 할당량을 사용할 수 있어야 합니다. 사용량을 확인하고 할당량 증가를 요청하려면 Azure Portal에서 사용량 및 할당량 보기를 참조하세요.

배포를 위한 흐름 준비

각 흐름에는 흐름의 코드/프롬프트, 정의 및 기타 아티팩트가 포함된 폴더가 있습니다. UI를 사용하여 흐름을 개발한 경우 흐름 세부 정보 페이지에서 흐름 폴더를 다운로드할 수 있습니다. CLI 또는 SDK를 사용하여 흐름을 개발한 경우 흐름 폴더가 이미 있습니다.

이 문서에서는 Azure Machine Learning 관리형 온라인 엔드포인트에 배포하는 예제로 샘플 흐름 "basic-chat"을 사용합니다.

기본 작업 영역 설정

다음 명령을 사용하여 CLI에 대한 기본 작업 영역 및 리소스 그룹을 설정합니다.

az account set --subscription <subscription ID>
az configure --defaults workspace=<Azure Machine Learning workspace name> group=<resource group>

흐름을 모델로 등록(선택 사항)

온라인 배포에서 등록된 모델을 참조하거나 모델 경로(모델 파일을 업로드할 위치)를 인라인으로 지정할 수 있습니다. 모델을 등록하고 배포 정의에 모델 이름 및 버전을 지정하는 것이 좋습니다. 양식 model:<model_name>:<version>을 사용합니다.

다음은 채팅 흐름에 대한 모델 정의 예제입니다.

$schema: https://azuremlschemas.azureedge.net/latest/model.schema.json
name: basic-chat-model
path: ../../../../examples/flows/chat/basic-chat
description: register basic chat flow folder as a custom model
properties:
  # In AuzreML studio UI, endpoint detail UI Test tab needs this property to know it's from prompt flow
  azureml.promptflow.source_flow_id: basic-chat
  
  # Following are properties only for chat flow 
  # endpoint detail UI Test tab needs this property to know it's a chat flow
  azureml.promptflow.mode: chat
  # endpoint detail UI Test tab needs this property to know which is the input column for chat flow
  azureml.promptflow.chat_input: question
  # endpoint detail UI Test tab needs this property to know which is the output column for chat flow
  azureml.promptflow.chat_output: answer

az ml model create --file model.yaml을 사용하여 모델을 작업 영역에 등록합니다.

엔드포인트 정의

엔드포인트를 정의하려면 다음을 지정해야 합니다.

• 엔드포인트 이름: 엔드포인트의 이름입니다. Azure 지역에서 고유해야 합니다. 명명 규칙에 대한 자세한 내용은 엔드포인트 제한을 참조하세요.
• 인증 모드: 엔드포인트에 대한 인증 방법입니다. 키 기반 인증과 Azure Machine Learning 토큰 기반 인증 중에서 선택합니다. 키는 만료되지 않지만 토큰은 만료됩니다. 인증에 대한 자세한 내용은 온라인 엔드포인트에 대한 인증을 참조하세요. 필요에 따라 엔드포인트에 설명과 태그를 추가할 수 있습니다.
• 필요에 따라 엔드포인트에 설명과 태그를 추가할 수 있습니다.
• 작업 영역에 연결하는 Kubernetes 클러스터(AKS 또는 Arc 지원 클러스터)에 배포하려는 경우 흐름을 Kubernetes 온라인 엔드포인트에 배포할 수 있습니다.

다음은 기본적으로 시스템 할당 ID를 사용하는 엔드포인트 정의 예제입니다.

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: basic-chat-endpoint
auth_mode: key
properties:
# this property only works for system-assigned identity.
# if the deploy user has access to connection secrets, 
# the endpoint system-assigned identity will be auto-assigned connection secrets reader role as well
  enforce_access_to_default_secret_stores: enabled

$schema: https://azuremlschemas.azureedge.net/latest/kubernetesOnlineEndpoint.schema.json
name: basic-chat-endpoint
compute: azureml:<Kubernetes compute name>
auth_mode: key

Kubernetes 온라인 엔드포인트를 만드는 경우 다음 추가 특성을 지정해야 합니다.

엔드포인트에 대한 자세한 구성은 관리형 온라인 엔드포인트 스키마를 참조하세요.

사용자 할당 ID 사용

기본적으로 온라인 엔드포인트를 만들 때 시스템 할당 관리 ID가 자동으로 생성됩니다. 엔드포인트에 대한 기존의 사용자 할당 관리 ID를 지정할 수도 있습니다.

사용자 할당 ID를 사용하려면 endpoint.yaml에서 다음 추가 특성을 지정할 수 있습니다.

identity:
  type: user_assigned
  user_assigned_identities:
    - resource_id: user_identity_ARM_id_place_holder

또한 다음과 같이 deployment.yaml의 environment_variables 아래에 사용자 할당 ID의 Client ID를 지정해야 합니다. Azure Portal 관리 ID의 Overview에서 Client ID를 찾을 수 있습니다.

environment_variables:
  AZURE_CLIENT_ID: <client_id_of_your_user_assigned_identity>

배포 정의

배포는 실제 유추를 수행하는 모델을 호스팅하는 데 필요한 리소스의 세트입니다.

다음은 model 섹션이 등록된 흐름 모델을 참조하는 배포 정의 예입니다. 흐름 모델 경로를 라인으로 지정할 수도 있습니다.

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: basic-chat-endpoint
model: azureml:basic-chat-model:1
  # You can also specify model files path inline
  # path: examples/flows/chat/basic-chat
environment: 
  image: mcr.microsoft.com/azureml/promptflow/promptflow-runtime:latest
  # inference config is used to build a serving container for online deployments
  inference_config:
    liveness_route:
      path: /health
      port: 8080
    readiness_route:
      path: /health
      port: 8080
    scoring_route:
      path: /score
      port: 8080
instance_type: Standard_E16s_v3
instance_count: 1
environment_variables:
  # for pulling connections from workspace
  PRT_CONFIG_OVERRIDE: deployment.subscription_id=<subscription_id>,deployment.resource_group=<resource_group>,deployment.workspace_name=<workspace_name>,deployment.endpoint_name=<endpoint_name>,deployment.deployment_name=<deployment_name>

  # (Optional) When there are multiple fields in the response, using this env variable will filter the fields to expose in the response.
  # For example, if there are 2 flow outputs: "answer", "context", and I only want to have "answer" in the endpoint response, I can set this env variable to '["answer"]'.
  # If you don't set this environment, by default all flow outputs will be included in the endpoint response.
  # PROMPTFLOW_RESPONSE_INCLUDED_FIELDS: '["category", "evidence"]'

$schema: https://azuremlschemas.azureedge.net/latest/kubernetesOnlineDeployment.schema.json
name: blue
type: kubernetes
endpoint_name: basic-chat-endpoint
model: azureml:basic-chat-model:1
  # You can also specify model files path inline
  # path: examples/flows/chat/basic-chat
environment: 
  image: mcr.microsoft.com/azureml/promptflow/promptflow-runtime:latest
  # inference config is used to build a serving container for online deployments
  inference_config:
    liveness_route:
      path: /health
      port: 8080
    readiness_route:
      path: /health
      port: 8080
    scoring_route:
      path: /score
      port: 8080
instance_type: <kubernetes custom instance type>
instance_count: 1
environment_variables:

  # for pulling connections from workspace
  PRT_CONFIG_OVERRIDE: deployment.subscription_id=<subscription_id>,deployment.resource_group=<resource_group>,deployment.workspace_name=<workspace_name>,deployment.endpoint_name=<endpoint_name>,deployment.deployment_name=<deployment_name>

  # (Optional) When there are multiple fields in the response, using this env variable will filter the fields to expose in the response.
  # For example, if there are 2 flow outputs: "answer", "context", and I only want to have "answer" in the endpoint response, I can set this env variable to '["answer"]'.
  # If you don't set this environment, by default all flow outputs will be included in the endpoint response.
  # PROMPTFLOW_RESPONSE_INCLUDED_FIELDS: '["category", "evidence"]'

Kubernetes 온라인 배포를 만드는 경우 다음 추가 특성을 지정해야 합니다.

Azure에 온라인 엔드포인트 배포

클라우드에서 엔드포인트를 만들려면 다음 코드를 실행합니다.

az ml online-endpoint create --file endpoint.yml

엔드포인트 아래에 blue라는 배포를 만들려면 다음 코드를 실행합니다.

az ml online-deployment create --file blue-deployment.yml --all-traffic

엔드포인트 및 배포 상태 확인

엔드포인트의 상태를 확인하려면 다음 코드를 실행합니다.

az ml online-endpoint show -n basic-chat-endpoint

배포 상태를 확인하려면 다음 코드를 실행합니다.

az ml online-deployment get-logs --name blue --endpoint basic-chat-endpoint

엔드포인트를 호출하여 모델을 사용하여 데이터 채점

다음과 같이 sample-request.json 파일을 만들 수 있습니다.

{
  "question": "What is Azure Machine Learning?",
  "chat_history":  []
}

az ml online-endpoint invoke --name basic-chat-endpoint --request-file sample-request.json

HTTP 클라이언트를 사용하여 호출할 수도 있습니다(예: curl 사용).

ENDPOINT_KEY=<your-endpoint-key>
ENDPOINT_URI=<your-endpoint-uri>

curl --request POST "$ENDPOINT_URI" --header "Authorization: Bearer $ENDPOINT_KEY" --header 'Content-Type: application/json' --data '{"question": "What is Azure Machine Learning?", "chat_history":  []}'

Azure Machine Learning 작업 영역에서 엔드포인트 키 및 엔드포인트 URI를 가져올 수 있습니다(엔드포인트>사용>기본 사용 정보).

고급 구성

흐름 개발과 다른 연결을 사용하여 배포

배포하는 동안 흐름의 연결을 재정의할 수 있습니다.

예를 들어 flow.dag.yaml 파일이 my_connection 연결을 사용하는 경우 다음과 같이 배포 yaml의 환경 변수를 추가하여 재정의할 수 있습니다.

옵션 1: 연결 이름 재정의

environment_variables:
  my_connection: <override_connection_name>

연결의 특정 필드를 재정의하려면 명명 패턴 <connection_name>_<field_name>으로 환경 변수를 추가하여 재정의할 수 있습니다. 예를 들어, 흐름이 chat_deployment_name이라는 구성 키로 my_connection이라는 연결을 사용하는 경우 제공 백 엔드는 기본적으로 환경 변수 'MY_CONNECTION_CHAT_DEPLOYMENT_NAME'에서 chat_deployment_name을 검색하려고 합니다. 환경 변수가 설정되지 않은 경우 흐름 정의의 원래 값을 사용합니다.

옵션 2: 자산을 참조하여 재정의

environment_variables:
  my_connection: ${{azureml://connections/<override_connection_name>}}

사용자 지정 환경을 사용하여 배포

이 섹션에서는 Docker 및 Azure Machine Learning 환경에 대한 지식이 있다는 가정 하에 Docker 빌드 컨텍스트를 사용하여 배포 환경을 지정하는 방법을 보여줍니다.

1. 로컬 환경에서 다음 파일이 포함된 image_build_with_reqirements라는 폴더를 만듭니다.

   |--image_build_with_reqirements
   |  |--requirements.txt
   |  |--Dockerfile
   

   • requirements.txt는 흐름의 종속성을 추적하는 데 사용된 흐름 폴더에서 상속되어야 합니다.

   • Dockerfile의 내용은 다음과 같습니다.

     FROM mcr.microsoft.com/azureml/promptflow/promptflow-runtime:latest
     COPY ./requirements.txt .
     RUN pip install -r requirements.txt
     

2. 배포 정의 yaml 파일의 환경 섹션을 다음 내용으로 바꿉니다.

   environment: 
     build:
       path: image_build_with_reqirements
       dockerfile_path: Dockerfile
     # deploy prompt flow is BYOC, so we need to specify the inference config
     inference_config:
       liveness_route:
         path: /health
         port: 8080
       readiness_route:
         path: /health
         port: 8080
       scoring_route:
         path: /score
         port: 8080
   

FastAPI 제공 엔진 사용(미리 보기)

기본적으로 프롬프트 흐름 제공은 FLASK 제공 엔진을 사용합니다. 프롬프트 흐름 SDK 버전 1.10.0부터 FastAPI 기반 제공 엔진을 지원합니다. 환경 변수 PROMPTFLOW_SERVING_ENGINE을 지정하여 fastapi 제공 엔진을 사용할 수 있습니다.

environment_variables:
  PROMPTFLOW_SERVING_ENGINE=fastapi

배포를 위한 동시성 구성

온라인 배포에 흐름을 배포할 때 동시성을 위해 구성하는 두 가지 환경 변수(PROMPTFLOW_WORKER_NUM 및 PROMPTFLOW_WORKER_THREADS)가 있습니다. 게다가 max_concurrent_requests_per_instance 매개 변수도 설정해야 합니다.

다음은 deployment.yaml 파일에서 구성하는 방법의 예입니다.

request_settings:
  max_concurrent_requests_per_instance: 10
environment_variables:
  PROMPTFLOW_WORKER_NUM: 4
  PROMPTFLOW_WORKER_THREADS: 1

• PROMPTFLOW_WORKER_NUM: 이 매개 변수는 하나의 컨테이너에서 시작될 작업자(프로세스) 수를 결정합니다. 기본값은 CPU 코어 수와 동일하며, 최댓값은 CPU 코어 수의 2배입니다.

• PROMPTFLOW_WORKER_THREADS: 이 매개 변수는 하나의 작업자에서 시작될 스레드 수를 결정합니다. 기본값은 1입니다.

  참고 항목

  PROMPTFLOW_WORKER_THREADS를 1보다 큰 값으로 설정하는 경우 흐름 코드가 스레드로부터 안전한지 확인합니다.

• max_concurrent_requests_per_instance: 배포에 허용되는 인스턴스당 최대 동시 요청 수입니다. 기본값은 10입니다.

  max_concurrent_requests_per_instance에 대한 제안 값은 요청 시간에 따라 다릅니다.

  • 요청 시간이 200ms를 초과하는 경우 max_concurrent_requests_per_instance를 PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS로 설정합니다.
  • 요청 시간이 200ms 이하인 경우 max_concurrent_requests_per_instance를 (1.5-2) * PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS로 설정합니다. 이렇게 하면 일부 요청이 서버 쪽에서 큐에 추가되도록 허용하여 총 처리량을 개선할 수 있습니다.
  • 지역 간 요청을 보내는 경우 임계값을 200ms에서 1s로 변경할 수 있습니다.

위의 매개 변수를 튜닝하는 동안 최적의 성능과 안정성을 보장하기 위해 다음 메트릭을 모니터링해야 합니다.

• 이 배포의 인스턴스 CPU/메모리 사용률
• 200개 이외의 응답(4xx, 5xx)
  • 429 응답을 받은 경우 이는 일반적으로 위 가이드에 따라 동시성 설정을 다시 조정하거나 배포의 크기를 조정해야 함을 나타냅니다.
• Azure OpenAI 제한 상태

엔드포인트 모니터링

일반 메트릭 수집

온라인 배포의 일반 메트릭(요청 수, 요청 대기 시간, 네트워크 바이트, CPU/GPU/디스크/메모리 사용률 등)을 볼 수 있습니다.

유추 시간 동안 추적 데이터 및 시스템 메트릭을 수집합니다.

배포 yaml 파일에 속성 app_insights_enabled: true를 추가하여 작업 영역에 연결된 Application Insights에 대한 유추 시간 동안 추적 데이터를 수집하고 흐름 배포 관련 메트릭(토큰 사용량, 흐름 대기 시간 등)을 프롬프트할 수도 있습니다. 프롬프트 흐름 배포의 추적 및 메트릭에 대해 자세히 알아봅니다.

프롬프트 흐름 관련 메트릭 및 추적은 연결된 작업 영역이 아닌 다른 Application Insights에 지정할 수 있습니다. 다음과 같이 배포 yaml 파일에 환경 변수를 지정할 수 있습니다. Azure Portal의 개요 페이지에서 Application Insights의 연결 문자열을 찾을 수 있습니다.

environment_variables:
  APPLICATIONINSIGHTS_CONNECTION_STRING: <connection_string>

일반 오류

엔드포인트를 사용할 때 업스트림 요청 시간 초과 문제

이러한 오류는 일반적으로 시간 제한으로 인해 발생합니다. 기본적으로 request_timeout_ms는 5000입니다. 최대 5분(300,000ms)까지 지정할 수 있습니다. 다음은 배포 yaml 파일에서 요청 시간 초과를 지정하는 방법을 보여 주는 예입니다. 여기에서 배포 스키마에 대해 자세히 알아봅니다.

request_settings:
  request_timeout_ms: 300000

properties:
  # indicate a deployment from prompt flow
  azureml.promptflow.source_flow_id: <value>

다음 단계

• 관리형 온라인 엔드포인트 스키마 및 관리형 온라인 배포 스키마에 대해 자세히 알아봅니다.
• UI에서 엔드포인트를 테스트하는 방법 및 엔드포인트를 모니터링하는 방법에 대해 자세히 알아봅니다.
• 관리형 온라인 엔드포인트 문제를 해결하는 방법에 대해 자세히 알아봅니다.
• 프롬프트 흐름 배포 문제 해결.
• 흐름을 개선하고 안전한 롤아웃 전략으로 향상된 버전을 배포하려면 온라인 엔드포인트에 대한 안전한 롤아웃을 참조하세요.
• 로컬 개발 서비스, Docker 컨테이너, Azure APP 서비스 등과 같은 다른 플랫폼에 배포 흐름에 대해 자세히 알아봅니다.