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

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

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

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

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

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

前提条件

• AML ワークスペース
• このワークスペースでのオンライン エンドポイント (リアルタイム)。

@odata.type

Microsoft.Skills.Custom.AmlSkill

スキルのパラメーター

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

使用するスキル パラメーター

必要な AML スキル パラメーターは、AML オンライン エンドポイントが使用する認証 (存在する場合) に応じて異なります。 AML オンライン エンドポイントでは、次の 2 つの認証オプションが提供されます。

• キーベースの認証。 AML スキルからのスコアリング要求を認証するために、静的なキーが提供されます。
  • uri および key パラメーターを使用します。
• トークンベースの認証。 AML オンライン エンドポイントは、トークン ベースの認証を使用してデプロイされます。 Azure AI Search Serviceの マネージド ID を有効にする必要があります。 その後、AML スキルは、サービスのマネージド ID を使用して、静的キーを必要とせず、AML オンライン エンドポイントに対して認証します。 ID は、所有者または共同作成者ロールに割り当てられる必要があります。
  • resourceId パラメーターを使用します。
  • 検索サービスが AML ワークスペースとは異なるリージョンにある場合は、 リージョン パラメータを使用して、AML オンライン エンドポイントがデプロイされたリージョンを設定します

スキルの入力

このスキルの "定義済みの" 入力はありません。 このスキルの実行時に既に利用可能な 1 つ以上のフィールドを入力として選択できます。そのため、AML オンライン エンドポイントに送信される JSON ペイロードには、さまざまなフィールドが存在することになります。

スキルの出力

このスキルの "定義済みの" 出力はありません。 AML オンライン エンドポイントが返す応答に応じて出力フィールドを追加し、JSON 応答からそれらを選択できるようにしてください。

定義例

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://contoso.count-things.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://contoso.count-things.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 エラーに関する入手可能な詳細情報が含まれるわかりやすいエラーが、インデクサーの実行履歴に追加されます。

関連項目

• スキルセットの定義方法
• AML オンライン エンドポイントのトラブルシューティング
• Azure AI Studio のモデルを使用した統合ベクター化