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

Articolo
04/15/2024

La competenza API Web personalizzata consente di estendere l'arricchimento tramite intelligenza artificiale chiamando un endpoint API Web che fornisce operazioni personalizzate. Analogamente alle competenze predefinite, una competenza API Web personalizzata ha input e output. A seconda degli input, l'API Web riceve un payload JSON quando l'indicizzatore viene eseguito e restituisce un payload JSON come risposta, insieme a 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 del payload JSON è descritta più avanti in questo documento.

La competenza DELL'API Web personalizzata viene usata anche nell'implementazione della funzionalità Azure OpenAI on Your Data( Dati). Se Azure OpenAI è configurato per l'accesso basato sui ruoli e si ricevono 403 Forbidden chiamate durante la creazione dell'indice vettoriale, verificare che Ricerca di Intelligenza artificiale di Azure abbia un'identità assegnata dal sistema ed eseguita come servizio attendibile in Azure OpenAI.

Nota

L'indicizzatore ritenta due volte 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 viene 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 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 un formato supportato: `api://<appId>`. Questo valore viene usato per definire l'ambito del token di autenticazione recuperato dall'indicizzatore e viene inviato insieme alla richiesta dell'API della competenza 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`.
`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 rappresentano nomi di intestazione e valori rappresentano i valori di intestazione inviati all'API Web insieme al payload. Le intestazioni seguenti non possono trovarsi in questa raccolta: `Accept`, `Accept-Charset`, `Content-LengthAccept-Encoding`, `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 il numero di "record di dati" (vedere la struttura del payload JSON seguente) inviati per ogni chiamata API. Se non impostato, viene scelto un valore predefinito di 1000. È consigliabile usare questo parametro per ottenere un compromesso appropriato tra la velocità effettiva di indicizzazione e il carico nell'API.
`degreeOfParallelism`	(Facoltativo) Se specificato, indica il numero di chiamate effettuate dall'indicizzatore in parallelo all'endpoint specificato. È possibile ridurre questo valore se l'endpoint non riesce sotto pressione o aumentarlo se l'endpoint può gestire il carico. Se non è impostato, viene usato un valore predefinito pari a 5. Può `degreeOfParallelism` essere impostato su un massimo di 10 e un minimo di 1.

Input competenze

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

Output competenze

Non sono disponibili 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

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

L'entità di primo livello viene chiamata values ed è una matrice di oggetti. Il numero di tali oggetti è al massimo .batchSize
Ogni oggetto nella values matrice ha:
- Una proprietà recordId che è una stringa univoca usata per identificare tale record.
- Proprietà data che è un oggetto JSON. I campi della data proprietà corrispondono ai "nomi" specificati nella inputs sezione della definizione della competenza. I valori di tali campi provengono da source questi campi (che possono essere provenienti da un campo nel documento o potenzialmente 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 Content-Type risposta) e deve soddisfare i vincoli seguenti:

Deve essere presente un'entità di primo livello denominata values, che deve essere una matrice di oggetti.
Il numero di oggetti nella matrice deve corrispondere al numero di oggetti inviati all'API Web.
Ogni oggetto deve avere:
- 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 errors proprietà, una matrice che elenca tutti gli errori rilevati che vengono aggiunti alla cronologia di esecuzione dell'indicizzatore. Questa proprietà è obbligatoria, ma può avere un valore null.
- Una warnings proprietà, una matrice che elenca tutti gli 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, recordId viene usato per la correlazione in modo che qualsiasi record nella risposta contenente un recordIdoggetto , che non faceva parte della richiesta originale all'API Web viene rimosso.

{
    "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, recordId ad esempio mancanti o duplicati, 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.

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