Erstellen eines Skillsets (Azure Cognitive Search-REST-API)
Ein Skillset ist eine Sammlung von kognitiven Fähigkeiten , die für die KI-Anreicherung verwendet werden, mit einer optionalen Spezifikation zum Erstellen eines externen Wissensspeichers in Azure Storage. Fähigkeiten rufen Verarbeitung natürlicher Sprache und andere Transformationen auf, z. B. Entitätserkennung, Schlüsselbegriffsextraktion, Blöcken von Text in logische Seiten.
Ein Skillset ist an einen Indexer angefügt. Um das Skillset zu verwenden, verweisen Sie in einem Indexer darauf, und führen Sie dann den Indexer aus, um Daten zu importieren, Transformationen und Anreicherung aufzurufen und die Ausgabefelder einem Index zuzuordnen. Ein Skillset ist eine Ressource auf hoher Ebene, funktioniert aber nur innerhalb der Indexerverarbeitung. Da es sich um eine Ressource auf hoher Ebene handelt, können Sie ein Skillset einmal erstellen und dann in mehreren Indexern darauf verweisen.
Sie können entweder POST oder PUT für die Anforderung verwenden. Für beide stellt das JSON-Dokument im Anforderungstext die Objektdefinition bereit.
PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
HTTPS ist für alle Dienstanforderungen erforderlich. Wenn das Skillset noch nicht vorhanden ist, wird es erstellt. Wenn er bereits vorhanden ist, wird er mit der neuen Definition aktualisiert.
Hinweis
Skillsets sind die Grundlage der KI-Bereicherung. Eine kostenlose Ressource ist für begrenzte Verarbeitung verfügbar, aber für größere oder häufigere Workloads ist eine abrechenbare Cognitive Services-Ressource erforderlich.
URI-Parameter
| Parameter | Beschreibung |
|---|---|
| Dienstname | Erforderlich. Legen Sie dies auf den eindeutigen, benutzerdefinierten Namen Ihres Suchdiensts fest. |
| Skillsetname | Erforderlich für den URI, wenn PUT verwendet wird. Der Name muss klein geschrieben sein, mit einem Buchstaben oder einer Zahl beginnen, keine Schrägstriche oder Punkte aufweisen und weniger als 128 Zeichen lang sein. Nach dem Start des Namens mit einem Buchstaben oder einer Zahl kann der Rest des Namens beliebige Buchstaben, Zahlen und Bindestriche enthalten, solange die Bindestriche nicht aufeinander folgen. |
| api-version | Erforderlich. Die aktuelle stabile Version ist api-version=2020-06-30. Weitere Versionen finden Sie unter API-Versionen . |
Anforderungsheader
Die folgende Tabelle beschreibt die erforderlichen und optionalen Anforderungsheader.
| Felder | BESCHREIBUNG |
|---|---|
| Content-Type | Erforderlich. Auf application/json |
| api-key | Erforderlich. api-key wird zum Authentifizieren der Anforderung beim Search-Dienst verwendet. Es handelt sich um einen für Ihren Dienst eindeutigen Zeichenfolgewert. Erstellen von Anforderungen muss einen api-key Header enthalten, der auf Ihren Administratorschlüssel (im Gegensatz zu einem Abfrageschlüssel) festgelegt ist. Sie finden den API-Schlüssel in Ihrem Suchdienstdashboard im Azure-Portal. |
Anforderungstext
Der Text der Anforderung enthält die Skillsetdefinition. Skills sind entweder eigenständig oder durch Eingabe-Ausgabezuordnungen miteinander verkettet, wobei die Ausgabe einer Transformation zu einer Eingabe an eine andere wird. Ein Skillset muss mindestens einen Skill umfassen. Theoretisch gibt es keine Obergrenze für die Anzahl von Skills, drei bis fünf ist jedoch eine gängige Konfiguration.
Der folgende JSON-Code ist eine allgemeine Darstellung der Hauptteile der Definition.
{
"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) { }
}
Die Anforderung enthält die folgenden Eigenschaften:
| Eigenschaft | Beschreibung |
|---|---|
| name | Erforderlich. Der Name des Skillsets. Der Name muss klein geschrieben sein, mit einem Buchstaben oder einer Zahl beginnen, keine Schrägstriche oder Punkte aufweisen und weniger als 128 Zeichen lang sein. Nach dem Start des Namens mit einem Buchstaben oder einer Zahl kann der Rest des Namens beliebige Buchstaben, Zahlen und Bindestriche enthalten, solange die Bindestriche nicht aufeinander folgen. |
| skills | Eine Reihe von Fähigkeiten. Jeder Skill verfügt über odata.type, Name, Kontext sowie Eingabe- und Ausgabeparameter. Das Array kann integrierte Skills und benutzerdefinierte Fähigkeiten enthalten. Mindestens eine Qualifikation ist erforderlich. Wenn Sie einen Wissensspeicher verwenden, schließen Sie einen Shaper-Skill ein, es sei denn, Sie definieren das Daten-Shape innerhalb der Projektion. |
| cognitiveServices | Ein All-in-One-Schlüssel ist für abrechenbare Fähigkeiten erforderlich, die Cognitive Services-APIs täglich für mehr als 20 Dokumente pro Indexer aufrufen. Der Schlüssel muss sich für eine Ressource in derselben Region wie der Suchdienst befinden. Weitere Informationen finden Sie unter Anfügen einer Cognitive Services-Ressource. Sie können den Schlüssel und diesen Abschnitt weglassen, wenn Ihr Skillset nur aus benutzerdefinierten Fähigkeiten, Hilfsfertigkeiten (Bedingt, Shaper, Textzusammenführung, Textaufteilung) oder der Dokumentextraktion besteht. Wenn Sie den Skill Benutzerdefinierte Entitätssuche verwenden, schließen Sie diesen Abschnitt und einen Schlüssel ein, um Transaktionen über 20 Transaktionen täglich pro Indexer zu aktivieren. |
| knowledgeStore | Optional. Ziel für die Anreicherungsausgabe in Azure Storage. Erfordert eine Verbindungszeichenfolge für ein Azure Storage-Konto und Projektionen. storageConnectionString (erforderlich) Eine Zeichenfolge in diesem Format: "DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net". projections (erforderlich) Ein Array von Projektionsobjekten tables, die aus , objects, bestehen files, die entweder angegeben oder NULL sind. tablesErstellt eine oder mehrere Tabellen in Azure Table Storage und projiziert Inhalte aus jedem Dokument als Zeilen in einer Tabelle. Jede Tabelle kann die folgenden drei Eigenschaften aufweisen:
objectsProjiziert Dokumente als Blobs in Azure Blob Storage. Jedes Objekt verfügt über zwei erforderliche Eigenschaften:
filesJeder Dateieintrag definiert die Speicherung binärer Images in Blob Storage. Dateiprojektionen weisen zwei erforderliche Eigenschaften auf:
|
| encryptionKey | Optional. Wird verwendet, um eine Ruhezustandsdefinition mit Ihren eigenen Schlüsseln zu verschlüsseln, die in Ihrem Azure-Key Vault verwaltet werden. Verfügbar für abrechenbare Suchdienste, die am oder nach dem 01.01.2019 erstellt wurden. Ein encryptionKey Abschnitt enthält einen benutzerdefinierten keyVaultKeyName (erforderlich), einen systemgenerierten keyVaultKeyVersion (erforderlich) und einen keyVaultUri schlüssel (erforderlich, der auch als DNS-Name bezeichnet wird). Ein Beispiel-URI kann "https://my-keyvault-name.vault.azure.net"" sein. Optional können Sie angeben accessCredentials , wenn Sie keine verwaltete Systemidentität verwenden. Eigenschaften von accessCredentials umfassen applicationId (Azure Active Directory-Anwendungs-ID, der Zugriffsberechtigungen für Ihre angegebene Azure Key Vault gewährt wurden) und applicationSecret (Authentifizierungsschlüssel der angegebenen Azure AD-Anwendung). Ein Beispiel im nächsten Abschnitt veranschaulicht die Syntax. |
Antwort
Bei einer erfolgreichen Anforderung wird der Statuscode „201 – erstellt“ angezeigt.
Standardmäßig enthält der Antworttext das JSON-Schema für die erstellte Skillsetdefinition. Wenn der Prefer-Anforderungsheader jedoch auf „return=minimal“ festgelegt ist, ist der Antworttext leer und der Statuscode lautet „204 – kein Inhalt“ statt „201 – erstellt“. Dies gilt unabhängig davon, ob zum Erstellen des Skillsets eine PUT- oder eine POST-Anforderung verwendet wurde.
Beispiele
Beispiel: Skillset, das Geschäftsentitäten und Stimmungen in Kundenbewertungen erkennt
Dieses Skillset verwendet zwei Skills asynchron, unabhängig verarbeitet /document/content als zwei verschiedene Transformationen. Die Qualifikationen sind Entitätserkennung und Stimmung. Stellt in der Anreicherungsstruktur /document/content den Inhalt (oder Kundenrezensionen) aus der externen Datenquelle bereit.
{
"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": { }
}
Beispiel: Wissensspeicher
Ein Skillset kann optional eine Ausgabe an den Wissensspeicher in Azure Storage senden. Es erfordert eine Verbindungszeichenfolge mit einem Azure Storage-Konto und Projektionen , die bestimmen, ob angereicherte Inhalte in Tabellen- oder Blobspeicher (als Objekte oder Dateien) landen. Projektionen erfordern in der Regel einen Vorlauf-Shaper-Skill , der Knoten aus einer Anreicherungsstruktur als Eingabe sammelt und eine einzelne Form ausgibt, die an die Projektion übergeben werden kann. Ein Shaper ist in der Regel der letzte Skill, der verarbeitet werden soll.
{
"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": { }
}
Beispiel: Verschlüsselungsschlüssel
Verschlüsselungsschlüssel sind kundenseitig verwaltete Schlüssel, die für die zusätzliche Verschlüsselung vertraulicher Inhalte verwendet werden. In diesem Beispiel wird gezeigt, wie Sie die kundenseitig verwaltete Verschlüsselung für ein Skillset angeben.
{
"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)"}
}
}