Competenza API Web personalizzata in una pipeline di arricchimento di Azure AI Search

Articolo
10/21/2024

La competenza dell'API Web personalizzata consente di estendere l'arricchimento tramite intelligenza artificiale chiamando un endpoint dell'API Web che fornisce operazioni personalizzate. Analogamente alle competenze predefinite, una competenza API Web personalizzata ha input e output. In base agli input, l'API Web riceve un payload JSON durante l'esecuzione dell'indicizzatore e restituisce come risposta un payload JSON con un codice di stato di esito positivo. È previsto che la risposta abbia gli output specificati dalla competenza personalizzata. Qualsiasi altra risposta è considerata un errore e non vengono eseguiti arricchimenti. La struttura dei payload JSON è descritta ulteriormente più avanti in questo documento.

La competenza dell'API Web personalizzata viene usata anche nell'implementazione della funzionalità Azure OpenAI sui dati. Se Azure OpenAI è configurato per l'accesso basato sui ruoli e si ricevono chiamate 403 Forbidden durante la creazione dell'indice vettoriale, assicurarsi che Azure AI Search abbia un'identità assegnata dal sistema e che sia eseguito come servizio attendibile in Azure OpenAI.

Nota

L'indicizzatore esegue due tentativi per determinati codici di stato HTTP standard restituiti dall'API Web. Questi codici di stato HTTP sono:

502 Bad Gateway
503 Service Unavailable
429 Too Many Requests

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Parametri della competenza

I parametri fanno distinzione tra maiuscole e minuscole.

Nome parametro	Descrizione
`uri`	URI dell'API Web a cui verrà inviato il payload JSON. È consentito solo lo schema URI https.
`authResourceId`	(Facoltativo) Stringa che, se impostata, indica che questa competenza deve usare un'identità gestita dal sistema nella connessione alla funzione o all'app che ospita il codice. Questa proprietà accetta un ID applicazione (client) o la registrazione dell'app in Microsoft Entra ID, in uno di questi formati: `api://<appId>`, `<appId>/.default`, `api://<appId>/.default`. Questo valore viene usato per definire l'ambito del token di autenticazione recuperato dall'indicizzatore e viene inviato insieme alla richiesta della competenza dell'API Web personalizzata alla funzione o all'app. L'impostazione di questa proprietà richiede che il servizio di ricerca sia configurato per l'identità gestita e che l'app per le funzioni di Azure sia configurata per l'accesso a Microsoft Entra. Per usare questo parametro, chiamare l'API con `api-version=2023-10-01-Preview`.
`authIdentity`	(Facoltativo) Identità gestita dall'utente usata dal servizio di ricerca per la connessione alla funzione o all'app che ospita il codice. È possibile usare un'identità gestita dal sistema o dall'utente. Per usare un'identità gestita dal sistema, lasciare `authIdentity` vuoto.
`httpMethod`	Metodo da usare per l'invio del payload. I metodi consentiti sono `PUT` o `POST`
`httpHeaders`	Raccolta di coppie chiave-valore in cui le chiavi corrispondono ai nomi di intestazione e i valori rappresentano i valori di intestazione che sono inviati all'API Web insieme al payload. In questa raccolta è proibito l'uso delle intestazioni seguenti: `Accept`, `Accept-Charset`, `Accept-Encoding`, `Content-Length`, `Content-Type`, `Cookie`, `Host`, `TE`, `Upgrade`, `Via`.
`timeout`	(facoltativo) Se specificato, indica il timeout per il client HTTP che effettua la chiamata API. Il valore deve essere formattato come valore XSD "dayTimeDuration" (un subset limitato di un valore duration ISO 8601 ). Ad esempio, `PT60S` per 60 secondi. Se non impostato, viene scelto un valore predefinito di 30 secondi. Il timeout può essere impostato su un massimo di 230 secondi e un minimo di 1 secondo.
`batchSize`	(Facoltativo) Indica quanti "record di dati" (vedere la struttura del payload JSON più avanti) vengono inviati per ogni chiamata API. Se non impostato, viene scelto un valore predefinito di 1000. È consigliabile usare questo parametro per ottenere un compromesso accettabile tra velocità effettiva di indicizzazione e carico sull'API.
`degreeOfParallelism`	(Facoltativo) Se specificato, indica il numero di chiamate effettuate dall'indicizzatore in parallelo all'endpoint specificato. È possibile diminuire questo valore se l'endpoint è in sovraccarico o aumentarlo se l'endpoint è in grado di gestire il carico. Se non è impostato, viene usato un valore predefinito pari a 5. `degreeOfParallelism` può essere impostato scegliendo un valore da 1 (minimo) a 10 (massimo).

Input competenze

Non esistono input predefiniti per questa competenza. Gli input sono costituiti da qualsiasi campo esistente o qualsiasi nodo nell'albero di arricchimento che si desidera passare alla competenza personalizzata.

Output competenze

Non esistono output predefiniti per questa competenza. Assicurarsi di definire un mapping dei campi di output nell'indicizzatore se l'output della competenza deve essere inviato a un campo nell'indice di ricerca.

Definizione di esempio

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "batchSize": 4,
  "context": "/document",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    },
    {
      "name": "language",
      "source": "/document/languageCode"
    },
    {
      "name": "phraseList",
      "source": "/document/keyphrases"
    }
  ],
  "outputs": [
    {
      "name": "hitPositions"
    }
  ]
}

Struttura JSON di input di esempio

La struttura JSON rappresenta il payload che viene inviato all'API Web. Segue sempre questi vincoli:

L'entità di primo livello è denominata values ed è una matrice di oggetti. Il numero massimo di tali oggetti è batchSize.
Ogni oggetto nella matrice values ha:
- Una proprietà recordId che è una stringa univoca usata per identificare tale record.
- Una proprietà data che è un oggetto JSON. I campi della data proprietà corrispondono ai "nomi" specificati nella inputs sezione della definizione della competenza. Il valore di questi campi proviene da source, che può essere un campo nel documento o provenire da un'altra competenza.

{
    "values": [
      {
        "recordId": "0",
        "data":
           {
             "text": "Este es un contrato en Inglés",
             "language": "es",
             "phraseList": ["Este", "Inglés"]
           }
      },
      {
        "recordId": "1",
        "data":
           {
             "text": "Hello world",
             "language": "en",
             "phraseList": ["Hi"]
           }
      },
      {
        "recordId": "2",
        "data":
           {
             "text": "Hello world, Hi world",
             "language": "en",
             "phraseList": ["world"]
           }
      },
      {
        "recordId": "3",
        "data":
           {
             "text": "Test",
             "language": "es",
             "phraseList": []
           }
      }
    ]
}

Struttura JSON di output di esempio

L'"output" corrisponde alla risposta restituita dall'API Web. L'API Web deve restituire solo un payload JSON verificato esaminando l'intestazione della risposta Content-Type, e deve soddisfare i vincoli seguenti:

Deve contenere un'entità di primo livello denominata values che deve essere una matrice di oggetti.
Il numero di oggetti nella matrice deve essere lo stesso degli oggetti inviati all'API Web.
Ogni oggetto deve avere:
- Una proprietà recordId.
- Una proprietà data, che è un oggetto in cui i campi sono arricchimenti corrispondenti ai "nomi" nell'output e il cui valore viene considerato l'arricchimento.
- Una proprietà errors, una matrice che elenca eventuali errori rilevati che vengono aggiunti alla cronologia di esecuzione dell'indicizzatore. Questa proprietà è obbligatoria, ma può avere un valore null.
- Una proprietà warnings, una matrice che elenca eventuali avvisi rilevati che vengono aggiunti alla cronologia di esecuzione dell'indicizzatore. Questa proprietà è obbligatoria, ma può avere un valore null.
L'ordinamento degli oggetti in values nella richiesta o nella risposta non è importante. Tuttavia, il valore recordId viene usato per la correlazione in modo che eventuali record nella risposta contenenti un recordId che non fa parte della richiesta originale all'API Web vengano rimossi.

{
    "values": [
        {
            "recordId": "3",
            "data": {
            },
            "errors": [
              {
                "message" : "'phraseList' should not be null or empty"
              }
            ],
            "warnings": null
        },
        {
            "recordId": "2",
            "data": {
                "hitPositions": [6, 16]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "0",
            "data": {
                "hitPositions": [0, 23]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "1",
            "data": {
                "hitPositions": []
            },
            "errors": null,
            "warnings": [
              {
                "message": "No occurrences of 'Hi' were found in the input text"
              }
            ]
        },
    ]
}

Casi di errore

Oltre alla non disponibilità dell'API Web o all'invio di codici di stato che non indicano un esito positivo, sono considerati casi di errore i seguenti:

Se l'API Web restituisce un codice di stato di esito positivo ma la risposta indica che non è application/json, la risposta viene considerata non valida e non vengono eseguiti arricchimenti.
Se nella matrice di risposta values sono presenti record non validi (ad esempio, recordId manca o è duplicato), non viene eseguito alcun arricchimento per i record non validi. È importante rispettare il contratto di competenza dell'API Web quando si sviluppano competenze personalizzate. È possibile fare riferimento a questo esempio fornito nel repository Power skill che segue il contratto previsto.

Nei casi in cui l'API Web non è disponibile o restituisce un errore HTTP, un errore descrittivo con i dettagli disponibili sull'errore HTTP viene aggiunto alla cronologia di esecuzione dell'indicizzatore.

Condividi tramite