CLI を使用したリアルタイム推論のためにフローをオンライン エンドポイントにデプロイする

この記事では、Azure Machine Learning v2 CLI を使用したリアルタイム推論で使用するために、 マネージド オンライン エンドポイントまたは Kubernetes オンライン エンドポイント にフローをデプロイする方法について説明します。

開始する前に、フローが適切にテストされ、本番環境にデプロイする準備ができていることを確認してください。 フローのテストの詳細については、フローのテストを参照してください。 フローのテスト後、マネージド オンライン エンドポイントとデプロイを作成する方法と、リアルタイム推論にエンドポイントを使用する方法について説明します。

• この記事では、CLI エクスペリエンスの使用方法について説明します。
• この記事では、Python SDK については取り上げません。 代わりに GitHub サンプル ノートブックを参照してください。 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 ロールベースのアクセス制御 (Azure RBAC) は、Azure Machine Learning の操作に対するアクセスを許可するために使用されます。 この記事の手順を実行するには、ユーザー アカウントに、Azure Machine Learning ワークスペースの所有者か共同作成者ロール、または "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/" を許可するカスタム ロールを割り当てる必要があります。 スタジオを使ってオンライン エンドポイントやデプロイを作成または管理する場合は、リソース グループ所有者から追加のアクセス許可 "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 のクォータを確保して、エラーが発生しないようにする必要があります。 たとえば、デプロイで Standard_DS3_v2 VM (4 コアを搭載) の 10 個のインスタンスを要求する場合は、使用可能な 48 コア (12 インスタンス 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 を指定する必要もあります。 Client ID は、Azure portal のマネージド ID の Overview にあります。

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

これを curl などの HTTP クライアントで呼び出すこともできます。

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":  []}'

エンドポイント キーとエンドポイント URI は、[エンドポイント]>[使用]>[基本消費量に関する情報] で Azure Machine Learning ワークスペースから取得できます。

詳細な構成

フロー開発とは異なる接続を使用してデプロイする

デプロイ中にフローの接続をオーバーライドできます。

たとえば、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

デプロイのコンカレンシーを構成する

オンライン デプロイにフローをデプロイする場合、コンカレンシーのために構成する環境変数が 2 つあります。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: このパラメーターを使うと、1 つのコンテナー内で開始されるワーカー (プロセス) 数を決定できます。 既定値は CPU コア数と等しく、最大値は CPU コア数の 2 倍です。

• PROMPTFLOW_WORKER_THREADS: このパラメーターを使うと、1 つのワーカーで開始されるスレッド数を決定できます。 既定値は 1です。

  Note

  PROMPTFLOW_WORKER_THREADS を 1 より大きい値に設定する場合は、フロー コードがスレッドセーフであることを確認します。

• max_concurrent_requests_per_instance: デプロイで許容するインスタンスごとの同時要求の最大数。 既定値は 10 です。

  max_concurrent_requests_per_instance の推奨値は要求時間によって変わります。

  • 要求時間が 200 ms を超える場合は、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 に設定します。 こうすると、一部の要求をサーバー側でキューに格納できるので、総スループットが向上します。
  • リージョンをまたがる要求を送信している場合は、しきい値を 200 ms から 1 s に変更できます。

上記のパラメーターを調整するときは、最適なパフォーマンスと安定性を確保するために次のメトリックを監視する必要があります。

• このデプロイのインスタンスの CPU/メモリ使用率
• 200 以外の応答 (4xx、5xx)
  • 429 応答を受け取った場合、これは通常、上記のガイドに従ってコンカレンシー設定を再調整するか、デプロイをスケーリングする必要があることを意味します。
• Azure OpenAI のスロットルの状態

エンドポイントを監視する

一般的なメトリックを収集する

オンライン デプロイの一般的なメトリック (要求数、要求の待機時間、ネットワーク バイト、CPU/GPU/ディスク/メモリ使用率など) を表示できます。

推論時にトレース データとシステム メトリックを収集する

また、デプロイ yaml ファイルにプロパティ app_insights_enabled: true を追加することで、ワークスペースにリンクされた Application Insights に対する推論時に、トレース データとプロンプト フロー デプロイ固有のメトリック (トークンの消費量、フローの待機時間など) を収集することもできます。 詳細については、トレースとプロンプト フロー デプロイのメトリックに関するセクションを参照してください。

プロンプト フロー固有のメトリックとトレースは、他の Application Insights (ワークスペースにリンクされたもの以外) に指定できます。 次のように、デプロイ yaml ファイルで環境変数を指定できます。 Application Insights の接続文字列は、Azure portal の [概要] ページで確認できます。

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 Service など、他のプラットフォームへのフローのデプロイの詳細について説明します。