Azure AI 検索エンリッチメントパイプラインにカスタムスキルを追加する

Note

Azure AI 検索は、Azure ポータル、REST API、およびAzure SDKから使用できます。また、Foundry IQ は、エンタープライズコンテンツを、Microsoft Foundry ポータルのエージェントの再利用可能なアクセス許可に対応したナレッジベースに変換するマネージドナレッジレイヤーです。

AI エンリッチメントパイプラインには、作成して発行する組み込みのスキルとカスタムスキルの両方を含めることができます。カスタムコードは検索サービスの外部で実行されますが (たとえば、Azure関数として)、入力を受け入れ、他のスキルと同様にスキルセットに出力を送信します。データは、モデルがデプロイされる geography で処理されます。

カスタムスキルは複雑に聞こえるかもしれませんが、簡単に実装できます。パターンマッチングまたは分類モデルを提供する既存のパッケージがある場合は、処理のために BLOB から抽出されたコンテンツをそれらのモデルに渡すことができます。 AI エンリッチメントはAzureベースであるため、Azureでモデルをホストする必要もあります。一般的なホスティングオプションには、Azure Functions または containers があります。

カスタムスキルを構築する予定の場合は、この記事で、スキルをパイプラインに統合するために使用するインターフェイスについて説明しています。主な要件は、スキルセット全体で使用できる方法で入力を受け入れて出力を出力する機能です。そのためこの記事で重点を置いているのは、エンリッチメントパイプラインに必要な入力と出力の形式です。

カスタムスキルの利点

カスタムスキルを構築すると、コンテンツに固有の変換を挿入することができます。たとえば、事業や財務の契約やドキュメントを区別するためのカスタム分類モデルを作成したり、関連コンテンツのオーディオファイルを細かく調べるために音声認識スキルを追加したりすることができます。詳細な例については、「例: AI エンリッチメント用のカスタムスキルを作成する」を参照してください。

エンドポイントとタイムアウト間隔を設定する

カスタム Web API スキルを使用して、カスタムスキルのインターフェイスを指定します。

"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"description": "This skill has a 230-second timeout",
"uri": "https://[your custom skill uri goes here]",
"authResourceId": "[for managed identity connections, your app's client ID goes here]",
"timeout": "PT230S",

URI は、関数またはアプリの HTTPS エンドポイントです。 URI を設定するときは、URI がセキュリティで保護されるようにします (HTTPS)。コードを Azure Function App でホストする場合は、要求を承認するために、ヘッダーに API キーを含めるか、URI に URI パラメーターとして含めます。

関数またはアプリで認証と承認にAzureマネージド ID とAzure ロールを使用している場合、カスタムスキルは要求に認証トークンを含めることができます。この方法に対する要件を次に説明します。

インデクサーの代わりに要求を送信する検索サービスは、Microsoft Entra IDが呼び出し元を認証できるように、マネージド ID (システムまたはユーザー割り当て) を使用するように構成する必要があります。
Microsoft Entra ID用に関数またはアプリを構成する必要があります。
カスタムスキル定義に、authResourceId プロパティが含まれる必要があります。このプロパティは、アプリケーション (クライアント) ID を、サポートされている形式でapi://<appId>受け取ります。

uriが、authResourceIdによって識別されるアプリケーションのエンドポイントを指していることを確認します。値が一致しない場合、認証エラーや要求が意図しないエンドポイントに送信される可能性があります。セキュリティガイダンス、推奨されるプラクティス、構成を確認する手順については、「マネージド ID 認証のセキュリティに関する考慮事項」を参照してください。

エンドポイントへの接続は、既定では 30 秒の時間内に応答が返されないとタイムアウトになります (PT30S)。インデックス作成パイプラインは同期的であり、その期間に応答が受信されない場合、インデックス作成によってタイムアウトエラーが発生します。この間隔は、timeout パラメーター (PT230S) を設定することで、最大値の 230 秒まで長くできます。

IP アクセス制限によって保護されたエンドポイントが応答しない場合は、タイムアウトエラーをより速く表示するために、 timeout を PT10Sなどの短い値に一時的に設定します。 Azure関数アプリの場合は、[>Networking>Access の制限] で受信 IP 規則を管理します。許可する IP アドレスについては、「インデクサー接続を許可するように IP ファイアウォール規則を構成する」を参照してください。

Web API 入力の書式設定

Web API は、処理するレコードの配列を受け入れる必要があります。各レコード内で、Web API への入力としてプロパティバッグを指定します。

コントラクトテキストに記載されている最初の日付を識別する基本的なエンリッチャーを作成するとします。この例では、カスタムスキルは単一の入力 ( contractText) を受け入れます。スキルには、契約日という 1 つの出力もあります。エンリッチャーをより興味深いものにするには、マルチパート複合型の形で contractDate を返します。

Web API は、入力レコードのバッチを受け取る準備ができている必要があります。 values配列の各メンバーは、特定のレコードの入力を表します。各レコードには、次の要素が必要です。

特定のレコードの一意の識別子であるrecordIdメンバー。エンリッチャーが結果を返すときは、呼び出し元がレコードの結果を入力と照合できるように、この recordId を提供する必要があります。
data メンバーは、各レコードに対応する一連の入力フィールドです。

結果の Web API 要求は次のようになります。

{
    "values": [
      {
        "recordId": "a1",
        "data":
           {
             "contractText": 
                "This is a contract that was issued on November 3, 2023 and that involves... "
           }
      },
      {
        "recordId": "b5",
        "data":
           {
             "contractText": 
                "In the City of Seattle, WA on February 5, 2018 there was a decision made..."
           }
      },
      {
        "recordId": "c3",
        "data":
           {
             "contractText": null
           }
      }
    ]
}

実際には、ここに示した 3 つだけでなく、数百、数千のレコードを指定してサービスが呼び出される可能性があります。

Web API 出力の書式設定

出力形式は、 recordId とプロパティバッグを含むレコードのセットです。この特定の例には出力が 1 つだけありますが、複数のプロパティを返すことができます。ベストプラクティスとして、レコードを処理できない場合にエラーメッセージと警告メッセージを返すことを検討してください。

{
  "values": 
  [
      {
        "recordId": "b5",
        "data" : 
        {
            "contractDate":  { "day" : 5, "month": 2, "year" : 2018 }
        }
      },
      {
        "recordId": "a1",
        "data" : {
            "contractDate": { "day" : 3, "month": 11, "year" : 2023 }                    
        }
      },
      {
        "recordId": "c3",
        "data" : 
        {
        },
        "errors": [ { "message": "contractText field required "}   ],  
        "warnings": [ {"message": "Date not found" }  ]
      }
    ]
}

スキルセットにカスタムスキルを追加する

Web API エンリッチャーを作成するときに、要求の一部として HTTP ヘッダーとパラメーターを定義できます。次のスニペットは、要求パラメータとオプションの HTTP ヘッダーをスキルセット定義に含めることができる方法を示しています。 HTTP ヘッダーを設定することは、構成設定をコードに渡す必要がある場合に便利です。

{
    "skills": [
      {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "name": "myCustomSkill",
        "description": "This skill calls an Azure function, which in turn calls TA sentiment",
        "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/DateExtractor?language=en",
        "context": "/document",
        "httpHeaders": {
            "DateExtractor-Api-Key": "foo"
        },
        "inputs": [
          {
            "name": "contractText",
            "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "contractDate",
            "targetName": "date"
          }
        ]
      }
  ]
}

Note

GET でスキルセットを取得すると、資格情報の漏えいを防ぐため、サービスはすべての <redacted> 値に対して httpHeaders を返します。格納されているヘッダー値を変更せずにスキルを更新するには、各値を <unchanged> に設定します。詳細と例については、「カスタム Web API スキル — スキルパラメーター」を参照してください。

このビデオを観る

ビデオでの概要とデモについては、次のデモを視聴してください。

次のステップ

この記事では、カスタムスキルをスキルセットに統合するために必要なインターフェイス要件について説明しました。カスタムスキルとスキルセットの構成の詳細については、次のリソースを参照してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-07-31