Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
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 EigenschaftresourceUriin 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, undhttps://<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 EigenschaftresourceUriin 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:
Azure API Management HTTPS-Gatewaybasis-URIs werden ebenfalls unterstützt, einschließlich Standardhosts |
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:
|
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.comcognitiveservices.azure.comservices.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.
Empfohlene Sicherheitsmaßnahmen
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 verwendenapiKey, speichern und drehen Sie sie sicher, und betten Sie sie nicht in die Quellcodeverwaltung ein. Der Dienst lehnt Konfigurationen ab, die sowohl alsapiKeyauchauthIdentity. - Überprüfen Sie in regelmäßigen Abständen Skillsetdefinitionen, Zuordnungen verwalteter Identitätsrollen und APIM-Konfigurationen, um zu bestätigen, dass
resourceUriWerte, 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.