Azure AI Search でスキルセットを作成する
スキルセットでは、画像または非構造化テキストを含むドキュメントからテキスト コンテンツと構造を生成する操作を定義します。 たとえば、画像の光学式文字認識 (OCR)、未区分のテキストのエンティティ認識、テキスト翻訳などです。 スキルセットは、テキストと画像が外部データ ソースから抽出された後、フィールド マッピングが処理された後に実行されます。
この記事では、REST API を使用してスキルセットを作成する方法について説明しますが、同じ概念と手順が他のプログラミング言語にも適用されます。
スキルセット定義の規則は次のとおりです。
- スキルセット コレクション内で一意の名前を付ける必要があります。 スキルセットは、任意のインデクサーで使用できる最上位レベルのリソースです。
- 少なくとも 1 つのスキルが必要です。 3 から 5 個のスキルが一般的です。 最大数は 30 です。
- スキルセットでは、同じ種類のスキルを繰り返すことができます。 たとえば、1 つのスキルセットに複数の 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 を呼び出す課金対象のスキルに使用されます。 課金対象のスキルやカスタム エンティティの参照を使用していない場合は、このセクションを削除します。 使用する場合は、Azure AI マルチサービス リソースをアタッチします。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 演算子として機能します。 この記事の多くの例は、この構文を示しています。
スキル コンテキストを設定する
各スキルには、操作を実行するレベルを決定する コンテキスト プロパティ があります。 "/document"
プロパティが明示的に設定されていない場合、既定値は context
、コンテキストはドキュメント全体になります (スキルはドキュメントごとに 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
プロパティは通常、次のいずれかの例に設定されます。
コンテキストの例 | 説明 |
---|---|
context : /document |
標準の入力と出力はドキュメントレベルです。 |
context : /document/pages/* |
センチメント分析などのいくつかのスキルは、より小さなテキスト チャンクで機能を発揮します。 大きなコンテンツ フィールドをページまたは文に分割している場合は、各コンポーネント部分にコンテキストを重ねる必要があります。 |
context : /document/normalized_images/* |
画像コンテンツの場合、入力と出力は親ドキュメントの画像ごとに 1 つです。 |
また、コンテキストは、エンリッチメント ツリーで出力が生成される場所を決定します。 たとえば、Entity Recognition スキルは、organizations
と呼ばれるプロパティを返し、orgs
としてキャプチャされます。 コンテキストが "/document"
の場合には、organizations
ノードが "/document"
の子として追加されます。 その後、ダウンストリーム スキルでこのノードを参照する場合、パスは "/document/orgs"
です。
入力を定義する
エンリッチされたドキュメントの読み取りと書き込みを行うスキル。 スキル入力は、受信データの起点を指定します。 多くの場合、エンリッチされたドキュメントのルート ノードです。 BLOB の場合、一般的なスキル入力はドキュメントのコンテンツ プロパティです。
各スキルのスキルリファレンスドキュメントには、スキルが消費できる入力が記載されています。 各入力は、特定の入力を識別する name
と、エンリッチされたドキュメント内のデータの場所を指定する source
を持ちます。 エンティティ認識スキルの例を次に示します。
"inputs": [
{
"name": "text",
"source": "/document/content"
},
{
"name": "languageCode",
"source": "/document/language"
}
]
スキルには複数の入力を含めることができます。
name
は特定の入力です。 エンティティ認識の場合、特定の入力は text と languageCode です。source
プロパティは、処理するコンテンツを提供するフィールドまたは行を指定します。 テキストベースのスキルの場合、ソースはテキストを提供するドキュメントまたは行のフィールドです。 イメージ ベースのスキルの場合、入力を提供するノードは正規化された画像です。ソースの例 説明 source
:/document
表形式データ セットの場合、ドキュメントは行に対応します。 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 関数を指します。これにより、指定したモデルまたは変換が呼び出されます。 詳細については、「Azure AI 検索のエンリッチメント パイプラインにカスタム スキルを追加する」を参照してください。
カスタム スキルは、パイプラインの外部にあるコードを実行しますが、スキル配列では、もう 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 定義を表示できます。
デバッグ セッションを試して、ターゲット ドキュメントに対してスキルセットの実行を呼び出し、スキルセットによって作成されるエンリッチメントされたドキュメントを調べます。 入力と出力の設定と値を表示および変更できます。 チュートリアル「チュートリアル: デバッグ セッションを使用してスキルセットをデバッグする」から始めることをお勧めします。
次のステップ
コンテキストと入力ソースのフィールドは、エンリッチメント ツリー内のノードへのパスです。 次の手順として、エンリッチ ツリー内のノードのパス構文について説明します。