Azure OpenAI-Vektorizer

Hinweis

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.

Der Azure OpenAIVektorizer stellt eine Verbindung mit einem Einbettungsmodell her, das in Ihrem Azure OpenAI in Foundry Models Ressource oder Microsoft Foundry Projekt bereitgestellt wird, um Einbettungen zur Abfragezeit zu generieren. Ihre Daten werden im Geo verarbeitet, in dem 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 Azure OpenAI-Vektorizer wird in der REST-API AzureOpenAIVectorizer aufgerufen. Verwenden Sie die neueste stabile Version von Indexes – Create (REST API) oder ein Azure SDK-Paket, das das Feature bereitstellt.

Hinweis

Dieser Vektorizer ist an Azure OpenAI gebunden und wird zum Azure OpenAI Standardpreis in Rechnung gestellt.

Voraussetzungen

  • Eine Azure OpenAI in Foundry-Modellen Ressource oder Foundry-Projekt.

    • Ihre Azure OpenAI-Ressource muss eine benutzerdefinierte Subdomäne haben, wie https://<resource-name>.openai.azure.com. Diesen Endpunkt finden Sie auf der Seite Keys and Endpoint im Azure-Portal und verwenden ihn für die Eigenschaft resourceUri in diesem Skill.

    • Die übergeordnete Ressource Ihres Foundry-Projekts bietet Zugriff auf mehrere Endpunkte, darunter https://<resource-name>.openai.azure.com, https://<resource-name>.services.ai.azure.com, und https://<resource-name>.cognitiveservices.azure.com. Diese Endpunkte findest du auf der Seite Keys and Endpoint im Azure Portal und nutze jeden von ihnen für die Eigenschaft resourceUri in dieser Fähigkeit.

  • Ein in Ihrer Ressource oder Ihrem Projekt bereitgestelltes Azure OpenAI-Embedding-Modell. Unterstützte Modelle finden Sie im nächsten Abschnitt.

Vectorizer-Parameter

Bei Parametern wird zwischen Groß- und Kleinschreibung unterschieden.

Parametername Beschreibung
resourceUri (Erforderlich) Der Modellressourcenbasis-URI. Unterstützte Ressourcendomänen sind:

  • openai.azure.com
  • services.ai.azure.com
  • cognitiveservices.azure.com

Azure API Management-HTTPS-Gatewaybasis-URIs werden ebenfalls unterstützt, einschließlich der Standardhosts azure-api.net und konfigurierter benutzerdefinierter Domänen. Legen Sie deploymentId separat fest. Geben Sie keine vollständige URL für den Embedding-Vorgang an. Informationen zu Routing-, Authentifizierungs-, RBAC- und Voraussetzungen für private Konnektivität finden Sie unter Verwenden von API Management mit Foundry IQ-Modellaufrufen (Azure KI-Suche).

apiKey Der geheime Schlüssel, mit dem man auf das Modell zugegriffen hat. Konfigurieren Sie nur eine Authentifizierungsmethode; wenn Sie einen Schlüssel verwenden, lassen Sie authIdentity leer.
deploymentId (Erforderlich) Die ID des bereitgestellten Azure OpenAI-Embedding-Modells. Das ist der Bereitstellungsname, den Sie beim Bereitstellen des Modells angegeben haben.
authIdentity Die vom Benutzer zugewiesene verwaltete Identität , die für die Verbindung verwendet wird. Lassen Sie sowohl apiKey als auch authIdentity aus, um die vom System zugewiesene Identität des Foundry IQ-Diensts zu verwenden. Weisen Sie für direkte Aufrufe oder Tokenpass-Through Cognitive Services OpenAI User der modellhostenden Azure OpenAI- oder der übergeordneten Foundry-Ressource zu. Informationen zur Identitätsauswahl und separaten Gateway-/Back-End-Zuordnungen finden Sie unter Rollenbereich und Identitätsbezeichner.
modelName (Erforderlich) Der Name des Azure OpenAI-Modells, das unter der angegebenen deploymentId bereitgestellt wurde. Unterstützte Werte sind:

  • text-embedding-ada-002
  • text-embedding-3-large
  • text-embedding-3-small

Unterstützte Vektorabfragetypen

Der Azure OpenAI-Vektorizer unterstützt nur text Vektorabfragen.

Informationen zu API-Verwaltungsendpunkt, Authentifizierung und Anforderungen für private Netzwerke finden Sie unter Verwenden der API-Verwaltung mit Foundry IQ-Modellaufrufen.

Erwartete Feldabmessungen

Die erwarteten Feldabmessungen für ein Feld, das mit einem Azure OpenAI-Vektorizer konfiguriert ist, hängen vom konfigurierten modelName ab.

modelName Mindestmaße Maximale Abmessungen
text-embedding-ada-002 1536 1536
text-embedding-3-large 1 3072
text-embedding-3-small 1 1536

Beispieldefinition

Das folgende Indexdefinitionsfragment konfiguriert eine direkte Azure OpenAI-Verbindung. Ersetzen Sie <api-key> vor dem Senden der Anforderung durch Ihre Anmeldeinformationen.

{
  "vectorizers": [
    {
        "name": "my-openai-vectorizer",
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
            "resourceUri": "https://my-fake-azure-openai-resource.openai.azure.com",
            "apiKey": "<api-key>",
            "deploymentId": "my-ada-002-deployment",
            "authIdentity": null,
            "modelName": "text-embedding-ada-002"
        }
    }
  ]
}

Beispiel für eine benutzerdefinierte Domäne in API Management

Dieses Indexdefinitionsfragment konfiguriert einen Vektorizer mit einer benutzerdefinierten API Management-Gatewaydomäne und der systemseitig zugewiesenen Identität des Foundry IQ-Diensts. Ersetzen Sie den Hostnamen und den Bereitstellungsnamen durch Ihre Werte. Wenn Sie stattdessen die Standardgatewaydomäne verwenden möchten, legen Sie resourceUri auf https://<apim-name>.azure-api.net fest.

{
  "vectorizers": [
    {
      "name": "apim-embedding",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://apim.contoso.com",
        "deploymentId": "my-text-embedding-3-small",
        "modelName": "text-embedding-3-small"
      }
    }
  ]
}

Referenz: Indizes - Erstellen.

Wählen Sie diesen Vektorizer in einem Vektorprofil aus, das dem einbettenden Modell entspricht, das zur Indizierungszeit verwendet wird. Um stattdessen eine angefügte, vom Benutzer zugewiesene Suchidentität auszuwählen, fügen Sie das folgende Objekt innerhalb azureOpenAIParametershinzu:

{
  "authIdentity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>"
  }
}

Geben Sie für die Schlüsselauthentifizierung apiKey an und lassen Sie authIdentity aus; Search sendet den Schlüssel im api-key-Header. Konfigurieren Sie das Gateway für die systemeigene Einbettungsroute und Authentifizierung.

Bewährte Verfahren für Leistungsoptimierung

Im Folgenden sind einige bewährte Methoden aufgeführt, die Sie beim Verwenden dieses Vektorizers berücksichtigen müssen:

  • Wenn du dein Azure OpenAI TPM (Tokens pro Minute)-Limit erreichst, solltest du die Empfehlung zu Quotenbeschränkungen in Betracht ziehen, um entsprechend darauf zu reagieren. Weitere Informationen zur Leistung Ihrer Azure OpenAI-Instanz finden Sie in der Dokumentation über das Azure OpenAI Monitoring.

  • Die Azure OpenAI-Einbettungsmodellbereitstellung, die Sie für diesen Vektorizer verwenden, sollte ideal von der Bereitstellung getrennt sein, die für andere Anwendungsfälle verwendet wird, einschließlich der embedding-Fähigkeit. Dadurch kann jede Bereitstellung auf ihren spezifischen Anwendungsfall zugeschnitten werden, was zu optimierter Leistung führt und den Datenverkehr vom Indexer einfach identifiziert sowie die Indexeinbettungsaufrufe erleichtert.

  • Ihre Azure OpenAI-Instanz sollte sich in derselben Region oder mindestens in der Nähe der Region befinden, in der Ihr Foundry IQ-Dienst gehostet wird. Dies reduziert die Latenz und verbessert die Geschwindigkeit der Datenübertragung zwischen den Diensten.

  • Um häufige 429-Fehlercodes zu vermeiden, sollten Sie den Lastenausgleich über die API-Verwaltung implementieren, indem Sie ein Lastenausgleichsgateway vor mehreren Azure OpenAI-Einbettungsmodellbereitstellungen implementieren.

  • Wenn Sie über ein größeres als standardmäßiges Azure OpenAI TPM (Token pro Minute) verfügen, wie in Kontingenten und Grenzwerten veröffentlicht, öffnen Sie einen Supportfall mit dem Foundry IQ-Team, damit dies entsprechend angepasst werden kann. Das hilft, dass Ihr Indexierungsprozess nicht unnötig durch das dokumentierte Standard-TPM-Limit verlangsamt wird, falls Sie höhere Limits haben.

Sicherheitsüberlegungen für die verwaltete Identitätsauthentifizierung

Wenn der Azure OpenAI-Vektorizer eine verwaltete Identität verwendet, sendet Foundry IQ ein Microsoft Entra Zugriffstoken für die Cognitive Services-Zielgruppe (https://cognitiveservices.azure.com) und den Abfragetext an den in resourceUri konfigurierten Endpunkt. Dieser Vorgang gilt, wenn Sie eine vom Benutzer zugewiesene Identität mit authIdentity auswählen oder sowohl apiKey als auch authIdentity weglassen, um die vom System zugewiesene Identität zu verwenden.

Konfigurieren Sie nur Endpunkte, denen Sie vertrauen, die unter Ihrer Kontrolle stehen und die sowohl das Token als auch den Text empfangen sollen. Ein Hostname allein stellt nicht die Eigentümerschaft oder Vertrauenswürdigkeit her. Verlassen Sie sich nicht auf eine Verbindungsüberprüfung, um festzustellen, dass ein API-Verwaltungsgateway einer Ressource vorgeschaltet ist, die Ihnen gehört.

Konfigurieren Sie den empfangenden Endpunkt, um die Signatur und Standardansprüche des Tokens zu überprüfen, einschließlich Aussteller, Zielgruppe, Mandant, Lebensdauer und erforderlichen Berechtigungen. Weisen Sie der verwalteten Identität des Foundry IQ-Diensts nur die mindestens erforderlichen Berechtigungen zu. Informationen zum Einrichten des Gateways und zur separaten API-Verwaltungs-zu-Back-End-Identität finden Sie unter Verwenden der API-Verwaltung mit Foundry IQ-Modellaufrufen.

Hinweis

Ein für die Zielgruppe "Foundry Tools" ausgestelltes verwaltetes Identitätstoken ist für alle Foundry Tools oder Azure OpenAI-Ressource gültig, für die die Identität autorisiert ist. Das Senden an einen nicht vertrauenswürdigen Endpunkt könnte das Token offenlegen.

Befolgen Sie die folgenden Methoden, um eine sichere Bereitstellung aufrechtzuerhalten:

  • Legen Sie resourceUri nur für Endpunkte fest, die Sie besitzen und denen Sie vertrauen. Verwenden Sie die Ressourcendomänen in Vectorizer-Parametern. Wenn Sie einen APIM-Endpunkt verwenden, bestätigen Sie das Routing, bevor Sie verwaltete Identität aktivieren. Ein vertrauenswürdig aussehender Hostname ist kein Nachweis der Inhaberschaft.
  • Wenden Sie bei jeder Verbindung das Prinzip der geringsten Rechte an. Gewähren Sie für direkte Azure OpenAI-Aufrufe oder die absichtliche Tokenweitergabe der ausgewählten Search-Identität Cognitive Services OpenAI-Benutzer für die Azure OpenAI- oder die übergeordnete Foundry-Ressource, die das Deployment hostet. Wenn APIM die Suchauthentifizierung beendet und seine eigene Identität verwendet, autorisieren Sie die Suche bei APIM, und gewähren Sie dieser Back-End-Rolle die Identität von APIM für die Modellhostingressource, nicht die Suche. Vermeiden Sie breitere Rollen.
  • Bewerten des Netzwerksicherheitsperimeters (Network Security Perimeter, NSP) und der privaten Konnektivität für die jeweilige Workload. Ein privater Endpunkt oder eine VNet-Integration auf dem Empfänger allein stellt keine Route vom Abfrageausführungshost bereit.
  • Wenn Sie einen APIM-Endpunkt verwenden, stellen Sie sicher, dass das Gateway eingehende Anforderungen überprüft und nur an das beabsichtigte Back-End weiterleitet. Außerdem sollten Sie die Zugriffsrichtlinien regelmäßig überprüfen.
  • Bevorzugen Sie verwaltete Identität gegenüber apiKey. Wenn Sie apiKey verwenden, speichern Sie es sicher und erneuern Sie es regelmäßig, und betten Sie es nicht in die Versionsverwaltung ein. Konfigurieren Sie nur eine Authentifizierungsmethode.
  • Überprüfen Sie in regelmäßigen Abständen Indexdefinitionen, Verwaltete Identitätsrollenzuweisungen und APIM-Konfigurationen, um zu bestätigen, dass resourceUri Werte, Zugriffssteuerungen und Identitätsberechtigungen aktuell und angemessen bleiben. Überprüfen Sie Konfigurationsänderungen im Rahmen Ihrer etablierten Change-Management- und Sicherheitsprüfprozesse.
  • Überwachen Sie die Anmeldeprotokolle, Authentifizierungsereignisse und Zugriffsprotokolle von Azure OpenAI und Foundry Tools auf unerwartete oder unbefugte Aktivitäten.
  • Entfernen Sie nicht verwendete Vektorisierer, Endpunkte, Rollenzuweisungen und API-Schlüssel, die nicht mehr benötigt werden.

Zugriff auf die Index- und Vektorizerkonfiguration beschränken

Benutzer, die Indexdefinitionen erstellen oder ändern können, steuern sowohl den Zielendpunkt (resourceUri) als auch die vom Vektorisierer verwendete Authentifizierungskonfiguration. Da der Vektorizer ein verwaltetes Identitätstoken für die Cognitive Services-Zielgruppe an diesen Endpunkt sendet, beschränken Sie diese Berechtigungen auf vertrauenswürdige Administratoren, und befolgen Sie Ihre standardmäßigen Change-Management- und Sicherheitsüberprüfungsprozesse, wenn Sie verwaltete Identitäts-fähige Vektorisierer konfigurieren.

Gehen Sie nicht davon aus, dass die Verwaltungseinstellung properties.dataExfiltrationProtections: ["BlockAll"] alle Azure OpenAI-Vektorizer deaktiviert. Beschränken Sie die Berechtigungen zum Bearbeiten von Indizes, und überprüfen Sie Ziele, Gatewayrichtlinien und Rollenzuweisungen. Informationen zu den gleichen Verantwortlichkeiten in Bezug auf das Zielvertrauen bei der Indizierung finden Sie unter Sicherheitsaspekte für benutzerdefinierte Web-API-Skills.

Siehe auch