Vaardighedenset maken (Azure AI Search REST API)
Een vaardighedenset is een verzameling cognitieve vaardigheden die worden gebruikt voor AI-verrijking, met een optionele specificatie voor het maken van een extern kennisarchief in Azure Storage. Vaardigheden roepen verwerking van natuurlijke taal en andere transformaties aan, zoals entiteitsherkenning, sleuteltermextractie, het indelen van tekst in logische pagina's, onder andere.
Een vaardighedenset is gekoppeld aan een indexeerfunctie. Als u de vaardighedenset wilt gebruiken, verwijst u ernaar in een indexeerfunctie en voert u de indexeerfunctie uit om gegevens te importeren, transformaties en verrijking aan te roepen en de uitvoervelden toe te wijzen aan een index. Een vaardighedenset is een resource op hoog niveau, maar is alleen operationeel binnen de verwerking van de indexeerfunctie. Als resource op hoog niveau kunt u eenmaal een vaardighedenset ontwerpen en er vervolgens naar verwijzen in meerdere indexeerfuncties.
U kunt POST of PUT voor de aanvraag gebruiken. Voor beide biedt het JSON-document in de aanvraagtekst de objectdefinitie.
PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
HTTPS is vereist voor alle serviceaanvragen. Als de vaardighedenset niet bestaat, wordt deze gemaakt. Als deze al bestaat, wordt deze bijgewerkt naar de nieuwe definitie.
Notitie
Vaardighedensets vormen de basis van AI-verrijking. Er is een gratis resource beschikbaar voor beperkte verwerking, maar voor grotere of frequentere workloads is een factureerbare Cognitive Services-resource vereist.
URI-parameters
| Parameter | Beschrijving |
|---|---|
| servicenaam | Vereist. Stel deze in op de unieke, door de gebruiker gedefinieerde naam van uw zoekservice. |
| naam van vaardighedenset | Vereist voor de URI als u PUT gebruikt. De naam moet uit kleine letters bestaan, beginnen met een letter of cijfer, geen schuine streepjes of punten hebben en uit minder dan 128 tekens bestaan. De naam moet beginnen met een letter of cijfer, maar de rest van de naam kan elke letter, cijfer en streepjes bevatten, zolang de streepjes niet opeenvolgend zijn. |
| api-versie | Vereist. Zie API-versies voor een lijst met ondersteunde versies. |
Aanvraagheaders
In de volgende tabel worden de vereiste en optionele aanvraagheaders beschreven.
| Velden | Description |
|---|---|
| Content-Type | Vereist. Stel dit in op application/json |
| api-sleutel | Optioneel als u Azure-rollen gebruikt en er een bearer-token wordt opgegeven voor de aanvraag, anders is een sleutel vereist. Maakaanvragen moeten een api-key header bevatten die is ingesteld op uw beheerderssleutel (in plaats van een querysleutel). Zie Verbinding maken met Azure AI Search met behulp van sleutelverificatie voor meer informatie. |
Aanvraagbody
De hoofdtekst van de aanvraag bevat de definitie van de vaardighedenset. Vaardigheden zijn zelfstandig of gekoppeld via invoer-uitvoerkoppelingen, waarbij de uitvoer van de ene transformatie wordt omgezet in invoer naar een andere. Een vaardighedenset moet ten minste één vaardigheid hebben. Er is geen theoretische limiet voor het maximum aantal vaardigheden, maar drie tot vijf is een algemene configuratie.
De volgende JSON is een weergave op hoog niveau van de belangrijkste onderdelen van de definitie.
{
"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) { }
}
Aanvraag bevat de volgende eigenschappen:
| Eigenschap | Beschrijving |
|---|---|
| naam | Vereist. De naam van de vaardighedenset. De naam moet uit kleine letters bestaan, beginnen met een letter of cijfer, geen schuine streepjes of punten hebben en uit minder dan 128 tekens bestaan. De naam moet beginnen met een letter of cijfer, maar de rest van de naam kan elke letter, cijfer en streepjes bevatten, zolang de streepjes niet opeenvolgend zijn. |
| Vaardigheden | Een reeks vaardigheden. Elke vaardigheid heeft een odata.type, naam, context en invoer- en uitvoerparameters. De matrix kan ingebouwde vaardigheden en aangepaste vaardigheden bevatten. Er is ten minste één vaardigheid vereist. Als u een kennisarchief gebruikt, neemt u een Shaper-vaardigheid op, tenzij u de gegevensshape in de projectie definieert. |
| cognitiveServices | Een alles-in-één-sleutel is vereist voor factureerbare vaardigheden die dagelijks Cognitive Services-API's op meer dan 20 documenten per indexeerfunctie aanroepen. De sleutel moet zijn voor een resource in dezelfde regio als de zoekservice. Zie Een Cognitive Services-resource bijvoegen voor meer informatie. Als u de vaardigheid Custom Entity Lookup gebruikt, voegt u deze sectie en een sleutel toe om transacties per dag meer dan 20 transacties per indexeerfunctie in te schakelen. U hebt geen Cognitive Services-sleutel nodig en kunt sectie dus uitsluiten cognitiveServices als uw vaardighedenset alleen bestaat uit aangepaste vaardigheden, hulpprogrammavaardigheden (voorwaardelijk, shaper, tekst samenvoegen, tekst splitsen) of de vaardigheid documentextractie. Als u de gekoppelde cognitive service-resource wilt verwijderen uit een vaardighedenset (om terug te keren naar het gebruik van de standaardlimieten), geeft u @odata.type op als #Microsoft.Azure.Search.DefaultCognitiveServices, raadpleegt u dit voorbeeld voor meer informatie. |
| knowledgeStore | Optioneel. Doel voor verrijkingsuitvoer naar Azure Storage. Vereist een verbindingsreeks naar een Azure Storage-account en projecties.
storageConnectionString (vereist) Een tekenreeks in deze indeling: "DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net".
projections (vereist) Een matrix van projectieobjecten die bestaan uit tables, objects, filesdie zijn opgegeven of null.
tables
Hiermee maakt u een of meer tabellen in Azure Table Storage en projecteert u inhoud van elk document als rijen in een tabel. Elke tabel kan de volgende drie eigenschappen hebben:
objects
Projecteert documenten als blobs in Azure Blob Storage. Elk object heeft twee vereiste eigenschappen:
files
Elke bestandsvermelding definieert de opslag van binaire afbeeldingen in Blob Storage. Bestandsprojecties hebben twee vereiste eigenschappen:
|
| encryptionKey | Optioneel. Wordt gebruikt om een definitie van een vaardighedenset at rest te versleutelen met uw eigen sleutels, beheerd in uw Azure Key Vault. Beschikbaar voor factureerbare zoekservices die zijn gemaakt op of na 01-01-2019.
Een encryptionKey sectie bevat een door de gebruiker gedefinieerde keyVaultKeyName (vereist), een door het systeem gegenereerde keyVaultKeyVersion (vereist) en een keyVaultUri die de sleutel verstrekt (vereist, ook wel DNS-naam genoemd). Een voorbeeld van een URI kan 'https://my-keyvault-name.vault.azure.net"' zijn.
U kunt desgewenst opgeven accessCredentials of u geen beheerde systeemidentiteit gebruikt. Eigenschappen van accessCredentials include applicationId (Microsoft Entra ID toepassings-id waaraan toegangsmachtigingen zijn verleend voor uw opgegeven Azure Key Vault) en applicationSecret (verificatiesleutel van de geregistreerde toepassing). Een voorbeeld in de volgende sectie illustreert de syntaxis. |
Antwoord
Voor een geslaagde aanvraag ziet u statuscode '201 Gemaakt'.
Standaard bevat de antwoordtekst de JSON voor de definitie van de vaardighedenset die is gemaakt. Als de Prefer aanvraagheader echter is ingesteld op return=minimal, is de antwoordtekst leeg en is de successtatuscode '204 Geen inhoud' in plaats van '201 gemaakt'. Dit geldt ongeacht of PUT of POST wordt gebruikt om de vaardighedenset te maken.
Voorbeelden
Voorbeeld: Vaardighedenset die zakelijke entiteiten en sentimenten herkent in klantbeoordelingen
Deze vaardighedenset maakt asynchroon gebruik van twee vaardigheden, die onafhankelijk worden verwerkt /document/content als twee verschillende transformaties. De vaardigheden zijn Entiteitsherkenning en Gevoel. Biedt in de verrijkingsstructuur /document/content de inhoud (of klantbeoordelingen) van de externe gegevensbron.
{
"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": { }
}
Voorbeeld: Kennisarchief
Een vaardighedenset kan desgewenst uitvoer verzenden naar het kennisarchief in Azure Storage. Hiervoor is een verbindingsreeks vereist voor een Azure Storage-account en projecties die bepalen of verrijkte inhoud in de tabel- of blobopslag terechtkomt (als objecten of bestanden). Voor projecties is meestal een upstream Shaper-vaardigheid vereist die knooppunten uit een verrijkingsstructuur als invoer verzamelt en één shape uitvoert die kan worden doorgegeven aan projectie. Een shaper is doorgaans de laatste vaardigheid die moet worden verwerkt.
{
"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": { }
}
Voorbeeld: Versleutelingssleutels
Versleutelingssleutels zijn door de klant beheerde sleutels die worden gebruikt voor aanvullende versleuteling van gevoelige inhoud. In dit voorbeeld ziet u hoe u door de klant beheerde versleuteling opgeeft voor een vaardighedenset.
{
"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)"}
}
}