Vaardighedenset maken of bijwerken (REST API preview)
Van toepassing op: 2023-07-01-Preview, 2021-04-30-Preview
Belangrijk
2023-07-01-Preview (geen wijzigingen).
2021-04-30-Preview voegt ondersteuning voor beheerde identiteiten toe voor verbindingen met betrekking tot vaardighedensets:
- 'storageConnectionString' onder kennisarchief accepteert een Azure-resource-id voor Azure AD verificatie.
- 'identiteit' accepteert een door de gebruiker toegewezen beheerde identiteit. Deze eigenschap bevindt zich onder kennisarchief. Deze staat ook onder 'encryptionKey' voor het ophalen van een door de klant beheerde sleutel in Azure Key Vault.
Deze preview-API ondersteunt ook een beheerde identiteitsverbinding vanuit een aangepaste vaardigheid. Zie Naslaginformatie over aangepaste web-API's voor meer informatie.
Een vaardighedenset is een verzameling cognitieve vaardigheden die worden gebruikt voor AI-verrijking, met de optie om ook een extern kennisarchief te maken in Azure Storage. Vaardigheden roepen verwerking van natuurlijke taal en andere machine learning-processen aan, zoals entiteitsherkenning, sleuteltermextractie, het opdelen van tekst in logische pagina's, onder andere.
Er is een vaardighedenset 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, verrijking aan te roepen en uitvoer naar een index te verzenden. Een vaardighedenset is een resource op hoog niveau, maar deze is alleen operationeel binnen de verwerking van de indexeerfunctie. Als resource op hoog niveau kunt u ernaar verwijzen in meerdere indexeerfuncties.
U kunt POST of PUT gebruiken voor een create-aanvraag. Voor beide biedt de aanvraagbody de objectdefinitie.
POST https://[service name].search.windows.net/skillsets?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
Voor updateaanvragen gebruikt u PUT en geeft u de naam van de vaardighedenset op in de URI.
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 u een vaardighedenset maakt, wordt deze toegevoegd aan uw zoekservice.
Als u een vaardighedenset bijwerkt , wordt een bestaande vaardighedenset volledig overschreven met de inhoud van de nettolading van de aanvraag. Een best practice voor updates is om de definitie van de vaardighedenset op te halen met een GET, deze te wijzigen en vervolgens bij te werken met PUT.
Notitie
Vaardighedensets vormen de basis van AI-verrijking. Een gratis resource is beschikbaar voor beperkte verwerking, maar voor grotere of frequentere workloads moet een factureerbare Cognitive Services-resource worden gekoppeld.
URI-parameters
| Parameter | Beschrijving |
|---|---|
| servicenaam | Vereist. Stel deze eigenschap 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 kleine letters bevatten, beginnen met een letter of cijfer, geen schuine streepjes of punten hebben en minder dan 128 tekens bevatten. Nadat u de naam met een letter of cijfer hebt gestart, kan de rest van de naam alle letters, nummers en streepjes bevatten, mits de streepjes niet opeenvolgend zijn. |
| api-versie | Vereist. De huidige preview-versie is 2023-07-01-Preview. Zie API-versies voor meer versies. |
| disableCacheReprocessingChangeDetection | Optioneel (false standaard). Is van toepassing op updatescenario's en het gebruik van verrijkingen in de cache tijdens het uitvoeren van vaardighedensets. Stel in op true om te voorkomen dat bestaande documenten worden bijgewerkt op basis van de huidige actie, bijvoorbeeld als u een vaardighedenset wilt bijwerken zonder de vaardighedenset uit te voeren. Zie Evaluatie van vaardighedenset omzeilen voor meer informatie. |
Aanvraagheaders
In de volgende tabel worden de vereiste en optionele aanvraagheaders beschreven.
| Velden | Description |
|---|---|
| Content-Type | Vereist. Stel deze eigenschap in op application/json |
| api-key | Optioneel als u Azure-rollen gebruikt en er een Bearer-token is opgegeven voor de aanvraag, anders is een sleutel vereist. Een API-sleutel is een unieke, door het systeem gegenereerde tekenreeks die de aanvraag verifieert bij uw zoekservice. Create-aanvragen 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 kleine letters bevatten, beginnen met een letter of cijfer, geen schuine streepjes of punten hebben en minder dan 128 tekens bevatten. Nadat u de naam met een letter of cijfer hebt gestart, kan de rest van de naam alle letters, nummers en streepjes bevatten, mits de streepjes niet opeenvolgend zijn. |
| Vaardigheden | Een reeks vaardigheden. Elke vaardigheid heeft een odata.type, naam, context en invoer- en uitvoerparameters. Referentie voor vaardigheden vindt u in de conceptuele documentatie. De matrix kan ingebouwde vaardigheden en aangepaste vaardigheden bevatten. Er is ten minste één vaardigheid vereist. Als u een kennisarchief gebruikt, moet u een Shaper-vaardigheid opnemen, 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 aanroepen voor meer dan 20 documenten, per indexeerfunctie. De sleutel moet voor een resource in dezelfde regio zijn als de zoekservice. Zie Een Cognitive Services-resource koppelen voor meer informatie. U kunt de sleutel en deze sectie weglaten als uw vaardighedenset alleen bestaat uit aangepaste vaardigheden, gebruiksvaardigheden (voorwaardelijk, shaper, tekst samenvoegen, tekst splitsen) of de vaardigheid Documentextractie. Als u de vaardigheid Aangepaste entiteit opzoeken gebruikt, voegt u deze sectie en een sleutel toe om transacties meer dan 20 transacties per dag per indexeerfunctie in te schakelen. |
| knowledgeStore | Optioneel. Doel voor verrijkingsuitvoer naar Azure Storage. Vereist een verbindingsreeks naar een Azure Storage-account en projecties. |
| encryptionKey | Optioneel. Wordt gebruikt voor het versleutelen van gevoelige gegevens in een vaardighedensetdefinitie met uw eigen sleutels, beheerd in uw Azure Key Vault. Zie Azure AI Search-versleuteling met door de klant beheerde sleutels in Azure Key Vault voor meer informatie. |
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 aanvraagheader Prefer echter is ingesteld op return=minimal, is de antwoordtekst leeg en is de successtatuscode '204 No Content' in plaats van '201 Created'. 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 met volledige toegang verbindingsreeks en vormgegeven invoer
Een kennisarchief vereist een verbindingsreeks naar een Azure Storage-account en projecties die bepalen of verrijkte inhoud in tabel- of blobopslag terechtkomt (als objecten of bestanden).
Projecties, met name tabelprojecties, vereisen een upstream Shaper-vaardigheid die knooppunten van 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. In een tabelprojectie bepalen knooppunten in de vaardigheid shaper de velden in de tabel.
{
"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": "DefaultEndpointsProtocol=https;AccountName=<storage-account-name>;AccountKey=<storage-account-key>;EndpointSuffix=core.windows.net;",
"projections": [
{
"tables": [
{ "tableName": "CustomerReviews", "generatedKeyName": "DocID", "source": "/document/shapeCustomerReviews" }
. . .
],
"objects": [ ],
"files": [ ]
}
]
}
"encryptionKey": { }
}
Voorbeeld: Verbindingen met behulp van een beheerde identiteit
Beheerde identiteiten kunnen worden gebruikt voor verbindingen met een kennisarchief en externe code van een aangepaste vaardigheid. In dit voorbeeld ziet u beide scenario's. Voor kennisarchief geeft de aanvullende eigenschap 'identiteit' een door de zoekservice toegewezen beheerde identiteit op die Azure AD gebruikt om de aanvraag te verifiëren. Als u 'identiteit' weglaat, wordt de door het systeem toegewezen beheerde identiteit van de zoekservice gebruikt. Als Azure AD de aanroeper wilt verifiëren, moet de zoekservice worden geconfigureerd voor een beheerde identiteit. De zoekidentiteit moet de machtiging Inzender voor opslagblobgegevens hebben om naar Azure Storage te kunnen schrijven.
Een aangepaste vaardigheid kan een beheerde identiteit gebruiken voor verificatie bij de Azure-functie of app die als host fungeert voor uw aangepaste code. Het bevat de eigenschap 'authResourceId' om aan te geven dat de verbinding wordt geverifieerd met behulp van een beheerde identiteit. De waarde van 'authResourceId' is de toepassings-id die is gemaakt door de Microsoft Identity-provider. Deze waarde wordt gebruikt voor het valideren van het verificatietoken dat is opgehaald door de indexeerfunctie en wordt samen met de aangepaste webvaardigheids-API-aanvraag verzonden.
{
"name": "reviews-ss",
"description": "A short description",
"skills":
[
{ ... },
{ ... },
{
"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"name": "sampleCustomSkill",
"description": "A custom skill that requests an access token for the application ID specified in authResourceID",
"context": "/document",
"uri": "https://[your-app-name].azurewebsites.net/api/EntitySearch",
"authResourceId": "api://xyz*****-****-****-****-********9876",
"batchSize": 4,
"degreeOfParallelism": null,
"inputs": [
{
"name": "text",
"source": "/document/content"
},
{
"name": "language",
"source": "/document/languageCode"
},
{
"name": "phraseList",
"source": "/document/keyphrases"
}
],
"outputs": [
{
"name": "<customSkillOutput>"
}
]
}
{
"@odata.type": "#Microsoft.Skills.Util.ShaperSkill",
"context": "/document/content",
"inputs": [ ... ],
"outputs": [ ...]
}
],
"cognitiveServices": { ... },
"knowledgeStore": {
"storageConnectionString": "ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Storage/storageAccounts/[storage account name]/;",
"identity": {
"@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
"userAssignedIdentity": "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[user identity name]",
"projections": [
{
"tables": [ ],
"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)"}
}
}
Definities
| Koppeling | Beschrijving |
|---|---|
| knowledgeStore | Configureert een verbinding met Azure Storage en projecteert verrijkte inhoud in de vorm van objecten, bestanden en tabellen voor het gebruik van kennisanalyse en gegevensverwerkingsscenario's. |
| encryptionKey | Hiermee configureert u een verbinding met Azure Key Vault voor door de klant beheerde versleuteling. |
knowledgeStore
Een kennisarchief is een opslagplaats met verrijkte gegevens die een vaardighedenset en AI-verrijkingspijplijn hebben gemaakt. Het bevindt zich in Azure Storage en bestaat uit gegevensprojecties in de vorm van objecten, bestanden en tabellen. Het wordt gebruikt voor niet-zoekscenario's, zoals kennisanalyse, gegevensverkenning in Power BI of als een gegevenssink voor meer downstreamverwerking door andere apps.
De verbinding met Azure Storage is een verbindingsreeks met volledige toegang die een sleutel bevat, of de opslagresource-id op voorwaarde dat de zoekservice wordt uitgevoerd onder een beheerde identiteit en een Azure-roltoewijzing heeft die schrijftoegang tot het eindpunt van het kennisarchief verleent.
| Kenmerk | Beschrijving |
|---|---|
| storageConnectionString | Vereist. Een tekenreeks in een van deze indelingen:"DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net""ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Storage/storageAccounts/[storage account name]/;" |
| identity | Optioneel. Het bevat een userAssignedIdentity van het type #Microsoft.Azure.Search.DataUserAssignedIdentity en geeft de door de gebruiker toegewezen beheerde identiteit van de zoekservice op. Deze eigenschap is afhankelijk storageConnectionString van de verbindingsreeks die een resource-id van uw opslagaccount opgeeft. Als de identity eigenschap null is, wordt de verbinding met een resource-id gemaakt met behulp van de door het systeem beheerde eigenschap. Als deze eigenschap is toegewezen aan het type #Microsoft.Azure.Search.DataNoneIdentity, wordt elke expliciete identiteit die eerder is opgegeven, gewist. |
| Projecties | Vereist. Een matrix met projecties bestaande uit tables, objects, files, die zijn opgegeven of null. |
Projecties
Projecties zijn definities van de gegevensstructuren in een kennisarchief. Alle namen zijn door de gebruiker gedefinieerd. U kunt een naamconventie gebruiken waarmee u gerelateerde inhoud in Azure Storage kunt identificeren.
| Kenmerk | Beschrijving |
|---|---|
| tabellen | Projecteert gegevensshapes in een of meer tabellen in Azure Table Storage, waarbij elementen uit elk document worden geprojecteerd in rijen in een tabel. Elke tabel kan de volgende drie eigenschappen hebben. name Eerst (vereist) bepaalt u de tabel die moet worden gemaakt of gebruikt in Azure Table Storage. Second ( generatedKeyName optioneel) is de naam van een kolom die een document uniek identificeert. Waarden voor deze kolom worden gegenereerd tijdens de verrijking. Als u deze weglaat, maakt de zoekservice een standaardsleutelkolom op basis van de tabelnaam. source Ten derde (vereist) is het pad naar een knooppunt van de verrijkingsstructuur dat de vorm van de projectie vormt. Dit is meestal de uitvoer van een Shaper-vaardigheid. Paden beginnen met /document/, die het verrijkte hoofddocument vertegenwoordigen en worden vervolgens uitgebreid naar /document/<shaper-output>/, of /document/content/, of een ander knooppunt in de verrijkingsstructuur. Voorbeelden: /document/countries/* (alle landen) of /document/countries/*/states/* (alle staten in alle landen). |
| Objecten | Projecteert documenten als blobs in Azure Blob Storage. Elk object heeft twee vereiste eigenschappen. storageContainer De eerste is de naam van de container die moet worden gemaakt of gebruikt in Azure Blob Storage. source Ten tweede is het pad naar het knooppunt van de verrijkingsstructuur dat de vorm van de projectie biedt. Dit moet een geldige JSON zijn. Het knooppunt moet een JSON-object leveren, hetzij van een vaardigheid die geldige JSON verzendt, hetzij de uitvoer van een Shaper-vaardigheid. |
| bestanden | Elke bestandsvermelding definieert de opslag van binaire afbeeldingen in Blob Storage. Bestandsprojecties hebben twee vereiste eigenschappen. storageContainer De eerste is de naam van de container die moet worden gemaakt of gebruikt in Azure Blob Storage. source Ten tweede is het pad naar het knooppunt van de verrijkingsboom die de hoofdmap van de projectie is. Een geldige waarde voor deze eigenschap is "/document/normalized_images/*" voor afbeeldingen die zijn opgehaald uit Blob Storage. |
encryptionKey
Hiermee configureert u een verbinding met Azure Key Vault voor aanvullende door de klant beheerde versleutelingssleutels (CMK). Versleuteling met door de klant beheerde sleutels is niet beschikbaar voor gratis services. Voor factureerbare services is deze alleen beschikbaar voor zoekservices die zijn gemaakt op of na 01-2019.
Een verbinding met de sleutelkluis moet worden geverifieerd. U kunt hiervoor accessCredentials of een beheerde identiteit gebruiken.
Beheerde identiteiten kunnen door het systeem of door de gebruiker zijn toegewezen (preview). Als de zoekservice zowel een door het systeem toegewezen beheerde identiteit als een roltoewijzing heeft die leestoegang tot de sleutelkluis verleent, kunt u zowel 'identiteit' als 'accessCredentials' weglaten en wordt de aanvraag geverifieerd met behulp van de beheerde identiteit. Als de zoekservice een door de gebruiker toegewezen identiteit en roltoewijzing heeft, stelt u de eigenschap 'identiteit' in op de resource-id van die identiteit.
| Kenmerk | Beschrijving |
|---|---|
| keyVaultKeyName | Vereist. Naam van de Azure Key Vault-sleutel die wordt gebruikt voor versleuteling. |
| keyVaultKeyVersion | Vereist. Versie van de Azure Key Vault-sleutel. |
| keyVaultUri | Vereist. URI van Azure Key Vault (ook wel DNS-naam genoemd) die de sleutel levert. Een voorbeeld van een URI kan zijn https://my-keyvault-name.vault.azure.net. |
| accessCredentials | Weglaten als u een beheerde identiteit gebruikt. Anders zijn de eigenschappen van accessCredentials include applicationId (een Azure Active Directory-toepassings-id met toegangsmachtigingen voor uw opgegeven Azure Key Vault) en applicationSecret (de verificatiesleutel van de opgegeven Azure AD toepassing). |
| identity | Optioneel, tenzij u een door de gebruiker toegewezen beheerde identiteit gebruikt voor de zoekserviceverbinding met Azure Key Vault. De indeling is "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]". |