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

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

AML スキルの使用

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

安定した REST API バージョンまたは同等の Azure SDK を使用して 、AML スキルを呼び出すことができます。 Azure AI Foundry ポータルでモデル カタログに接続するには、プレビュー 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 スキルは、モデル カタログからモデルを使用して埋め込みを生成するための インデックス作成に対応 します。

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

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

前提条件

• カタログからデプロイされた埋め込みモデル用の Azure AI Foundry プロジェクト 、または作成するカスタム モデル用の AML ワークスペース 。
• カタログからデプロイされた埋め込みモデルのモデル エンドポイント、またはカスタム モデルの AML ワークスペースのオンライン エンドポイント (リアルタイム)。

@odata.type

Microsoft.Skills.Custom.AmlSkill

スキルのパラメーター

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

認証

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

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

• トークン ベースの認証。トークン ベースの認証を使用して AML オンライン エンドポイントがデプロイされます。 Azure AI Search サービスには、 AML ワークスペースでのマネージド ID とロールの割り当てが必要です。 その後、AML スキルは、サービスのマネージド ID を使用して、静的キーを必要とせず、AML オンライン エンドポイントに対して認証します。 検索サービス ID には 、所有者 ロールまたは 共同作成者 ロールが必要です。 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" に対応します。 これらのフィールドの値は、ドキュメントまたは別のスキルのフィールドから取得できる、それらのフィールドの "ソース" から取得されます。

{
  "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 エラーに関する使用可能な詳細を含むわかりやすいエラーがインデクサーの実行履歴に追加されます。

関連項目

• Azure AI Searchでスキルセットを作成する
• Azure AI Foundry モデル カタログからの埋め込みモデルの使用
• Azure Machine Learning オンライン エンドポイントのデプロイとスコアリングのトラブルシューティング