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.
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.
Erstellen Sie eine indizierte OneLake-Wissensquelle mit der 2026-11-01-preview REST-API, um Microsoft OneLake-Dateien aufzunehmen und Quellberechtigungen in Foundry IQ (Azure KI-Suche) beizubehalten.
Wissensquellen werden unabhängig erstellt, in einer Wissensbasis referenziert und als Erdungsdaten verwendet, wenn die Wissensbasis zur Laufzeit abgefragt wird.
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.
Spezielle Vorschaubedingungen für Foundry IQ (Azure KI-Suche) finden Sie unter Vorschaufunktionen.
Ausdrücke, die beim Herstellen einer Verbindung mit externen Datenquellen gelten, finden Sie unter "Externe Datenquellen".
Wenn Sie eine indizierte OneLake-Wissensquelle erstellen, generiert Foundry IQ automatisch die folgenden Objekte:
- Eine Datenquelle, die ein Seehaus darstellt.
- Ein Skillset, das Segmente vektorisiert und optional multimodale Inhalte aus dem Lakehouse vektorisiert.
- Ein Index, der angereicherte Inhalte speichert und die Kriterien für den agentischen Abruf erfüllt.
- Ein Indexer, der die vorherigen Objekte verwendet, um die Indizierungs- und Anreicherungspipeline zu steuern.
Der generierte Indexer entspricht dem OneLake-Indexer. Die Voraussetzungen, unterstützten Aufgaben, Dokumentformate und Einschränkungen gelten auch für OneLake-Wissensquellen. Weitere Informationen finden Sie in der OneLake-Indexerdokumentation und in den Indexergrenzwerten. Die normale Unterstützung für die Erfassung von Verknüpfungen unterscheidet sich von dem berechtigungsabhängigen Abruf, der von Verknüpfungen abgeleitete Inhalte in dieser Vorschau ausschließt. Wenn das generierte Skillset einen externen Dienst aufruft, gelten auch die Eingabe- und Dienstgrenzwerte dieser Qualifikation.
Voraussetzungen
Ein Foundry IQ-Dienst in der öffentlichen Azure-Cloud in einer Region, die agentische Abrufe ermöglicht.
Abschluss der Voraussetzungen für den OneLake-Indexer und die Datenvorbereitung.
Abschluss der Voraussetzungen für die Beibehaltung von OneLake-Berechtigungen. Der Foundry IQ-Dienst muss über eine vom System zugewiesene verwaltete Identität verfügen. Weisen Sie dieser Identität die Rolle Admin im Fabric-Arbeitsbereich zu.
Berechtigung zum Erstellen von Wissensquellen. Konfigurieren Sie die schlüssellose Authentifizierung mit den Rollen "Mitwirkender des Suchdiensts " und " Indexdatenmitwirkender ", die Ihrem Benutzerkonto zugewiesen sind (empfohlen), oder verwenden Sie einen Administrator-API-Schlüssel.
Ein REST-Client. Verwenden Sie die REST-API-Version
2026-11-01-previewdes Suchdiensts für die Anfragen in diesem Artikel. Rufen Sie für die schlüssellose Authentifizierung ein Microsoft Entra ID-Token für denAuthorizationHeader ab.Wenn Sie
contentExtractionModealsstandardkonfigurieren, verwenden Sie eine Microsoft Foundry-Ressource in einer von Content Understanding in Foundry Tools unterstützten Region und ihrenhttps://<resource-name>.services.ai.azure.com-Endpunkt. Stellen Sie ein Einbettungsmodell bereit und stellen Sie ein multimodales Chatmodell bereit, wenn Sie die Bildverbalisierung aktivieren. Das Beispiel in diesem Artikel verwendetminimalund deaktiviert die Bildbeschreibung.Weisen Sie für Aufrufe mit verwalteter Identität an Azure OpenAI-Einbettungen oder die Bildverbalisierung der ausgewählten Identität auf der Azure OpenAI- oder der übergeordneten Foundry-Ressource, die mit
resourceUriübereinstimmt, Cognitive Services OpenAI User zu. Extraktionsdienstberechtigungen sind getrennt. Siehe "Rolle zuweisen".Verwenden Sie für die private Erfassung einen berechtigten S2-, S3-, L1- oder L2-Dedicated-Dienst, der die Workloadanforderungen für freigegebene private Links erfüllt. Erstellen und genehmigen Sie einen freigegebenen privaten Link zum Fabric-Arbeitsbereich unter Verwendung des
workspaceZiels und derMicrosoft.Fabric/privateLinkServicesForFabricGruppen-ID, wie in Unterstützte Ressourcentypen beschrieben. Konfigurieren Sie genehmigte Links für alle geschützten Extraktions-, Modell- oder anderen Azure-Abhängigkeiten, die Ihre Pipeline verwendet.
Einschränkungen
Serverless und S3 HD unterstützen weder die private Indexerausführung noch ausgehende freigegebene private Links für Search. Die Konfiguration des Netzwerksicherheitsperimeters steuert den unterstützten Zugriff auf öffentliche Endpunkte; die private Ausführung wird nicht aktiviert.
Wenn die Erfassung von OneLake-Berechtigungen aktiviert ist, lassen Sie den Ressourcenspeicher, den Anreicherungscache und die Graph-Extraktionseinstellungen aus. Unterstützte Fähigkeiten und andere Vorschaueinschränkungen finden Sie unter Einschränkungen bei der Beibehaltung von Berechtigungen in OneLake.
Überprüfen auf vorhandene Wissensquellen
Eine Wissensquelle ist ein wiederverwendbares Objekt auf oberster Ebene. Überprüfen Sie vorhandene Wissensquellen, bevor Sie einen Namen auswählen oder ein neues Objekt erstellen.
Senden Sie GET /knowledgesources?api-version=2026-11-01-preview&$select=name,kind an Ihren Suchendpunkt.
Um eine einzelne Definition zu überprüfen, senden Sie GET /knowledgesources/<knowledge-source-name>?api-version=2026-11-01-preview. Fügen Sie Ihren Authentifizierungsheader in jede Anforderung ein.
Erstellen einer Wissensquelle
Erstellen Sie die Wissensquelle mit der folgenden REST-Anforderung. In diesem Beispiel wird eine minimale Inhaltsextraktion verwendet, die Bildverbalisierung deaktiviert und die Erhaltung von OneLake-Berechtigungen aktiviert.
OneLake-Berechtigungen beibehalten (Vorschau)
Legen Sie sowohl oneLakeParentFolders als auch oneLakeLakehouseId in indexedOneLakeParameters.ingestionParameters.ingestionPermissionOptions fest. Im Gegensatz zu indexerPermissionOptions einer direkten OneLake-Datenquelle sind beide Werte für eine gesicherte indizierte OneLake-Wissensquelle zusammen erforderlich.
Ersetzen Sie den Namen des Foundry IQ-Diensts, Zugriffstokens, Arbeitsbereichs-ID und Lakehouse-ID durch Ihre Werte.
PUT https://<search-service>.search.windows.net/knowledgesources/my-secured-onelake-ks?api-version=2026-11-01-preview
Authorization: Bearer <access-token>
Content-Type: application/json
{
"name": "my-secured-onelake-ks",
"kind": "indexedOneLake",
"indexedOneLakeParameters": {
"fabricWorkspaceId": "<fabric-workspace-id>",
"lakehouseId": "<lakehouse-id>",
"ingestionParameters": {
"contentExtractionMode": "minimal",
"disableImageVerbalization": true,
"ingestionPermissionOptions": [
"oneLakeParentFolders",
"oneLakeLakehouseId"
]
}
}
}
Informationen zur Berechtigungskonfiguration und deren Einschränkungen finden Sie unter Konfigurieren einer indizierten OneLake-Wissensquelle.
Die Erstellungsantwort listet die generierten Objekte unter indexedOneLakeParameters.createdResources. Die Wissensquelle generiert den berechtigungsfähigen Index, Feldzuordnungen und Chunkprojektionen. Sie müssen diese Zuordnungen nicht separat konfigurieren. Informationen zu generierten Feldanforderungen und Abfragezeitautorisierungen finden Sie unter "Beibehalten von OneLake-Berechtigungen".
Optionale Einstellungen verwenden die folgenden Eigenschaftspfade:
-
indexedOneLakeParameters.targetPath: Beschränken Sie die Aufnahme auf einen Ordner im Lakehouse. Von Verknüpfungen abgeleitete Inhalte bleiben vom berechtigungsabhängigen Abruf ausgeschlossen. -
indexedOneLakeParameters.ingestionParameters.embeddingModel: Konfigurieren sie optionale Inhaltsvektorisierung. -
indexedOneLakeParameters.ingestionParameters.chatCompletionModel: Konfigurieren Sie ein Chat-Completion-Modell für die Bildverbalisierung oder Kontextextraktion. Im Beispiel bleibt die Bildverbalisierung deaktiviert. -
indexedOneLakeParameters.ingestionParameters.ingestionSchedule: Abruf von Quelländerungen mitintervalund optionalstartTimekonfigurieren. Die automatische Fortsetzung nach einem berechtigten Ausführungszeitstopp ist von diesem Abrufintervall getrennt. Weder die Planung noch die Fortsetzung legen die Aktualität der Berechtigung fest.
Behalten Sie beim Hinzufügen optionaler Einstellungen beide Berechtigungsoptionen bei. Der Netzwerkzugriffsmodus ist standardmäßig auf public festgelegt; für geeignete Dedicated-Konfigurationen siehe Einschränken der Aufnahme in ein privates Netzwerk.
Datenaufnahme auf ein privates Netzwerk beschränken
Private Ingestion für indizierte OneLake-Wissensquellen ist allgemein in der REST-API 2026-10-01 für berechtigte dedizierte Dienste verfügbar. Für die Erhaltung der OneLake-Berechtigung im Beispiel dieses Artikels ist 2026-11-01-preview separat erforderlich.
Setzen Sie indexedOneLakeParameters.ingestionParameters.networkAccessMode in der Erstellungsanforderung auf private.
Erfüllen Sie die Voraussetzungen für das private Netzwerk.
Setzen Sie
privatein der Anfrage zum Erstellen der Wissensquelle aufnetworkAccessMode. Sie können diese Eigenschaft nur während der Erstellung festlegen, einschließlich in der stabilen2026-10-01API. Um den gespeicherten Modus später zu ändern, löschen Sie die Wissensquelle, und erstellen Sie sie erneut. Berechtigte Blob-, ADLS-Gen2- und Azure SQL-Quellen können stattdessen die Netzwerküberschreibung für den vorläufig generierten Indexer verwenden. Diese Ausnahme gilt nicht für indizierte SharePoint-Quellen oder andere Quelltypen.Die Erstellung kann fehlschlagen, wenn die Dienstebene oder Laufzeit keine private Ausführung unterstützt oder wenn ein erforderlicher freigegebener privater Link nicht vorhanden ist. Serverless und S3 HD unterstützen keine private Ausführung. Die Konfiguration des Netzwerksicherheitsperimeters steuert den Zugriff auf unterstützte öffentliche Endpunkte, nicht die private Ausführung.
Vergewissern Sie sich, dass
parameters.configuration.executionEnvironmentdes generierten Indexersprivateist.Vergewissern Sie sich, dass jeder erforderliche freigegebene private Link genehmigt, bereitgestellt und auf die richtige Abhängigkeit ausgerichtet ist. Die erfolgreiche Erstellung allein bestätigt die Genehmigung oder Zielbestimmung von Links nicht. Wenn eine Portalüberprüfung keine abonnementübergreifende Ressource auflösen kann, überprüfen Sie die Genehmigung und Bereitschaft für die Zielressource und den Foundry IQ-Dienst manuell.
Fragen Sie den Status der Wissensquelle ab, bis
lastSynchronizationState.endTimeeinen Wert hat. Vergewissern Sie sich, dassitemsUpdatesFailed0ist, und überprüfen Sie dann den connectorspezifischen Quellinhalt. Die Synchronisierung schlägt fehl, wenn eine Abhängigkeit nicht erreichbar ist.
Konfigurieren der Standardextraktion
Wenn Sie Inhaltsverständnis für die Layoutextraktion und semantische Blöcke anstelle der minimal Extraktion in den vorherigen Beispielen verwenden möchten, setzen Sie contentExtractionMode auf standard und konfigurieren Sie aiServices mit Ihrem Foundry-Ressourcenendpunkt. Verwenden Sie die in Voraussetzungen beschriebenen Ressourcen und Bereitstellungen.
Die Standardextraktion verursacht Gebühren für das Inhaltsverständnis und, wenn die Bildverbalisierung aktiviert ist, Modellnutzungsgebühren. Weitere Informationen finden Sie unter Steuerelemente für Abrechnung und Bildbeschreibung.
Verwenden Sie automatische sprachspezifische Analysatoren (Vorschau)
Um automatische Sprachanalysatoren zu aktivieren, setzen Sie indexedOneLakeParameters.ingestionParameters.contentExtractionMode auf minimal. Legen Sie diesen indexedOneLakeParameters.ingestionParameters.aiServices.uri Wert auf Ihren Microsoft Foundry-Ressourcenendpunkt fest. Foundry IQ erkennt die Sprache jedes Quelldokuments und wendet einen passenden Microsoft-Sprachanalysator an. Sie geben keinen Analyzer in der Wissensquelldefinition oder in einer Abfrage an.
Lassen Sie indexedOneLakeParameters.ingestionParameters.aiServices.apiKey für die schlüssellose Authentifizierung weg. Weisen Sie die Rolle "Cognitive Services User" ihrer Microsoft Foundry-Ressource der verwalteten Identität Ihres Foundry IQ-Diensts zu.
Unterstützte Sprachen sind Englisch, Japanisch, Französisch, Spanisch, Deutsch, Niederländisch, Italienisch, Brasilianisches Portugiesisch, Europäisches Portugiesisch, Vereinfachtes Chinesisch, Traditionelles Chinesisch und Koreanisch.
Für mehrsprachige Inhalte wählt Foundry IQ einen Analyzer basierend auf der vorherrschenden erkannten Sprache aus. Er verwendet den Standardanalysator, wenn die Sprache nicht unterstützt oder unsicher ist.
Wenn Sie diese Option aktivieren, enthält der generierte Index sprachspezifische Inhaltsfelder für jede unterstützte Sprache, auch wenn Ihre Daten diese Sprachen nicht enthalten. Während der Aufnahme ordnet Foundry IQ Dokumente dem Feld ihrer erkannten Sprache zu. Nicht verwendete Felder enthalten keinen indizierten Inhalt und haben minimale Speicherauswirkungen, zählen jedoch weiterhin zur Indexfeldgrenze. Berücksichtigen Sie diese Felder bei der Planung der Feldanzahl und der Speicherkapazität.
Die Spracherkennung ist nach der kostenlosen KI-Anreicherungszuweisung kostenpflichtig.
Überprüfen des Ingestion-Status
Senden Sie GET /knowledgesources/my-secured-onelake-ks/status?api-version=2026-11-01-preview mit Ihrem Authentifizierungsheader an Ihren Suchendpunkt.
Überprüfen Sie den Synchronisierungsstatus, den aktuellen und vorherigen Synchronisierungszustand sowie Fehler auf Dokumentebene. Verwenden Sie den Indexerstatus und den Ausführungsverlauf, um Ingestionsfehler zu untersuchen. Die erfolgreiche Erfassung bedeutet nicht, dass Änderungen an den Quellberechtigungen weitergegeben wurden. Siehe Berechtigungs- und Pfadfrische.
Überprüfen der generierten Objekte
Die generierte Datenquelle, das Skillset, der Indexer und der Index verwenden Namen basierend auf dem Wissensquellnamen. Sie können diese Namen nicht ändern. Vermeiden Sie das direkte Bearbeiten der Objekte, da Änderungen die Indexer-Pipeline beeinträchtigen können.
Verwenden Sie die von indexedOneLakeParameters.createdResources generierten Objektnamen, um jede Definition abzurufen. Senden Sie GET /<resource-collection>/<generated-object-name>?api-version=2026-11-01-preview mit Ihrem Authentifizierungsheader an Ihren Suchendpunkt. Die Ressourcensammlungen sind indexers, datasources, skillsets, und indexes.
- Senden sie
GET /indexers/<generated-indexer-name>/status?api-version=2026-11-01-previewmit Ihrem Authentifizierungsheader. ÜberprüfenlastResultundexecutionHistoryauf Ausführungsstatus und Fehlermeldungen, einschließlich Verbindungs- oder Kontingentfehlern. Siehe „Überwachen mit Get Indexer Status“. - Überprüfen Sie die Datenquelle, um die Konfiguration der Lakehouse-Verbindung und der verwalteten Identität zu überprüfen.
- Überprüfen Sie das Skillset, um zu sehen, wie Inhalte segmentiert und optional vektorisiert werden.
- Überprüfen Sie die Inhalts- und Berechtigungsfelder des Indexes. Stellen Sie sicher, dass die generierten Feldzuordnungen und Chunk-Projektionen Quellspeicherortmetadaten beibehalten.
Zuweisen zu einer Wissensbasis
Wenn Sie mit der Wissensquelle zufrieden sind, fügen Sie sie einer Wissensbasis hinzu.
Legen Sie für jede Wissensdatenbank, die eine indizierte OneLake-Wissensquelle angibt, includeReferenceSourceData auf true. Diese Einstellung ist erforderlich, um die Quelldokument-URL in die Quellenangabe zu übernehmen.
Abfragen einer Wissensbasis
Rufen Sie nach der Konfiguration der Knowledge Base die Abrufen-Aktion oder den MCP-Endpunkt auf, um die Wissensquelle abzufragen.
Dokumentebenenberechtigungen erzwingen (Vorschau)
Verwenden Sie 2026-11-01-preview für berechtigungsabhängige OneLake-Anfragen. Schließen Sie das Zugriffstoken des anfordernden Benutzers in x-ms-query-source-authorizationein, wie unter Erzwingen von Berechtigungen zur Abfragezeit (Vorschau) beschrieben. Folgen Sie den OneLake-Abfrage- und Testanleitungen , um zulässige und verweigerte Benutzer zu überprüfen.
Surface in Dokumente eingebettete Bilder (Vorschau)
Die Bildbereitstellung wird nicht unterstützt, wenn ingestionPermissionOptions konfiguriert ist. Fügen Sie assetStore daher nicht der gesicherten Wissensquelle in diesem Artikel hinzu. Informationen zu Szenarien ohne Berechtigungsaufnahme finden Sie unter Surface in Dokumente eingebettete Bilder im agentischen Abruf (Vorschau).
Löschen einer Wissensquelle
Löschen Sie vor dem Löschen einer Wissensquelle alle Wissensdatenbanken, die darauf verweisen, oder aktualisieren Sie die Wissensbasisdefinition, um den Verweis zu entfernen. Wenn die Quelle noch verwendet wird, schlägt das Löschen fehl und gibt eine Liste der betroffenen Wissensdatenbanken zurück.
- Senden Sie
GET /knowledgebases?api-version=2026-11-01-preview, um Wissensdatenbanken aufzulisten. Verwenden SieGET /knowledgebases/<knowledge-base-name>?api-version=2026-11-01-preview, um jede Definition auf Verweise auf die Wissensquelle zu prüfen. -
Aktualisieren Sie die Wissensbasis , um den Verweis zu entfernen. Alternativ können Sie
DELETE /knowledgebases/<knowledge-base-name>?api-version=2026-11-01-previewsenden, wenn Sie diese Wissensbasis nicht mehr benötigen. - Senden
DELETE /knowledgesources/my-secured-onelake-ks?api-version=2026-11-01-preview, um die Wissensquelle zu löschen. Fügen Sie Ihren Authentifizierungsheader in jede Anforderung ein.
Durch das Löschen einer indizierten OneLake-Wissensquelle werden auch die generierten Datenquellen, das Skillset, der Indexer und der Index gelöscht. Das Quell-Lakehouse oder Dateien werden nicht in Microsoft Fabric gelöscht.