リアルタイム推論を行うためにマネージドオンラインエンドポイントとしてフローをデプロイする

[アーティクル]
05/08/2024

適切にフローを構築してテストしたら、リアルタイム推論のためにエンドポイントを呼び出せるように、フローをエンドポイントとしてデプロイすることができます。

この記事では、リアルタイム推論を行うためにフローをマネージドオンラインエンドポイントとしてデプロイする方法について説明します。これを実行する手順は次のとおりです。

フローをテストし、デプロイの準備を整える
オンラインデプロイを作成する
エンドポイントにアクセス許可を付与する
エンドポイントをテストする
エンドポイントを使う

重要

この記事で "(プレビュー)" と付記されている項目は、現在、パブリックプレビュー段階です。プレビューバージョンはサービスレベルアグリーメントなしで提供されています。運用環境のワークロードに使用することはお勧めできません。特定の機能はサポート対象ではなく、機能が制限されることがあります。詳しくは、Microsoft Azure プレビューの追加使用条件に関するページをご覧ください。

前提条件

プロンプトフローでフローを構築してテストする方法を確認します。
マネージドオンラインエンドポイントに関する基本事項を理解している。マネージドオンラインエンドポイントは、Azure の強力な CPU マシンおよび GPU マシンと連携して、スケーラブルでフルマネージドな方法で動作し、基になるデプロイインフラストラクチャの設定と管理のオーバーヘッドからユーザーを解放します。マネージドオンラインエンドポイントの詳細については、「オンラインエンドポイントとリアルタイム推論のデプロイ」を参照してください。
Azure ロールベースのアクセス制御 (Azure RBAC) は、Azure Machine Learning の操作に対するアクセスを許可するために使用されます。プロンプトフローでエンドポイントをデプロイできるようにするには、AzureML データ科学者、または Azure Machine Learning ワークスペースに対してさらに多くの特権を持つロールがユーザーアカウントに割り当てられている必要があります。
マネージド ID の基礎知識を習得します。マネージド ID の詳細を確認してください。

Note

マネージドオンラインエンドポイントがサポートするのは、マネージド仮想ネットワークだけです。ワークスペースがカスタム VNet 内にある場合は、他のデプロイオプション (CLI/SDK を使う Kubernetes オンラインエンドポイントへのデプロイや、Docker などの他のプラットフォームへのデプロイなど) を試す必要があります。

フローを構築し、デプロイの準備を整える

基本のチュートリアルを既に完了している場合は、バッチ実行を送信して結果を評価するというフローのテストは適切に完了しています。

このチュートリアルを完了していない場合は、フローを構築する必要があります。デプロイ前にバッチ実行と評価によってフローを適切にテストすることが推奨されるベストプラクティスです。

例としてサンプルフロー Web 分類を使ってフローのデプロイ方法を説明します。このサンプルフローは標準のフローです。チャットフローのデプロイも同様です。評価フローはデプロイをサポートしていません。

デプロイで使用される環境を定義する

UI でマネージドオンラインエンドポイントにプロンプトフローをデプロイする場合、既定で、デプロイでは、フローの requirements.txt で指定された最新のプロンプトフローイメージと依存関係に基づいて作成された環境が使用されます。 requirements.txt で、必要な追加のパッケージを指定できます。 requirements.txt は、フローフォルダーのルートフォルダーにあります。

Note

Azure DevOps でプライベートフィードを使用している場合は、まずプライベートフィードを使用してイメージをビルドし、UI でデプロイするカスタム環境を選択する必要があります。

オンラインデプロイを作成する

フローを構築し、適切にテストしたら、リアルタイム推論を行うためのオンラインエンドポイントを作成します。

プロンプトフローは、フローまたはバッチ実行からエンドポイントをデプロイすることをサポートします。デプロイ前にフローをテストすることが推奨されるベストプラクティスです。

フローの作成ページまたは実行の詳細ページで [デプロイ] を選びます。

フローの作成ページ:

実行の詳細ページ:

エンドポイントを構成するウィザードが表示されます。次の手順があります。

基本設定

この手順では、デプロイの基本設定を構成できます。

プロパティ	説明
エンドポイント	新しいエンドポイントをデプロイするか、既存のエンドポイントを更新するかを選択できます。 [新規] を選択した場合は、エンドポイント名を指定する必要があります。
デプロイ名	- 同じエンドポイント内では、デプロイ名は一意である必要があります。 - 既存のエンドポイントを選択し、既存のデプロイ名を入力した場合、そのデプロイは新しい構成で上書きされます。
仮想マシン	デプロイに使用する VM サイズ。サポートされているサイズの一覧については、マネージドオンラインエンドポイント SKU の一覧に関するページを参照してください。
インスタンス数	デプロイに使用するインスタンスの数。想定されるワークロードに値を指定します。高可用性を実現するために、この値を少なくとも 3 に設定することをお勧めします。アップグレードを実行するために 20% 余分に予約されています。詳細については、マネージドオンラインエンドポイントのクォータに関する記事を参照してください。
推論データの収集	これを有効にすると、フローの入力と出力が Azure Machine Learning データ資産で自動的に収集され、後で監視するために使用できます。詳細については、生成 AI アプリケーションを監視する方法に関するページを参照してください。

基本設定が完了したら、[確認および作成] を直接選択して作成を完了するか、[次へ] を選択して [詳細設定] を構成できます。

詳細設定 - エンドポイント

エンドポイントに次の設定を指定できます。

認証の種類

エンドポイントの認証方法。キーベースの認証により、有効期限のない主キーとセカンダリキーが提供されます。 Azure Machine Learning トークンベースの認証により、定期的に自動更新されるトークンが提供されます。認証の詳細については、オンラインエンドポイントの認証に関する記事を参照してください。

ID の種類

推論するには、エンドポイントから Azure コンテナーレジストリやワークスペース接続などの Azure リソースにアクセスする必要があります。マネージド ID にアクセス許可を付与することで、Azure リソースにアクセスできるアクセス許可をエンドポイントに付与することができます。

システム割り当て ID はエンドポイントの作成後に自動作成されますが、ユーザー割り当て ID はユーザーが作成します。マネージド ID の詳細を確認してください。

システム割り当て

接続シークレットへのアクセスを実施する (プレビュー) かどうかのオプションがあることがわかります。フローで接続が使用される場合、エンドポイントは推論を実行するために接続にアクセスする必要があります。このオプションは既定で有効になっています。接続シークレット閲覧者アクセス許可がある場合、接続に自動的にアクセスするための Azure Machine Learning ワークスペース接続シークレット閲覧者ロールがエンドポイントに付与されます。このオプションを無効にする場合は、自分でシステム割り当て ID にこのロールを手動で付与するか、管理者に支援を求める必要があります。詳しくは、エンドポイント ID にアクセス許可を付与する方法をご覧ください。

ユーザー割り当て

デプロイの作成中に、Azure では、ワークスペースの Azure Container Registry (ACR) からユーザーコンテナーイメージをプルし、ユーザーモデルとコード成果物をワークスペースストレージアカウントからユーザーコンテナーにマウントしようとします。

ユーザー割り当て ID に関連付けられたエンドポイントを作成した場合、デプロイの作成前に、次のロールがユーザー割り当て ID に付与されている必要があります。そうしないと、デプロイの作成が失敗します。

Scope	ロール	必要な理由
Azure Machine Learning ワークスペース	Azure Machine Learning ワークスペース接続シークレット閲覧者ロールまたは "Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action" を持つカスタマイズされたロール	ワークスペース接続の取得
ワークスペースコンテナーレジストリ	ACR のプル	コンテナーイメージのプル
ワークスペースの既定のストレージ	ストレージ BLOB データ閲覧者	ストレージからのモデルの読み込み
(省略可能) Azure Machine Learning ワークスペース	ワークスペースメトリックライター	エンドポイントをデプロイした後、CPU、GPU、ディスク、メモリ使用率などのエンドポイント関連のメトリックを監視する場合は、このアクセス許可を ID に付与する必要があります。

エンドポイント ID にアクセス許可を付与する方法の詳細なガイダンスについては、「エンドポイントにアクセス許可を付与する」を参照してください。

重要

フローで Microsoft Entra ID ベース認証の接続を使う場合は、システム割り当て ID を使うかユーザー割り当て ID を使うかに関わらず、常にマネージド ID に対して対応するリソースの適切なロールを付与して、マネージド ID がそのリソースに対する API 呼び出しを行えるようにする必要があります。たとえば、Azure OpenAI 接続で Microsoft Entra ID ベースの認証を使う場合は、エンドポイントマネージド ID に対して、対応する Azure OpenAI リソースの Cognitive Services OpenAI ユーザーまたは Cognitive Services OpenAI 共同作成者ロールを付与する必要があります。

詳細設定 - デプロイ

この手順では、タグを除き、デプロイで使用される環境を指定することもできます。

現在のフロー定義の環境を使用する

既定のデプロイでは、flow.dag.yaml で指定されている基本イメージと、requirements.txt で指定されている依存関係に基づいて作成された環境が使われます。

フローの Raw file mode を選ぶと、flow.dag.yaml で基本イメージを指定できます。イメージが指定されていない場合は、最新のプロンプトフローの基本イメージが既定の基本イメージになります。
フローフォルダーのルートフォルダーで requirements.txt を見つけて、その中の依存関係を追加できます。

カスタマイズされた環境を使用する

カスタマイズされた環境を作成して、デプロイに使うこともできます。

Note

カスタム環境は、次の要件を満たす必要があります。

Docker イメージは、プロンプトフローの基本イメージ mcr.microsoft.com/azureml/promptflow/promptflow-runtime-stable:<newest_version> を基にして作成されている必要があります。最新バージョンはこちらで入手できます。
環境の定義には、inference_config が含まれている必要があります。

以下は、カスタマイズされた環境の定義の例です。

$schema: https://azuremlschemas.azureedge.net/latest/environment.schema.json
name: pf-customized-test
build:
  path: ./image_build
  dockerfile_path: Dockerfile
description: promptflow customized runtime
inference_config:
  liveness_route:
    port: 8080
    path: /health
  readiness_route:
    port: 8080
    path: /health
  scoring_route:
    port: 8080
    path: /score

Application Insights 診断 (プレビュー) をオンにすることでトレースを有効にする

これを有効にすると、推論時の (トークン数、フロー待機時間、フロー要求などの) トレースデータとシステムメトリックが、ワークスペースにリンクされた Application Insights へと収集されます。詳細については、「トレースデータとメトリックを提供するプロンプトフロー」を参照してください。

ワークスペースにリンクされたものとは別の Application Insights を指定したい場合は、CLI で構成を行うことができます。

詳細設定 - 出力と接続

この手順では、すべてのフロー出力を表示し、デプロイするエンドポイントの応答に含める出力を指定できます。既定では、すべてのフロー出力が選択されます。

また、推論を実行するときにエンドポイントで使用される接続を指定することもできます。既定では、フローから継承されます。

上記のすべての手順を構成して確認したら、[確認および作成] を選んで作成を完了できます。

Note

エンドポイントの作成、モデルの登録、デプロイの作成など、いくつかのステージが含まれるため、エンドポイントの作成には約 15 分以上かかります。

通知によるデプロイ作成の進行状況は、プロンプトフローのデプロイから始まることを理解できます。

エンドポイントにアクセス許可を付与する

重要

アクセス許可の付与 (ロールの割り当ての追加) は、特定の Azure リソースの所有者のみ有効です。 IT 管理者に支援を求める必要がある場合があります。 デプロイの作成の前に、ユーザー割り当て ID にロールを付与することをお勧めします。付与されたアクセス許可が有効になるまでに 15 分以上かかる場合があります。

以下の手順で、Azure portal UI ですべてのアクセス許可を付与できます。

Azure portal の Azure Machine Learning ワークスペースの概要ページに移動します。
[アクセス制御] を選び、[ロール割り当ての追加] を選びます。
[Azure Machine Learning Workspace Connection Secrets Reader]\(Azure Machine Learning ワークスペース接続シークレット閲覧者\) を選択し、[次へ] に進みます。

Note

Azure Machine Learning ワークスペース接続シークレット閲覧者は、ワークスペース接続を取得するためのアクセス許可がある組み込みロールです。

カスタマイズしたロールを使う場合は、カスタマイズしたロールに "Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action" のアクセス許可があることを確認します。詳細については、カスタムロールの作成方法に関する記事を参照してください。
[マネージド ID] を選び、メンバーを選びます。

システム割り当て ID の場合は、[システム割り当てマネージド ID] の [Machine learning online endpoint] (機械学習オンラインエンドポイント) を選び、エンドポイント名で検索します。

ユーザー割り当て ID の場合は、[ユーザー割り当てマネージド ID] を選び、ID 名で検索します。
ユーザー割り当て ID の場合、ワークスペースコンテナーレジストリとストレージアカウントにもアクセス許可を付与する必要があります。コンテナーレジストリとストレージアカウントは、Azure portal のワークスペースの概要ページで確認できます。

ワークスペースコンテナーレジストリの概要ページに移動し、[アクセス制御] を選び、[ロールの割り当ての追加] を選んで、[ACR pull |Pull container image]\(ACR プル | コンテナーイメージのプル\) をエンドポイント ID に割り当てます。

ワークスペースの既定のストレージの概要ページに移動し、[アクセス制御] を選び、[ロールの割り当ての追加] を選んで、[ストレージ BLOB データ閲覧者] をエンドポイント ID に割り当てます。
(省略可能) ユーザー割り当て ID の場合、CPU、GPU、ディスク、メモリ使用率などのエンドポイント関連のメトリックを監視する場合は、ワークスペースの [ワークスペースメトリックライター] ロールも ID に付与する必要があります。

エンドポイントの状態を確認する

デプロイウィザードが完了すると、通知を受け取ります。エンドポイントとデプロイが正常に作成されたら、エンドポイントの詳細ページへの通知で [Deploy details] (デプロイの詳細) を選択できます。

また、スタジオの [エンドポイント] ページに直接移動し、デプロイしたエンドポイントの状態を確認することもできます。

サンプルデータを使用してエンドポイントをテストする

エンドポイントの詳細ページで [テスト] タブに切り替えます。

値を入力し、[テスト] ボタンを選択できます。

[テスト結果] は次のようになります。

チャットフローからデプロイされたエンドポイントをテストする

チャットフローからデプロイされたエンドポイントの場合は、イマーシブチャットウィンドウでテストできます。

chat_input はチャットフローの開発時に設定したものです。入力ボックスに chat_input のメッセージを入力できます。右側の [入力] パネルで chat_input 以外の他の入力値を指定することができます。詳細については、チャットフローの開発方法に関する記事を参照してください。

エンドポイントを使う

エンドポイントの詳細ページで [Consume] (使用) タブに切り替えます。エンドポイントを使うための REST エンドポイントとキー/トークンを確認できます。さまざまな言語でエンドポイントを使うためのサンプルコードもあります。

フロー入力に従ってデータ値を入力する必要があることに注意してください。この記事では、例として Web 分類サンプルフローを使います。data = {"url": "<the_url_to_be_classified>"} を指定し、サンプル使用コードにキーまたはトークンを入力する必要があります。

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

Azure Monitor を使用してマネージドオンラインエンドポイントの一般的なメトリックを表示する (省略可能)

スタジオのエンドポイントの [詳細] ページのリンクをたどると、オンラインエンドポイントとそのデプロイのさまざまなメトリック (要求番号、要求の待機時間、ネットワークバイト、CPU/GPU/ディスク/メモリの使用状況など) を表示できます。これらのリンクに従うと、エンドポイントまたはデプロイの Azure portal の正確なメトリックページに移動します。

注意

エンドポイントにユーザー割り当て ID を指定する場合は、必ず Azure Machine Learning ワークスペースの [Workspace metrics writer] (ワークスペースメトリックライター) をユーザー割り当て ID に割り当ててください。そうしないと、エンドポイントはメトリックをログできません。

オンラインエンドポイントメトリックを表示する方法の詳細については、「オンラインエンドポイントを監視する」を参照してください。

プロンプトフローエンドポイント固有のメトリックとトレースデータを表示する (省略可能)

UI デプロイウィザードで Application Insights 診断を有効にすると、トレースデータとプロンプトフロー固有のメトリックが、ワークスペースにリンクされた Application Insights へと収集されます。デプロイに対するトレースの有効化の詳細を確認してください。

プロンプトフローからデプロイされたエンドポイントをトラブルシューティングする

アクション "Microsoft.MachineLearningService/workspaces/datastores/read" を実行する権限がない

フローにインデックス検索ツールが含まれている場合、フローをデプロイした後に、エンドポイントではワークスペースデータストアにアクセスして、チャンクと埋め込みを含む MLIndex yaml ファイルまたは FAISS フォルダーを読み取る必要があります。そのため、それを行うためのアクセス許可をエンドポイント ID に付与する必要があります。

ワークスペーススコープに対する AzureML データサイエンティストか、"MachineLearningService/workspace/datastore/reader" アクションを含むカスタムロールをエンドポイント ID に付与できます。

MissingDriverProgram エラー

カスタム環境を使ってフローをデプロイすると、次のエラーが発生する場合は、カスタム環境の定義で inference_config を指定しなかったためである可能性があります。

'error': 
{
    'code': 'BadRequest', 
    'message': 'The request is invalid.', 
    'details': 
         {'code': 'MissingDriverProgram', 
          'message': 'Could not find driver program in the request.', 
          'details': [], 
          'additionalInfo': []
         }
}

このエラーを修正するには、2 つの方法があります。

(推奨) カスタム環境の詳細ページでコンテナーイメージの URI を調べて、flow.dag.yaml ファイルでフローの基本イメージとしてそれを設定できます。 UI でフローをデプロイするときは、[現在のフロー定義の環境を使用する] を選ぶだけで、この基本イメージとデプロイに対する requirement.txt に基づいてカスタマイズされた環境が、バックエンドサービスによって作成されます。フロー定義で指定された環境についての詳細を理解してください。
カスタム環境の定義に inference_config を追加すると、このエラーを修正できます。カスタマイズされた環境を使う方法の詳細を理解してください。

以下は、カスタマイズされた環境の定義の例です。

$schema: https://azuremlschemas.azureedge.net/latest/environment.schema.json
name: pf-customized-test
build:
  path: ./image_build
  dockerfile_path: Dockerfile
description: promptflow customized runtime
inference_config:
  liveness_route:
    port: 8080
    path: /health
  readiness_route:
    port: 8080
    path: /health
  scoring_route:
    port: 8080
    path: /score

モデルの応答に時間がかかりすぎる

デプロイの応答に時間がかかりすぎていることに気づく場合があります。これには、いくつかの発生要因が考えられます。

モデルが十分に強力ではない (例: text-ada に対して gpt が使用されている)
インデックスクエリが最適化されておらず、時間がかかりすぎる
フローに含まれている処理手順が多すぎる

モデルのパフォーマンスを向上するために、上記の考慮事項を使ってエンドポイントを最適化することを検討してください。

デプロイスキーマをフェッチできません

エンドポイントをデプロイし、エンドポイント詳細ページの [テスト] タブでテストする際、[テスト] タブに次のように [デプロイスキーマをフェッチできません] と表示される場合は、次の 2 つの方法を試してこの問題を収束できます。

エンドポイント ID に対して正しいアクセス許可が付与されていることを確認します。詳しくは、「エンドポイント ID にアクセス許可を付与する方法」をご覧ください。

ワークスペースシークレット一覧へのアクセスが拒否されました

"Access denied to list workspace secret" (ワークスペースシークレット一覧へのアクセスが拒否されました) などのエラーが発生した場合は、エンドポイント ID に対して正しいアクセス許可が付与されているかをチェックします。詳しくは、「エンドポイント ID にアクセス許可を付与する方法」をご覧ください。

リソースをクリーンアップする

このチュートリアルの完了後にエンドポイントを使う予定がない場合は、エンドポイントを削除してください。

Note

完全に削除されるまで約 20 分かかります。

次の方法で共有

リアルタイム推論を行うためにマネージドオンラインエンドポイントとしてフローをデプロイする

前提条件

フローを構築し、デプロイの準備を整える

デプロイで使用される環境を定義する

オンラインデプロイを作成する

基本設定

詳細設定 - エンドポイント

認証の種類

ID の種類

システム割り当て

ユーザー割り当て

詳細設定 - デプロイ

現在のフロー定義の環境を使用する

カスタマイズされた環境を使用する

Application Insights 診断 (プレビュー) をオンにすることでトレースを有効にする

詳細設定 - 出力と接続

エンドポイントにアクセス許可を付与する

エンドポイントの状態を確認する

サンプルデータを使用してエンドポイントをテストする

チャットフローからデプロイされたエンドポイントをテストする

エンドポイントを使う

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

Azure Monitor を使用してマネージドオンラインエンドポイントの一般的なメトリックを表示する (省略可能)

プロンプトフローエンドポイント固有のメトリックとトレースデータを表示する (省略可能)

プロンプトフローからデプロイされたエンドポイントをトラブルシューティングする

アクション "Microsoft.MachineLearningService/workspaces/datastores/read" を実行する権限がない

MissingDriverProgram エラー

モデルの応答に時間がかかりすぎる

デプロイスキーマをフェッチできません

ワークスペースシークレット一覧へのアクセスが拒否されました

リソースをクリーンアップする

次のステップ

その他のリソース

次の方法で共有

リアルタイム推論を行うためにマネージド オンライン エンドポイントとしてフローをデプロイする

前提条件

フローを構築し、デプロイの準備を整える

デプロイで使用される環境を定義する

オンライン デプロイを作成する

基本設定

詳細設定 - エンドポイント

認証の種類

ID の種類

システム割り当て

ユーザー割り当て

詳細設定 - デプロイ

現在のフロー定義の環境を使用する

カスタマイズされた環境を使用する

Application Insights 診断 (プレビュー) をオンにすることでトレースを有効にする

詳細設定 - 出力と接続

エンドポイントにアクセス許可を付与する

エンドポイントの状態を確認する

サンプル データを使用してエンドポイントをテストする

チャット フローからデプロイされたエンドポイントをテストする

エンドポイントを使う

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

Azure Monitor を使用してマネージド オンライン エンドポイントの一般的なメトリックを表示する (省略可能)

プロンプト フロー エンドポイント固有のメトリックとトレース データを表示する (省略可能)

プロンプト フローからデプロイされたエンドポイントをトラブルシューティングする

アクション "Microsoft.MachineLearningService/workspaces/datastores/read" を実行する権限がない

MissingDriverProgram エラー

モデルの応答に時間がかかりすぎる

デプロイ スキーマをフェッチできません

ワークスペース シークレット一覧へのアクセスが拒否されました

リソースをクリーンアップする

次のステップ

その他のリソース

リアルタイム推論を行うためにマネージドオンラインエンドポイントとしてフローをデプロイする

オンラインデプロイを作成する

サンプルデータを使用してエンドポイントをテストする

チャットフローからデプロイされたエンドポイントをテストする

Azure Monitor を使用してマネージドオンラインエンドポイントの一般的なメトリックを表示する (省略可能)

プロンプトフローエンドポイント固有のメトリックとトレースデータを表示する (省略可能)

プロンプトフローからデプロイされたエンドポイントをトラブルシューティングする

デプロイスキーマをフェッチできません

ワークスペースシークレット一覧へのアクセスが拒否されました