Condividi tramite

Vettoruzzatore dell'API Web personalizzato

Il vettorizzatore dell'API Web personalizzata consente di configurare le query di ricerca per chiamare un endpoint dell'API Web che genera vettori durante l'esecuzione della query. La struttura del payload JSON necessaria per l'endpoint è descritta più avanti in questo articolo. I dati vengono elaborati nell'area geografica in cui viene distribuito il modello.

Anche se i vettorizzatori vengono usati in fase di query, è possibile specificarli nelle definizioni di indice e farvi riferimento sui campi vettoriali tramite un profilo vettoriale. Per altre informazioni, vedere Configurare un vettore in un indice di ricerca.

Il vettore dell'API Web personalizzato viene chiamato WebApiVectorizer nell'API REST. Usare la versione stabile più recente di Indici - Creare (API REST) o un pacchetto di Azure SDK che fornisce la funzionalità.

Parametri del vettorizzatore

I parametri sono sensibili alle lettere 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 utilizzato per inviare il 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 con il payload. In questa raccolta non sono consentite le intestazioni seguenti: Accept, Accept-CharsetAccept-Encoding, Content-Length, Content-TypeCookieHostTEUpgrade. Via
authResourceId (Facoltativo) Stringa che, se impostata, indica che questo vettore usa un'identità gestita per la 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 dei formati seguenti: api://<appId>, <appId>/.default, api://<appId>/.default. Questo valore definisce l'ambito del token di autenticazione recuperato dalla pipeline di query e inviato con la 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 connettersi alla funzione o all'app che ospita il codice. È possibile usare un'identità gestita dal sistema o gestita dall'utente. Per usare un'identità gestita dal sistema, lasciare authIdentity vuoto.
timeout (Facoltativo) Il timeout per il client HTTP che effettua la chiamata API. Deve essere formattato come valore XSD dayTimeDuration (un subset limitato di un valore di durata ISO 8601 ). Ad esempio, PT60S significa 60 secondi. Se non è impostato, il valore predefinito è 30 secondi. Il timeout può essere compreso tra 1 e 230 secondi.

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 per un endpoint usato con il vettore dell'API Web personalizzata è la stessa della struttura usata dalla competenza API Web personalizzata, descritta in modo più dettagliato nella documentazione della competenza.

Quando si implementa un endpoint API Web per il vettore dell'API Web personalizzato, tenere presenti le 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 vettore e non sono disponibili per il 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

  • Last updated on