トラブルシューティングガイダンス

[アーティクル]
09/01/2024

この記事では、プロンプトフローの使用法についてよく寄せられる質問にお答えします。

コードファーストエクスペリエンスのフローを更新する際に "パッケージツールが見つかりません" というエラーが発生する

コードファーストのエクスペリエンスのフローを更新するときに、フローに Faiss インデックス検索、ベクターインデックス検索、ベクター DB 検索、コンテンツの安全性 (テキスト) の各ツールが使われている場合は、次のようなエラーメッセージが表示されることがあります。

Package tool 'embeddingstore.tool.faiss_index_lookup.search' is not found in the current environment.

この問題を解決するには、次の 2 つのオプションがあります。

方法 1

コンピューティングセッションを最新の基本イメージバージョンに更新します。
[生ファイルモード] を選択して、生コードビューに切り替えます。次に、flow.dag.yaml ファイルを開きます。

ツール名を更新します。

ツール名を更新する方法を示すスクリーンショット。

ツール	新しいツール名
Faiss インデックス検索	promptflow_vectordb.tool.faiss_index_lookup.FaissIndexLookup.search
ベクターインデックスルックアップ	promptflow_vectordb.tool.vector_index_lookup.VectorIndexLookup.search
ベクター DB ルックアップ	promptflow_vectordb.tool.vector_db_lookup.VectorDBLookup.search
コンテンツの安全性 (テキスト)	content_safety_text.tools.content_safety_text_tool.analyze_text

flow.dag.yaml ファイルを保存します。

オプション 2
- コンピューティングセッションを最新の基本イメージバージョンに更新する
- 古いツールを削除し、新しいツールを再作成します。

"ファイルまたはディレクトリが存在しません" エラー

プロンプトフローは、フローのスナップショットを保存するためにファイル共有記憶域に依存します。ファイル共有記憶域に問題がある場合は、次の問題が発生することがあります。回避策を次に示します。

プライベートストレージアカウントを使用している場合は、「プロンプトフローでのネットワークの分離」を参照して、お使いのワークスペースからそのストレージアカウントにアクセスできることをご確認ください。
ストレージアカウントがパブリックアクセスを有効にしている場合、ワークスペースに workspaceworkingdirectory というデータストアがあるか確認してください。これは、ファイル共有の種類である必要があります。
- このデータストアを取得しなかった場合は、ワークスペースに追加する必要があります。
  - code-391ff5ac-6576-460f-ba4d-7e03433c68b6 という名前のファイル共有を作成します。
  - workspaceworkingdirectory という名前のデータストアを作成します。「データストアを作成する」を参照してください。
- workspaceworkingdirectory データストアはあるが、その種類が fileshare ではなく blob の場合は、新しいワークスペースを作成します。 Azure Data Lake Storage Gen2 の階層型名前空間を有効にしていないストレージを、ワークスペースの既定のストレージアカウントとして使用します。詳細については、「ワークスペースの作成」を参照してください。

フローが見つからない

この問題には、次の理由が考えられます。

ストレージアカウントへのパブリックアクセスが無効になっている場合は、ストレージファイアウォールに IP を追加するか、ストレージアカウントにプライベートエンドポイントが接続されている仮想ネットワーク経由でアクセスを有効にして、アクセスを確保する必要があります。
データストアのアカウントキーがストレージアカウントと同期していない場合があります。これを修正するには、データストアの詳細ページでアカウントキーを更新してみてください。
AI Studio を使用している場合は、AI Studio がストレージアカウントにアクセスできるように CORS を設定する必要があります。そうしないと、フロー不足などの問題が発生します。この問題を解決するには、ストレージアカウントに次の CORS 設定を追加します。
- ストレージアカウントのページに移動し、settings の下にある Resource sharing (CORS) を選択して、File service タブを選択します。
- 許可されたオリジン: https://mlworkspace.azure.ai,https://ml.azure.com,https://*.ml.azure.com,https://ai.azure.com,https://*.ai.azure.com,https://mlworkspacecanary.azure.ai,https://mlworkspace.azureml-test.net
- 許可されたメソッド: DELETE, GET, HEAD, POST, OPTIONS, PUT

"XXX という名前のモジュールがありません" という理由で実行に失敗した

この種類のエラーは、コンピューティングセッションに必要なパッケージがないことに関連しています。既定の環境を使用している場合は、コンピューティングセッションのイメージで最新バージョンが使用されていることを確認します。カスタム基本イメージを使用している場合は、必要なすべてのパッケージが Docker コンテキストにインストールされていることを確認します。詳細については、「コンピューティングセッションの基本イメージをカスタマイズする」を参照してください。

コンピューティングセッションで使用されるサーバーレスインスタンスの検索先

コンピューティングセッションで使用されるサーバーレスインスタンスは、コンピューティングページのコンピューティングセッション一覧タブで確認できます。サーバーレスインスタンスを管理する方法の詳細をご覧ください。

カスタム基本イメージを使用したコンピューティングセッションの失敗

requirements.txt またはカスタム基本イメージを使用したコンピューティングセッションの開始の失敗

コンピューティングセッションによる、flow.dag.yaml での requirements.txt またはカスタム基本イメージを使用したイメージのカスタマイズのサポート。一般的なケースでは、requirements.txt の使用をおすすめします。この場合、pip install -r requirements.txt を使用してパッケージがインストールされます。 Python パッケージ以外の依存関係がある場合は、「基本イメージのカスタマイズ」に従って、プロンプトフローの基本イメージの上に新しいイメージベースを構築する必要があります。その後、flow.dag.yaml で使用します。コンピューティングセッションで基本イメージを指定する方法の詳細をご覧ください。

任意の基本イメージを使用してコンピューティングセッションを作成することはできません。プロンプトフローによって提供される基本イメージを使用する必要があります。
requirements.txt 内では promptflow と promptflow-tools のバージョンを固定しないでください。これは既に基本イメージ内に含まれています。以前のバージョンの promptflow と promptflow-tools を使用すると、予期しない動作が発生する可能性があります。

LLM ツールで未加工の入出力を見つけて詳細に調査する方法

プロンプトフローでは、成功した実行が表示されたフローページと実行の詳細ページの出力セクションで、LLM ツールの未加工の入出力を見つけることができます。 view full output ボタンを選択すると、出力全体が表示されます。

Trace セクションには、LLM ツールに対する各要求と応答が含まれています。 LLM モデルに送信された未加工のメッセージと、LLM モデルからの未加工の応答を確認できます。

Azure OpenAI の 409 エラーを修正する方法

Azure OpenAI で 409 エラーが発生する可能性があります。これは、Azure OpenAI のレート制限に達したことを意味します。エラーメッセージは、LLM ノードの出力セクションで確認できます。 Azure OpenAI のレート制限の詳細をご覧ください。

どのノードが最も時間を消費しているかを特定する

コンピューティングセッションログを確認します。
次の警告ログ形式を見つけます。

{ノード名} has been running for {期間} seconds.

次に例を示します。
- ケース 1: Python スクリプトノードが長時間実行される。
  
  この場合、PythonScriptNode が長時間 (ほぼ 300 秒) 実行されていたことがわかります。その後は、ノードの詳細を確認すれば問題の内容を確認できます。
- ケース 2: LLM ノードが長時間実行される。
  
  このケースでは、ログに request canceled メッセージが見つかった場合、OpenAI API 呼び出しに時間がかかりすぎてタイムアウト制限を超えている可能性があります。
  
  OpenAI API のタイムアウトは、ネットワークの問題や、処理時間が長くなる複雑な要求が原因となっている可能性があります。詳細については、「OpenAI API のタイムアウト」を参照してください。
  
  数秒待ってから、要求を再試行してください。通常、ネットワークの問題であればこのアクションで解決します。
  
  再試行してもうまくいかない場合は、gpt-4-32k などの長いコンテキストモデルを使用しており max_tokens に大きな値を設定しているかどうかを確認します。もしそうであれば、想定内の動作です。プロンプトで、対話型モードの上限しきい値よりも長い時間がかかる長い応答が生成される可能性があるためです。この場合は Bulk test を試すことをお勧めします。このモードにはタイムアウト設定がありません。
特定ノードの問題であることを示すものがログに何も見つからない場合
- ログを用意して、プロンプトフローチーム (promptflow-eng) にお問い合わせください。こちらで根本原因の特定を試みます。

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

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

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

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

CLI または SDK を使用してフローをデプロイする場合、タイムアウトエラーが発生することがあります。既定では、request_timeout_ms は 5,000 です。最大 5 分 (300,000 ミリ秒) を指定できます。デプロイ yaml ファイルで要求タイムアウトを指定する方法を示す例を次に示します。詳細については、デプロイスキーマに関する記事を参照してください。

request_settings:
  request_timeout_ms: 300000

OpenAI API で認証エラーが発生する

Azure OpenAI キーを再生成し、プロンプトフローで使用されている接続を手動で更新すると、キーの再生成前に作成された既存のエンドポイントの呼び出し時に "Unauthorized. Access token is missing, invalid, audience is incorrect or have expired。(承認されていません。アクセストークンが見つからない、無効、対象ユーザーが正しくない、または期限切れです。)" のようなエラーが発生する場合があります。

これは、エンドポイント/デプロイで使用されている接続が自動的に更新されないためです。デプロイでのキーまたはシークレットの変更は、手動更新によって行う必要があります。この目的は、意図しないオフライン操作が原因でオンラインの運用デプロイに影響が生るのを避けることです。

エンドポイントがスタジオ UI にデプロイされた場合は、単に、同じデプロイ名を使用して、フローを既存のエンドポイントに再デプロイできます。
エンドポイントが SDK または CLI を使用してデプロイされた場合は、デプロイ定義に何らかの変更 (ダミーの環境変数を追加するなど) を加え、az ml online-deployment update を使用してデプロイを更新する必要があります。

プロンプトフローのデプロイにおける脆弱性の問題

プロンプトフローのランタイムに関連する脆弱性について、軽減に役立つ方法を次に示します。

フローフォルダー内のrequirements.txt にある依存関係パッケージを更新します。
フローにカスタマイズされた基本イメージを使用している場合は、プロンプトフローのランタイムを最新バージョンに更新し、基本イメージをリビルドしてから、フローを再デプロイする必要があります。

マネージドオンラインデプロイのその他の脆弱性については、Azure Machine Learning で毎月の頻度で問題を修正しています。

"MissingDriverProgram Error (MissingDriverProgram エラー)" または "Could not find driver program in the request (要求でドライバープログラムが見つかりませんでした)"

フローをデプロイして、次のエラーが発生した場合、それはデプロイ環境に関連していると考えられます。

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

Could not find driver program in the request

このエラーを解決するには 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 3.5 を使用する)
インデックスクエリが最適化されておらず、時間がかかりすぎる
フローに含まれている処理手順が多すぎる

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

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

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

エンドポイント ID に対して正しいアクセス許可が付与されていることを確認します。詳しくは、「エンドポイント ID にアクセス許可を付与する方法」をご覧ください。
原因は、フローを古いバージョンのランタイムで実行していて、フローをデプロイし、そのデプロイでも、古いバージョンのランタイムを含んだ環境が使用されたことであると考えられます。ランタイムを更新するには、「UI でランタイムを更新する」に従って最新のランタイムでフローを再実行してから、フローをもう一度デプロイします。

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

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

プロンプトフローで資格情報のないデータストアを使用する方法。

Azure AI Studio で資格情報のないストレージを使用するため。基本的に次のことを行う必要があります。

データストアの認証の種類を [なし] に変更します。
ストレージに対するプロジェクト MSI とユーザー BLOB/ファイルデータ共同作成者のアクセス許可を付与します。

データストアの認証の種類を None に変更する

この部分 Identity ベースのデータ認証に従ってデータストアの資格情報を減らすことができます。

データストアの認証の種類を None に変更する必要があります。これは、meid_token ベースの認証を意味します。データストアの詳細ページまたは CLI/SDK から変更できます。 https://github.com/Azure/azureml-examples/tree/main/cli/resources/datastore

BLOB ベースのデータストアの場合は、認証の種類を変更したり、ワークスペース MSI を有効にしてストレージアカウントにアクセスしたりできます。

ファイル共有ベースのデータストアの場合は、認証の種類のみを変更できます。

ユーザー ID またはマネージド ID にアクセス許可を付与する

プロンプトフローで資格情報のないデータストアを使用するには、データストアにアクセスするための十分なアクセス許可をユーザー ID またはマネージド ID に付与する必要があります。

ワークスペースシステム割り当てマネージド ID にストレージアカウントに Storage Blob Data Contributor と Storage File Data Privileged Contributor があることを確認します。少なくとも読み取り/書き込み (削除も含める方が良い) アクセス許可が必要です。
プロンプトフローでこの既定のオプションでユーザー ID を使用している場合は、ユーザー ID がストレージアカウントに対して次のロールを持っていることを確認する必要があります。
- Storage Blob Data Contributor ストレージアカウントでは、少なくとも読み取り/書き込み (削除も含める方が良い) アクセス許可が必要です。
- Storage File Data Privileged Contributor ストレージアカウントでは、少なくとも読み取り/書き込み (削除も含める方が良い) アクセス許可が必要です。
ユーザー割り当てマネージド ID を使用している場合は、マネージド ID がストレージアカウントに対して次のロールを持っていることを確認する必要があります。
- Storage Blob Data Contributor ストレージアカウントでは、少なくとも読み取り/書き込み (削除も含める方が良い) アクセス許可が必要です。
- Storage File Data Privileged Contributor ストレージアカウントでは、少なくとも読み取り/書き込み (削除も含める方が良い) アクセス許可が必要です。
- 一方、作成とテストフローにプロンプトフローを使用する場合は、少なくともユーザー ID Storage Blob Data Read ロールをストレージアカウントに割り当てる必要があります。
それでもフローの詳細ページを表示できない場合で、プロンプトフローを初めて使用する場合は、2024-01-01 より前の場合は、ワークスペースにリンクされているストレージアカウントに Storage Table Data Contributor としてワークスペース MSI を付与する必要があります。

次の方法で共有

トラブルシューティングガイダンス

コードファーストエクスペリエンスのフローを更新する際に "パッケージツールが見つかりません" というエラーが発生する

"ファイルまたはディレクトリが存在しません" エラー

フローが見つからない

"XXX という名前のモジュールがありません" という理由で実行に失敗した

コンピューティングセッションで使用されるサーバーレスインスタンスの検索先

カスタム基本イメージを使用したコンピューティングセッションの失敗

requirements.txt またはカスタム基本イメージを使用したコンピューティングセッションの開始の失敗

LLM ツールで未加工の入出力を見つけて詳細に調査する方法

Azure OpenAI の 409 エラーを修正する方法

どのノードが最も時間を消費しているかを特定する

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

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

OpenAI API で認証エラーが発生する

プロンプトフローのデプロイにおける脆弱性の問題

"MissingDriverProgram Error (MissingDriverProgram エラー)" または "Could not find driver program in the request (要求でドライバープログラムが見つかりませんでした)"

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

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

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

プロンプトフローで資格情報のないデータストアを使用する方法。

データストアの認証の種類を None に変更する

ユーザー ID またはマネージド ID にアクセス許可を付与する

フィードバック

その他のリソース

次の方法で共有

トラブルシューティング ガイダンス

フロー作成に関連する問題

コードファースト エクスペリエンスのフローを更新する際に "パッケージ ツールが見つかりません" というエラーが発生する

"ファイルまたはディレクトリが存在しません" エラー

フローが見つからない

コンピューティング セッション関連の問題

"XXX という名前のモジュールがありません" という理由で実行に失敗した

コンピューティング セッションで使用されるサーバーレス インスタンスの検索先

カスタム基本イメージを使用したコンピューティング セッションの失敗

requirements.txt またはカスタム基本イメージを使用したコンピューティング セッションの開始の失敗

フロー実行に関連する問題

LLM ツールで未加工の入出力を見つけて詳細に調査する方法

Azure OpenAI の 409 エラーを修正する方法

どのノードが最も時間を消費しているかを特定する

フローのデプロイに関連する問題

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

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

OpenAI API で認証エラーが発生する

プロンプト フローのデプロイにおける脆弱性の問題

"MissingDriverProgram Error (MissingDriverProgram エラー)" または "Could not find driver program in the request (要求でドライバー プログラムが見つかりませんでした)"

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

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

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

認証と ID に関連する問題

プロンプト フローで資格情報のないデータストアを使用する方法。

データストアの認証の種類を None に変更する

ユーザー ID またはマネージド ID にアクセス許可を付与する

フィードバック

その他のリソース

トラブルシューティングガイダンス

コードファーストエクスペリエンスのフローを更新する際に "パッケージツールが見つかりません" というエラーが発生する

コンピューティングセッション関連の問題

コンピューティングセッションで使用されるサーバーレスインスタンスの検索先

カスタム基本イメージを使用したコンピューティングセッションの失敗

requirements.txt またはカスタム基本イメージを使用したコンピューティングセッションの開始の失敗

プロンプトフローのデプロイにおける脆弱性の問題

"MissingDriverProgram Error (MissingDriverProgram エラー)" または "Could not find driver program in the request (要求でドライバープログラムが見つかりませんでした)"

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

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

プロンプトフローで資格情報のないデータストアを使用する方法。