Azure AI Search のエンリッチメント パイプラインのカスタム Web API スキル

カスタム Web API スキルを使用すると、Web API エンドポイントを呼び出してカスタム操作を提供することで、AI 強化を拡張できます。 組み込みのスキルと同様、カスタム Web API スキルには入力と出力があります。 入力に応じて、Web API はインデクサーの実行時に JSON ペイロードを受信し、応答としての JSON ペイロードと成功の状態コードを出力します。 正常な応答には、カスタム スキルによって指定された出力が含まれます。 その他の応答はエラーと見なされ、エンリッチメントは実行されません。 JSON ペイロードの構造については、このドキュメントで後ほど説明します。

カスタム Web API スキルはまた、Azure OpenAI On Your Data 機能の実装でも使用されます。 Azure OpenAI がロール ベースのアクセス用に構成されており、ベクトル ストアの作成時に 403 Forbidden 呼び出しを受け取る場合は、Azure AI 検索にシステム割り当て ID があり、Azure OpenAI で信頼されたサービスとして実行されていることを確認します。

Note

インデクサーは、Web API から返された特定の標準 HTTP 状態コードに対して 2 回再試行します。 これらの HTTP 状態コードは次のとおりです。

  • 502 Bad Gateway
  • 503 Service Unavailable
  • 429 Too Many Requests

@odata.type

Microsoft.Skills.Custom.WebApiSkill

スキルのパラメーター

パラメーターの大文字と小文字は区別されます。

パラメーター名 説明
uri JSON ペイロードが送信される Web API の URI。 https URI スキームのみが許可されます。
authResourceId (省略可能) 文字列が設定されている場合は、コードがホストされている関数またはアプリへの接続で、このスキルがマネージド ID を使う必要があることを示します。 このプロパティは、Microsoft Entra ID でのアプリケーション (クライアント) ID またはアプリの登録をサポートされている形式である api://<appId> で受け取ります。 この値は、インデクサーによって取得される認証トークンのスコープを設定するために使用され、カスタム Web スキル API 要求と共に関数またはアプリに送信されます。 このプロパティを設定するには、検索サービスがマネージド ID 用に構成されており、かつ Azure 関数アプリが Microsoft Entra サインイン用に構成されている必要があります。 このパラメーターを使用するには、api-version=2023-10-01-Preview で API を呼び出します。
httpMethod ペイロードの送信時に使用されるメソッドです。 許可されるメソッドは PUT または POST です
httpHeaders キーと値のペアのコレクション。ここで、キーはヘッダー名を表し、値はペイロードと共に Web API に送信されるヘッダー値を表します。 次のヘッダーは、このコレクションに含めることはできません: AcceptAccept-CharsetAccept-EncodingContent-LengthContent-TypeCookieHostTEUpgradeVia
timeout (省略可能) 指定した場合は、API 呼び出しを行う http クライアントのタイムアウト値を示します。 XSD "dayTimeDuration" 値 (ISO 8601 期間値の制限されたサブセット) として書式設定する必要があります。 たとえば、60 秒の場合は PT60S とします。 設定しなかった場合は、既定値の 30 秒が選択されます。 タイムアウトは、最大で 230 秒、最小で 1 秒に設定できます。
batchSize (省略可能) API 呼び出しごとに送信される "データ レコード" の数を示します (後の JSON ペイロードの構造を参照)。 設定しなかった場合は、既定値の 1000 が選択されます。 このパラメーターを使用して、インデックス作成のスループットと API への負荷の適切なトレードオフを確保することをお勧めします。
degreeOfParallelism (省略可能) 指定されている場合は、指定したエンドポイントに対してインデクサーが並列に行う呼び出しの数を示します。 エンドポイントが負荷を受けて失敗している場合は、この値を小さくすることができます。また、エンドポイントが負荷を処理できる場合は、大きくすることができます。 設定しない場合は、既定値の 5 が使用されます。 degreeOfParallelism には、最大値として 10、最小値として 1 を設定できます。

スキルの入力

このスキルの定義済みの入力はありません。 入力は、任意の既存のフィールド、またはカスタム スキルに渡す エンリッチメント ツリー内の任意のノード です。

スキルの出力

このスキルの定義済みの出力はありません。 スキルの出力を検索インデックスのフィールドに送信する必要がある場合は、必ずインデクサーで出力フィールド マッピングを定義してください。

定義例

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "batchSize": 4,
  "context": "/document",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    },
    {
      "name": "language",
      "source": "/document/languageCode"
    },
    {
      "name": "phraseList",
      "source": "/document/keyphrases"
    }
  ],
  "outputs": [
    {
      "name": "hitPositions"
    }
  ]
}

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

この JSON 構造体は、Web API に送信されるペイロードを表します。 これは、常に次の制約に従います。

  • 最上位レベルのエンティティは values と呼ばれ、オブジェクトの配列です。 このようなオブジェクトの数は、多くとも batchSize です。

  • values 配列内の各オブジェクトには、次のものが含まれています。

    • recordId プロパティ。これは、そのレコードを識別するために使用される一意の文字列です。

    • data プロパティ。これは JSON オブジェクトです。 data プロパティのフィールドは、スキル定義の inputs セクションで指定されている "名前" に対応します。 これらのフィールドの値は、これらのフィールドの source から来ています (これは、ドキュメント内のフィールドから、あるいは別のスキルから来ている可能性があります)。

{
    "values": [
      {
        "recordId": "0",
        "data":
           {
             "text": "Este es un contrato en Inglés",
             "language": "es",
             "phraseList": ["Este", "Inglés"]
           }
      },
      {
        "recordId": "1",
        "data":
           {
             "text": "Hello world",
             "language": "en",
             "phraseList": ["Hi"]
           }
      },
      {
        "recordId": "2",
        "data":
           {
             "text": "Hello world, Hi world",
             "language": "en",
             "phraseList": ["world"]
           }
      },
      {
        "recordId": "3",
        "data":
           {
             "text": "Test",
             "language": "es",
             "phraseList": []
           }
      }
    ]
}

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

"出力" は、Web API から返された応答に対応します。 Web API は JSON ペイロードのみを返す必要があります (Content-Type 応答ヘッダーを参照することで確認されます)。また、次の制約を満たす必要があります。

  • オブジェクトの配列である values と呼ばれる最上位レベルのエンティティが存在する必要があります。

  • 配列内のオブジェクトの数は、Web API に送信されるオブジェクトの数と同じになっている必要があります。

  • 各オブジェクトには次のプロパティが必要です。

    • recordId プロパティ。

    • data プロパティ。このオブジェクトでは、フィールドは output 内の "名前" に一致するエンリッチメントであり、その値はエンリッチメントと見なされます。

    • インデクサーの実行履歴に追加される発生したすべてのエラーがリストされている配列である errors プロパティ。 このプロパティは必須ですが、null 値にすることもできます。

    • インデクサーの実行履歴に追加される発生したすべての警告がリストされている配列である warnings プロパティ。 このプロパティは必須ですが、null 値にすることもできます。

  • 要求または応答の values 内のオブジェクトの順序は重要ではありません。 ただし、recordId は相関関係に使用されるため、Web API への元の要求の一部ではなかった、recordId が含まれている応答内のレコードはすべて破棄されます。

{
    "values": [
        {
            "recordId": "3",
            "data": {
            },
            "errors": [
              {
                "message" : "'phraseList' should not be null or empty"
              }
            ],
            "warnings": null
        },
        {
            "recordId": "2",
            "data": {
                "hitPositions": [6, 16]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "0",
            "data": {
                "hitPositions": [0, 23]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "1",
            "data": {
                "hitPositions": []
            },
            "errors": null,
            "warnings": [
              {
                "message": "No occurrences of 'Hi' were found in the input text"
              }
            ]
        },
    ]
}

エラーになる場合

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

  • Web API から成功の状態コードが返されたが、応答ではそれが application/json でないことが示されている場合、その応答は無効と見なされ、エンリッチメントは実行されません。

  • 応答の values 配列に無効なレコードが存在する (たとえば、recordId がないか、または重複している) 場合、それらの無効なレコードに対してエンリッチメントは実行されません。 カスタム スキルを開発している場合は、Web API スキルのコントラクトに従うことが重要です。 予測されるコントラクトに従う Power Skills リポジトリで提供されているこの例を参照できます。

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

関連項目