スキルセットの作成 (Azure AI Search REST API)
スキルセットは、AI エンリッチメントに使用される コグニティブ スキル のコレクションであり、Azure Storage で外部ナレッジ ストアを作成するためのオプションの仕様が用意されています。 スキルは自然言語処理や、エンティティ認識、キー フレーズ抽出、テキストの論理ページへのチャンクなど、その他の変換を呼び出します。
スキルセットはイン デクサーにアタッチされます。 スキルセットを使用するには、インデクサーでそれを参照し、インデクサーを実行してデータをインポートし、変換とエンリッチメントを呼び出し、出力フィールドをインデックスにマップします。 スキルセットは高レベルのリソースですが、インデクサー処理内でのみ動作します。 スキルセットは高レベルのリソースであるため、一度設計すればその後は、複数のインデクサーで参照できます。
要求に対して POST または PUT を使用できます。 いずれの場合も、要求本文の JSON ドキュメントによってオブジェクト定義が提供されます。
PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
HTTPS はすべてのサービス要求に必要です。 スキルセットが存在しない場合は、作成されます。 既に存在する場合は、新しい定義に更新されます。
注意
スキルセットは AI エンリッチメントの基礎です。 制限付き処理には無料のリソースを使用できますが、より大規模または頻繁なワークロードでは、 課金対象の Cognitive Services リソース が必要です。
URI パラメーター
| パラメーター | 説明 |
|---|---|
| サービス名 | 必須。 これを検索サービスの一意のユーザー定義名に設定します。 |
| スキルセット名 | PUT を使用する場合は、URI で必須です。 名前は小文字で、文字または数字で始まり、スラッシュやドットがなく、128 文字未満である必要があります。 名前は文字または数字で始まる必要がありますが、ダッシュが連続していない限り、名前の残りの部分には任意の文字、数字、ダッシュを含めることができます。 |
| api-version | 必須。 サポートされている バージョンの 一覧については、「API のバージョン」を参照してください。 |
要求ヘッダー
次の表では、必須と省略可能の要求ヘッダーについて説明します。
| フィールド | 説明 |
|---|---|
| Content-Type | 必須。 これを application/json |
| api-key | Azure ロールを使用していて、要求にベアラー トークンが指定されている場合は省略可能。それ以外の場合はキーが必要です。 要求の作成には、(クエリ キーではなく) 管理キーに設定されたヘッダーを含める api-key 必要があります。 詳細については、「 キー認証を使用して Azure AI Search に接続 する」を参照してください。 |
要求本文
要求の本文には、スキルセット定義が含まれています。 スキルはスタンドアロンであるか、入力と出力の関連付けを介して連結されます。ここで、ある変換の出力が別の変換への入力になります。 1 つのスキルセットには、スキルが少なくとも 1 つ必要です。 スキルの最大数に理論的な制限はありませんが、3 から 5 が一般的な構成です。
次の JSON は、定義のメイン部分の大まかな表現です。
{
"name" : (optional on PUT; required on POST) "Name of the skillset",
"description" : (optional) "Anything you want, or nothing at all",
"skills" : (required) ["An array of skills. Each skill has an odata.type, name, input and output parameters"],
"cognitiveServices":
{
"@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
"description": "Optional. Anything you want, or null",
"key": "<YOUR-COGNITIVE-SERVICES-ALL-IN-ONE-KEY>"
},
"knowledgeStore": (optional) { ... },
"encryptionKey": (optional) { }
}
要求には次のプロパティが含まれます。
| プロパティ | 説明 |
|---|---|
| name | 必須。 スキルセットの名前。 名前は小文字で、文字または数字で始まり、スラッシュやドットがなく、128 文字未満である必要があります。 名前は文字または数字で始まる必要がありますが、ダッシュが連続していない限り、名前の残りの部分には任意の文字、数字、ダッシュを含めることができます。 |
| スキル | スキルの配列。 各スキルには、odata.type、名前、コンテキスト、および入力パラメーターと出力パラメーターがあります。 配列には、 組み込みのスキル と カスタム スキルを含めることができます。 少なくとも 1 つのスキルが必要です。 ナレッジ ストアを使用している場合は、プロジェクション内でデータ図形を定義しない限り、 Shaper スキル を含めます。 |
| cognitiveServices | インデクサーごとに毎日 20 を超えるドキュメントに対してCognitive Services APIsを呼び出す課金対象スキルには、オールインワン キーが必要です。 キーは、検索サービスと同じリージョン内のリソース用である必要があります。 詳細については、「 Cognitive Services リソースをアタッチする」を参照してください。 カスタム エンティティ参照スキルを使用している場合は、このセクションと、インデクサーごとに毎日 20 トランザクションを超えるトランザクションを有効にするキーを含めます。 Cognitive Services キーは必要ありません。そのため、スキルセットがカスタム スキル、ユーティリティ スキル (条件付き、シェーパー、テキストマージ、テキスト分割)、またはドキュメント抽出スキルのみで構成されている場合は、セクションを除外 cognitiveServicesできます。スキルセットからアタッチされたコグニティブ サービス リソースを削除する場合 ("既定" の制限を使用して元に戻すには) として #Microsoft.Azure.Search.DefaultCognitiveServicesを指定@odata.typeします。詳細については、この例を参照してください。 |
| knowledgeStore | 省略可能。 Azure Storage へのエンリッチメント出力の宛先。 Azure Storage アカウントとプロジェクションへの接続文字列が必要です。 storageConnectionString (必須)次の形式の文字列: "DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net"。 projections(必須)、 で構成されるプロジェクション オブジェクトのtablesobjectsfiles配列。これは、指定または null です。 tablesAzure Table Storage に 1 つ以上のテーブルを作成し、各ドキュメントの内容をテーブル内の行として投影します。 各テーブルには、次の 3 つのプロパティを含めることができます。
objectsAzure Blob Storageの BLOB としてドキュメントをプロジェクトします。 各オブジェクトには、次の 2 つの必須プロパティがあります。
files各ファイル エントリは、Blob Storage 内のバイナリ イメージのストレージを定義します。 ファイル プロジェクションには、次の 2 つの必須プロパティがあります。
|
| encryptionKey | 省略可能。 Azure Key Vaultで管理されている、独自のキーを使用して保存中のスキルセット定義を暗号化するために使用されます。 2019-01-01 以降に作成された課金対象の検索サービスで使用できます。 encryptionKeyセクションには、ユーザー定義 keyVaultKeyName (必須)、システムによって生成された keyVaultKeyVersion (必須)、キーkeyVaultUriを提供する (必須、DNS 名とも呼ばれます) が含まれます。 URI の例としては、"https://my-keyvault-name.vault.azure.net"" があります。 必要に応じて、マネージド システム ID を使用していないかどうかを指定 accessCredentials できます。 のaccessCredentialsプロパティには、指定した Azure Key Vaultへのアクセス許可が付与されたアプリケーション ID Microsoft Entra ID)、および applicationSecret (登録済みアプリケーションの認証キー) が含まれますapplicationId。 次のセクションの例は、構文を示しています。 |
Response
要求が成功した場合は、状態コード "201 Created" が表示されます。
既定では、応答本文には作成されたスキルセット定義の JSON が含まれます。 ただし、要求ヘッダーが にreturn=minimal設定されている場合Prefer、応答本文は空で、成功状態コードは "201 Created" ではなく "204 No Content" です。 これは、スキルセットを作成するのに PUT または POST のどちらが使用されかに関わらず同じです。
例
例: 顧客レビューでビジネス エンティティとセンチメントを認識するスキルセット
このスキルセットは、2 つの異なる変換として個別に処理 /document/content する 2 つのスキルを非同期的に使用します。 スキルは エンティティ認識 と センチメントです。 エンリッチメント ツリーで、 /document/content 外部データ ソースのコンテンツ (または顧客レビュー) を提供します。
{
"name": "reviews-ss",
"description":
"Extract company names from customer reviews, and detect positive or negative sentiment from the same reviews.",
"skills":
[
{
"@odata.type": "#Microsoft.Skills.Text.V3.EntityRecognitionSkill",
"context": "/document/content",
"categories": [ "Organization" ],
"defaultLanguageCode": "en",
"inputs": [
{
"name": "text",
"source": "/document/content"
}
],
"outputs": [
{
"name": "organizations",
"targetName": "companyName"
}
]
},
{
"@odata.type": "#Microsoft.Skills.Text.V3.SentimentSkill",
"inputs": [
{
"name": "text",
"source": "/document/content"
},
{
"name": "languageCode",
"source": "/document/languageCode"
}
],
"outputs": [
{
"name": "sentiment",
"targetName": "reviewSentiment"
},
{
"name": "confidenceScores",
"targetName": "sentimentScore"
}
]
}
],
"cognitiveServices":
{
"@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
"description": "mycogsvcs resource in West US 2",
"key": "<your cognitive services all-in-one key goes here>"
},
"knowledgeStore": { },
"encryptionKey": { }
}
例: ナレッジ ストア
スキルセットは、必要に応じて Azure Storage の ナレッジ ストア に出力を送信できます。 これには、Azure Storage アカウントへの接続文字列と、エンリッチされたコンテンツが (オブジェクトまたはファイルとして) テーブルまたは BLOB ストレージに格納されるかどうかを決定するプロジェクションが必要です。 通常、プロジェクションには、エンリッチメント ツリーからノードを入力として収集し、プロジェクションに渡すことができる 1 つの図形を出力するアップストリーム の Shaper スキル が必要です。 通常、シェーパーは最後に処理されるスキルです。
{
"name": "reviews-ss",
"description":
"Extract company names from customer reviews, and detect positive or negative sentiment from the same reviews.",
"skills":
[
{ ... },
{ ... },
{
"@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
"context": "/document/content",
"inputs": [
{
"name": "Company",
"source": "/document/content/companyName"
},
{
"name": "Sentiment_Score",
"source": "/document/content/sentimentScore"
},
{
"name": "Sentiment_Label",
"source": "/document/content/reviewSentiment"
}
],
"outputs": [
{
"name": "output",
"targetName": "shapeCustomerReviews"
}
]
}
],
"cognitiveServices":
{
"@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
"description": "mycogsvcs resource in West US 2",
"key": "<your cognitive services all-in-one key goes here>"
},
"knowledgeStore": {
"storageConnectionString": "<your storage account connection string>",
"projections": [
{
"tables": [
{ "tableName": "CustomerReviews", "generatedKeyName": "DocID", "source": "/document/shapeCustomerReviews" }
. . .
],
"objects": [ ],
"files": [ ]
}
]
}
"encryptionKey": { }
}
例: 暗号化キー
暗号化キーは、機密性の 高いコンテンツの追加の暗号化 に使用されるカスタマー マネージド キーです。 この例では、スキルセットでカスタマー マネージド暗号化を指定する方法を示します。
{
"name": "reviews-ss",
"description": "A brief description of the skillset",
"skills": [ omitted for brevity ],
"cognitiveServices": { omitted for brevity },
"knowledgeStore": { omitted for brevity },
"encryptionKey": (optional) {
"keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
"keyVaultKeyVersion": "Version of the Azure Key Vault key",
"keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
"accessCredentials": (optional, only if not using managed system identity) {
"applicationId": "Azure Active Directory Application ID that was granted access permissions to your specified Azure Key Vault",
"applicationSecret": "Authentication key of the specified Azure AD application)"}
}
}