Benutzerdefinierte Web-API-Vektorisierung

Mit dem Benutzerdefinierten Web-API-Vektorizer können Sie Suchabfragen so konfigurieren, dass ein Web-API-Endpunkt aufgerufen wird, der Einbettungen zur Abfragezeit generiert. Die erforderliche JSON-Nutzlaststruktur für den Endpunkt wird weiter unten in diesem Artikel beschrieben. Ihre Daten werden in der geographie verarbeitet, in der Ihr Modell bereitgestellt wird.

Obwohl Vektorisierer zur Abfragezeit verwendet werden, werden sie in Indexdefinitionen angegeben und über ein Vektorprofil auf Vektorfelder referenziert. Weitere Informationen finden Sie unter Konfigurieren eines Vektorizers in einem Suchindex.

Der benutzerdefinierte Web-API-Vektorisierer wird in der REST-API als WebApiVectorizer genannt. Verwenden Sie die neueste stabile Version von Indexes – Create (REST API) oder ein Azure SDK-Paket, das das Feature bereitstellt.

Vektorisierungsparameter

Bei Parametern wird die Groß-/Kleinschreibung beachtet.

Unterstützte Vektorabfragetypen

Die benutzerdefinierte Web-API-Vektorisierung unterstützt text-, imageUrl- und imageBinary-Vektorabfragen.

Beispieldefinition

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

Aktualisieren von Headerwerten nach GET

Wenn Sie eine Indexdefinition abrufen, gibt der Dienst den Sentinel <redacted> für jeden httpHeaders Wert in einem benutzerdefinierten Web-API-Vektorizer zurück. Beispiel:

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

Um den gespeicherten api-key Wert wiederzuverwenden, aktualisieren Sie denselben vorhandenen Vektorizer mit demselben namekindund lassen sie unverändert uri , und übermitteln Sie den Sentinel erneut für den entsprechenden Headernamen:

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

Bei unverändertem uriFormat können Sie für beibehaltene Kopfzeilenwerte mit tatsächlichen Ersetzungswerten für andere vorhandene Kopfzeilen mischen <redacted> . Geben Sie einen tatsächlichen Wert für jeden hinzugefügten oder umbenannten Header an, da der Sentinel nur für eine vorhandene Kopfzeile mit demselben Namen auf demselben Vektorizer gilt.

Wenn Sie den uriWert ändern, geben Sie tatsächliche Werte für jeden httpHeaders Eintrag in derselben Aktualisierung an. Der Dienst verwendet keine gespeicherten Werte für einen anderen 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
    }
}

Wenn die Anmeldeinformationen nicht verfügbar sind und Sie die uriAnmeldeinformationen ändern, sie am externen Endpunkt drehen oder neu generieren müssen. Übermitteln Sie dann die neuen uri Werte und Die Kopfzeilenwerte zusammen.

Der <redacted> Wert ist ein Dienst-Sentinel, keine Anmeldeinformationen. Sie kann keinen Vektorisierer erstellen oder einen für einen anderen Vektorisierer gespeicherten Headerwert abrufen oder wiederverwenden.

Struktur der JSON-Nutzdaten

Die erforderliche JSON-Nutzlaststruktur für einen Endpunkt, der mit dem Benutzerdefinierten Web-API-Vektorizer verwendet wird, entspricht der Struktur, die von der Benutzerdefinierten Web-API-Fähigkeit verwendet wird. Weitere Informationen finden Sie in der Qualifikationsdokumentation.

Beachten Sie beim Implementieren eines Web-API-Endpunkts für den benutzerdefinierten Web-API-Vektorizer die folgenden Überlegungen:

• Die Vektorisierung sendet beim Übermitteln einer Anforderung an den Endpunkt jeweils nur einen Datensatz im values-Array.

• Die Vektorisierung übergibt die Daten, die in einem bestimmten Schlüssel im data-JSON-Objekt in den Anforderungsnutzdaten vektorisiert werden sollen. Dieser Schlüssel ist text, imageUrl oder imageBinary, je nachdem, welche Art von Vektorabfrage angefordert wurde.

• Die Vektorisierung erwartet, dass sich die resultierende Einbettung unter dem vector-Schlüssel im data-JSON-Objekt in den Antwortnutzdaten befindet.

• Der Vektorizer ignoriert alle Fehler oder Warnungen, die vom Endpunkt zurückgegeben werden. Diese Fehler und Warnungen sind für das Abfragezeitdebugging nicht verfügbar.

• Wenn eine imageBinary-Vektorabfrage angefordert wurde, lauten die an den Endpunkt gesandten Anforderungsnutzdaten wie folgt:

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

Siehe auch

• integrierte Vektorisierung
• Konfigurieren einer Vektorisierung in einem Suchindex
• Benutzerdefinierter Web-API-Skill