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 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.

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": "<your-header-value>"
            },
            "timeout": "PT60S",
            "authResourceId": null,
            "authIdentity": null
        }
    }
]

Aggiornare i valori dell'intestazione dopo GET

Quando si recupera una definizione di indice, il servizio restituisce il sentinel <redacted> per ogni httpHeaders valore in un vettore dell'API Web personalizzata. Per esempio:

{
    "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
    }
}

Per riutilizzare il valore archiviato api-key , aggiornare lo stesso vettore esistente con lo stesso name e kind, lasciarne uri invariato e inviare nuovamente sentinel per il nome dell'intestazione corrispondente:

{
    "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
    }
}

Con un oggetto non modificato uri, è possibile combinare <redacted> i valori di intestazione conservati con i valori effettivi di sostituzione per altre intestazioni esistenti. Specificare un valore effettivo per ogni intestazione aggiunta o rinominata perché sentinel si applica solo a un'intestazione esistente con lo stesso nome nello stesso vettore.

Se si modifica uri, specificare i valori effettivi per ogni httpHeaders voce nello stesso aggiornamento. Il servizio non riutilizza i valori archiviati per un oggetto diverso uri:

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

Se le credenziali non sono disponibili ed è necessario modificare , uriruotarle o rigenerarle nell'endpoint esterno. Inviare quindi i valori di intestazione e nuovi uri insieme.

Il <redacted> valore è un servizio sentinel, non una credenziale. Non può creare un vettore o recuperare o riutilizzare un valore di intestazione archiviato per un altro vettore.

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

• Vettorizzazione integrata
• Come configurare un vettorizzatore in un indice di ricerca
• Competenza API Web personalizzata
• Competenza avanzata Hugging Face Embeddings Generator (può essere usata anche per vettorizzazione API Web personalizzata)