Azure OpenAI Einbettungsfertigkeit

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.

Die Azure OpenAI Embedding Fähigkeit verbindet sich mit einem Embedding-Modell, das auf Ihrer Azure OpenAI in Foundry Models Ressource oder Microsoft Foundry bereitgestellt wird, um Embeddings während der Indexierung zu generieren. Ihre Daten werden im Geo verarbeitet, in dem Ihr Modell bereitgestellt wird.

Der Import Data Wizard im Azure-Portal nutzt die Azure OpenAI Embedding-Fähigkeit, um Inhalte zu vektorisieren. Du kannst den Wizard ausführen und das generierte Skillset überprüfen, um zu sehen, wie der Wizard die Fertigkeit für das Einbetten von Modellen aufbaut.

Note

Diese Fähigkeit wird garantiert OpenAI Azure und wird zum OpenAI-Standardpreis Azure OpenAI-Standardpreis berechnet.

Voraussetzungen

  • Eine Azure OpenAI in Foundry Models oder Foundry Projekt.

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

    • 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 Azure OpenAI-Embedding-Modell, das auf Ihre Ressource oder Ihr Projekt bereitgestellt wird. Für unterstützte Modelle siehe Abschnitt Skill-Parameter .

@odata.type

Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill

Datenlimits

Die maximale Größe einer Texteingabe sollte 8.000 Token betragen. Wenn die Eingabe das maximal erlaubte Maximum überschreitet, wirft das Modell einen ungültigen Anforderungsfehler. Weitere Informationen finden Sie im Schlüsselkonzept tokens in der Azure OpenAI-Dokumentation. Überlege, die Text-Split-Fähigkeit zu verwenden, wenn du Datenchunking brauchst.

Qualifikationsparameter

Die Parameter sind groß- und kleinschreibungssensitiv.

Eingaben 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 Standardhosts azure-api.net und konfigurierter benutzerdefinierter Domänen. Legen Sie separat fest deploymentId . Geben Sie keine vollständige URL des Einbettungsvorgangs an. Informationen zu Routing-, Authentifizierungs-, RBAC- und privaten Konnektivitätsqualifikationen finden Sie unter Verwenden der API-Verwaltung mit Foundry IQ (Azure KI-Suche)-Modellaufrufen.

apiKey Der geheime Schlüssel, mit dem man auf das Modell zugegriffen hat. Wenn du einen Schlüssel gibst, lass authIdentity es leer. Wenn du sowohl als auch apiKeyauthIdentityeinstellst, wird die apiKey für die Verbindung verwendet.
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 beides apiKey aus und authIdentity verwenden Sie die vom System zugewiesene Identität des Foundry IQ-Diensts. Weisen Sie für direkte Aufrufe oder Tokendurchlauf den OpenAI-Benutzer von Cognitive Services dem Modellhosting Azure OpenAI- oder übergeordnete 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
dimensions (Optional) Die Dimensionen der Embeddings, die du erzeugen möchtest, vorausgesetzt, das Modell unterstützt einen Dimensionsbereich. Standardmäßig sind die maximalen Abmessungen für jedes Modell. Für Skillsets, die mit REST-API-Versionen vor der Vorschau des 01.10.2023 erstellt wurden, sind die Dimensionen auf 1536 festgelegt. Wenn du die Eigenschaft dimensions in dieser Skill setzt, setze die dimensions Eigenschaft in der Vektorfelddefinition auf denselben Wert.

Unterstützte Dimensionen durch modelName

Die unterstützten Dimensionen für eine Azure OpenAI-Einbettungsfähigkeit hängen vom konfigurierten modelName ab.

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

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

Qualifikationseingaben

Eingabe Beschreibung
text Der Eingabetext wird vektorisiert. Wenn du Datenchunking verwendest, könnte die Quelle ./document/pages/*

Skill-Ergebnisse

Output Beschreibung
embedding Vektorisierte Einbettung für den Eingabetext.

Beispieldefinition

Betrachten wir einen Datensatz mit folgenden Feldern:

{
    "content": "Microsoft released Windows 10."
}

Dann könnte deine Fertigkeitsdefinition so aussehen:

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://my-demo-openai-eastus.openai.azure.com/",
  "deploymentId": "my-text-embedding-ada-002-model",
  "modelName": "text-embedding-ada-002",
  "dimensions": 1536,
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ]
}

Beispiel für eine benutzerdefinierte API-Verwaltung

Diese vollständige Qualifikationsdefinition verwendet eine konfigurierte benutzerdefinierte API-Verwaltungsgatewaydomäne und eine angefügte, vom Benutzer zugewiesene Suchidentität. Ersetzen Sie den Beispielhostnamen, den Bereitstellungsnamen und die Identitätsressourcen-ID durch Ihre Werte. Wenn Sie stattdessen die Standardgatewaydomäne verwenden möchten, legen Sie folgendes resourceUri fest:https://<apim-name>.azure-api.net

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "name": "apim-embedding",
  "context": "/document",
  "resourceUri": "https://apim.contoso.com",
  "deploymentId": "my-text-embedding-3-small",
  "modelName": "text-embedding-3-small",
  "dimensions": 1536,
  "authIdentity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<identity-name>"
  },
  "inputs": [{ "name": "text", "source": "/document/content" }],
  "outputs": [{ "name": "embedding" }]
}

Referenz: Skillsets – Erstellen oder Aktualisieren.

Lassen Sie die vom System zugewiesene Suchidentität aus authIdentity und apiKey verwenden Sie sie. Geben Sie apiKey für die Schlüsselauthentifizierung anstelle von authIdentity; Die Suche sendet sie in der api-key Kopfzeile. Konfigurieren Sie das Gateway für die systemeigene Einbettungsroute und Authentifizierung.

Beispielausgabe

Für den gegebenen Eingabetext wird eine vektorisierte Einbettung erzeugt.

{
  "embedding": [
        0.018990106880664825,
        -0.0073809814639389515,
        .... 
        0.021276434883475304,
      ]
}

Die Ausgabe befindet sich im Speicher. Um diese Ausgabe an ein Feld im Suchindex zu senden, musst du ein outputFieldMapping definieren, das die vektorisierte Einbettungsausgabe (die ein Array ist) auf ein Vektorfeld abbildet. Angenommen, die Fertigkeitsausgabe befindet sich im Einbettungsknoten des Dokuments und content_vector das Feld im Suchindex ist, sollte das outputFieldMapping im Indexer wie folgt aussehen:

  "outputFieldMappings": [
    {
      "sourceFieldName": "/document/embedding/*",
      "targetFieldName": "content_vector"
    }
  ]

Bewährte Methoden

Im Folgenden finden Sie einige bewährte Praktiken, die Sie bei der Nutzung dieser Fähigkeit beachten sollten:

  • Wenn du dein Azure OpenAI TPM (Tokens pro Minute)-Limit erreichst, solltest du die Quota-Grenzen in Betracht ziehen, damit du entsprechend umgehen kannst. Weitere Informationen zur Leistung Ihrer Azure OpenAI-Überwachung finden Sie in der Dokumentation Azure OpenAI Monitoring/c0.

  • Die Azure OpenAI-Embeddings-Modellbereitstellung, die du für diese Fähigkeit verwendest, sollte idealerweise von der Bereitstellung für andere Anwendungsfälle getrennt sein, einschließlich des query-Vektorizers. Dadurch kann jede Bereitstellung auf ihren spezifischen Anwendungsfall zugeschnitten werden, was zu optimierter Leistung führt und den Datenverkehr vom Indexer leicht identifiziert und die Indexaufrufe einbetten.

  • 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äufig 429 Fehlercodes zu vermeiden, sollten Sie den Lastenausgleich über die API-Verwaltung implementieren, indem Sie ein Gateway 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.

  • Beispiele und funktionierende Codebeispiele mit dieser Fähigkeit finden Sie unter den folgenden Links:

Fehler und Warnungen

Zustand Ergebnis
Null oder ungültige URI Fehler
Null oder ungültige DeploymentID Fehler
Der Text ist leer Warnung
Der Text ist größer als 8.000 Tokens Fehler

Sicherheitsüberlegungen für die verwaltete Identitätsauthentifizierung

Wenn die Azure OpenAI Embedding Skill die verwaltete Identitätsauthentifizierung verwendet, erhält Foundry IQ ein Microsoft Entra Zugriffstoken für die Zielgruppe "Foundry Tools" (https://cognitiveservices.azure.com) und schließt es in Anforderungen ein, die an den von resourceUriihnen angegebenen Endpunkt gesendet werden. Die verwaltete Identitätsauthentifizierung gilt, wenn authIdentity festgelegt wird oder wenn beide apiKey leer sind und authIdentity der Dienst die vom System zugewiesene Identität verwendet.

Der endpunkt, auf resourceUri den verwiesen wird, wird erwartet, dass es sich um Ihre eigene Azure OpenAI- oder Foundry Tools-Ressource handelt. Unterstützte Domains sind:

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

Azure API Management (APIM)-Endpunkte (*.azure-api.net) werden ebenfalls unterstützt. Da ein APIM-Hostname nicht allein anhand seines Namens überprüft werden kann, überprüft Foundry IQ diese Endpunkte mit einer Live-Konnektivitätsprüfung zur Konfigurationszeit anstatt nach Domänenabgleich. Sie sind für das Konfigurieren und Verwalten der Beziehung zwischen dem APIM-Endpunkt und der Azure OpenAI- oder Foundry Tools-Ressource dahinter verantwortlich.

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 verfügbar machen.

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

  • Legen Sie nur auf Endpunkte fest resourceUri , die Sie besitzen und vertrauen. Bevorzugen Sie die zuvor aufgeführten Domänen der Foundry Tools. Wenn Sie einen APIM-Endpunkt verwenden, stellen Sie sicher, dass sie Ihre eigene Ressource vorgibt, bevor Sie verwaltete Identität aktivieren. Ein vertrauenswürdig aussehender Hostname ist kein Besitznachweis.
  • Wenden Sie das Prinzip der geringsten Rechte auf die verwaltete Identität an, die vom Foundry IQ-Dienst verwendet wird. Die Azure OpenAI Embedding-Fähigkeit erfordert nur die Rolle "Cognitive Services OpenAI User" für die Zielressource. Vermeiden Sie die Gewährung breiterer Rollen.
  • Verwenden Sie den Netzwerksicherheitsperimeter (Network Security Perimeter, NSP) und private Endpunkte oder die VNet-Integration, um einzuschränken, welche Endpunkte der Foundry IQ-Dienst erreichen kann und von welchen Quellen die Zielressource Anforderungen akzeptiert.
  • 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 es verwenden apiKey, speichern und drehen Sie sie sicher, und betten Sie sie nicht in die Quellcodeverwaltung ein. Der Dienst lehnt Konfigurationen ab, die sowohl als apiKeyauch authIdentity .
  • Überprüfen Sie in regelmäßigen Abständen Skillsetdefinitionen, Zuordnungen verwalteter Identitätsrollen und APIM-Konfigurationen, um zu bestätigen, dass resourceUri Werte, Zugriffssteuerungen und Identitätsberechtigungen aktuell und angemessen bleiben. Überprüfen Sie Konfigurationsänderungen durch Ihre etablierten Change-Management- und Sicherheitsüberprüfungsprozesse.
  • Überwachen Sie Azure Anmeldeprotokolle der OpenAI- und Foundry-Tools, Authentifizierungsereignisse und Zugriffsprotokolle auf unerwartete oder nicht autorisierte Aktivitäten.
  • Entfernen Sie nicht verwendete Fähigkeiten, Endpunkte, Rollenzuweisungen und API-Schlüssel, die nicht mehr benötigt werden.

Einschränken des Zugriffs auf die Konfiguration von Skillset

Benutzer, die Skillsets erstellen, ändern oder ausführen können, steuern sowohl den Zielendpunkt (resourceUri) als auch die von der Qualifikation verwendete Authentifizierungskonfiguration. Da die Fähigkeit ein verwaltetes Identitätstoken für die Zielgruppe "Foundry Tools" 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 beim Konfigurieren verwalteter Identitätsfunktionen.

Siehe auch