Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Wichtig
Diese API-Referenz gilt für eine Ältere Version. Informationen zur aktualisierten Referenzdokumentation finden Sie unter Rest-Vorgänge der Datenebene . Verwenden Sie den Filter oben links, um eine Version auszuwählen.
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 natürliche Sprachverarbeitung und andere Transformationen auf, z. B. Entitätserkennung, Schlüsselauszug, Blockierung von Text in logische Seiten, unter anderem.
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, aber sie ist nur innerhalb der Indexerverarbeitung funktionsfähig. Als high-level-Ressource können Sie ein Skillset einmal entwerfen und dann in mehreren Indexern darauf verweisen.
Sie können POST oder PUT für die Anforderung verwenden. Für beides 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 Serviceanfragen 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-Anreicherung. Eine kostenlose Ressource ist für die eingeschränkte Verarbeitung verfügbar, aber für größere oder häufigere Workloads ist eine abrechnende Cognitive Services-Ressource erforderlich.
URI-Parameter
| Parameter | BESCHREIBUNG |
|---|---|
| Dienstname | Erforderlich. Legen Sie dies auf den eindeutigen, benutzerdefinierten Namen Ihres Suchdiensts fest. |
| Skillset-Name | Erforderlich für den URI, wenn PUT verwendet wird. Der Name muss klein geschrieben sein, beginnt mit einem Buchstaben oder einer Zahl, hat keine Schrägstriche oder Punkte und darf maximal 128 Zeichen lang sein. Der Name muss mit einem Buchstaben oder einer Zahl beginnen, aber der Rest des Namens kann beliebige Buchstaben, Zahlen und Gedankenstriche enthalten, solange die Bindestriche nicht aufeinander folgen. |
| API-Version | Erforderlich. Eine Liste der unterstützten Versionen finden Sie unter API-Versionen . |
Anforderungsheader
In der folgenden Tabelle werden die erforderlichen und optionalen Anforderungsheader beschrieben.
| Felder | BESCHREIBUNG |
|---|---|
| Inhaltstyp | Erforderlich. Legen Sie dies auf application/json |
| API-Schlüssel | Optional, wenn Sie Azure-Rollen verwenden und ein Bearertoken auf der Anforderung bereitgestellt wird, andernfalls ist ein Schlüssel erforderlich. Erstellen von Anforderungen müssen einen api-key Header enthalten, der auf Ihren Administratorschlüssel festgelegt ist (im Gegensatz zu einem Abfrageschlüssel). Details finden Sie unter Herstellen einer Verbindung mit Azure AI Search mithilfe der Schlüsselauthentifizierung . |
Anfragekörper
Der Textkörper der Anforderung enthält die Definition des Skillset. Fähigkeiten sind entweder eigenständig oder durch Eingabeausgabezuordnungen verkettet, wobei die Ausgabe einer Transformation zu einer anderen Eingabe wird. Ein Skillset muss mindestens eine Fähigkeit haben. Es gibt keine theoretische Grenze für die maximale Anzahl von Fähigkeiten, aber drei bis fünf ist eine gemeinsame 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:
| Eigentum | BESCHREIBUNG |
|---|---|
| Name | Erforderlich. Der Name des Skillsets. Der Name muss klein geschrieben sein, beginnt mit einem Buchstaben oder einer Zahl, hat keine Schrägstriche oder Punkte und darf maximal 128 Zeichen lang sein. Der Name muss mit einem Buchstaben oder einer Zahl beginnen, aber der Rest des Namens kann beliebige Buchstaben, Zahlen und Gedankenstriche enthalten, solange die Bindestriche nicht aufeinander folgen. |
| Fähigkeiten | Eine Reihe von Fähigkeiten. Jede Fähigkeit hat einen odata.type, Name, Kontext und Eingabe- und Ausgabeparameter. Das Array kann integrierte Fähigkeiten und benutzerdefinierte Fähigkeiten umfassen. Mindestens eine Fähigkeit ist erforderlich. Wenn Sie einen Wissensspeicher verwenden, schließen Sie eine Shaper-Fähigkeit ein, es sei denn, Sie definieren das Daten-Shape innerhalb der Projektion. |
| cognitiveServices | Ein All-in-One-Schlüssel ist für abrechnende Fähigkeiten erforderlich, die cognitive Services-APIs täglich auf mehr als 20 Dokumente pro Indexer aufrufen. Der Schlüssel muss für eine Ressource in derselben Region wie der Suchdienst sein. Weitere Informationen finden Sie unter Anfügen einer Cognitive Services-Ressource. Wenn Sie die Fähigkeit zur benutzerdefinierten Entitätssuche verwenden, schließen Sie diesen Abschnitt und einen Schlüssel ein, um Transaktionen zu ermöglichen, die über 20 Transaktionen pro Indexer hinausgehen. Sie benötigen keinen Cognitive Services Key und können daher einen Abschnitt ausschließen cognitiveServices , wenn Ihr Skillset nur aus benutzerdefinierten Fähigkeiten, Hilfsfertigkeiten (Bedingt, Shaper, Textzusammenführung, Textteilung) oder dokumentextraktionsfertigen Fähigkeiten besteht. Wenn Sie Ihre angefügte kognitive Dienstressource aus einem Skillset entfernen möchten (um die "Standardgrenzwerte" zu verwenden), geben Sie @odata.type folgendes #Microsoft.Azure.Search.DefaultCognitiveServicesan: Weitere Informationen finden Sie in diesem Beispiel . |
| knowledgeStore | Wahlfrei. Ziel für die Anreicherungsausgabe in Azure Storage. Erfordert eine Verbindungszeichenfolge zu einem 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, filesdie entweder angegeben oder NULL sind.
tables
Erstellt eine oder mehrere Tabellen in Azure Table Storage, wobei Inhalte aus jedem Dokument als Zeilen in einer Tabelle projiziert werden. Jede Tabelle kann die folgenden drei Eigenschaften aufweisen:
objects
Projektet Dokumente als Blobs in Azure Blob Storage. Jedes Objekt verfügt über zwei erforderliche Eigenschaften:
files
Jeder Dateieintrag definiert die Speicherung binärer Bilder im Blob Storage. Dateiprojektionen weisen zwei erforderliche Eigenschaften auf:
|
| encryptionKey | Wahlfrei. Wird verwendet, um eine ruhende Definition mit Ihren eigenen Schlüsseln zu verschlüsseln, die in Ihrem Azure Key Vault verwaltet werden. Verfügbar für abrechnende Suchdienste, die am oder nach 2019-01-01 erstellt wurden.
Ein encryptionKey Abschnitt enthält einen benutzerdefinierten keyVaultKeyName (erforderlichen), vom System generierten keyVaultKeyVersion (erforderlich) und einen keyVaultUri bereitgestellten Schlüssel (erforderlich, auch als DNS-Name bezeichnet). Ein Beispiel-URI kann "https://my-keyvault-name.vault.azure.net"" sein.
Optional können Sie angeben accessCredentials , ob Sie keine verwaltete Systemidentität verwenden. Eigenschaften von accessCredentials Include applicationId (Microsoft Entra ID-Anwendungs-ID, die Zugriffsberechtigungen für Ihren angegebenen Azure Key Vault gewährt wurde) und applicationSecret (Authentifizierungsschlüssel der registrierten Anwendung). Ein Beispiel im nächsten Abschnitt veranschaulicht die Syntax. |
Antwort
Für eine erfolgreiche Anforderung sollte der Statuscode "201 Erstellt" angezeigt werden.
Standardmäßig enthält der Antworttext den JSON-Code für die erstellte Skillset-Definition. Wenn der Prefer Anforderungsheader jedoch auf "201 Erstellt" festgelegt return=minimalist, ist der Antworttext leer, und der Erfolgsstatuscode lautet "204 Kein Inhalt". Dies gilt unabhängig davon, ob PUT oder POST verwendet wird, um das Skillset zu erstellen.
Beispiele
Beispiel: Skillset, das Geschäftsentitäten und Stimmungen in Kundenrezensionen erkennt
Dieses Skillset verwendet zwei Fähigkeiten asynchron, unabhängig verarbeitet /document/content als zwei verschiedene Transformationen. Die Fähigkeiten sind Entitätserkennung und Stimmung. Stellt in der Anreicherungsstruktur /document/content die Inhalte (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 Ausgaben 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 eine vorgelagerte Shaper-Fähigkeit , die 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 die letzte Fähigkeit, verarbeitet zu werden.
{
"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 vom Kunden verwaltete Schlüssel, die für die zusätzliche Verschlüsselung vertraulicher Inhalte verwendet werden. In diesem Beispiel wird gezeigt, wie Sie die vom Kunden 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)"}
}
}