Azure AI Search でスキルセットを作成する

[アーティクル]
03/14/2024

スキルセットでは、画像または非構造化テキストを含むドキュメントからテキストコンテンツと構造を生成する操作を定義します。たとえば、画像の OCR、未区分のテキストのエンティティ認識、テキスト翻訳などです。スキルセットは、テキストと画像が外部データソースから抽出された後、フィールドマッピングが処理された後に実行されます。

この記事では、REST API を使用してスキルセットを作成する方法について説明しますが、同じ概念と手順が他のプログラミング言語にも適用されます。

スキルセット定義の規則は次のとおりです。

スキルセットコレクション内で一意の名前。スキルセットは、任意のインデクサーで使用できる最上位レベルのリソースです。
少なくとも 1 つのスキル。 3 から 5 個のスキルが一般的です。最大数は 30 です。
スキルセットは、同じ種類のスキル (たとえば、複数の Shaper スキル) を繰り返すことができます。
スキルセットは、チェーンされた操作、ループ、分岐をサポートします。

インデクサーはスキルセットの実行を推進します。スキルセットをテストする前に、インデクサー、データソース、インデックスが必要です。

ヒント

エンリッチメントキャッシングを有効にすることで、既に処理したコンテンツを再利用し、開発コストを削減することができます。

スキルセットの定義の追加

基本構造から開始します。スキルセットの作成 REST API では、要求の本文は JSON で作成され、次のセクションがあります。

{
   "name":"skillset-template",
   "description":"A description makes the skillset self-documenting (comments aren't allowed in JSON itself)",
   "skills":[
       
   ],
   "cognitiveServices":{
      "@odata.type":"#Microsoft.Azure.Search.CognitiveServicesByKey",
      "description":"An Azure AI services resource in the same region as Azure AI Search",
      "key":"<Your-Cognitive-Services-Multiservice-Key>"
   },
   "knowledgeStore":{
      "storageConnectionString":"<Your-Azure-Storage-Connection-String>",
      "projections":[
         {
            "tables":[ ],
            "objects":[ ],
            "files":[ ]
         }
      ]
    },
    "encryptionKey":{ }
}

名前と説明の後には、スキルセットに以下の 4 つの主要なプロパティがあります。

skills 配列、順序なしスキルのコレクション。スキルには、実用的なもの (テキストの分割など)、変革をもたらすもの (Azure AI サービスの AI をベースにしたもの)、ユーザーが提供するカスタムスキルなどがあります。次のセクションでは、スキル配列の例を示しています。
cognitiveServices は、Azure AI サービス API を呼び出す課金対象のスキルに使用されます。課金対象のスキルやカスタムエンティティの参照を使用していない場合は、このセクションを削除します。使用している場合はリソースをアタッチします。
knowledgeStore (省略可能) が Azure Storage のテーブル、BLOB、およびファイルにスキルセットの出力を投影するための Azure Storage アカウントと設定を指定します。不要な場合は、このセクションを削除します。それ以外の場合は、ナレッジストアを指定します。
encryptionKey (省略可能) がスキルセット定義で機微な内容 (説明、接続文字列、キー) を暗号化するために使用される Azure Key Vault およびユーザーが管理するキーを指定します。ユーザーが管理する暗号化を使用していない場合は、このプロパティを削除します。

スキルを追加する

スキルセット定義内では、実行するスキルをスキル配列で指定します。 3 ~ 5 のスキルが一般的ですが、サービスの制限に従って、必要な数のスキルを追加できます。

エンリッチメントパイプラインの最終結果は、検索インデックスまたはナレッジストアのいずれかのテキストコンテンツです。このため、ほとんどのスキルは画像 (OCR テキスト、キャプション、タグ) からテキストを作成するか、既存のテキストを分析して新しい情報 (エンティティ、キーフレーズ、センチメント) を作成します。独立して動作するスキルは、並列に処理されます。相互に依存するスキルは、1 つのスキル (キーフレーズなど) の出力を 2 番目のスキル (テキスト翻訳など) の入力として指定します。検索サービスは、スキルの実行順序と実行環境を決定します。

すべてのスキルには、型、コンテキスト、入力、出力があります。スキルには、必要に応じて名前と説明が含まれることがあります。次の例は、基本構造を比較できるように、2 つの関連のない組み込みスキルを示しています。

"skills": [
    {
        "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
        "name": "#1",
        "description": "This skill detects organizations in the source content",
        "context": "/document",
        "categories": [
            "Organization"
        ],
        "inputs": [
            {
                "name": "text",
                "source": "/document/content"
            }
        ],
        "outputs": [
            {
                "name": "organizations",
                "targetName": "orgs"
            }
        ]
    },
    {
        "name": "#2",
        "description": "This skill detects corporate logos in the source files",
        "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
        "context": "/document/normalized_images/*",
        "visualFeatures": [
            "brands"
        ],
        "inputs": [
            {
                "name": "image",
                "source": "/document/normalized_images/*"
            }
        ],
        "outputs": [
            {
                "name": "brands"
            }
        ]
    }
]

各スキルは、入力値とそれに必要なパラメーターに関して一意です。スキル参照ドキュメントには、特定のスキルのすべてのパラメータとプロパティが記載されています。違いはありますが、ほとんどのスキルは共通のセットを共有し、同様のパターンになっています。

Note

条件付きスキルを使用して式を作成すると、ループや分岐が含まれる複雑なスキルセットを構築できます。構文では、いくつかの修正が加えられた JSON ポインターパス表記を使用して、強化ツリー内のノードを識別します。 "/" ではツリー内の下位レベルが走査され、"*" はコンテキストでの for-each 演算子として機能します。この記事の多くの例は、構文を示しています。

スキルコンテキストを設定する

各スキルには、操作を実行するレベルを決定するコンテキストプロパティがあります。 "context" プロパティが明示的に設定されていない場合、既定値は "/document"、コンテキストはドキュメント全体になります (スキルはドキュメントごとに 1 回呼び出されます)。

"skills":[
  {
    "@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
    "context": "/document",
    "inputs": [],
    "outputs": []
  },
  {
      "@odata.type": "#Microsoft.Skills.Vision.ImageAnalysisSkill",
      "context": "/document/normalized_images/*",
      "visualFeatures": [],
      "inputs": [],
      "outputs": []
  }
]

コンテキストは通常、次のいずれかの例に設定されます。

コンテキストの例	説明
"context": "/document"	標準の入力と出力はドキュメントレベルです。
"context": "/document/pages/*"	センチメント分析などのいくつかのスキルは、より小さなテキストチャンクで機能を発揮します。大きなコンテンツフィールドをページまたは文に分割している場合は、各コンポーネント部分にコンテキストを重ねる必要があります。
"context": "/document/normalized_images/*"	画像コンテンツの場合、入力と出力は親ドキュメントの画像ごとに 1 つです。

また、コンテキストは、エンリッチメントツリーで出力が生成される場所を決定します。たとえば、Entity Recognition スキルは、"organizations" と呼ばれるプロパティを返し、orgs としてキャプチャされます。コンテキストが "/document" の場合には、"組織" ノードが "/document" の子として追加されます。その後、ダウンストリームスキルでこのノードを参照する場合、パスは "/document/orgs" になります。

入力を定義する

エンリッチされたドキュメントの読み取りと書き込みを行うスキル。スキル入力は、受信データの起点を指定します。多くの場合、エンリッチされたドキュメントのルートノードです。 BLOB の場合、一般的なスキル入力はドキュメントのコンテンツプロパティです。

各スキルのスキルリファレンスドキュメントには、スキルが消費できる入力が記載されています。各入力には、特定の入力を識別する "名前" と、エンリッチされたドキュメント内のデータの場所を指定する "ソース" があります。エンティティ認識スキルの例を次に示します。

"inputs": [
    {
        "name": "text", 
        "source": "/document/content"
    },
    {
        "name": "languageCode", 
        "source": "/document/language"
    }
]

スキルには複数の入力を含めることができます。 "name" は特定の入力です。エンティティ認識の場合、特定の入力は "text" と "languageCode" です。

"source" プロパティは、処理するコンテンツを提供するフィールドまたは行を指定します。テキストベースのスキルの場合、ソースはテキストを提供するドキュメントまたは行のフィールドです。イメージベースのスキルの場合、入力を提供するノードは正規化された画像です。

ソースの例	説明
"ソース": "/ドキュメント"	表形式データセットの場合、ドキュメントは行に対応します。
"source": "/document/content"	Blob の場合、ソースは通常、blob のコンテンツプロパティです。
"source": "/document/some-named-field"	エンティティ認識やキーフレーズ抽出などのテキストベースのスキルの場合、配信元は、"説明" や "概要" など、分析が十分なテキストを含むフィールドである必要があります。
"source": "/document/normalized_images/*"	イメージコンテンツの場合、ソースはドキュメント解析中に正規化されたイメージです。

スキルが配列を反復処理する場合、コンテキストと入力ソースの両方が正しい位置に/*を含める必要があります。

出力を定義する

各スキルは、スキルセット内で名前によって参照される特定の種類の出力を生成するように設計されています。スキルの出力には、"name" と省略可能な "targetName" があります。

各スキルのスキルリファレンスドキュメントには、スキルが生成できる出力が記載されています。エンティティ認識スキルの例を次に示します。

"outputs": [
    {
        "name": "persons", 
        "targetName": "people"
    },
    {
        "name": "organizations", 
        "targetName": "orgs"
    },
    {
        "name": "locations", 
        "targetName": "places"
    }
]

スキルには複数の出力を含めることができます。 "name" は、特定の出力を識別します。たとえば、エンティティ認識の場合、出力には "persons"、"locations"、"organizations"などがあります。
"targetName" は、このノードをエンリッチメントされたドキュメントに含める名前を指定します。これは、スキル出力の名前が同じである場合に便利です。同じ出力を返すスキルが複数ある場合は、エンリッチメントノードパスでの名前のあいまいさを解消するために "targetName" を使用します。ターゲット名が指定されていない場合、name プロパティは両方に使用されます。

状況によっては、配列の各要素を別々に参照する必要があります。たとえば、"/document/orgs" の各要素を別のスキルに別々に渡す必要があるとします。これを行うには、パス "/document/orgs/*" にアスタリスクを追加します。

スキルの出力は、エンリッチメントツリーの新しいノードとしてエンリッチメントされたドキュメントに書き込まれます。センチメントスコアや言語コードなど、単純な値である可能性があります。コレクション (組織、ユーザー、場所の一覧など) でもかまいません。スキルの出力は、Shaper スキルの場合と同様に、複雑な構造にすることもできます。スキルの入力によって図形の構成が決まりますが、出力は名前付きオブジェクトであり、検索インデックス、ナレッジストアプロジェクション、または別のスキルでその名前で参照できます。

カスタムスキルを追加する

このセクションには、カスタムスキルの例が含まれています。 URI は Azure 関数を指します。これにより、指定したモデルまたは変換が呼び出されます。詳細については、カスタムインターフェイスの定義に関するページを参照してください。

カスタムスキルは、パイプラインの外部にあるコードを実行していますが、スキル配列では、もう 1 つのスキルに過ぎません。組み込みのスキルと同様に、型、コンテキスト、入力、および出力があります。また、組み込みのスキルと同様に、エンリッチメントツリーの読み取りと書き込みも行います。 "context" フィールドが、アスタリスク付きで "/document/orgs/*" に設定されていることに注目してください。これは、エンリッチメントステップが"/document/orgs" の下にある組織 "ごと" に呼び出されることを意味します。

この例の会社の説明などの出力は、特定された組織ごとに生成されます。ダウンストリームのステップ (キーフレーズの抽出など) で説明を参照するときは、パス "/document/orgs/*/companyDescription" を使用して実行します。

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "This skill calls an Azure function, which in turn calls custom code",
  "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/InvokeCode?code=foo",
  "httpHeaders": {
      "Ocp-Apim-Subscription-Key": "foobar"
  },
  "context": "/document/orgs/*",
  "inputs": [
    {
      "name": "query",
      "source": "/document/orgs/*"
    }
  ],
  "outputs": [
    {
      "name": "description",
      "targetName": "companyDescription"
    }
  ]
}

出力先に出力を送信する

スキルの出力は必要に応じて再利用のためにキャッシュできますが、通常は一時的なもので、スキルの実行が進行中にのみ存在します。

検索インデックスのフィールドに出力を送るには、インデクサーで出力フィールドマッピングを作成します。
出力をナレッジストアに送るには、プロジェクションを作成します。
ダウンストリームスキルに出力を送信するには、ダウンストリームスキルの入力ソースプロパティで、ノード名 (例: "/document/organization") で出力を参照します。例については、「注釈の参照」を参照してください。

最初のスキルセットのヒント

データのインポート ウィザードを試してください。

ウィザードでは、最初の段階では困難になる可能性があるいくつかの手順が自動化されます。フィールドマッピングや出力フィールドマッピングなど、スキルセット、インデックス、インデクサーを定義します。また、使用している場合は、ナレッジストアでプロジェクションを定義します。 OCR や画像解析などの一部のスキルでは、ドキュメント解析中に分離された画像とテキストの内容を結合するユーティリティスキルがウィザードによって追加されます。

ウィザードの実行後、Azure portal 内の各オブジェクトを開いて、その JSON 定義を表示できます。
デバッグセッションを試して、ターゲットドキュメントに対してスキルセットの実行を呼び出し、スキルセットによって作成されるエンリッチメントされたドキュメントを調べます。入力と出力の設定と値を表示および変更できます。チュートリアル「チュートリアル: デバッグセッションを使用してスキルセットをデバッグする」から始めることをお勧めします。

次のステップ

コンテキストと入力ソースのフィールドは、エンリッチメントツリー内のノードへのパスです。次の手順として、エンリッチツリー内のノードのパス構文について説明します。

スキルセットで注釈を参照する