Verwenden Sie API Management für Modellaufrufe mit Foundry IQ (Azure KI-Suche)

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.

Important

Features oder Funktionen, die in diesem Artikel als "Vorschau" gekennzeichnet sind, befinden sich in der öffentlichen Vorschau und unterliegen den ergänzenden Nutzungsbedingungen für Microsoft Azure Previews.

Vorschaubegriffe speziell für Foundry IQ (Azure KI-Suche) finden Sie unter Vorschaufunktionen.

Informationen zu Bedingungen, die gelten, wenn Sie unterstützte Nicht-Microsoft Modelle verwenden, finden Sie unter Drittanbietermodelle. Wenn Sie API Management so konfigurieren, dass es an unterstützte Gateways von Drittanbietern weiterleitet, lesen Sie Gateways von Drittanbietern über API Management.

Verwenden Sie Azure API Management als Gateway für unterstützte Foundry IQ (Azure KI-Suche)-Modellaufrufe, um Routing, Drosselung, Lastenausgleich und Überwachung zu zentralisieren. Die Unterstützung hängt von der Suchworkload sowie von ihrem Modellprotokoll, ihrer Authentifizierung und ihrer Ausführungsumgebung ab.

Beginnend mit 2026-11-01-preview, openAI-kompatible Wissensbasis-LLMs für den agentischen Abruf akzeptieren vollständige Endpunkt-URLs. Diese Endpunkte können API-Verwaltung, ein Kundengateway oder ein direkt konfigurierter kompatibler Drittanbieter sein. API Management ist für diese Konfiguration der Wissensdatenbank nicht erforderlich. Azure OpenAI-Einstellungen und Einstellungen für kompatible Wissensdatenbanken haben unterschiedliche Schnittstellen.

Prerequisites

  • Ein Foundry IQ-Dienst und die Berechtigung zum Konfigurieren der Workload. Weisen Sie beispielsweise Search Service Contributor zu, um Indizes und Wissensdatenbanken zu erstellen oder zu aktualisieren. Siehe "Verbinden mithilfe von Rollen".
  • Ein Modellendpunkt, der die für die Workload erforderlichen Protokolle und Funktionen implementiert, einschließlich strukturierter Ausgabe- und Toolaufrufe, sofern erforderlich.
  • Für die API-Verwaltung, eine konfigurierte Gateway-API und ein Back-End mit separater Authentifizierung für Such-zu-Gateway- und Gateway-zu-Backend-Verbindungen.
  • Für kompatible Wissensbasis-LLMs und systemeigene GPT-6-KB-Profile legen Sie api-version=2026-11-01-preview bei Anforderungen zum Erstellen, Aktualisieren und Abrufen der Wissensbasis fest. Befolgen Sie die November-Vorschau-KB-Konfiguration und die Abrufverifizierung. Verwenden Sie die vorhandenen Workload-API-Versionen für andere Konfigurationen.
  • Für verwaltete Identitäten sind eine aktivierte Foundry IQ-Dienstidentität, Autorisierung am empfangenden Endpunkt und die Berechtigung zum Zuweisen aller erforderlichen Rollen erforderlich.

Wählen Sie eine unterstützte Workload und API aus

Die folgende Tabelle beschreibt Verbindungen von Modellen, nicht die Zertifizierung aller Topologien privater Netzwerke. Siehe Private Konnektivität für Netzwerkqualifikationen.

Arbeitsbelastung Verfügbarkeit der Such-API Protokoll- und Modellauswahl Endpunkt und Authentifizierung
Azure OpenAI-Embedding-Skill Native Unterstützung für 2023-10-01-preview; stabile 2024-07-01. Konfigurierbare moderne Modellabmessungen von 2024-05-01-preview oder Stable 2024-07-01. Einbettungen; drei Einbettungsprofile. Native Ressourcen-URI plus Bereitstellungs-ID; Standard- und benutzerdefinierte Gatewaydomänen von API Management werden unterstützt. Nativer Schlüssel oder verwaltete Identität.
Azure OpenAI-Vektorizer Native Unterstützung durch 2023-10-01-preview; stabile 2024-07-01. Einbettungen für Textabfragen; drei Einbettungsprofile. Native Ressourcen-URI plus Bereitstellungs-ID; Standard- und benutzerdefinierte API-Verwaltungsgatewaydomänen werden unterstützt. Nativer Schlüssel oder verwaltete Identität.
GenAI Prompt-Skill Von 2025-05-01-preview; GA 2026-04-01. Chat Completions mit einem Endpunkt und einem Modell, die die Eingaben und Generierungsparameter des Skills unterstützen. Vollständige uri; Standard- oder benutzerdefinierte API-Management-Gatewaydomäne. Native Schlüssel-/Identitätseigenschaften.
Optionale LLM für Inhaltsverständnis Base skill GA 2026-04-01; optionale LLM-Eigenschaften GA 2026-10-01. Inhaltsverständnisvorgang mit einem unterstützten Modell in der angefügten Ressource. Modell- und Bereitstellungseinstellungen in der Foundry-Ressource, die dem Skillset angefügt ist.
Modell für nativen KB-Abruf Bestehender systemeigener KB-Vertrag; GPT-6 Antwortprofile erfordern 2026-11-01-preview. Suche wählt Chat Completions oder Responses im Modellprofil aus. Einstellungen für native Ressourcen/Bereitstellungen. Die API-Verwaltung wird mit diesen Einstellungen nicht unterstützt. verwenden Sie die separat unterstützte KB-Vorschau für eine Gatewayverbindung.
Kompatibles KB-Abrufmodell 2026-11-01-preview. Profilgewählte Chatabschlusse oder Antworten; 21 unterstützte KB-Profile. Vollständige HTTPS-POST-URL; Header oder verwaltete Identität mit benutzerdefinierter Zielgruppe. Wird mit Web-Wissensquellen nicht unterstützt.
Nativer Chat zur Erfassung von Wissensquellen Vorhandener Vertrag für verwaltete Ingestion Non-Content Understanding Image Verbalization erstellt Chat-Abschlussanforderungen; Content Understanding verwendet einen eigenen Vorgang. Systemeigenes Aufnahmemodell und Bereitstellungseinstellungen.
native Einbettungen für Wissensquellen Vorhandener verwalteter Ingestionsvertrag. Native Embeddings. Systemeigene Ressourcen- und Bereitstellungseinstellungen.

Die API-Verwaltung wird nicht als Gateway für Analyzeranforderungen für Content Understanding oder optionale Aufrufe des Bildbeschreibungsmodells unterstützt.

Die kompatible KB-Vorschau gilt nur für die Konfiguration des Abrufmodells. Es ändert die Konfiguration des Wissensquellen-Aufnahmemodells nicht oder erweitert die systemeigene Einbettungskompetenz und den Vektorizer auf kompatible Anbieterprotokolle.

Für berechtigungsgeschützte Inhalte macht ein separater GenAI Prompt-Skill (Chat Completion) API Management nicht zu einem unterstützten Ziel. Für die Nur-ACL-Aufnahme erfordert diese Fähigkeit einen unterstützten Microsoft-Endpunkt eines Erstanbieters, nicht API Management. Bei der Aufnahme von Vertraulichkeitsbezeichnungen wird diese Fähigkeit nicht unterstützt. Überprüfen Sie die SharePoint ACL-Einschränkungen vor der Konfiguration der Anreicherung. Die Authentifizierung oder das private Routing entfernt diese Einschränkungen nicht.

Suchdatenebenen-API-Versionen, Suchverwaltungs-API-Versionen, API-Verwaltungsversionen, nachgelagerte Modell-API-Versionen und bereitgestellte Modellversionen sind unabhängig. Durch das Ändern einer Such-API-Version wird die downstream-API nicht geändert oder ein anderes Modell bereitgestellt.

Grundlegendes zu Endpunkt- und Protokollanforderungen

Nativen Endpunkte

Legen Sie für die Azure OpenAI-Einbindungskompetenz und -Vektorizer resourceUri auf den Basis-URI der Ressourcenbasis-URI oder den HTTPS-API-Verwaltungsgatewaybasis-URI fest. Sie können sowohl den Standardgatewayhostnamen, wie z. B. https://<apim-name>.azure-api.net, als auch eine konfigurierte benutzerdefinierte Domäne, wie z. B. https://apim.contoso.com, verwenden. deploymentId separat festlegen. Die Unterstützung für benutzerdefinierte Domänen ändert das systemeigene Einbettungsprotokoll nicht und fügt keine Unterstützung für beliebige kompatible Anbieter hinzu.

Die Suche erstellt /openai/deployments/<deploymentId>/embeddings?api-version=2023-05-15 für diese nativen Einbettungsaufrufe. Konfigurieren Sie die Gateway-API und Richtlinien, um diesen Pfad und diese Abfragezeichenfolge zu akzeptieren und an die beabsichtigte Azure OpenAI-Bereitstellung weiterzuleiten. Wenn das Back-End einen anderen Pfad, Bereitstellungsnamen oder eine andere API-Version benötigt, schreiben Sie ihn in API Management um. Geben Sie keine vollständige URL des Embeddings-Vorgangs in resourceUri ein.

Das folgende Parameterfragment verwendet die Standardgatewaydomäne. Verwenden Sie sie als Parameter der Einbettungskompetenz oder innerhalb des azureOpenAIParameters eines Vektorizers. Er verwendet die vom System zugewiesene Identität des Foundry IQ-Diensts, da sowohl apiKey als auch authIdentity weggelassen werden.

{
  "resourceUri": "https://contoso-models.azure-api.net",
  "deploymentId": "my-text-embedding-3-small",
  "modelName": "text-embedding-3-small"
}

Ändern Sie für eine benutzerdefinierte Gatewaydomäne nur resourceUri in https://apim.contoso.com. Konfigurieren Sie diesen Hostnamen und sein TLS-Zertifikat im API-Verwaltungsgateway. Die Bereitstellungs- und Modelleinstellungen bleiben getrennt. Vollständige Definitionen und die vom Benutzer zugewiesene Identitätsauswahl finden Sie in den Beispielen für Embedding-Skill und Vektorisierer.

Geben Sie für die GenAI Prompt-Fähigkeit den vollständigen Modellaufruf urian, einschließlich des Vorgangspfads und aller erforderlichen Abfrageparameter. API-Verwaltungsstandard- und benutzerdefinierte Gatewaydomänen werden unterstützt. Eine Gatewaybasis-URL allein ist keine vollständige GenAI-Vorgangs-URL.

Aufrufe für systemeigene KB-Chatabschlüsse verwenden den Bereitstellungspfad, z. B. https://<resource-name>.openai.azure.com/openai/deployments/<deployment>/chat/completions?api-version=2024-08-01-preview. Native GPT-6 KB-Profile verwenden https://<resource-name>.openai.azure.com/openai/v1/responses, wobei die Bereitstellungs-ID im Anforderungstext model steht.

Kompatible Endpunkte

Für kompatible Wissensbasis-LLMs, die für den Abruf verwendet werden:

  1. Geben Sie eine vollständige absolute HTTPS POST-URL an uri, einschließlich der Pfad- und Abfrageparameter. Beispiel:
    • Chatvervollständigungen: https://<apim-name>.azure-api.net/openai/deployments/<deployment>/chat/completions?api-version=<downstream-api-version>.
    • Antworten: https://<gateway-host>/openai/v1/responses.
  2. Konfigurieren Sie den Endpunkt so, dass es das ausgewählte Protokoll akzeptiert. Search sendet die URL unverändert: Es hängt keinen Bereitstellungspfad, keine Operation und kein api-version an.
  3. Betten Sie keine Anmeldeinformationen oder ein Fragment in die URL ein. Die Suche folgt auch Weiterleitungen zum selben Host nicht.
  4. Konfigurieren Sie das Routing an der URL oder dem Gateway. Kompatible Request-Bodys der Wissensdatenbank lassen model weg. Wenn der Anbieter einen model Bezeichner erfordert, muss das Gateway ihn angeben.

Benutzerdefinierte Gatewaydomänen und direkte kompatible Endpunkte von Drittanbietern verwenden diesen Vertrag. Wenn für eine Anbieter-URL ein Modell im Anforderungstext erforderlich ist, benötigen Sie ein Gateway oder einen Adapter, der diesen Wert bereitstellt.

modelName wählt das Profil und die Funktionen der Suche aus. Sie wählt die tatsächliche Downstreambereitstellung nicht aus oder überprüft sie nicht, identifiziert eine datierte Anbietermodellversion oder macht ein beliebiges Anbieterprotokoll kompatibel. Es gibt keine öffentliche Protokollauswahl für die kompatible Wissensbasiskonfiguration.

Behalten Sie für den Responses-Wissensdatenbankabruf zustandslose Fortsetzungsstrukturen, Eingaben und Ausgaben von Funktionsaufrufen sowie verschlüsselte Reasoning-Inhalte bei. Search sendet store:false. Das Akzeptieren einer Modellnamenzeichenfolge oder einer einfachen Textanforderung ist keine ausreichende Kompatibilität. Die Protokollübersetzung an einem Gateway macht das nachgelagerte Protokoll nicht zu einem nativen Search-Protokoll.

Konfigurieren Sie die Such-zu-Gateway-Authentifizierung

Trennen Sie die Authentifizierung von Anwendung zu Suche getrennt von der Authentifizierung von Such-zu-Gateways. Die Anmeldeinformationen, die Sie zum Erstellen oder Abfragen eines Search-Objekts verwenden, sind nicht die Anmeldeinformationen, die für ausgehende Modellaufrufe verwendet werden.

Native Authentifizierung

Native Azure OpenAI-Einbettungseinstellungen verwenden apiKey oder die von Search verwaltete Identität. Die Schlüsselauthentifizierung emittiert api-key, nicht automatisch Ocp-Apim-Subscription-Key. Konfigurieren Sie den Abonnementschlüsselheader oder die Richtlinien von API Management so, dass sie mit dem Header übereinstimmen, den die Workload sendet.

Native verwaltete Identität erhält ein Token für die Cognitive Services-Zielgruppe (https://cognitiveservices.azure.com). Lassen Sie apiKey und authIdentity für eine vom System zugewiesene Identität weg, oder verwenden Sie für eine zugeordnete, vom Benutzer zugewiesene Identität das Identitätsobjekt der Workload. Konfigurieren Sie nur eine Authentifizierungsmethode. Sehen Sie sich jeden Workloadverweis für die unterstützten Identitätseigenschaften an.

Konfigurieren Sie das Gateway, um das Token zu überprüfen und die ausgewählte Suchidentität zu autorisieren, einschließlich Signatur, Aussteller, Cognitive Services-Zielgruppe, Mandant, Lebensdauer und erforderlichen Berechtigungen. Die systemeigene Authentifizierung erwirbt kein Token für die Anwendungszielgruppe einer benutzerdefinierten Gatewayanwendung. Verwenden Sie das Client-zu-Gateway-Muster in Szenario 2: Die Client-App autorisiert die API-Verwaltung, wobei die Validierung für die Audience konfiguriert ist, an die diese Workload tatsächlich sendet. Szenario 3 beschreibt die Autorisierung des Anmeldeinformations-Managers für SaaS-Back-Ends, nicht diese Verbindung.

Kompatible Authentifizierung

Wenn Sie eine kompatible Knowledge-Base-LLM-Verbindung erstellen, geben Sie genau einen effektiven Authentifizierungsmodus in openAICompatibleParameters an:

Modus Configuration Anforderung an den Empfangsendpunkt
Gespeicherte Header Eine nicht erwendige headers Karte. Headernamen und Werte sind geheim. Akzeptieren und überprüfen Sie die konfigurierten Anmeldeinformationen. Für API Management kann diese Anforderung den Abonnementheader enthalten.
Verwaltete Identität managedIdentityAudience, optional zusammen mit authIdentity. Überprüfen und autorisieren Sie die Suchidentität für die Zielgruppe der Kundenanwendung.

managedIdentityAudiencemuss eine kanonische Microsoft Entra Anwendungs-GUID sein, z11111111-2222-3333-4444-555555555555. B. . Verwenden Sie api://, /.default, keinen Bereich oder die Cognitive Services-Zielgruppe nicht. Lassen Sie authIdentity weg, um die dem Foundry IQ-Dienst zugewiesene Systemidentität zu verwenden.

Um eine angefügte benutzerzugewiesene Identität auszuwählen, fügen Sie dieses Identitätsobjekt zusammen mit managedIdentityAudience hinzu:

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

Dieses Eigenschaftenfragment ist keine vollständige Verbindung. Beide Modi zusammen, keiner der beiden Modi beim Erstellen, eine leere Kopfzeilenzuordnung oder authIdentity ohne managedIdentityAudience sind ungültig. Bei Fehlern beim Tokenerwerb oder bei der Validierung wird nicht auf die anonyme Authentifizierung zurückgegriffen.

Konfigurieren Sie die Gateway-zu-Back-End-Authentifizierung

Sichern Sie die Back-End-Verbindung unabhängig. Bei einem von Microsoft betriebenen Azure OpenAI-Back-End ist ein gängiges Muster die Beendigung von Anmeldeinformationen bei der API-Verwaltung, gefolgt von der Authentifizierung mit der eigenen system- oder vom Benutzer zugewiesenen verwalteten Identität von API Management. Weisen Sie diesen Identity Cognitive Services OpenAI-Benutzer auf der Azure OpenAI- oder übergeordneten Foundry-Ressource zu, die die Back-End-Bereitstellung hostet und ihren Endpunkt besitzt. Konfigurieren Sie die Back-End-Richtlinie, um diese Identität zu verwenden. Die Suchidentität benötigt keine Rolle in diesem Back-End, wenn die API-Verwaltung ihre Anmeldeinformationen beendet und ihre eigene Identität verwendet.

Speichern Sie alternativ den Back-End-Schlüssel in einem API Management-benannten Wert, und verwenden Sie eine Richtlinie, um ihn an das Back-End zu senden. Der Back-End-Schlüssel ist nicht der Search-to-Gateway-Abonnementschlüssel.

Konfigurieren Sie für ein Kunden- oder Drittanbieter-Back-End die erforderliche Autorisierung, Routing und Protokollanpassung des Back-Ends. Die verwaltete Identität von Search-to-Gateway stellt in diesem Back-End keine Autorisierung her.

Siehe dienstseitige Authentifizierungsoptionen, verwaltete API-Identitäten und generative KI-Gatewayfunktionen.

Auswählen des Rollenbereichs und der Identität

Weisen Sie für direkte Azure OpenAI-Aufrufe oder die absichtliche Tokenweitergabe der ausgewählten verwalteten Search-Identität Cognitive Services OpenAI User zu. Legen Sie die Zuordnung auf die Azure OpenAI- oder übergeordnete Foundry-Ressource fest, die die Bereitstellung hostet und den Endpunkt besitzt.

Wenn das Projekt contoso-project beispielsweise die Bereitstellung my-text-embedding-3-small für die übergeordnete Ressource contoso-foundry verwendet, ist der Rollenbereich /subscriptions/<model-subscription-id>/resourceGroups/<model-resource-group>/providers/Microsoft.CognitiveServices/accounts/contoso-foundry. Verwenden Sie für eine eigenständige Azure OpenAI-Ressource namens contoso-modelsdie entsprechende Ressourcen-ID, die auf /Microsoft.CognitiveServices/accounts/contoso-models. Keiner der beiden Bereiche enthält /projects/<project-name> oder den Bereitstellungsnamen.

Informationen zu Identitätsbezeichnern und Rollenzuweisungsschritten finden Sie unter Eine Rolle zuweisen. Identifizieren Sie für eine benutzerdefinierte API-Verwaltungsdomäne die Modellhostingressource aus der Back-End-Konfiguration des Gateways und nicht vom Gatewayhost.

Weisen Sie auf der Seite Access control (IAM) der modellhostenden Ressource dem richtigen Sicherheitsprinzipal die Rolle zu. Wenn sich die Suche und die Modellressource in verschiedenen Ressourcengruppen oder Abonnements im selben Microsoft Entra Mandanten befinden, verwenden Sie das Abonnement und die Ressourcengruppe der Modellressource im Rollenzuweisungsbereich. Stellen Sie sicher, dass Sie über rollenzuweisungsberechtigungen in diesem Bereich verfügen. Siehe Azure RBAC-Bereich. Verwaltete Identitäten unterstützen keinen verzeichnisübergreifenden Zugriff.

Überprüfen Sie bei 401- oder 403-Fehlern die ausgewählte Identität, den Ressourcenbereich, die Ausbreitung der Rollenzuweisung und jeden Authentifizierungsschritt. Wenn die lokale Authentifizierung für die Modellressource deaktiviert ist, verwenden Sie eine autorisierte verwaltete Identität anstelle eines Schlüssels. RBAC gewährt Autorisierung; es konfiguriert keine DNS-, Firewalls- oder privaten Routen.

Verwenden eines kompatiblen Knowledge Base-Modells

Die vollständige REST-Konfiguration, die genauen 21 KB-Modellprofile und separate Beispiele für Chatabschlusse und Antworten finden Sie unter Verwenden eines openAI-kompatiblen Modells (Vorschau).

Sie können eine vorhandene Wissensbasis von einer nativen Azure OpenAI oder Microsoft Foundry-Modellendpunkt zu einem APIM- oder benutzerdefinierten Domänenendpunkt wechseln, ohne ihn neu zu erstellen. Verwenden Sie 2026-11-01-preview oder eine spätere unterstützte Preview-Version, und befolgen Sie die Anforderungen zum Aktualisieren der Modellverbindung.

Konfigurieren Sie das Abruf-LLM unter der models-Sammlung der Wissensbasis mithilfe von kind: "openAICompatible" und openAICompatibleParameters. Eine Wissensbasis mit einer Web-Wissensquelle erfordert native Azure OpenAI-Chatkonfiguration.

Überprüfen Sie nach der Konfiguration die Verbindung zum Abrufmodell in derselben Wissensdatenbank mit 2026-11-01-preview. Verwenden Sie LLM-gesicherten Abruf und prüfen Sie nichtsecret-Modellaktivitäten und Gatewayrouting. Eine erfolgreiche Erstellung oder GET allein überprüft keinen Modellaufruf.

Unterstützte Azure OpenAI-Einbettungsmodelle

Einbettungsprofile

Die Azure OpenAI Embedding Skill und Vectorizer unterstützen die folgenden Modelle. Verwenden Sie die vorhandene Workloadkonfiguration mit resourceUri, deploymentIdund modelName.

Profile Standardabmessungen Akzeptierte Dimensionen
text-embedding-ada-002 1536 Nur 1536
text-embedding-3-small 1536 1–1536
text-embedding-3-large 3072 1–3072

Effektive Ausgabeabmessungen müssen mit dem Vektorfeld übereinstimmen. Verwenden Sie dasselbe Einbettungsmodell und die gleichen Einstellungen zur Aufnahme- und Abfragezeit; Gleiche Dimensionen allein richten keinen freigegebenen semantischen Raum ein. Vollständige Konfigurationen finden Sie in den Referenzen zum Einbetten und Azure OpenAI-Vektorisierer.

Aktualisieren von Anmeldeinformationen und Modellkonfiguration

Für kompatible Wissensbasis-LLMs sind headers nur schreibbar. Öffentliche Antworten lassen die Eigenschaft vollständig aus, einschließlich der Kopfzeilennamen. Sie geben keinen maskierten Wert, {} oder null zurück.

Bei derselben Knowledge Base- und Modellbindung kann ein Update, das keine gespeicherten Anmeldeinformationen enthält, nur dann beibehalten, wenn der genaue Endpunkt, das Modellprofil und die Authentifizierungsidentität headers unverändert bleiben.

Update Erforderliche Aktion
Unverändertes Lesen-zu-PUT Behalten Sie die gleichen Ressourcen-/Bindungs- und Verbindungs-/Profil-/Identitätseinstellungen bei. Ausgelassene Header können gespeicherte Anmeldeinformationen beibehalten.
Ziel, Profil oder Identität geändert Geben Sie eine neue Authentifizierung an. Übertragen Sie kein weggelassenes Geheimnis in den geänderten Gültigkeitsbereich.
Kopieren, Umbenennen oder Erstellen aus einem Leseergebnis Geben Sie die Authentifizierung explizit an; Auslassung erbt die Anmeldeinformationen eines anderen Objekts nicht.
Header-Anmeldedaten rotieren Senden Sie die vollständige gültige Ersatzheaderzuordnung in derselben Modellbindung.
Zwischen Header-/Managed-Identity-Modi wechseln Geben Sie den neuen gültigen Modus an, und entfernen Sie den alten Modus aus der Anforderung.
Abgelehnte Aktualisierung Vorhandene gespeicherte Anmeldeinformationen bleiben unverändert.

Ersetzen Sie beispielsweise einen KB-Header, indem Sie die vorhandene vollständige KB-Definition mit einer Ersatzzuordnung headers senden. Bei einem nachfolgenden GET wird headers weggelassen; ein unveränderter PUT dieses Leseergebnisses kann den Ersatz beibehalten. Ändern Sie uri in diesem Leseergebnis nicht und erwarten Sie nicht, dass das ausgelassene Geheimnis dabei erhalten bleibt.

Wiederholen Sie die ÜBERPRÜFUNG des LLM-gesicherten Abrufs nach der Drehung und nach einem unveränderten Read-to-PUT-Update. Vergewissern Sie sich, dass das Gateway die Ersatzanmeldeinformationen akzeptiert und der Abruf weiterhin erfolgreich ist, ohne Headernamen, Werte oder Token zu protokollieren.

Private Konnektivität konfigurieren

Ein privater API-Verwaltungsendpunkt ist eine eingehende Verbindung zu ihrer Gateway-Laufzeitunterressource. Gateway ist keine Dienstebene. URLs für Verwaltung, Portal und Entwickerdokumentation sind keine Endpunkte für Modellaufrufe und werden nicht von dieser Gateway-Private-Link-Verbindung abgedeckt.

API Management-Tarife und Topologie

Tarif oder Topologie API-Verwaltungsfunktion Suchabfrage
Standard v2 Eingehender privater Endpunkt und integration ausgehender virtueller Netzwerke. Überprüfen Sie die Ausführungsroute der Search-Arbeitslast separat.
Premium v2 Eingehende private Endpunkte und Integrations-/Einfügungsoptionen für virtuelle Netzwerke. Eine API-Verwaltungsfunktion ist keine Garantie dafür, dass jede injizierte Topologie mit einer freigegebenen privaten Verbindung von Search funktioniert.
Classic Premium, nicht VNet-injiziert Unterstützt eingehende private Endpunkte. Behandeln Sie nicht alle klassischen Premium-Instanzen als nicht unterstützt.
Classic Premium, interne VNet-Injektion Private Endpunkte werden nicht unterstützt. Wird für diesen Entwurf für freigegebene private Links nicht unterstützt.
Classic Premium, externe VNet-Injektion Private Endpunkte werden nicht unterstützt. Wird für diesen Entwurf für freigegebene private Links nicht unterstützt.
Classic Developer, Basic, Standard Enthalten in der Unterstützung privater Endpunkte der API-Verwaltung, vorbehaltlich ihrer Einschränkungen. Keine umfassende Zertifizierung von Suchauslastungsrouten.
Gateway für selbstgehostete oder Arbeitsbereiche Wird für die dokumentierte eingehende Private-Endpunkt-Verbindung nicht unterstützt. Diese Einschränkung betrifft private Konnektivität, nicht alle öffentlichen Protokollszenarien.

Weitere Informationen finden Sie unter API Management v2-Ebenen und Einschränkungen für private Endpunkte. API Management v2-Funktionen verwenden die Verwaltungs-API 2024-05-01 oder höher oder später. Diese Version wählt nicht die Search-Datenebene oder Verwaltungs-API aus.

Classic Premium wird weiterhin unterstützt und wird nicht eingestellt. Die API-Verwaltung verfügt derzeit nicht über automatisierte Tools zum Migrieren einer vorhandenen instanz der klassischen Ebene, einschließlich Premium, zu einer v2-Ebenen-Instanz. Die v2-Ebenen sind für neu erstellte Instanzen verfügbar. Weitere Informationen finden Sie in den häufig gestellten Fragen zur Migration zu API Management v2 und zur klassischen Ebene.

Beispielsweise wird eine klassische Premium-Instanz mit interner VNet-Einfügung und einer Zielbestimmung Microsoft.ApiManagement/service / Gateway für freigegebene private Suchlinks nicht unterstützt. Die externe VNet-Einfügung hat dieselbe Einschränkung. Eine richtige Ressourcen-ID, genehmigte Verbindungsanforderung oder benutzerdefinierte Domäne entfernt diese Topologieeinschränkung nicht.

Folgen Sie für berechtigte Indexererweiterungen ausgehende Verbindungen über einen freigegebenen privaten Link:

  1. Bestätigen Sie die Eignung der Suchebene, Cloud, Workload und des privaten Ausführungskontexts.
  2. Erstellen Sie einen freigegebenen Private Link für den Ressourcentyp Microsoft.ApiManagement/service mit Gruppen-ID Gateway. Der vorhandene Suchleitfaden verwendet die Verwaltungs-API 2025-05-01; dies ist nicht die Version der nachgelagerten Modell-API.
  3. Genehmigen Sie die Verbindung in der API-Verwaltung, und bestätigen Sie die erfolgreiche Bereitstellung und Genehmigung.
  4. Legen Sie parameters.configuration.executionEnvironment der berechtigten Indexer auf "private" fest.
  5. Überprüfen Sie die DNS-Auflösung, TLS und das Routing aus der tatsächlichen Ausführungsumgebung. Verwenden Sie den konfigurierten Gatewayhostnamen, nicht eine private IP-Adresse, im Modell-URI. Das Zertifikat muss mit diesem Hostnamen übereinstimmen. Konfigurieren Sie für eine benutzerdefinierte Domäne DNS für diesen Namen sowie das standardmäßige privatelink.azure-api.net private DNS-Setup. Standard v2 und Premium v2 erfordern außerdem, dass der benutzerdefinierte Gatewayname öffentlich aufgelöst werden kann; siehe Dns-Einschränkungen für die benutzerdefinierte Domäne.
  6. Deaktivieren Sie den öffentlichen Netzwerkzugriff von API Management erst, nachdem der private Endpunkt konfiguriert wurde und die private Route überprüft wurde. Halten Sie für eine öffentliche Search-to-APIM-Verbindung den öffentlichen Endpunkt des Gateways unter den Netzwerkrichtlinien zugänglich. Die Einstellungen für öffentliche Netzwerke bei Search, API Management und dem Backend sind unabhängig voneinander.
  7. Sichern Sie die Vernetzung zwischen API Management und dem Backend unabhängig voneinander.

Fügen Sie keine Indexerausführungseigenschaften zu KB-Abruf- oder Abfragevektorisierungsanforderungen hinzu. Die Registrierung des Ziels des API Management-Gateways begründet keine Unterstützung privater Routen für jeden Ausführungshost für KBs oder Query-Vectorizer. Das Akzeptieren einer privaten Zieladresse richtet keine Route ein. Die API-Verwaltungsunterstützung bietet auch keine allgemeine Unterstützung für beliebige Microsoft.Network/privateLinkServices Ziele.

Sicherheitsaspekte

Foundry IQ sendet Modelleingaben und konfiguriertes Authentifizierungsmaterial an den ausgewählten Endpunkt. Konfigurieren Sie nur Endpunkte, denen Sie vertrauen und die Sie kontrollieren und die diese Eingaben und Anmeldeinformationen empfangen sollen. Ein Hostname oder eine Audience-GUID allein stellt keinen Endpunktbesitz, keine Autorisierung oder private Konnektivität her.

Überprüfen Sie verwaltete Identitätstoken am empfangenden Endpunkt, einschließlich Signatur, Aussteller, Zielgruppe, Mandant, Lebensdauer und erforderlichen Berechtigungen. Wenden Sie auf Such- und API-Verwaltungsidentitäten das Prinzip der geringsten Rechte an. Beschränken Sie die Berechtigung zum Ändern von Indexdefinitionen, Wissensdatenbanken, Wissensquellen und Gatewayrichtlinien.

Überprüfen Sie Routing, downstream-Anbieter, Protokollierung, Aufbewahrung, geografische Verarbeitung und Zugriffssteuerungen, bevor Sie eine Verbindung aktivieren. Sichern Sie die Such-zu-Gateway-Authentifizierung getrennt von der Gateway-zu-Back-End-Authentifizierung. Eine verwaltete Identität macht ein kunden- oder drittanbieterseitiges Back-End nicht zu einem von Microsoft betriebenen.

Die Suchverwaltungseinstellung properties.dataExfiltrationProtections verwendet den öffentlichen Wert ["BlockAll"]. Es blockiert kompatible Wissensbasismodellaufrufe. Behandeln Sie diesen Wert nicht als Schalter, der jeden Azure OpenAI-Vektorizer deaktiviert. Überprüfen Sie Azure OpenAI-Vektorizer-Sicherheitsleitfaden und die Netzwerksteuerelemente der jeweiligen Workload.

Problembehandlung für nicht unterstützte Kombinationen

Symptom oder Konfiguration Was soll überprüft werden?
Vorgang nicht gefunden oder Umleitung Geben Sie die vollständige kompatible POST-URL und die richtigen Abfrageparameter an. Die Suche fügt keine Pfade an oder folgt Weiterleitungen.
Fehlendes Anbietermodell Kompatible KB-Textkörper lassen model aus. Url-Routing oder Gatewayeinfügung konfigurieren; modelName ist keine Anbieterbereitstellungsauswahl.
Responses KB-Fehler Verwenden Sie ein Responses-KB-Profil und einen Endpunkt mit Unterstützung für Novembervorschau und erforderlichen Fortsetzungsstrukturen. Es gibt keine zugesagten Chatabschluss-Fallbacks.
Authentifizierung abgelehnt Verwenden Sie genau einen gültigen Modus. Überprüfen Sie systemeigene und benutzerdefinierte App-Zielgruppen, Tokenüberprüfungen, Headernamen und beide Authentifizierungsbeine.
Aktualisierung schlägt nach dem Lesen eines Objekts fehl. Geben Sie neue Anmeldeinformationen für den geänderten Bereich an. Kopieren Sie Anmeldeinformationen mit ausschließlichem Schreibzugriff nicht durch Weglassen.
Azure OpenAI-Einbettungsanforderung schlägt fehl Verwenden Sie ein unterstütztes Einbettungsmodell, übereinstimmende Dimensionen und die Ressourcen-URI- und Bereitstellungseinstellungen, die für die Fähigkeit oder den Vektorisierer dokumentiert sind.
Private Anfrage schlägt fehl Überprüfen Sie die Eignung der Workload-Ausführungsroute, Genehmigung, DNS, TLS, API-Verwaltungsebene/Topologie und Back-End-Konnektivität unabhängig voneinander.
Web-Wissensquelle mit einem kompatiblen KB-Modell Verwenden Sie die native Azure OpenAI-Chatkonfiguration.