Condividi tramite

Vettoruzzatore dell'API Web personalizzato

  • Articolo

Il vettorizzatore dell'API Web personalizzato consente di configurare le query di ricerca per chiamare un endpoint API Web per generare incorporamenti in fase di query. La struttura del payload JSON da implementare nell'endpoint fornito è descritta più avanti in questo documento. I dati vengono elaborati nell'area geografica in cui viene distribuito il modello.

I vettori vengono usati in fase di query, ma specificati nelle definizioni di indice e a cui viene fatto riferimento sui campi vettoriali tramite un profilo vettoriale. Il vettore dell'API Web personalizzato viene chiamato WebApiVectorizer nell'API.

Parametri del vettorizzatore

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.
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.
authResourceId (Facoltativo) Stringa che, se impostata, indica che questo vettorizzatore 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 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 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.
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.
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.

Tipi di query vettoriali supportati

Il vettorizzatore di API Web personalizzata supporta le query vettoriali text, imageUrl e imageBinary.

Definizione di esempio

"vectorizers": [
    {
        "name": "my-custom-web-api-vectorizer",
        "kind": "customWebApi",
        "customWebApiParameters": {
            "uri": "https://contoso.embeddings.com",
            "httpMethod": "POST",
            "httpHeaders": {
                "api-key": "0000000000000000000000000000000000000"
            },
            "timeout": "PT60S",
            "authResourceId": null,
            "authIdentity": null
        },
    }
]

Struttura del payload JSON

La struttura del payload JSON necessaria prevista per un endpoint quando viene usata con il vettorizzatore dell'API Web personalizzato è identica a quella della competenza API Web personalizzata, descritta in modo più dettagliato nella documentazione per la competenza.

Quando si implementa un endpoint API Web da usare con il vettorizzatore dell'API Web personalizzato, è necessario tenere presenti le altre considerazioni seguenti.

  • Il vettorizzatore invia un solo record alla volta nell'valuesarray quando si effettua una richiesta all'endpoint.

  • Il vettorizzatore passa i dati da vettorizzare in una chiave specifica nell'dataoggetto JSON nel payload della richiesta. Tale chiave è text, imageUrl o imageBinary, a seconda del tipo di query vettoriale richiesta.

  • Il vettorizzatore prevede che l'incorporamento risultante sia sotto la chiave vector nell'oggetto JSON data nel payload della risposta.

  • Eventuali errori o avvisi restituiti dall'endpoint vengono ignorati dal vettorizzatore e non sono recuperabili a scopo di debug in fase di query.

  • Se è stata richiesta una query vettoriale imageBinary, il payload della richiesta inviato all'endpoint è il seguente:

    {
    "values": [
        {
            "recordId": "0",
            "data":
            {
                "imageBinary": {
                    "data": "<base 64 encoded image binary data>"
                }
            }
        }
    ]
}

Vedi anche