Benutzerdefinierte Web-API-Vektorisierung

Note

Foundry IQ (Azure KI-Suche) bietet direkte Indizierungs- und Abfrage-APIs zusammen mit Wissensquellen- und Knowledge Base-APIs auf höherer Ebene für den verwalteten Abruf. Verwenden Sie das Azure Portal, REST-APIs oder Azure SDKs, um diese Funktionen zu konfigurieren, oder verbinden Sie Agents mit Wissensdatenbanken im Microsoft Foundry-Portal.

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.

Parametername Beschreibung
uri Der URI der Web-API, an die das JSON-Datenpaket gesendet wird. Nur das HTTPS-URI-Schema ist zulässig. GET- und LIST-Antworten schwärzen sensible Abfragewerte, einschließlich sig und code. Um den Vektorizer zu aktualisieren, ohne den gespeicherten URI zu ändern, setzen Sie uri vollständig auf <unchanged>. Informationen zu zurückgegebenen Platzhaltern und Abgleichsregeln finden Sie unter URI-Schwärzung und Aktualisierungen unter Beibehaltung von Anmeldeinformationen.
httpMethod Die Methode, die zum Senden der Nutzlast verwendet wird. Zulässige Methoden sind PUT oder POST.
httpHeaders Eine Sammlung von Schlüssel-Wert-Paaren, bei der die Schlüssel Headernamen sind und die Werte an Ihre Web-API gesendet werden. Die folgenden Kopfzeilen sind verboten: Accept, Accept-Charset, Accept-Encoding, Content-Length, Content-Type, Cookie, Host, TE, Upgrade und Via. GET- und LIST-Antworten geben für jeden Headerwert <redacted> zurück. Informationen zu Updateanforderungen finden Sie unter Headerwerte nach GET aktualisieren.
authResourceId (Optional) Eine Zeichenfolge, die, falls festgelegt, angibt, dass dieser Vektorizer eine verwaltete Identität für die Verbindung mit der Funktion oder App verwendet, die den Code hostet. Diese Eigenschaft verwendet eine Anwendungs-ID (Client-ID) oder App-Registrierung in Microsoft Entra ID in einem der folgenden Formate: api://<appId>, <appId>/.default, api://<appId>/.default. Dieser Wert bezieht sich auf das Authentifizierungstoken, das von der Abfragepipeline abgerufen und mit der benutzerdefinierten Web-API-Anforderung an die Funktion oder App gesendet wird. Das Festlegen dieser Eigenschaft erfordert, dass Ihr Foundry IQ-Dienst für verwaltete Identität konfiguriert ist und Ihre Azure-Funktions-App für Microsoft Entra Anmeldung konfiguriert ist.
authIdentity (Optional) Eine vom Findry IQ-Dienst verwendete vom Benutzer verwaltete Identität, um eine Verbindung mit der Funktion oder App herzustellen, die den Code hosten soll. Sie können entweder eine vom System verwaltete oder vom Benutzer verwaltete Identität verwenden. Wenn Sie eine vom System verwaltete Identität verwenden möchten, lassen Sie sie authIdentity leer.
timeout (Optional) Das Timeout für den HTTP-Client, der den API-Aufruf vornimmt. Sie muss als XSD-Wert dayTimeDuration formatiert werden (eine eingeschränkte Teilmenge eines ISO 8601-Dauerwerts ). Bedeutet beispielsweise PT60S 60 Sekunden. Wenn sie nicht festgelegt ist, beträgt der Standardwert 30 Sekunden. Das Timeout kann zwischen 1 und 230 Sekunden betragen.

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 mit GET abrufen oder Indizes mit LIST auflisten, gibt der Dienst <redacted> für jeden httpHeaders-Wert in einem benutzerdefinierten Web-API-Vektorisierer 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 kind, name und Endpunkt. Übermitteln Sie den zurückgegebenen Platzhalter für den übereinstimmenden Headernamen erneut:

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

Für denselben vorhandenen Vektorisierer und Endpunkt können Sie mit <redacted> oder <unchanged> beibehaltene Headerwerte mit tatsächlichen Ersetzungswerten kombinieren. Explizite Werte haben Vorrang vor Platzhaltern. Geben Sie einen tatsächlichen Wert für jeden hinzugefügten oder umbenannten Header an, da ein Platzhalter eine eindeutige vorhandene Quelle erfordert. Informationen zu URI-Abfrageänderungen finden Sie unter URI-Schwärzung und Aktualisierungen zur Wahrung von Anmeldeinformationen.

Wenn Sie den Endpunkt ändern, stellen Sie tatsächliche URI- und geheime Header-Werte im selben Update bereit. Der Dienst verwendet keine gespeicherten Secrets für einen anderen Endpunkt:

{
    "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 den Endpunkt ändern müssen, rotieren oder regenerieren Sie sie beim externen Endpunkt. Übermitteln Sie dann die neuen uri Werte und die Kopfzeilenwerte zusammen.

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

Geben Sie für einen neuen Index, einen umbenannten Vektorizer oder einen anderen Dienst die Ziel-URI-Abfrage und Headeranmeldeinformationen an. Konfigurieren Sie für verwaltete Identitäten explizit die unterstützten Authentifizierungseigenschaften und die Zielautorisierung.

URI-Unkenntlichmachung und Aktualisierungen unter Beibehaltung der Anmeldeinformation

Dieses URI-Abfrageverhalten gilt für alle API-Versionen.

Wenn Sie einen Index mit GET abrufen oder Indizes mit LIST auflisten, redigiert Foundry IQ vertrauliche Benutzerdefinierte Web-API-Abfragewerte, einschließlich sig und code, und HTTP-Headerwerte. Diese geschwärzten Werte schützen SAS-Signaturen (Shared Access Signature), Funktionsschlüssel und Headeranmeldeinformationen.

Um gespeicherte geheime Schlüssel beizubehalten, aktualisieren Sie denselben vorhandenen Index und Vektorizer mit demselben Vektorizernamen, -typ und -endpunkt. Übermitteln Sie die zurückgegebenen <redacted> oder <unchanged> Platzhalter in der vollständigen Indexdefinition für die PUT-Verwaltungsanforderung. Beibehaltene Kopfzeilen müssen mit vorhandenen Kopfzeilennamen übereinstimmen. Dieser PUT aktualisiert die Indexdefinition; es ist nicht der Endpunktaufruf, der durch httpMethod des Vektorisierers gesteuert wird. Sie können das Ganze uri auch auf <unchanged> setzen, um den gespeicherten URI beizubehalten.

Geheime Werte werden nicht an einen anderen Endpunkt übertragen oder in eine neue Ressource kopiert. Das Ändern eines Endpunkts, das Klonen einer geschwärzten Definition oder die anderweitige erneute Zuordnung einer Ressource erfordert explizite Geheimnisse.

Wenn der Dienst keine eindeutige vorhandene Quelle für einen Platzhalter identifizieren kann, schlägt der PUT mit 400 Bad Request fehl und fordert den tatsächlichen geheimen Wert an. Ein nicht aufgelöster oder beibehaltener Platzhalter ist keine verwendbare Anmeldeinformation. Die geheime Wiederherstellung ist atomisch: Bei einer fehlgeschlagenen Wiederherstellung werden URI- oder Headeränderungen nicht teilweise angewendet.

Sie können jederzeit Ersatz-URI oder Header-Geheimnisse bereitstellen. Explizite Werte haben Vorrang vor Platzhaltern.

URI-Abfrageupdates folgen den folgenden Regeln:

  • Bei einem Azure Function-Parameter code können Sie andere nicht geheime Abfrageparameter aktualisieren und gleichzeitig den gespeicherten Funktionsschlüssel für denselben Endpunkt beibehalten.
  • Bei einem SAS-Parameter sig ist die Signatur an die umgebende Konfiguration der nicht geheimen Abfrageparameter gebunden. Wenn sich der Bereich, die Berechtigungen, der Ablauf, die Ressource, die Version, die Sortierung, die Groß-/Kleinschreibung oder die Codierung ändern, stellen Sie eine neue Signatur bereit. Selbst semantisch gleichwertige neu angeordnete oder neu codierte Abfragetexte erfordern eine neue Signatur.

Geheime Abfrageparameternamen werden erkannt, wobei die Groß-/Kleinschreibung nicht beachtet wird, auch wenn sie prozentkodiert sind. Der Dienst behält Ihre URI-Darstellung bei, anstatt sie zu normalisieren. Wiederholte geheime Parameter werden nach Vorkommen abgeglichen. Wenn ihr Vorkommensmuster nicht mehr mit dem gespeicherten URI übereinstimmt, geben Sie tatsächliche Werte an.

Vorhandene GET-then-PUT-Workflows, die <redacted> oder <unchanged> verwenden, werden weiterhin unterstützt. Beispiele für Kopfzeilen finden Sie unter Aktualisieren von Headerwerten nach GET.

Informationen zu benutzerdefinierten Fähigkeiten finden Sie unter Benutzerdefinierte Web-API-URI-Schwärzung und Aktualisierungen von Anmeldeinformationen.

Diese URI- und Headerregeln gewährleisten keine Unterstützung für die Beibehaltung bei anderen Vektorizertypen oder -eigenschaften. Informationen zu Zielabhängigkeitsprüfungen und der sicheren Wiederherstellungssequenz finden Sie unter Sichern, Wiederherstellen oder Klonen eines Indexes.

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