Aggiungere una competenza personalizzata in una pipeline di arricchimento di Azure AI Search
Una pipeline di arricchimento tramite intelligenza artificiale può includere competenze predefinite 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. I dati vengono elaborati nell'area geografica in cui viene distribuito il modello.
Le competenze personalizzate possono sembrare complesse, ma possono essere semplici e immediate in termini di implementazione. Se si dispone di pacchetti esistenti che forniscono dei 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 input e generare output in modi che possano essere usati all'interno del set di competenze nel suo complesso. Di conseguenza, questo articolo è incentrato sui 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: creare 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 (di sistema o assegnata dall'utente) così 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 proprietà
authResourceId. 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 enricher basic che identifica la prima data menzionata 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 l'enricher più interessante, restituire il valore “”contractDate” sotto forma di un tipo complesso multiparte.
L'API Web deve essere pronta a ricevere un batch di record di input. Ogni membro della matrice dei “valori” rappresenta l'input per un record specifico. Ogni record deve avere gli elementi seguenti:
Un membro "recordId" che rappresenta l'identificatore univoco per un record specifico. Quando l'enricher restituisce i risultati, deve fornire il valore "recordId" per consentire al chiamante di abbinare i risultati dei record al relativo input.
Un 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 che contiene 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.