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

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

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

• この記事では、CLI エクスペリエンスの使用方法について説明します。
• Python SDK については、この記事では取り上げません。 代わりに、GitHubサンプル ノートブックを参照してください。 Python SDK を使用するには、Azure Machine Learning用の Python SDK v2 が必要です。 詳細については、「 Azure Machine Learningを参照してください。

前提 条件

• 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 ポータルで使用量とクォータを表示するを参照してください。

フローをデプロイする準備をする

各フローには、フローのコード/プロンプト、定義、およびその他の成果物を含むフォルダーがあります。 UI を使用してフローを開発した場合は、フローの詳細ページからフロー フォルダーをダウンロードできます。 CLI または SDK を使用してフローを開発した場合は、フロー フォルダーが既に存在している必要があります。

この記事では、例としてサンプル フロー "basic-chat"を使用して、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

さらに、次のようにClient IDenvironment_variablesのユーザーに割り当てられた ID のdeployment.yamlを指定する必要もあります。 Client IDは、Azure ポータルのマネージド 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

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

エンドポイント キーとエンドポイント URI は、Endpoints>Consume>Basic consumption info の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 です。

  メモ

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

• max_concurrent_requests_per_instance: デプロイで許可されるインスタンスあたりの同時要求の最大数。 既定値は 10 です。

  max_concurrent_requests_per_instanceの推奨値は、要求時間によって異なります。

  • 要求時間が 200 ミリ秒を超える場合は、 max_concurrent_requests_per_instance を PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS に設定します。
  • 要求時間が 200 ミリ秒以下の場合は、 max_concurrent_requests_per_instance を (1.5-2) * PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS に設定します。 これにより、一部の要求をサーバー側でキューに入れられるようにすることで、合計スループットを向上させることができます。
  • リージョンをまたがる要求を送信する場合は、しきい値を 200 ミリ秒から 1 秒に変更できます。

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

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

エンドポイントの監視

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

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

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

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

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

environment_variables:
  APPLICATIONINSIGHTS_CONNECTION_STRING: <connection_string>

一般的なエラー

エンドポイントを使用するときのアップストリーム要求タイムアウトの問題

このようなエラーは通常、タイムアウトが原因で発生します。 既定では、 request_timeout_ms は 5000 です。 最大 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 サービスなどの他のプラットフォームにフローをデプロイする