Creare il set di competenze (API REST ricerca intelligenza artificiale di Azure)
Un set di competenze è una raccolta di competenze cognitive usate per l'arricchimento di intelligenza artificiale, con una specifica facoltativa per la creazione di un archivio conoscenze esterno in Archiviazione di Azure. Le competenze richiamano l'elaborazione del linguaggio naturale e altre trasformazioni, ad esempio il riconoscimento delle entità, l'estrazione di frasi chiave, il testo in blocchi in pagine logiche, tra gli altri.
Un set di competenze è collegato a un indicizzatore. Per usare il set di competenze, fare riferimento in un indicizzatore e quindi eseguire l'indicizzatore per importare dati, richiamare trasformazioni e arricchimento e eseguire il mapping dei campi di output a un indice. Un set di competenze è una risorsa di alto livello, ma è operativa solo all'interno dell'elaborazione dell'indicizzatore. In quanto risorsa di alto livello, è possibile progettare un set di competenze una sola volta e quindi farvi riferimento in più indicizzatori.
È possibile usare POST o PUT nella richiesta. Per uno, il documento JSON nel corpo della richiesta fornisce la definizione dell'oggetto.
PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=[api-version]
Content-Type: application/json
api-key: [admin key]
Per tutte le richieste del servizio, è necessario usare il protocollo HTTPS. Se il set di competenze non esiste, viene creato. Se esiste già, viene aggiornato alla nuova definizione.
Nota
I set di competenze sono la base dell'arricchimento dell'intelligenza artificiale. Una risorsa gratuita è disponibile per l'elaborazione limitata, ma per carichi di lavoro più grandi o più frequenti, è necessaria una risorsa servizi cognitivi fatturabili .
Parametri dell'URI
| Parametro | Descrizione |
|---|---|
| nome servizio | Obbligatorio. Impostare questo valore sul nome univoco definito dall'utente del servizio di ricerca. |
| nome del set di competenze | Obbligatorio nell'URI se si usa PUT. Il nome deve essere minuscolo, iniziare con una lettera o un numero, non avere barre o punti e essere inferiore a 128 caratteri. Il nome deve iniziare con una lettera o un numero, ma il resto del nome può includere qualsiasi lettera, numero e trattini, purché i trattini non siano consecutivi. |
| api-version | Obbligatorio. Per un elenco di versioni supportate, vedere Versioni API . |
Intestazioni richiesta
La tabella seguente descrive le intestazioni della richiesta obbligatorie e facoltative.
| Campi | Descrizione |
|---|---|
| Content-Type | Obbligatorio. Impostare il valore su application/json |
| api-key | Facoltativo se si usano ruoli di Azure e viene fornito un token di connessione nella richiesta, altrimenti è necessaria una chiave. Le richieste di creazione devono includere un api-key set di intestazioni sulla chiave di amministrazione , anziché una chiave di query. Per informazioni dettagliate, vedere Connettersi a Ricerca intelligenza artificiale di Azure usando l'autenticazione delle chiavi . |
Corpo della richiesta
Il corpo della richiesta contiene la definizione del set di competenze. Le competenze sono autonome o concatenate tramite associazioni di input-output, in cui l'output di una trasformazione diventa input a un altro. Un set di competenze deve includere almeno una competenza. Non esiste alcun limite teorico per il numero massimo di competenze, ma tre a cinque è una configurazione comune.
Il codice JSON seguente è una rappresentazione generale delle parti principali della definizione.
{
"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) { }
}
La richiesta contiene le proprietà seguenti:
| Proprietà | Descrizione |
|---|---|
| name | Obbligatorio. Nome del set di competenze. Il nome deve essere minuscolo, iniziare con una lettera o un numero, non avere barre o punti e essere inferiore a 128 caratteri. Il nome deve iniziare con una lettera o un numero, ma il resto del nome può includere qualsiasi lettera, numero e trattini, purché i trattini non siano consecutivi. |
| skills | Matrice di competenze. Ogni competenza ha un parametro odata.type, nome, contesto e input e output. La matrice può includere competenze predefinite e competenze personalizzate. È necessaria almeno una competenza. Se si usa un archivio conoscenze, includere una competenza Shaper a meno che non si definisca la forma dei dati all'interno della proiezione. |
| cognitiveServices | Una chiave all-in-one è necessaria per le competenze fatturabili che chiamano API Servizi cognitivi su più di 20 documenti giornalieri, per indicizzatore. La chiave deve essere per una risorsa nella stessa area del servizio di ricerca. Per altre informazioni, vedere Collegare una risorsa servizi cognitivi. Se si usa la competenza Ricerca entità personalizzata , includere questa sezione e una chiave per abilitare le transazioni oltre 20 transazioni giornaliere per indicizzatore. Non è necessaria la chiave di Servizi cognitivi e quindi è possibile escludere cognitiveServices la sezione se il set di competenze è costituito solo da competenze personalizzate, competenze di utilità (condizionale, Shaper, Unione di testo, Suddivisione testo) o la competenza Estrazione documenti. Se si vuole rimuovere la risorsa del servizio cognitivo associata da un set di competenze (per ripristinare l'uso dei limiti predefiniti) specificare @odata.type come #Microsoft.Azure.Search.DefaultCognitiveServices, Vedere questo esempio per altre informazioni. |
| knowledgeStore | facoltativo. Destinazione dell'output di arricchimento in Archiviazione di Azure. Richiede un stringa di connessione a un account e proiezioni di Archiviazione di Azure. storageConnectionString (obbligatorio) Stringa in questo formato: "DefaultEndpointsProtocol=https;AccountName=<ACCOUNT-NAME>;AccountKey=<ACCOUNT-KEY>;EndpointSuffix=core.windows.net". projections (obbligatorio) Matrice di oggetti di proiezione costituiti da tables, objects, files, che sono specificati o Null. tablesCrea una o più tabelle in Archiviazione tabelle di Azure, proiettando il contenuto da ogni documento come righe in una tabella. Ogni tabella può avere le tre proprietà seguenti:
objectsProgetti come BLOB in Archiviazione BLOB di Azure. Ogni oggetto ha due proprietà necessarie:
filesOgni voce di file definisce l'archiviazione delle immagini binarie nell'archiviazione BLOB. Le proiezioni di file hanno due proprietà necessarie:
|
| EncryptionKey | facoltativo. Usato per crittografare una definizione del set di competenze inattivi con le proprie chiavi, gestite nell'Key Vault di Azure. Disponibile per i servizi di ricerca fatturabili creati in o dopo il 2019-01-01. Una encryptionKey sezione contiene un oggetto definito keyVaultKeyName dall'utente (obbligatorio), un sistema generato keyVaultKeyVersion dal sistema (obbligatorio) e una keyVaultUri chiave (richiesta, definita anche come nome DNS). Un URI di esempio potrebbe essere "https://my-keyvault-name.vault.azure.net". Facoltativamente, è possibile specificare accessCredentials se non si usa un'identità del sistema gestita. Proprietà di inclusione applicationId (Microsoft Entra ID ID applicazione che è stato concesso le autorizzazioni di accesso all'Key Vault di Azure specificato) e applicationSecret (chiave di accessCredentials autenticazione dell'applicazione registrata). Un esempio nella sezione successiva illustra la sintassi. |
Risposta
In caso di richiesta eseguita correttamente, viene visualizzato il codice di stato "201 - Creato".
Per impostazione predefinita, il corpo della risposta contiene il codice JSON per la definizione del set di competenze creata. Tuttavia, se l'intestazione della richiesta è impostata su return=minimal, il corpo della risposta è vuoto e il codice di stato dell'esito Prefer positivo è "204 Nessun contenuto" anziché "201 Creato". Questo vale indipendentemente dall'uso del metodo PUT o POST per creare il set di competenze.
Esempio
Esempio: Set di competenze che riconosce le entità aziendali e il sentiment nelle recensioni dei clienti
Questo set di competenze usa due competenze in modo asincrono, elaborando /document/content in modo indipendente come due trasformazioni diverse. Le competenze sono Riconoscimento entità e Sentiment. Nell'albero di arricchimento fornisce /document/content il contenuto (o le revisioni dei clienti) dall'origine dati esterna.
{
"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": { }
}
Esempio: Archivio conoscenze
Un set di competenze può inviare facoltativamente l'output all'archivio conoscenze in Archiviazione di Azure. Richiede un stringa di connessione a un account di archiviazione di Azure e proiezioni che determinano se il contenuto arricchito si trova nella tabella o nell'archiviazione BLOB (come oggetti o file). Le proiezioni in genere richiedono una competenza shaper upstream che raccoglie i nodi da un albero di arricchimento come input, output di una singola forma che può essere passata alla proiezione. Un shaper è in genere l'ultima competenza da elaborare.
{
"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": { }
}
Esempio: Chiavi di crittografia
Le chiavi di crittografia sono chiavi gestite dal cliente usate per la crittografia aggiuntiva del contenuto sensibile. Questo esempio illustra come specificare la crittografia gestita dal cliente in un set di competenze.
{
"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)"}
}
}
Vedi anche
- Definire un insieme di competenze
- Panoramica dell'arricchimento dell'intelligenza artificiale
- Panoramica del set di competenze
- Panoramica dell'archivio conoscenze
- Panoramica della proiezione
- Esercitazione: Usare REST e intelligenza artificiale per generare contenuto ricercabile da BLOB
- Competenze predefinite