Erstellen von Skillset (Azure AI 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 allgemeine Ressource, ist aber nur innerhalb der Indexerverarbeitung betriebsbereit. 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 nicht vorhanden ist, wird es erstellt. Wenn sie bereits vorhanden ist, wird sie auf die neue 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. Der Name muss mit einem Buchstaben oder einer Zahl beginnen, aber der Rest des Namens kann beliebige Buchstaben, Zahlen und Bindestriche enthalten, solange die Bindestriche nicht aufeinander folgen. |
| api-version | Erforderlich. Eine Liste der unterstützten 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 | Optional, wenn Sie Azure-Rollen verwenden und ein Bearertoken für die Anforderung bereitgestellt wird, andernfalls ist ein Schlüssel erforderlich. Erstellen von Anforderungen muss einen api-key Header enthalten, der auf Ihren Administratorschlüssel (im Gegensatz zu einem Abfrageschlüssel) festgelegt ist. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit Azure AI Search mithilfe der Schlüsselauthentifizierung . |
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. Es gibt keine theoretische Begrenzung für die maximale Anzahl von Qualifikationen, aber drei bis fünf ist eine gängige Konfiguration.
Der folgende JSON-Code ist eine allgemeine Darstellung des Standard Teile 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. Der Name muss mit einem Buchstaben oder einer Zahl beginnen, aber der Rest des Namens kann 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. Wenn Sie den Skill Benutzerdefinierte Entitätssuche verwenden, fügen Sie diesen Abschnitt und einen Schlüssel hinzu, um Transaktionen über 20 Transaktionen täglich pro Indexer zu aktivieren. Sie benötigen keinen Cognitive Services-Schlüssel und können daher den Abschnitt ausschließen cognitiveServices, wenn Ihr Skillset nur aus benutzerdefinierten Skills, Hilfsfähigkeiten (Bedingt, Shaper, Textzusammenführung, Textteilung) oder der Dokumentextraktion besteht. Wenn Sie Ihre angefügte Cognitive Service-Ressource aus einem Skillset entfernen möchten (um die Standardgrenzwerte zu rückgängig machen), geben Sie als #Microsoft.Azure.Search.DefaultCognitiveServicesan@odata.type. Weitere Informationen finden Sie in diesem Beispiel. |
| 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, der den Schlüssel bereitstellt (erforderlich, auch als DNS-Name bezeichnet). 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 (Microsoft Entra ID Anwendungs-ID, der Zugriffsberechtigungen für Die angegebene Azure-Key Vault gewährt wurden) und applicationSecret (Authentifizierungsschlüssel der registrierten 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=minimalfestgelegt ist, ist der Antworttext leer, und der Erfolgreiche status Code lautet "204 No Content" anstelle von "201 Created". 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 zu 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 Upstream 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)"}
}
}