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 Search にシステム割り当て ID があり、Azure OpenAI で信頼されたサービスとして実行されていることを確認します。

@odata.type

Microsoft.Skills.Custom.WebApiSkill

スキルのパラメーター

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

スキルの入力

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

スキルの出力

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

定義例

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

関連項目

• スキルセットを定義する
• AI 強化パイプラインにカスタム スキルを追加する
• 例: AI エンリッチメント用のカスタム スキルを作成する
• Power Skills リポジトリ