Teilen über

Benutzerdefinierte Web-API-Vektorisierung

  • Artikel

Wichtig

Dieses Feature befindet sich in der Public Preview-Phase und unterliegt zusätzlichen Nutzungsbedingungen. Die REST-API 2023-10-01-Preview und alle neueren REST-APIs in der Vorschau unterstützen dieses Feature.

Mit der benutzerdefinierten Web-API-Vektorisierung können Sie Ihre Suchabfragen so konfigurieren, dass sie einen Web-API-Endpunkt aufrufen, um Einbettungen zur Abfragezeit zu generieren. Die Struktur der JSON-Nutzdaten, die im bereitgestellten Endpunkt implementiert werden müssen, wird weiter unten in diesem Dokument beschrieben. Ihre Daten werden im geografischen Raum verarbeitet, in dem Ihr Modell bereitgestellt wird.

Vektorisierungsparameter

Bei den Parametern wird zwischen Groß- und Kleinschreibung unterschieden.

Parametername Beschreibung
uri Der URI der Web-API, an die die JSON-Nutzdaten gesendet werden. Nur das HTTPS-URI-Schema ist zulässig.
httpMethod Diese Methode wird zum Senden der Nutzlast verwendet: Zulässige Methoden sind PUT oder POST.
httpHeaders Eine Sammlung von Schlüssel-Wert-Paaren, bei denen die Schlüssel Headernamen und die Werte Headerwerte darstellen, die zusammen mit den Nutzdaten an Ihre Web-API gesendet werden. Die folgenden Header dürfen nicht in dieser Sammlung enthalten sein: Accept, Accept-Charset, Accept-Encoding, Content-Length, Content-Type, Cookie, Host, TE, Upgrade, Via.
authResourceId (Optional) Eine Zeichenfolge, die, wenn sie festgelegt wird, angibt, dass diese Vektorisierung bei der Verbindung mit der Funktion oder App, die den Code hostet, eine verwaltete Identität verwenden soll. Diese Eigenschaft wird auf eine Anwendungs-ID (Client) oder auf die Registrierung einer App in Microsoft Entra ID festgelegt. Dabei wird ein unterstütztes Format verwendet: api://<appId>. Dieser Wert wird verwendet, um den Gültigkeitsbereich des vom Indexer abgerufenen Authentifizierungstokens festzulegen. Er wird zusammen mit der benutzerdefinierten Web-API-Anforderung an die Funktion oder App gesandt. Wenn diese Eigenschaft festgelegt wird, muss Ihr Suchdienst für die verwaltete Identität konfiguriert und Ihre Azure-Funktions-App für eine Microsoft Entra-Anmeldung konfiguriert sein.
authIdentity (Optional) Eine benutzerseitig verwaltete Identität, die vom Suchdienst zum Herstellen einer Verbindung mit der Funktion oder App verwendet wird, die den Code hostet. Sie können entweder eine system- oder eine benutzerverwaltete Identität verwenden. Um eine systemseitig verwaltete Identität zu verwenden, lassen Sie authIdentity leer.
timeout (Optional) Wenn angegeben, wird damit das Zeitlimit für den HTTP-Client angegeben, der den API-Aufruf durchführt. Es muss als XSD-Wert „dayTimeDuration“ formatiert sein (eine eingeschränkte Teilmenge eines ISO 8601-Zeitwerts). Zum Beispiel PT60S für 60 Sekunden. Wenn kein Wert festgelegt ist, wird ein Standardwert von 30 Sekunden ausgewählt. Das Zeitlimit kann auf maximal 230 Sekunden und mindestens 1 Sekunde festgelegt werden.

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

Struktur der JSON-Nutzdaten

Die erforderliche JSON-Nutzdatenstruktur, die für einen Endpunkt erwartet wird, wenn er mit der benutzerdefinierten Web-API-Vektorisierung verwendet wird, ist identisch mit der des benutzerdefinierten Web-API-Skills, der in der Dokumentation für den Skill erläutert wird.

Bei der Implementierung eines Web-API-Endpunkts für die Verwendung mit der benutzerdefinierten Web-API-Vektorisierung gibt es die folgenden weiteren Ü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.

  • Alle vom Endpunkt zurückgegebenen Fehler oder Warnungen werden von der Vektorisierung ignoriert und können zur Abfragezeit nicht für Zwecke zum Debuggen abgerufen werden.

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

Weitere Informationen