Skapa kompetensuppsättning (REST API för Azure AI Search)
En kompetensuppsättning är en samling kognitiva färdigheter som används för AI-berikning, med en valfri specifikation för att skapa ett externt kunskapslager i Azure Storage. Kunskaper anropar bearbetning av naturligt språk och andra omvandlingar, till exempel entitetsigenkänning, extrahering av nyckelfraser, segmentering av text i logiska sidor, bland annat.
En kompetensuppsättning är kopplad till en indexerare. Om du vill använda kompetensuppsättningen refererar du till den i en indexerare och kör sedan indexeraren för att importera data, anropa transformeringar och berikning och mappa utdatafälten till ett index. En kompetensuppsättning är en resurs på hög nivå, men den fungerar bara inom indexerarens bearbetning. Som en resurs på hög nivå kan du utforma en kompetensuppsättning en gång och sedan referera till den i flera indexerare.
Du kan använda POST eller PUT på begäran. För någon av dem innehåller JSON-dokumentet i begärandetexten objektdefinitionen.
PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
HTTPS krävs för alla tjänstbegäranden. Om kompetensuppsättningen inte finns skapas den. Om den redan finns uppdateras den till den nya definitionen.
Anteckning
Kompetensuppsättningar är grunden för AI-berikning. En kostnadsfri resurs är tillgänglig för begränsad bearbetning, men för större eller mer frekventa arbetsbelastningar krävs en fakturerbar Cognitive Services-resurs .
URI-parametrar
| Parameter | Beskrivning |
|---|---|
| tjänstnamn | Krävs. Ange det unika, användardefinierade namnet på söktjänsten. |
| kompetensuppsättningens namn | Krävs på URI:n om du använder PUT. Namnet måste vara gemener, börja med en bokstav eller ett tal, ha inga snedstreck eller punkter och vara färre än 128 tecken. Namnet måste börja med en bokstav eller ett tal, men resten av namnet kan innehålla valfri bokstav, siffra och bindestreck, så länge bindestrecken inte är i följd. |
| api-version | Krävs. En lista över versioner som stöds finns i API-versioner . |
Rubriker för begäran
I följande tabell beskrivs nödvändiga och valfria begärandehuvuden.
| Fält | Description |
|---|---|
| Content-Type | Krävs. Ange detta till application/json |
| api-key | Valfritt om du använder Azure-roller och en ägartoken anges på begäran, annars krävs en nyckel. Skapa begäranden måste innehålla en api-key rubrik inställd på din administratörsnyckel (till skillnad från en frågenyckel). Mer information finns i Ansluta till Azure AI Search med nyckelautentisering . |
Begärandetext
Brödtexten i begäran innehåller kompetensuppsättningsdefinitionen. Färdigheter är antingen fristående eller sammanlänkade via indatautdataassociationer, där utdata från en transformering blir indata till en annan. En kompetensuppsättning måste ha minst en färdighet. Det finns ingen teoretisk gräns för maximalt antal färdigheter, men tre till fem är en vanlig konfiguration.
Följande JSON är en övergripande representation av definitionens huvuddelar.
{
"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) { }
}
Begäran innehåller följande egenskaper:
| Egenskap | Beskrivning |
|---|---|
| name | Krävs. Namnet på kompetensuppsättningen. Namnet måste vara gemener, börja med en bokstav eller ett tal, ha inga snedstreck eller punkter och vara färre än 128 tecken. Namnet måste börja med en bokstav eller ett tal, men resten av namnet kan innehålla valfri bokstav, siffra och bindestreck, så länge bindestrecken inte är i följd. |
| Färdigheter | En matris med färdigheter. Varje färdighet har parametrarna odata.type, name, context och input och output. Matrisen kan innehålla inbyggda färdigheter och anpassade färdigheter. Minst en färdighet krävs. Om du använder ett kunskapslager ska du inkludera en Shaper-färdighet om du inte definierar dataformen i projektionen. |
| cognitiveServices | En allt-i-ett-nyckel krävs för fakturerbara färdigheter som anropar API:er för Cognitive Services på fler än 20 dokument dagligen, per indexerare. Nyckeln måste vara för en resurs i samma region som söktjänsten. Mer information finns i Koppla en Cognitive Services-resurs. Om du använder färdigheten Anpassad entitetsökning inkluderar du det här avsnittet och en nyckel för att aktivera transaktioner utöver 20 transaktioner dagligen per indexerare. Du behöver inte Cognitive Services-nyckeln och kan därför exkludera cognitiveServices avsnitt om din kompetensuppsättning endast består av anpassade färdigheter, verktygskunskaper (villkorsstyrd, formning, textsammanslagning, textdelning) eller kunskapen för dokumentextrahering. Om du vill ta bort din anslutna cognitive service-resurs från en kompetensuppsättning (för att återgå till att använda standardgränserna) anger du @odata.type som #Microsoft.Azure.Search.DefaultCognitiveServices, Mer information finns i det här exemplet . |
| knowledgeStore | Valfritt. Mål för berikande utdata till Azure Storage. Kräver en anslutningssträng till ett Azure Storage-konto och projektioner.
storageConnectionString (krävs) En sträng i det här formatet: "DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net".
projections (krävs) En matris med projektionsobjekt som består av tables, objects, files, som antingen är angivna eller null.
tables
Skapar en eller flera tabeller i Azure Table Storage och projicerar innehåll från varje dokument som rader i en tabell. Varje tabell kan ha följande tre egenskaper:
objects
Projicerar dokument som blobar i Azure Blob Storage. Varje objekt har två obligatoriska egenskaper:
files
Varje filpost definierar lagring av binära avbildningar i Blob Storage. Filprojektioner har två egenskaper som krävs:
|
| encryptionKey | Valfritt. Används för att kryptera en kompetensuppsättningsdefinition i vila med dina egna nycklar som hanteras i azure-Key Vault. Tillgängligt för fakturerbara söktjänster som skapats på eller efter 2019-01-01.
Ett encryptionKey avsnitt innehåller en användardefinierad keyVaultKeyName (obligatorisk), ett systemgenererat (obligatoriskt keyVaultKeyVersion ) och en keyVaultUri som tillhandahåller nyckeln (krävs, även kallat DNS-namn). Ett exempel på URI kan vara "https://my-keyvault-name.vault.azure.net".
Du kan också ange accessCredentials om du inte använder en hanterad systemidentitet. Egenskaper för accessCredentials inkluderar applicationId (Microsoft Entra ID program-ID som har beviljats åtkomstbehörigheter till din angivna Azure-Key Vault) och applicationSecret (autentiseringsnyckel för det registrerade programmet). Ett exempel i nästa avsnitt illustrerar syntaxen. |
Svarsåtgärder
För en lyckad begäran bör du se statuskoden "201 Skapad".
Som standard innehåller svarstexten JSON för den definition av kompetensuppsättning som skapades. Men om Prefer begärandehuvudet är inställt på return=minimalär svarstexten tom och statuskoden för lyckad status är "204 Inget innehåll" i stället för "201 Skapad". Detta gäller oavsett om PUT eller POST används för att skapa kompetensuppsättningen.
Exempel
Exempel: Kompetensuppsättning som identifierar affärsentiteter och sentiment i kundrecensioner
Den här kompetensuppsättningen använder två färdigheter asynkront, oberoende bearbetning /document/content som två olika transformeringar. Färdigheterna är Entitetsigenkänning och Sentiment. I berikningsträdet /document/content tillhandahåller innehållet (eller kundgranskningarna) från den externa datakällan.
{
"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": { }
}
Exempel: Kunskapslager
En kompetensuppsättning kan också skicka utdata till kunskapsarkivet i Azure Storage. Det kräver en anslutningssträng till ett Azure Storage-konto och projektioner som avgör om berikat innehåll hamnar i tabell- eller bloblagring (som objekt eller filer). Projektioner kräver vanligtvis en överordnad Shaper-färdighet som samlar in noder från ett berikande träd som indata och matar ut en enda form som kan skickas till projektionen. En formare är vanligtvis den sista färdigheten som bearbetas.
{
"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": { }
}
Exempel: Krypteringsnycklar
Krypteringsnycklar är kundhanterade nycklar som används för ytterligare kryptering av känsligt innehåll. Det här exemplet visar hur du anger kundhanterad kryptering för en kompetensuppsättning.
{
"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)"}
}
}