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.
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.
Eine indizierte Azure SQL-Wissensquelle übernimmt Zeilen aus Azure SQL-Datenbank oder Azure SQL Managed Instance in eine agentische Retrievalpipeline in Foundry IQ (Azure KI-Suche). Diese Funktion ist mit der REST-API 2026-10-01 allgemein verfügbar.
Wissensquellen werden unabhängig erstellt, in einer Wissensbasis referenziert und als Erdungsdaten verwendet, wenn die Wissensbasis zur Laufzeit abgefragt wird.
Im Gegensatz zu dateibasierten Wissensquellen wie Azure Blob Storage und OneLake wird jede SQL-Zeile als ein logisches Dokument behandelt. Sie steuern das Indexschema über explizite Spaltenzuordnungen, anstatt ein festes Dokumentschema zu verwenden.
Wenn Sie eine indizierte Wissensquelle in Azure SQL erstellen, legen Sie eine SQL-Datenquelle, optionale Spaltenzuordnungen und optionale Modelle fest, mit denen automatisch die folgenden Foundry IQ-Objekte generiert werden:
- Eine Datenquelle, die die SQL-Tabelle oder -Ansicht darstellt.
- Ein Index, dessen Felder von Ihren Spaltenzuordnungen abgeleitet werden.
- Ein Skillset, das Einbettungen generiert. Der Dienst erstellt nur dann ein Skillset, wenn Sie angeben
embeddingColumns. - Ein Indexer, der die vorherigen Objekte verwendet, um die Aufnahmepipeline zu steuern.
Der generierte Indexer entspricht dem Azure SQL indexer, dessen Voraussetzungen, Änderungserkennungsrichtlinien und Einschränkungen auch für indizierte Azure SQL Wissensquellen gelten. Weitere Informationen finden Sie in der Azure SQL Indexerdokumentation.
Nutzungssupport
| Azure Portal | Microsoft Foundry-Portal | .NET SDK | Python SDK | Java SDK | JavaScript SDK | REST-API |
|---|---|---|---|---|---|---|
| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
Voraussetzungen
Ein Foundry IQ-Dienst in jeder Region, die agentische Suche ermöglicht.
Abschluss der voraussetzungen für Azure SQL indexer, einschließlich:
Eine Azure SQL-Datenbank oder Azure SQL Managed Instance mit einer Tabelle oder Ansicht, die importiert werden soll.
Ein einwertige Primärschlüssel in der Quelltabelle oder -ansicht.
Für Ansichten eine Spalte, die zum Erkennen von Änderungen mit oberen Grenzwerten geeignet ist. Wir empfehlen nachdrücklich eine
rowversionSpalte.
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.
Wenn Sie
embeddingColumnsangeben und für Azure OpenAI-Einbettungen eine verwaltete Identität verwenden, weisen Sie der ausgewählten Identität auf der Azure OpenAI- oder der übergeordneten Foundry-Ressource, die mitresourceUriübereinstimmt, Cognitive Services OpenAI User zu. Siehe Rolle zuweisen.Wenn Sie
privateaufnetworkAccessModefestlegen, müssen Sie die folgenden Anforderungen erfüllen:Verwenden Sie einen S2-, S3-, L1- oder L2 Foundry IQ-Dienst. Überprüfen Sie die kanonische Supportmatrix für freigegebene private Links auf Konfigurations- und Leistungsstufenanforderungen.
Erstellen und genehmigen Sie einen Shared Private Link zum SQL-Server. Beachten Sie die unterstützten Ressourcentypen für die Ziel- und Gruppen-ID. Der SQL Managed Instance Freigegebener privater Link (Vorschau) ist als Vorschau verfügbar.
Verwenden Sie die SQL-Authentifizierung oder verwaltete Identität, sofern der Connector dies unterstützt. freigegebene private Links von SQL Managed Instance erfordern SQL-Authentifizierung; die verwaltete Identität wird für diese Verbindung nicht unterstützt. Gewähren Sie für verwaltete Identitäten mit SQL-Datenbank die erforderlichen Azure und Datenbankrollen. Verwenden Sie eine Verbindungszeichenfolge mit
Database=<database-name>und der Ressourcen-ID des SQL-Servers.ingestionParameters.identitynur für eine benutzerzugewiesene Identität festlegen. Wenn Sie es weglassen, verwendet der Indexer die vom System zugewiesene Identität des Foundry IQ-Diensts.Wenn Sie
embeddingColumnsangeben, erstellen und genehmigen Sie einen freigegebenen privaten Link für jeden geschützten Einbettungsmodellendpunkt unter Verwendung der unterstützten Ressourcentypen. Ohne Embedding-Spalten ist kein Embedding-Skillset und keine Modellverbindung erforderlich.
Das neueste
Azure.Search.DocumentsVorschaupaket:dotnet add package Azure.Search.Documents --prereleaseFür die schlüssellose Authentifizierung das Paket
Azure.Identity:dotnet add package Azure.Identity
Das neueste
azure-search-documentsVorschaupaket:pip install --pre azure-search-documentsFür die schlüssellose Authentifizierung das Paket
azure-identity:pip install azure-identity
Die Version 2026-10-01 der REST-API des Suchdiensts.
Fügen Sie für die schlüssellose Authentifizierung ein Microsoft Entra ID-Token in den
AuthorizationHeader jeder HTTP-Anforderung ein.
Einschränkungen und Überlegungen
- Eine Wissensquelle kann Daten aus genau einer Tabelle oder einer Ansicht aufnehmen.
- Die Quelltabelle oder -ansicht muss einen einwertigen Primärschlüssel haben. Zusammengesetzte Schlüssel werden nicht unterstützt.
- Der Primärschlüssel wird automatisch ermittelt und kann nicht überschrieben werden.
-
contentExtractionModeunterstützt nur"minimal". - Bildextraktion und Bildverbalisierung werden nicht unterstützt.
- Die Echtzeitsynchronisierung wird nicht unterstützt. Der generierte Indexer ist zeitplanbasiert.
- Sql-Abruf in Echtzeit wird nicht unterstützt. Die Wissensquelle ist indiziert, nicht remote.
Vorbereiten des generierten Indexers
Eine indizierte Azure SQL Wissensquelle erstellt automatisch einen Indexer zum Steuern der Aufnahme. Überprüfen Sie die folgenden Details, bevor Sie die Wissensquelle erstellen.
Änderungserkennung
Der generierte Indexer verwendet standardmäßige Azure SQL Indexeränderungserkennung:
Tabellen: Der Dienst wendet die integrierte SQL-Änderungsnachverfolgung automatisch an. Aktivieren Sie die SQL-Änderungsnachverfolgung in der Quelltabelle, bevor Sie die Wissensquelle erstellen.
Ansichten: Der Dienst wendet die Änderungserkennung per High-Water-Mark an. Geben Sie die Spalte an, die in
highWaterMarkColumnNameverwendet werden soll. EinerowversionSpalte wird dringend empfohlen. Um Löschungen in einer Ansicht zu erkennen, fügen Sie der Ansicht eine Soft-Delete-Markierungsspalte hinzu, wie unter Richtlinie zur Löscherkennung mit einer Soft-Delete-Spalte beschrieben.
Authentifizierung
Der generierte Indexer unterstützt zwei Authentifizierungsoptionen:
SQL-Authentifizierung: Geben Sie im Verbindungszeichenfolge einen Benutzernamen und ein Kennwort an.
Verwaltete Identitätsauthentifizierung: Verwenden Sie eine vom System zugewiesene oder vom Benutzer zugewiesene verwaltete Identität, die über Azure RBAC- und Rollen auf Datenbankebene für die SQL-Ressource verfügt.
Informationen zu Verbindungszeichenfolge Formaten, Rollenanforderungen und Setupschritten finden Sie in den Azure SQL Indexervoraussetzungen und Verbinden über eine verwaltete Identität.
Überprüfen auf vorhandene Wissensquellen
Eine Wissensquelle ist ein wiederverwendbares Objekt auf oberster Ebene. Das Wissen über vorhandene Wissensquellen ist hilfreich, um neue Objekte wiederzuverwenden oder zu benennen.
Führen Sie den folgenden Code aus, um Wissensquellen nach Namen und Typ auflisten.
// List knowledge sources by name and type
using Azure.Search.Documents.Indexes;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var knowledgeSources = indexClient.GetKnowledgeSourcesAsync();
Console.WriteLine("Knowledge Sources:");
await foreach (var ks in knowledgeSources)
{
Console.WriteLine($" Name: {ks.Name}, Type: {ks.GetType().Name}");
}
Reference:SearchIndexClient
# List knowledge sources by name and type
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
for ks in index_client.list_knowledge_sources():
print(f" - {ks.name} ({ks.kind})")
Reference:SearchIndexClient
### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version={{api-version}}&$select=name,kind
Authorization: Bearer {{token}}
Referenz:Wissensquellen - Liste
Sie können auch eine einzelne Wissensquelle anhand des Namens zurückgeben, um die JSON-Definition zu überprüfen.
using Azure.Search.Documents.Indexes;
using System.Text.Json;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
// Specify the knowledge source name to retrieve
string ksNameToGet = "earth-knowledge-source";
// Get its definition
var knowledgeSourceResponse = await indexClient.GetKnowledgeSourceAsync(ksNameToGet);
var ks = knowledgeSourceResponse.Value;
// Serialize to JSON for display
var jsonOptions = new JsonSerializerOptions
{
WriteIndented = true,
DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.Never
};
Console.WriteLine(JsonSerializer.Serialize(ks, ks.GetType(), jsonOptions));
Reference:SearchIndexClient
# Get a knowledge source definition
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
import json
index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
ks = index_client.get_knowledge_source("knowledge_source_name")
print(json.dumps(ks.as_dict(), indent = 2))
Reference:SearchIndexClient
### Get a knowledge source definition
GET {{search-url}}/knowledgesources('{{knowledge-source-name}}')?api-version={{api-version}}
Authorization: Bearer {{token}}
Referenz:Wissensquellen - Abrufen
Der folgende JSON-Code ist eine Beispielantwort für eine indizierte Azure SQL Wissensquelle.
{
"name": "indexedsqlks",
"kind": "indexedSql",
"description": "Sample indexed Azure SQL knowledge source.",
"encryptionKey": null,
"indexedSqlParameters": {
"connectionString": "<sql-connection-string>",
"tableOrView": "dbo.tbl_hotels",
"contentColumns": [
{ "name": "hotelName", "sourceField": "HotelName", "searchFieldType": "Edm.String" },
{ "name": "description", "sourceField": "Description", "searchFieldType": "Edm.String" }
],
"embeddingColumns": [
{ "name": "descriptionVector", "sourceField": "Description" }
],
"ingestionParameters": {
"contentExtractionMode": "minimal",
"embeddingModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "<aoai-endpoint>",
"deploymentId": "text-embedding-3-large",
"modelName": "text-embedding-3-large"
}
}
},
"createdResources": {
"datasource": "indexedsqlks-datasource",
"indexer": "indexedsqlks-indexer",
"skillset": "indexedsqlks-skillset",
"index": "indexedsqlks-index"
}
}
}
Erstellen einer Wissensquelle
Führen Sie den folgenden Code aus, um eine indizierte Azure SQL Wissensquelle zu erstellen.
using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
var embeddingParams = new AzureOpenAIVectorizerParameters
{
ResourceUri = new Uri(aoaiEndpoint),
DeploymentName = aoaiEmbeddingDeployment,
ModelName = aoaiEmbeddingModel
};
var ingestionParams = new KnowledgeSourceIngestionParameters
{
NetworkAccessMode = KnowledgeSourceNetworkAccessMode.Public,
ContentExtractionMode = "minimal",
EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
{
AzureOpenAIParameters = embeddingParams
}
};
var sqlParams = new IndexedSqlKnowledgeSourceParameters(
connectionString: sqlConnectionString,
tableOrView: "dbo.tbl_hotels")
{
ContentColumns =
{
new ContentColumnMapping("hotelName", "HotelName", "Edm.String"),
new ContentColumnMapping("description", "Description", "Edm.String")
},
EmbeddingColumns =
{
new EmbeddingColumnMapping("descriptionVector", "Description")
},
IngestionParameters = ingestionParams
};
var knowledgeSource = new IndexedSqlKnowledgeSource(
name: "indexedsqlks",
indexedSqlParameters: sqlParams)
{
Description = "Indexed Azure SQL knowledge source."
};
await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Knowledge source '{knowledgeSource.Name}' created or updated successfully.");
Reference:SearchIndexClient, IndexedSqlKnowledgeSource
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
AzureOpenAIVectorizerParameters,
ContentColumnMapping,
EmbeddingColumnMapping,
IndexedSqlKnowledgeSource,
IndexedSqlKnowledgeSourceParameters,
)
from azure.search.documents.knowledgebases.models import (
KnowledgeSourceAzureOpenAIVectorizer,
KnowledgeSourceIngestionParameters,
KnowledgeSourceNetworkAccessMode,
)
index_client = SearchIndexClient(endpoint="<search-endpoint>", credential=DefaultAzureCredential())
embedding_params = AzureOpenAIVectorizerParameters(
resource_url="<aoai-endpoint>",
deployment_name="<aoai-embedding-deployment>",
model_name="<aoai-embedding-model>",
)
ingestion_params = KnowledgeSourceIngestionParameters(
network_access_mode=KnowledgeSourceNetworkAccessMode.PUBLIC,
content_extraction_mode="minimal",
embedding_model=KnowledgeSourceAzureOpenAIVectorizer(
azure_open_ai_parameters=embedding_params
),
)
knowledge_source = IndexedSqlKnowledgeSource(
name="indexedsqlks",
description="Indexed Azure SQL knowledge source.",
indexed_sql_parameters=IndexedSqlKnowledgeSourceParameters(
connection_string="Server=tcp:{server}.database.windows.net,1433;Database={db};...;",
table_or_view="dbo.tbl_hotels",
content_columns=[
ContentColumnMapping(
name="hotelName",
source_field="HotelName",
search_field_type="Edm.String",
),
ContentColumnMapping(
name="description",
source_field="Description",
search_field_type="Edm.String",
),
],
embedding_columns=[
EmbeddingColumnMapping(
name="descriptionVector",
source_field="Description",
)
],
ingestion_parameters=ingestion_params,
),
)
index_client.create_or_update_knowledge_source(knowledge_source=knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")
Reference:SearchIndexClient
### Create an indexed Azure SQL knowledge source
PUT {{search-endpoint}}/knowledgesources/indexedsqlks?api-version=2026-10-01
Authorization: Bearer {{search-access-token}}
Content-Type: application/json
Prefer: return=representation
{
"name": "indexedsqlks",
"kind": "indexedSql",
"description": "Indexed Azure SQL knowledge source.",
"indexedSqlParameters": {
"connectionString": "Server=tcp:{server}.database.windows.net,1433;Database={db};...;",
"tableOrView": "dbo.tbl_hotels",
"contentColumns": [
{ "name": "hotelName", "sourceField": "HotelName", "searchFieldType": "Edm.String" },
{ "name": "description", "sourceField": "Description", "searchFieldType": "Edm.String" }
],
"embeddingColumns": [
{ "name": "descriptionVector", "sourceField": "Description" }
],
"ingestionParameters": {
"networkAccessMode": "public",
"contentExtractionMode": "minimal",
"embeddingModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "{{aoai-endpoint}}",
"deploymentId": "{{aoai-embedding-deployment}}",
"modelName": "{{aoai-embedding-model}}"
}
}
}
}
}
Verwenden Sie indexedSqlParameters, um die SQL-Tabelle oder -Ansicht zu identifizieren, die erfasst werden soll, und um die Spaltenzuordnungen zu definieren, die im generierten Index zu Feldern werden. Geben Sie für Ansichten die Spalte mit den hohen Grenzwerten an, die für die Änderungserkennung verwendet wird.
Spaltenzuordnung
Verwenden Sie contentColumns, um SQL-Textspalten in durchsuchbare Felder im generierten Foundry IQ-Index zuzuordnen. Jede Inhaltsspaltenzuordnung benennt das Zielindexfeld, die SQL-Quellspalte und den Foundry-IQ-Feldtyp. Verwenden Sie contentColumns für Edm.String.
Einbettungszuordnung
Verwenden Sie embeddingColumns, um SQL-Textspalten generierten Vektorfeldern zuzuordnen. Geben Sie in ingestionParameters ein Einbettungsmodell an, wenn Sie Einbettungsspalten verwenden.
Für indizierte Azure SQL-Wissensquellen muss "minimal"contentExtractionMode sein, da die SQL-Erfassung zeilenbasiert ist und keine Inhalte aus binären Dokumenten extrahiert. Bildextraktion und Bildverbalisierung werden nicht unterstützt, daher haben chatCompletionModel, assetStore, aiServices und bildbezogene Einstellungen keine Wirkung.
Regeln für Standardwerte und Validierung
Die folgenden Standardwerte gelten, wenn Sie eine indizierte Azure SQL Wissensquelle erstellen.
Wenn Sie
contentColumnsweglassen, ordnet der Dienst SQL-Spalten, die sicher als Text dargestellt werden können, im generierten Index automatischEdm.String-Feldern zu, wobei eine 1:1-Zuordnung verwendet wird, bei dernamegleichsourceFieldist.Wenn Sie weglassen
embeddingColumns, erstellt der Dienst keine Vektorfelder und konfiguriert keine Einbettungskompetenz.embeddingColumnsist unabhängig voncontentColumns. Um Vektoren zu formatieren, die dem abrufbaren Text entsprechen, fügen Sie dieselbe SQL-Spalte in beide Arrays ein.Der Primärschlüssel der Quelltabelle oder -ansicht wird automatisch ermittelt. Explizite Überschreibungen werden nicht unterstützt, und die Quelle muss über einen einwertigen Primärschlüssel verfügen.
Datenaufnahme auf ein privates Netzwerk beschränken
In der stabilen 2026-10-01 API steuert networkAccessMode die Netzwerkumgebung, in der der generierte Indexer für eine indizierte Azure SQL-Wissensquelle ausgeführt wird. Diese Einstellung betrifft nur die Datenaufnahme und ändert weder Abrufanfragen noch -antworten der Wissensdatenbank. Überprüfen Sie die Unterstützungsmatrix für freigegebene private Links auf berechtigte Konfigurationen und unabhängige Vorschauabhängigkeiten.
networkAccessMode ist standardmäßig auf public eingestellt, wodurch das vorhandene Verhalten des öffentlichen Netzwerks beibehalten wird. Wenn networkAccessModeprivate ist, wird der generierte Indexer in der privaten Ausführungsumgebung ausgeführt. Es verwendet genehmigte gemeinsam genutzte private Links, um auf die Quellverbindung für Azure SQL-Datenbank oder SQL Managed Instance sowie auf unterstützte Azure-Abhängigkeiten wie Azure OpenAI-Modelle und Microsoft-Foundry-Ressourcen zuzugreifen.
So konfigurieren und überprüfen Sie den privaten Netzwerkzugriff:
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.
Überprüfen des Ingestion-Status
Führen Sie den folgenden Code aus, um den Fortschritt und die Integrität der Erfassung zu überwachen, einschließlich der Wissensquelle und detaillierter Indizierungsfehler für Wissensquellen, die eine Indexerpipeline generieren und einen Suchindex auffüllen.
using Azure.Search.Documents.Indexes;
using System.Text.Json;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));
// Get knowledge source ingestion status
var statusResponse = await indexClient.GetKnowledgeSourceStatusAsync(knowledgeSourceName);
var status = statusResponse.Value;
// Serialize to JSON for display
var json = JsonSerializer.Serialize(status, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(json);
Reference:SearchIndexClient
# Check knowledge source ingestion status
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
import json
index_client = SearchIndexClient(endpoint="search_url", credential=AzureKeyCredential("api_key"))
status = index_client.get_knowledge_source_status("knowledge_source_name")
print(json.dumps(status.as_dict(), indent=2))
Reference:SearchIndexClient
### Check knowledge source ingestion status
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}/status?api-version={{api-version}}
Authorization: Bearer {{token}}
Content-Type: application/json
Referenz:Wissensquellen – Status abrufen
Eine Antwort für eine Anforderung, die Aufnahmeparameter enthält und aktiv Inhalte erfasst, kann wie im folgenden Beispiel aussehen.
{
"kind": "azureBlob",
"synchronizationStatus": "active",
"synchronizationInterval": "1d",
"currentSynchronizationState": {
"startTime": "2026-04-10T19:30:00Z",
"itemUpdatesProcessed": 1100,
"itemsUpdatesFailed": 100,
"itemsSkipped": 1100,
"errors": [
{
"key": "Item id 1",
"docURL": "https://contoso.blob.core.windows.net/contracts/2024/Q4/doc-00023.csv",
"statusCode": 400,
"componentName": "DocumentExtraction.AzureBlob.MyDataSource",
"errorMessage": "Could not read the value of column 'foo' at index '0'.",
"details": "The file could not be parsed.",
"documentationLink": "https://go.microsoft.com/fwlink/?linkid=2049388"
}
]
},
"lastSynchronizationState": {
"status": "partialSuccess",
"startTime": "2026-04-09T19:30:00Z",
"endTime": "2026-04-09T19:40:01Z",
"itemUpdatesProcessed": 1100,
"itemsUpdatesFailed": 100,
"itemsSkipped": 1100,
"errors": null
},
"statistics": {
"totalSynchronizations": 25,
"averageSynchronizationDuration": "00:15:20",
"averageItemsProcessedPerSynchronization": 500
}
}
Note
Die Eigenschaft kind und das Array currentSynchronizationState.errors[] mit Fehlerdetails auf Dokumentebene sind ab der API-Version 2026-04-01 verfügbar. Für frühere API-Versionen werden diese Felder nicht zurückgegeben. Das lastSynchronizationState.status Feld ist auch neu in 2026-04-01.
Überprüfen der generierten Objekte
Wenn Sie diese Wissensquelle erstellen, generiert Foundry IQ (Azure KI-Suche) automatisch eine Datenquelle, einen Indexer und einen Index sowie ein Skillset, wenn die Aufnahmepipeline eine benötigt. Die Erstellungsantwort listet jedes Objekt unter createdResources.
Diese Objekte werden gemäß einer festen Vorlage generiert, und ihre Namen basieren auf dem Namen der Wissensquelle. Sie können die Objektnamen nicht ändern. Vermeiden Sie das direkte Bearbeiten dieser Objekte, da Änderungen Fehler oder Inkompatibilitäten verursachen können, die die Indexerpipeline unterbrechen.
Nur für berechtigte Blob-, ADLS Gen2- und Azure SQL-Quellen ermöglicht die Außerkraftsetzung des Zwischennetzwerks das Ändern der Ausführungsumgebung des generierten Indexers. Diese Ausnahme gilt nicht für indizierte SharePoint-Inhalte oder OneLake und lässt keine anderen generierten Objektänderungen zu. Spätere Aktualisierungen der Wissensquelle oder Regeneration können die Außerkraftsetzung überschreiben.
Sie können das Azure Portal verwenden, um die Objekterstellung zu überprüfen. Der Workflow lautet:
Überprüfen Sie den Indexer auf Erfolgs- oder Fehlermeldungen. Hier werden Verbindungs- oder Kontingentfehler angezeigt.
Überprüfen Sie die Datenquelle, um die Verbindung mit Ihrem Datenspeicher zu überprüfen. Die Verbindung verwendet entweder eine Verbindungszeichenfolge oder eine verwaltete Identität, je nachdem, wie Sie die Wissensquelle konfiguriert haben.
Wenn ein Skillset generiert wird, überprüfen Sie die Anreicherungs- und Vektorisierungseinstellungen. SQL-Wissensquellen generieren nur dann ein Skillset, wenn Sie angeben
embeddingColumns.Überprüfen Sie den Index, um zu sehen, wie Ihre Inhalte für den Abruf indiziert und verfügbar gemacht werden, einschließlich der durchsuchbaren und filterbaren Felder und welche Felder Vektoren für die Ähnlichkeitssuche speichern. Verwenden Sie den Such-Explorer, um Abfragen für den generierten Index auszuführen.
Zuweisen zu einer Wissensbasis
Wenn Sie mit der Wissensquelle zufrieden sind, fügen Sie sie einer Wissensbasis hinzu.
Abfragen einer Wissensbasis
Rufen Sie nach der Konfiguration der Knowledge Base die Abrufaktion oder den MCP-Endpunkt auf, um die Wissensquelle abzufragen.
Löschen einer Wissensquelle
Bevor Sie eine Wissensquelle löschen können, müssen Sie alle Knowledge Basen löschen, die darauf verweisen, oder die Knowledge Base-Definition aktualisieren, um den Verweis zu entfernen. Für Wissensquellen, die eine Index- und Indexerpipeline generieren, werden auch alle generierten Objekte gelöscht. Wenn Sie jedoch einen vorhandenen Index zum Erstellen einer Wissensquelle verwendet haben, wird Ihr Index nicht gelöscht.
Wenn Sie versuchen, eine verwendete Wissensquelle zu löschen, schlägt die Aktion fehl und gibt eine Liste der betroffenen Wissensdatenbanken zurück.
So löschen Sie eine Wissensquelle:
Erhalten Sie eine Liste aller Wissensdatenbanken in Ihrem Foundry IQ-Dienst.
using Azure.Search.Documents.Indexes; var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential); var knowledgeBases = indexClient.GetKnowledgeBasesAsync(); Console.WriteLine("Knowledge Bases:"); await foreach (var kb in knowledgeBases) { Console.WriteLine($" - {kb.Name}"); }Reference:SearchIndexClient
Eine Beispielantwort könnte wie folgt aussehen:
{ "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)", "value": [ { "name": "my-kb" }, { "name": "my-kb-2" } ] }Rufen Sie eine individuelle Wissensbasisdefinition ab, um nach Wissensquellenverweise zu suchen.
using Azure.Search.Documents.Indexes; using System.Text.Json; var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential); // Specify the knowledge base name to retrieve string kbNameToGet = "earth-knowledge-base"; // Get a specific knowledge base definition var knowledgeBaseResponse = await indexClient.GetKnowledgeBaseAsync(kbNameToGet); var kb = knowledgeBaseResponse.Value; // Serialize to JSON for display string json = JsonSerializer.Serialize(kb, new JsonSerializerOptions { WriteIndented = true }); Console.WriteLine(json);Reference:SearchIndexClient
Eine Beispielantwort könnte wie folgt aussehen:
{ "Name": "earth-knowledge-base", "KnowledgeSources": [ { "Name": "earth-knowledge-source" } ], "Models": [ {} ], "RetrievalReasoningEffort": {}, "OutputMode": {}, "ETag": "\u00220x8DE278629D782B3\u0022", "EncryptionKey": null, "Description": null, "RetrievalInstructions": null, "AnswerInstructions": null }Löschen Sie entweder die Wissensdatenbank, oder aktualisieren Sie, wenn Sie über mehrere Wissensquellen verfügen, die Wissensbasis, um die Quelle zu entfernen. In diesem Beispiel wird das Löschen gezeigt.
using Azure.Search.Documents.Indexes; var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential); await indexClient.DeleteKnowledgeBaseAsync(knowledgeBaseName); System.Console.WriteLine($"Knowledge base '{knowledgeBaseName}' deleted successfully.");Reference:SearchIndexClient
Löschen Sie die Wissensquelle.
await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName); System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");Reference:SearchIndexClient
Erhalten Sie eine Liste aller Wissensbasen auf Ihrem Foundry IQ Service.
# Get knowledge bases from azure.core.credentials import AzureKeyCredential from azure.search.documents.indexes import SearchIndexClient index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key")) print("Knowledge Bases:") for kb in index_client.list_knowledge_bases(): print(f" - {kb.name}")Reference:SearchIndexClient
Eine Beispielantwort könnte wie folgt aussehen:
{ "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)", "value": [ { "name": "my-kb" }, { "name": "my-kb-2" } ] }Rufen Sie eine individuelle Wissensbasisdefinition ab, um nach Wissensquellenverweise zu suchen.
# Get a knowledge base definition from azure.core.credentials import AzureKeyCredential from azure.search.documents.indexes import SearchIndexClient index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key")) kb = index_client.get_knowledge_base("knowledge_base_name") print(kb)Reference:SearchIndexClient
Eine Beispielantwort könnte wie folgt aussehen:
{ "name": "my-kb", "description": null, "retrievalInstructions": null, "answerInstructions": null, "outputMode": null, "knowledgeSources": [ { "name": "my-blob-ks" } ], "models": [], "encryptionKey": null, "retrievalReasoningEffort": { "kind": "low" } }Löschen Sie entweder die Wissensdatenbank, oder aktualisieren Sie, wenn Sie über mehrere Wissensquellen verfügen, die Wissensbasis, um die Quelle zu entfernen. In diesem Beispiel wird das Löschen gezeigt.
# Delete a knowledge base from azure.core.credentials import AzureKeyCredential from azure.search.documents.indexes import SearchIndexClient index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key")) index_client.delete_knowledge_base("knowledge_base_name") print(f"Knowledge base deleted successfully.")Reference:SearchIndexClient
Löschen Sie die Wissensquelle.
# Delete a knowledge source from azure.core.credentials import AzureKeyCredential from azure.search.documents.indexes import SearchIndexClient index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key")) index_client.delete_knowledge_source("knowledge_source_name") print(f"Knowledge source deleted successfully.")Reference:SearchIndexClient
Erhalten Sie eine Liste aller Wissensbasen auf Ihrem Foundry IQ Service.
### Get knowledge bases GET {{search-url}}/knowledgebases?api-version={{api-version}}&$select=name Authorization: Bearer {{token}}Referenz:Wissensdatenbanken - Liste
Eine Beispielantwort könnte wie folgt aussehen:
{ "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)", "value": [ { "name": "my-kb" }, { "name": "my-kb-2" } ] }Rufen Sie eine individuelle Wissensbasisdefinition ab, um nach Wissensquellenverweise zu suchen.
### Get a knowledge base definition GET {{search-url}}/knowledgebases('{{knowledge-base-name}}')?api-version={{api-version}} Authorization: Bearer {{token}}Referenz:Wissensdatenbanken – Abrufen
Eine Beispielantwort könnte wie folgt aussehen:
{ "name": "my-kb", "description": null, "retrievalInstructions": null, "answerInstructions": null, "outputMode": null, "knowledgeSources": [ { "name": "my-blob-ks" } ], "models": [], "encryptionKey": null, "retrievalReasoningEffort": { "kind": "low" } }Löschen Sie entweder die Wissensdatenbank, oder aktualisieren Sie, wenn Sie über mehrere Wissensquellen verfügen, die Wissensbasis, um die Quelle zu entfernen. In diesem Beispiel wird das Löschen gezeigt.
### Delete a knowledge base DELETE {{search-url}}/knowledgebases('{{knowledge-base-name}}')?api-version={{api-version}} Authorization: Bearer {{token}}Referenz:Knowledge Bases - Löschen
Löschen Sie die Wissensquelle.
### Delete a knowledge source DELETE {{search-url}}/knowledgesources('{{knowledge-source-name}}')?api-version={{api-version}} Authorization: Bearer {{token}}Referenz:Wissensquellen - Löschen