Aggiungere una competenza personalizzata in una pipeline di arricchimento di Azure AI Search
Una pipeline di arricchimento tramite intelligenza artificiale può includere competenzepredefinite e competenze personalizzate create e pubblicate personalmente. Il codice personalizzato viene eseguito esternamente dal servizio di ricerca (ad esempio, come funzione di Azure), ma accetta input e invia output al set di competenze esattamente come qualsiasi altra competenza.
Le competenze personalizzate possono sembrare complesse, ma possono essere semplici e semplici in termini di implementazione. Se si dispone di pacchetti esistenti che forniscono modelli di ricerca o classificazione, il contenuto estratto dai BLOB può essere passato a questi modelli per l'elaborazione. Poiché l'arricchimento tramite intelligenza artificiale è basato su Azure, anche il modello deve trovarsi in Azure. Alcune metodologie di hosting comuni includono l'uso di Funzioni di Azure o contenitori.
Se si sta creando una competenza personalizzata, questo articolo descrive l'interfaccia usata per integrare la competenza nella pipeline. Il requisito principale è la possibilità di accettare gli input e generare output in modi utilizzabili all'interno del set di competenze nel suo complesso. Di conseguenza, l'attenzione di questo articolo riguarda i formati di input e output richiesti dalla pipeline di arricchimento.
Vantaggi delle competenze personalizzate
Compilare un'esperienza personalizzata permette di inserire trasformazioni esclusive nel proprio contenuto. Ad esempio, è possibile compilare modelli di classificazione personalizzati per distinguere i contratti e documenti commerciali da quelli finanziari oppure aggiungere una competenza di riconoscimento vocale per analizzare in modo più approfondito i file audio allo scopo di individuare il contenuto pertinente. Per un esempio dettagliato, vedere Esempio: Creazione di una competenza personalizzata per l'arricchimento tramite intelligenza artificiale.
Impostare l'endpoint e l'intervallo di timeout
L'interfaccia per una competenza personalizzata viene specificata tramite la competenza API Web personalizzata.
"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"description": "This skill has a 230 second timeout",
"uri": "https://[your custom skill uri goes here]",
"authResourceId": "[for managed identity connections, your app's client ID goes here]",
"timeout": "PT230S",
L'URI è l'endpoint HTTPS della funzione o dell'app. Quando si imposta l'URI, assicurarsi che l'URI sia sicuro (HTTPS). Se il codice è ospitato in un'app per le funzioni di Azure, l'URI deve includere una chiave API nell'intestazione o come parametro URI per autorizzare la richiesta.
Se invece la funzione o l'app usa identità gestite di Azure e ruoli di Azure per l'autenticazione e l'autorizzazione, la competenza personalizzata può includere un token di autenticazione nella richiesta. I punti seguenti descrivono i requisiti per questo approccio:
Il servizio di ricerca, che invia la richiesta per conto dell'indicizzatore, deve essere configurato in modo da usare un'identità gestita (sistema o assegnata dall'utente) in modo che il chiamante possa essere autenticato da Microsoft Entra ID.
La funzione o l'app deve essere configurata per Microsoft Entra ID.
La definizione della competenza personalizzata deve includere una
authResourceIdproprietà . Questa proprietà accetta un ID applicazione (client) in un formato supportato:api://<appId>.
Per impostazione predefinita, la connessione all'endpoint raggiunge il timeout se una risposta non viene restituita all'interno di una finestra di 30 secondi (PT30S). La pipeline di indicizzazione è sincrona e l'indicizzazione genererà un errore di timeout se una risposta non viene ricevuta in tale intervallo di tempo. È possibile aumentare l'intervallo fino a un valore massimo di 230 secondi impostando il parametro di timeout (PT230S).
Formattare gli input dell'API Web
L'API Web deve accettare una matrice di record da elaborare. All'interno di ogni record, fornire un contenitore di proprietà come input per l'API Web.
Si supponga di voler creare un arricchimento di base che identifichi la prima data indicata nel testo di un contratto. In questo esempio, la competenza personalizzata accetta un singolo input "contractText" come testo del contratto. La competenza ha anche un singolo output, ovvero la data del contratto. Per rendere più interessante l'arricchimento, restituire questo "contractDate" nella forma di un tipo complesso multipart.
L'API Web deve essere pronta a ricevere un batch di record di input. Ogni membro della matrice "values" rappresenta l'input per un determinato record. Ogni record deve avere gli elementi seguenti:
Membro "recordId" che rappresenta l'identificatore univoco per un determinato record. Quando l'enricher restituisce i risultati, deve fornire questo "recordId" per consentire al chiamante di associare i risultati del record al relativo input.
Membro "data", che è essenzialmente un contenitore di campi di input per ogni record.
La richiesta dell'API Web risultante potrebbe essere simile alla seguente:
{
"values": [
{
"recordId": "a1",
"data":
{
"contractText":
"This is a contract that was issues on November 3, 2023 and that involves... "
}
},
{
"recordId": "b5",
"data":
{
"contractText":
"In the City of Seattle, WA on February 5, 2018 there was a decision made..."
}
},
{
"recordId": "c3",
"data":
{
"contractText": null
}
}
]
}
In pratica, il codice può essere chiamato con centinaia o migliaia di record anziché solo i tre illustrati qui.
Formattare gli output dell'API Web
Il formato dell'output è un set di record contenente un "recordId" e un contenitore delle proprietà. Questo specifico esempio ha un solo output, ma è possibile restituire più proprietà. Come procedura consigliata, valutare la possibilità di restituire messaggi di errore e di avviso se non è stato possibile elaborare un record.
{
"values":
[
{
"recordId": "b5",
"data" :
{
"contractDate": { "day" : 5, "month": 2, "year" : 2018 }
}
},
{
"recordId": "a1",
"data" : {
"contractDate": { "day" : 3, "month": 11, "year" : 2023 }
}
},
{
"recordId": "c3",
"data" :
{
},
"errors": [ { "message": "contractText field required "} ],
"warnings": [ {"message": "Date not found" } ]
}
]
}
Aggiungere una competenza personalizzata a un set di competenze
Quando si crea un enricher API Web, è possibile descrivere intestazioni HTTP e parametri come parte della richiesta. Il frammento di codice seguente mostra come i parametri della richiesta e le intestazioni HTTP facoltative possono essere inclusi nella definizione del set di competenze. L'impostazione di un'intestazione HTTP è utile se è necessario passare le impostazioni di configurazione al codice.
{
"skills": [
{
"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"name": "myCustomSkill",
"description": "This skill calls an Azure function, which in turn calls TA sentiment",
"uri": "https://indexer-e2e-webskill.azurewebsites.net/api/DateExtractor?language=en",
"context": "/document",
"httpHeaders": {
"DateExtractor-Api-Key": "foo"
},
"inputs": [
{
"name": "contractText",
"source": "/document/content"
}
],
"outputs": [
{
"name": "contractDate",
"targetName": "date"
}
]
}
]
}
Guarda il video
Per un'introduzione video e una demo, guardare la demo seguente.
Passaggi successivi
Questo articolo ha illustrato i requisiti di interfaccia necessari per l'integrazione di una competenza personalizzata in un set di competenze. Continuare con questi collegamenti per altre informazioni sulle competenze personalizzate e sulla composizione del set di competenze.