次の方法で共有

Azure AI Search エンリッチメント パイプラインの AML スキル

  • [アーティクル]

重要

Azure AI Foundry モデル カタログへのインデクサー接続のサポートは、 使用条件の下でパブリック プレビュー段階にあります。 プレビュー REST API では、このスキルがサポートされています。

AML スキルを使用すると、カスタム Azure Machine Learning (AML) モデルまたは Azure AI Foundry にデプロイされたベース 埋め込みモデルを使用して AI エンリッチメントを拡張できます。 AML モデルがトレーニングされてデプロイされるとAML スキルによってスキルセットに統合されます。

AML スキルの使用

他の組み込みスキルと同様に、カスタム AML スキルには入力と出力があります。 入力は、デプロイされた AML オンライン エンドポイントに JSON オブジェクトとして送信されます。 エンドポイントの出力は、成功状態コードと共に、応答の JSON ペイロードである必要があります。 データは、モデルがデプロイされている geo で処理されます。 応答は、 AML スキル定義で指定された出力を提供することが期待されます。 その他の応答はエラーと見なされ、エンリッチメントは実行されません。

Note

インデクサーは、AML オンライン エンドポイントから特定の標準 HTTP 状態コードが返された場合には、再試行を 2 回行います。 これらの HTTP 状態コードは次のとおりです。

  • 503 Service Unavailable
  • 429 Too Many Requests

AML スキルは、2024-07-01 安定した API バージョンまたは同等の Azure SDK、または Azure AI Foundry ポータルのモデル カタログへの接続用の 2024-05-01-preview API バージョンを使用して呼び出すことができます。

Azure AI Foundry のモデルの AML スキル

2024-05-01-preview REST API と Azure portal (2024-05-01-preview も対象) から、Azure AI Search は Azure AI Foundry ポータルのモデル カタログへのクエリ時間接続に Azure AI Foundry モデル カタログ ベクターライザー を提供します。 そのベクタライザーをクエリに使用する場合は、 AML スキルが、Azure AI Foundry モデル カタログ内のモデルを使用して埋め込みを生成するための インデックス作成に対応する です。

インデックス作成中、 AML スキルはモデル カタログに接続して、インデックスのベクトルを生成できます。 クエリ時に、クエリはベクター 化を使用して同じモデルに接続し、ベクター クエリのテキスト文字列をベクター化できます。 このワークフローでは、インデックス作成とクエリの両方に同じ埋め込みモデルを使用できるように、 AML スキルとモデル カタログ ベクターライザーを一緒に使用する必要があります。 Azure AI Foundry モデル カタログからの埋め込みモデルの使用サポートされている埋め込みモデルの一覧についてはを参照してください。

Import と vectorize data ウィザードを使用して、Azure AI Foundry にデプロイされた埋め込みモデル用の AML スキルを含むスキルセットを生成することをお勧めします。 入力、出力、マッピングの AML スキル定義はウィザードによって生成されるため、コードを記述する前にモデルを簡単にテストできます。

前提条件

@odata.type

Microsoft.Skills.Custom.AmlSkill

スキルのパラメーター

パラメーターの大文字と小文字は区別されます。 どのパラメーターを使用するかは、AML オンライン エンドポイントが必要とする認証 (存在する場合) によって異なります

パラメーター名 説明
uri (キー認証の場合に必要) JSON ペイロードが送信される AML オンライン エンドポイントのスコアリング URI。 https URI スキームのみが許可されます。 Azure AI Foundry モデル カタログにモデルを埋め込む場合、これがターゲット URI です。
key ( キー認証に必要) AML オンライン エンドポイントの キー または
resourceId (トークン認証の場合に必要)。 AML オンライン エンドポイントの Azure Resource Manager リソース ID。 subscriptions/{guid}/resourceGroups/{resource-group-name}/Microsoft.MachineLearningServices/workspaces/{workspace-name}/onlineendpoints/{endpoint_name} 形式にする必要があります。
region (トークン認証の場合は省略可能)。 AML オンライン エンドポイントがデプロイされるリージョン。
timeout (省略可能) 指定した場合は、API 呼び出しを行う http クライアントのタイムアウト値を示します。 XSD "dayTimeDuration" 値 (ISO 8601 期間値の制限されたサブセット) として書式設定する必要があります。 たとえば、60 秒の場合は PT60S とします。 設定しなかった場合は、既定値の 30 秒が選択されます。 タイムアウトは、最大で 230 秒、最小で 1 秒に設定できます。
degreeOfParallelism (省略可能) 指定した場合は、指定したエンドポイントに対してインデクサーが並列で行う呼び出しの数を示します。 要求負荷が高すぎてエンドポイントが失敗する場合は、この値を減らすことができます。 エンドポイントで詳細な要求を受け入れることができ、インデクサーのパフォーマンスを向上させる必要がある場合は、この値を増やすことができます。 設定しない場合は、既定値の 5 が使用されます。 degreeOfParallelism には、最大値として 10、最小値として 1 を設定できます。

認証

AML オンライン エンドポイントでは、次の 2 つの認証オプションが提供されます。

  • キーベースの認証。 静的キーは、AML スキルからのスコアリング要求を認証するために提供されます。 この接続の uri パラメーターと key パラメーターを設定します。

  • トークン ベースの認証。AML オンライン エンドポイントがトークン ベースの認証を使用してデプロイ。 Azure AI Search サービスの 管理 ID を有効にし、ワークスペースにロールの割り当てを設定する必要があります。 その後、AML スキルは、サービスのマネージド ID を使用して、静的キーを必要とせず、AML オンライン エンドポイントに対して認証します。 検索サービス ID は、 Owner または Contributor である必要があります。 resourceId パラメーターを設定し、検索サービスが AML ワークスペースとは異なるリージョンにある場合は、region パラメーターを設定します。

スキルの入力

スキル入力は、ドキュメントのノードでありドキュメントの解読中に作成されます。 たとえば、ルート ドキュメント、正規化されたイメージ、または BLOB の内容などです。 このスキルの定義済みの入力はありません。 入力の場合は、AML スキルの実行時に設定される 1 つ以上のノードを指定する必要があります。

スキルの出力

スキル出力は、スキルによって作成されたエンリッチメントされたドキュメントの新しいノードです。 このスキルの定義済みの出力はありません。 出力の場合は、AML スキルの JSON 応答から設定できるノードを指定する必要があります。

定義例

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A custom model that detects the language in a document.",
    "uri": "https://language-model.models.contoso.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

入力の JSON 構造体のサンプル

この JSON 構造体は、AML オンライン エンドポイントに送信されるペイロードを表します。 構造体の最上位レベルのフィールドは、スキル定義の inputs セクションで指定された "names" に対応します。 これらのフィールドの値は、それらのフィールドの source からの値になります (これは、ドキュメント内のフィールドからの値になる可能性もありますし、他のスキルからの値になる可能性もあります)

{
  "text": "Este es un contrato en Inglés"
}

出力の JSON 構造体のサンプル

出力は、AML オンライン エンドポイントから返された応答に対応します。 AML オンライン エンドポイントは、JSON ペイロードのみを返す必要があります (Content-Type 応答ヘッダーを確認することで検証されます)。また、フィールドが output 内の "names" に一致するエンリッチメントで、値がエンリッチメントと見なされるオブジェクトである必要もあります。

{
    "detected_language_code": "es"
}

インライン整形のサンプルの定義

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://language-model.models.contoso.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "shapedText",
        "sourceContext": "/document",
        "inputs": [
            {
              "name": "content",
              "source": "/document/content"
            }
        ]
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

インライン整形の入力 JSON 構造体

{
  "shapedText": { "content": "Este es un contrato en Inglés" }
}

インライン整形のサンプル出力 JSON 構造体

{
    "detected_language_code": "es"
}

エラーになる場合

AML が利用できない場合や、成功以外の状態コードが送信された場合に加え、次の場合もエラーと見なされます。

  • AML オンライン エンドポイントは成功状態コードを返しますが、応答は application/jsonされていないことを示し、応答は無効と見なされ、エンリッチメントは実行されません。

  • AML オンライン エンドポイントは無効な JSON を返します。

AML オンライン エンドポイントが使用できない場合や HTTP エラーが返された場合は、HTTP エラーに関する使用可能な詳細を含むわかりやすいエラーがインデクサーの実行履歴に追加されます。

関連項目