Vettoruzzatore dell'API Web personalizzato

Note

Azure AI Search è disponibile tramite il portale di Azure, le API REST e Azure SDK. È inoltre alla base di Foundry IQ, il livello di conoscenza gestito che trasforma il contenuto aziendale in knowledge base riutilizzabili e con riconoscimento delle autorizzazioni per gli agenti nel portale di Microsoft Foundry.

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 nel geography 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 Indexes - Creare (API REST) o un pacchetto SDK Azure 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. Quando si recupera l'indice con GET, il servizio restituisce il valore del parametro di query ?code= come ?code=<redacted> per evitare l'esposizione delle chiavi di funzione. Per aggiornare il vettorizzatore senza modificare l'URI archiviato, impostare uri su <unchanged>.
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 Quando si recupera l'indice con GET, il servizio restituisce <redacted> in modo che tutti i valori di intestazione impediscano l'esposizione delle credenziali. Per aggiornare il vettore senza modificare i valori di intestazione archiviati, impostare ogni valore su <unchanged>. Il servizio ripristina il valore archiviato originale.
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 una 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 search service sia configurato per l'identità gestita e che l'app per le funzioni Azure sia configurata per l'accesso a Microsoft Entra.
authIdentity (Facoltativo) Identità gestita dall'utente usata dal search service 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
        }
    }
]

Note

Quando si recupera l'indice usando GET, il servizio restituisce <redacted> per tutti i httpHeaders valori nella configurazione del vettore per impedire l'esposizione delle credenziali. Per aggiornare il vettore senza modificare i valori di intestazione archiviati, passare <unchanged> per ogni campo interessato. Il servizio ripristina il valore archiviato originale.

L'esempio seguente mostra una risposta GET per il vettorizzatore precedente:

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


To update this vectorizer without changing the existing `api-key` value, use `<unchanged>`:

```json
"httpHeaders": {
    "api-key": "<unchanged>"
}

Struttura del payload JSON

La struttura del payload JSON richiesta per un endpoint usato con il vettorizzatore API Web personalizzato è la stessa di quella usata dalla competenza API Web personalizzata. Per altre informazioni, vedere la documentazione sulle competenze.

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.

  • Il vettorizzatore ignora eventuali errori o avvisi restituiti dall'endpoint. Questi errori e avvisi 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