Azure Cognitive Search エンリッチメント パイプラインにカスタム スキルを追加する方法How to add a custom skill to an Azure Cognitive Search enrichment pipeline

Azure Cognitive Search のエンリッチメント パイプラインは、組み込みのコグニティブ スキルと、個人的に作成してパイプラインに追加するカスタム スキルから組み立てることができます。An enrichment pipeline in Azure Cognitive Search can be assembled from built-in cognitive skills as well as custom skills that you personally create and add to the pipeline. この記事では、AI エンリッチメント パイプラインに含めることができるようにインターフェイスを公開するカスタム スキルの作成方法について説明します。In this article, learn how to create a custom skill that exposes an interface allowing it to be included in an AI enrichment pipeline.

カスタム スキルを構築すると、コンテンツに固有の変換を挿入することができます。Building a custom skill gives you a way to insert transformations unique to your content. カスタム スキルは独立して実行され、必要なすべてのエンリッチメント ステップが適用されます。A custom skill executes independently, applying whatever enrichment step you require. たとえば、フィールド固有のカスタム エンティティを定義して、ビジネスおよび財務の契約やドキュメントを区別するためのカスタム分類モデルを作成したり、音声認識スキルを追加して、関連するコンテンツのオーディオ ファイルを細かく調べたりすることができます。For example, you could define field-specific custom entities, build custom classification models to differentiate business and financial contracts and documents, or add a speech recognition skill to reach deeper into audio files for relevant content. 手順の例については、例: AI エンリッチメント用のカスタム スキルを作成するを参照してください。For a step-by-step example, see Example: Creating a custom skill for AI enrichment.

どのようなカスタム機能が必要な場合でも、カスタム スキルをエンリッチメント パイプラインの他の部分に接続するための単純でわかりやすいインターフェイスがあります。Whatever custom capability you require, there is a simple and clear interface for connecting a custom skill to the rest of the enrichment pipeline. スキルセットに含めるための唯一の要件は、入力を受け入れて、スキルセット内で全体として使用できる方法で出力を行うことです。The only requirement for inclusion in a skillset is the ability to accept inputs and emit outputs in ways that are consumable within the skillset as a whole. この記事で焦点となっているのは、エンリッチメント パイプラインが必要とする入力と出力の形式です。The focus of this article is on the input and output formats that the enrichment pipeline requires.

Web API のカスタム スキル インターフェイスWeb API custom skill interface

Web API のカスタム スキル エンドポイントが、30 秒以内に応答を返さない場合、既定ではタイムアウトになります。Custom WebAPI skill endpoints by default timeout if they don't return a response within a 30 second window. インデックス作成パイプラインは同期的であり、この時間内に応答が受信されない場合は、タイムアウト エラーが発生します。The indexing pipeline is synchronous and indexing will produce a timeout error if a response is not received in that window. タイムアウト パラメーターを設定することで、タイムアウトを最長で 230 秒に構成できます。It is possible to configure the timeout to be up to 230 seconds, by setting the timeout parameter:

        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "description": "This skill has a 230 second timeout",
        "uri": "https://[your custom skill uri goes here]",
        "timeout": "PT230S",

URI が安全 (HTTPS) であることを確認します。Make sure the URI is secure (HTTPS).

現在のところ、カスタム スキルとやり取りするための唯一のメカニズムは、Web API インターフェイスです。Currently, the only mechanism for interacting with a custom skill is through a Web API interface. Web API は、このセクションで説明する要件を満たしている必要があります。The Web API needs must meet the requirements described in this section.

1.Web API の入力形式1. Web API Input Format

Web API は、処理されるレコードの配列を受け取る必要があります。The Web API must accept an array of records to be processed. 各レコードには、Web API に提供される入力である "プロパティ バッグ" が含まれていなければなりません。Each record must contain a "property bag" that is the input provided to your Web API.

契約のテキストに記載されている最初の日付を識別する簡単なエンリッチャーを作成したいとします。Suppose you want to create a simple enricher that identifies the first date mentioned in the text of a contract. この例では、スキルは単一の入力 contractText を契約テキストとして受け取ります。In this example, the skill accepts a single input contractText as the contract text. スキルには、契約の日付である 1 つの出力もあります。The skill also has a single output, which is the date of the contract. エンリッチャーをより興味深いものにするために、この contractDate をマルチパートの複合型形式で返します。To make the enricher more interesting, return this contractDate in the shape of a multi-part complex type.

Web API は、入力レコードのバッチを受け取る準備ができている必要があります。Your Web API should be ready to receive a batch of input records. values 配列の各メンバーは、特定のレコードの入力を表します。Each member of the values array represents the input for a particular record. 各レコードには、次の要素が必要です。Each record is required to have the following elements:

  • 特定のレコードの一意の識別子である recordId メンバー。A recordId member that is the unique identifier for a particular record. エンリッチャーが結果を返すとき、呼び出し元がレコード結果を入力とマッチさせることができるように、この recordId を提供する必要があります。When your enricher returns the results, it must provide this recordId in order to allow the caller to match the record results to their input.

  • data メンバー。基本的には各レコードの入力フィールドのバッグ。A data member, which is essentially a bag of input fields for each record.

具体的には、上の例では Web API が次のような要求を想定します。To be more concrete, per the example above, your Web API should expect requests that look like this:

{
    "values": [
      {
        "recordId": "a1",
        "data":
           {
             "contractText": 
                "This is a contract that was issues on November 3, 2017 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 つのレコードだけでなく、数百または数千のレコードでサービスが呼び出されることがあります。In reality, your service may get called with hundreds or thousands of records instead of only the three shown here.

2.Web API の出力形式2. Web API Output Format

出力の形式は、recordId を含むレコードのセット、およびプロパティ バッグですThe format of the output is a set of records containing a recordId, and a property bag

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

この特定の例では出力が 1 つしかありませんが、複数のプロパティを出力することができます。This particular example has only one output, but you could output more than one property.

エラーと警告Errors and Warning

前の例で示されていたように、レコードごとにエラー メッセージと警告メッセージを返すことができます。As shown in the previous example, you may return error and warning messages for each record.

スキルセットのカスタム スキルの使用Consuming custom skills from skillset

Web API エンリッチャーを作成すると、HTTP ヘッダーとパラメーターを要求の一部として記述できます。When you create a Web API enricher, you can describe HTTP headers and parameters as part of the request. 次のスニペットは、要求パラメーターと "オプションの" HTTP ヘッダーをスキルセット定義の一部として記述する方法を示しています。The snippet below shows how request parameters and optional HTTP headers may be described as part of the skillset definition. HTTP ヘッダーは要件ではありませんが、これを使用すると、追加の構成機能をスキルに追加して、スキルセット定義から設定できます。HTTP headers are not a requirement, but they allow you to add additional configuration capabilities to your skill and to set them from the skillset definition.

{
    "skills": [
      {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "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"
          }
        ]
      }
  ]
}

次のステップNext steps

この記事では、カスタム スキルをスキルセットに統合するために必要なインターフェイス要件について説明しました。This article covered the interface requirements necessary for integrating a custom skill into a skillset. カスタム スキルとスキルセットの構成の詳細については、次のリンクをクリックしてください。Click the following links to learn more about custom skills and skillset composition.