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

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

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

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

필수 구성 요소

• 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개 인스턴스 4개 코어)에 대한 할당량을 사용할 수 있어야 합니다. 사용량 및 요청 할당량 증가를 보려면 Azure Portal에서 사용량 및 할당량 보기 참조하세요.

배포를 위한 흐름 준비

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

이 문서에서는 Azure Machine Learning 관리되는 온라인 엔드포인트에 배포하는 예로 샘플 흐름 "기본 채팅"을 사용합니다.

기본 작업 영역 설정

다음 명령을 사용하여 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 포털에서 관리 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

다음과 같은 curlHTTP 클라이언트를 사용하여 엔드포인트를 호출할 수도 있습니다.

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 작업 영역의 Endpoints>Consume>Basic consumption info에서 엔드포인트 키와 엔드포인트 URI를 가져옵니다.

고급 구성

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

배포할 때 흐름의 연결을 재정의하는 것을 고려해 볼 수 있습니다.

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

옵션 1: 연결 이름 재정의

environment_variables:
  my_connection: <override_connection_name>

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

옵션 2: 자산을 참조하여 덮어쓰기

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

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

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

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 기반 서비스 엔진이 지원됩니다. 환경 변수fastapi를 PROMPTFLOW_SERVING_ENGINE 지정하여 서비스 엔진을 사용할 수 있습니다.

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 코어 수의 두 배입니다.

• 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로 설정합니다.
  • 요청 시간이 200 ms 이하인 경우, max_concurrent_requests_per_instance를 (1.5-2) * PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS로 설정합니다. 이 설정은 일부 요청이 서버 쪽에서 큐에 대기하도록 허용하여 총 처리량을 향상시킬 수 있습니다.
  • 지역 간 요청을 보내는 경우 임계값을 200ms에서 1초로 변경할 수 있습니다.

이러한 매개 변수를 조정하는 동안 다음 메트릭을 모니터링하여 최적의 성능과 안정성을 보장합니다.

• 이 배포에 대한 인스턴스 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 5,000밀리초입니다. 최대 5분( 300,000밀리초)까지 설정할 수 있습니다. 다음 예제에서는 배포 YAML 파일에서 요청 시간 제한을 지정하는 방법을 보여줍니다. 배포 스키마에 대한 자세한 내용은 관리되는 온라인 배포 스키마를 참조하세요.

request_settings:
  request_timeout_ms: 300000

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

다음 단계

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