Erstellen einer Blob-Wissensquelle aus Azure Blob Storage oder ADLS Gen2

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.

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 Blob-Wissensquelle führt Inhalte aus Azure Blob Storage oder ADLS Gen2 in eine agentenbasierte Retrievalpipeline in Foundry IQ (Azure KI-Suche) ein. Wissensquellen werden unabhängig erstellt, in einer Wissensbasis referenziert und als Groundingdaten verwendet, wenn die Wissensbasis zur Laufzeit abgefragt wird.

Wenn Sie eine Blob-Wissensquelle erstellen, legen Sie eine externe Datenquelle, Modelle und Eigenschaften fest, mit denen die folgenden Foundry IQ-Objekte automatisch generiert werden:

  • Eine Datenquelle, die einen Blob-Container repräsentiert.
  • Ein Skillset, das multimodale Inhalte aus dem Container in Blöcke unterteilt und optional 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 BLOB-Indexer, dessen Voraussetzungen, unterstützte Dokumentformate und Einschränkungen auch für Blob-Wissensquellen gelten. Weitere Informationen finden Sie in der Blobindexerdokumentation und in den Indexergrenzwerten. Wenn das generierte Skillset einen externen Dienst aufruft, gelten auch die Eingabe- und Dienstgrenzwerte dieser Qualifikation.

Verwendungsunterstützung

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 Abrufung ermöglicht.

  • Ein Azure Blob Storage- oder Azure Data Lake Storage (ADLS) Gen2Konto.

  • Ein Blobcontainer mit unterstützten Inhaltstypen für Textinhalte. Bei optionaler Bildverbalisierung hängt der unterstützte Inhaltstyp davon ab, ob Ihr Chat-Vervollständigungsmodell die Bilddatei analysieren und beschreiben kann.

  • Wenn contentExtractionModestandard ist, verwenden Sie eine Microsoft Foundry-Ressource in einer von Content Understanding in Foundry Tools unterstützten Region mit einem https://<resource-name>.services.ai.azure.com-Endpunkt. Die Ressource muss über eine Bereitstellung für ein Einbettungsmodell und, wenn Sie die Bildverbalisierung aktivieren, über eine Bereitstellung für ein multimodales Chatmodell verfügen.

  • 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.

  • Eine verwaltete Identität für den Foundry IQ-Dienst mit Storage Blob Data Reader im Bereich des Quellspeicherkontos und des Cognitive Services-Benutzers auf der Microsoft Foundry-Ressource. Wenn Sie einen Ressourcenspeicher in einem anderen Speicherkonto konfigurieren, weisen Sie auch Storage Blob Data Contributor im Bereich dieses Speicherkontos zu. Wenn der Quellcontainer und der Assetcontainer dasselbe Konto verwenden, gewährt Storage Blob Data Contributor sowohl Lesezugriff auf die Quelle als auch Lese-/Schreibzugriff auf den Assetspeicher.

    • Weisen Sie für Aufrufe mit verwalteter Identität an Azure OpenAI-Einbettungs- oder Chatbereitstellungen der ausgewählten Identität auf der Azure OpenAI- oder übergeordneten Foundry-Ressource, die mit resourceUri übereinstimmt, Cognitive Services OpenAI User zu. Extraktionsdienstberechtigungen sind getrennt. Siehe Rolle zuweisen.
  • Wenn Sie private auf networkAccessMode festlegen, müssen Sie die folgenden Anforderungen erfüllen:

    • Verwenden Sie einen S2-, S3-, L1- oder L2 Foundry IQ-Dienst. Überprüfen Sie die kanonische Unterstützungsmatrix für freigegebene private Links auf Konfigurations- und Tarifqualifikationen.

    • Aktivieren Sie eine vom System zugewiesene oder vom Benutzer zugewiesene verwaltete Identität im Foundry IQ-Dienst, gewähren Sie ihm die Rolle "Storage Blob Data Reader" für das Speicherkonto, und verwenden Sie eine ResourceId=/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account> Verbindungszeichenfolge. Setzen Sie für eine benutzerzugewiesene Identität auch ingestionParameters.identity.

    • Erstellen und genehmigen Sie die unter unterstützten Ressourcentypen aufgeführten Speicherlinks. Für ADLS Gen2 sind beide blob und dfs Links erforderlich.

    • Erstellen und genehmigen Sie einen Link für jede geschützte Modell-, Extraktions-, Anreicherungs- oder Ressourcenspeicherabhängigkeit, die von Ihrer Konfiguration verwendet wird. Beachten Sie die unterstützten Ressourcentypen für jede Ziel- und Gruppen-ID.

  • Erforderliches Azure.Search.Documents-Paket:

    • Für 2026-08-01-preview Funktionen das neueste Vorschaupaket: dotnet add package Azure.Search.Documents --prerelease

    • Für 2026-10-01, das neueste stabile Paket: dotnet add package Azure.Search.Documents

  • Für die schlüssellose Authentifizierung das Paket Azure.Identity: dotnet add package Azure.Identity

  • Erforderliches azure-search-documents-Paket:

    • Für 2026-08-01-preview Funktionen das neueste Vorschaupaket: pip install --pre azure-search-documents

    • Für 2026-10-01, das neueste stabile Paket: pip install azure-search-documents

  • Für die schlüssellose Authentifizierung das Paket azure-identity: pip install azure-identity

  • Erforderliche REST-API-Version für den Suchdienst:

  • Fügen Sie für die schlüssellose Authentifizierung ein Microsoft Entra ID-Token in den Authorization Header jeder HTTP-Anforderung ein.

Verwenden Sie für die Berechtigungsaufnahme REST 2026-10-01 , wie unter "Erzwingen von Berechtigungen auf Dokumentebene" gezeigt. Die stabilen 2026-04-01 SDK-Beispiele konfigurieren keine Aufnahme von Berechtigungen. Überprüfen Sie das Änderungsprotokoll des Pakets auf Unterstützung für die erforderliche API-Version und -Eigenschaften.

Die REST-Beispiele verwenden die neueste Vorschau-API, 2026-11-01-preview. Vorschau-SDK-Beispiele entsprechen weiterhin ihrem dokumentierten 2026-08-01-preview-Vertrag. Überprüfen Sie das Paket-Änderungsprotokoll, bevor Sie eine neuere API-Version als Ziel festlegen.

Ü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

Die folgende Antwort schwärzt vertrauliche Werte und listet generierte Objekte unter createdResources auf. Bevor Sie es erneut verwenden, um eine andere Wissensquelle zu erstellen, geben Sie Zielanmeldeinformationen an oder konfigurieren Sie eine unterstützte verwaltete Identität; geschwärzte Werte sind keine Anmeldeinformationen.

{
  "name": "my-blob-ks",
  "kind": "azureBlob",
  "description": "A sample blob knowledge source.",
  "encryptionKey": null,
  "azureBlobParameters": {
    "connectionString": "<REDACTED>",
    "containerName": "blobcontainer",
    "folderPath": null,
    "isADLSGen2": false,
    "ingestionParameters": {
      "disableImageVerbalization": false,
      "ingestionPermissionOptions": [],
      "contentExtractionMode": "standard",
      "identity": null,
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "text-embedding-3-large",
          "modelName": "text-embedding-3-large",
          "authIdentity": null
        }
      },
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<aoai-endpoint>",
          "deploymentId": "gpt-5-mini",
          "modelName": "gpt-5-mini",
          "authIdentity": null
        }
      },
      "ingestionSchedule": null,
      "assetStore": null,
      "aiServices": {
        "uri": "<aoai-endpoint>"
      }
    },
    "createdResources": {
      "datasource": "my-blob-ks-datasource",
      "indexer": "my-blob-ks-indexer",
      "skillset": "my-blob-ks-skillset",
      "index": "my-blob-ks-index"
    }
  }
}

Erstellen einer Wissensquelle

Führen Sie den folgenden Code aus, um eine Blob-Wissensquelle zu erstellen.

// Create a blob knowledge source
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;
using Azure.Search.Documents.Models;
using Azure.Identity;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());

var chatCompletionParams = new AzureOpenAIVectorizerParameters
{
    ResourceUri = new Uri(aoaiEndpoint),
    DeploymentName = aoaiGptDeployment,
    ModelName = aoaiGptModel
};

var embeddingParams = new AzureOpenAIVectorizerParameters
{
    ResourceUri = new Uri(aoaiEndpoint),
    DeploymentName = aoaiEmbeddingDeployment,
    ModelName = aoaiEmbeddingModel
};

var ingestionParams = new KnowledgeSourceIngestionParameters
{
    NetworkAccessMode = KnowledgeSourceNetworkAccessMode.Public,
    DisableImageVerbalization = false,
    ChatCompletionModel = new KnowledgeBaseAzureOpenAIModel(azureOpenAIParameters: chatCompletionParams),
    EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
    {
        AzureOpenAIParameters = embeddingParams
    },
    IngestionPermissionOptions = new List<KnowledgeSourceIngestionPermissionOption>
    {
        KnowledgeSourceIngestionPermissionOption.RbacScope
    }
};

var blobParams = new AzureBlobKnowledgeSourceParameters(
    connectionString: connectionString,
    containerName: containerName
)
{
    IsAdlsGen2 = false,
    IngestionParameters = ingestionParams
};

var knowledgeSource = new AzureBlobKnowledgeSource(
    name: "my-blob-ks",
    azureBlobParameters: blobParams
)
{
    Description = "This knowledge source pulls from a blob storage container."
};

await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Knowledge source '{knowledgeSource.Name}' created or updated successfully.");

Reference:SearchIndexClient, AzureBlobKnowledgeSource

# Create a blob knowledge source
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import AzureBlobKnowledgeSource, AzureBlobKnowledgeSourceParameters, KnowledgeBaseAzureOpenAIModel, AzureOpenAIVectorizerParameters, KnowledgeSourceAzureOpenAIVectorizer, KnowledgeSourceContentExtractionMode, KnowledgeSourceIngestionParameters
from azure.search.documents.knowledgebases.models import KnowledgeSourceNetworkAccessMode

index_client = SearchIndexClient(endpoint = "<search-endpoint>", credential = DefaultAzureCredential())

knowledge_source = AzureBlobKnowledgeSource(
    name = "my-blob-ks",
    description = "This knowledge source pulls from a blob storage container.",
    encryption_key = None,
    azure_blob_parameters = AzureBlobKnowledgeSourceParameters(
        connection_string = "blob_connection_string",
        container_name = "blob_container_name",
        folder_path = None,
        is_adls_gen2 = False,
        ingestion_parameters = KnowledgeSourceIngestionParameters(
            network_access_mode = KnowledgeSourceNetworkAccessMode.PUBLIC,
            identity = None,
            disable_image_verbalization = False,
            chat_completion_model = KnowledgeBaseAzureOpenAIModel(
                azure_open_ai_parameters = AzureOpenAIVectorizerParameters(
                    resource_url = "<aoai-endpoint>",
                    deployment_name = "<aoai-gpt-deployment>",
                    model_name = "<aoai-gpt-model>",
                )
            ),
            embedding_model = KnowledgeSourceAzureOpenAIVectorizer(
                azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
                    resource_url = "<aoai-endpoint>",
                    deployment_name = "<aoai-embedding-deployment>",
                    model_name = "<aoai-embedding-model>",
                )
            ),
            content_extraction_mode = KnowledgeSourceContentExtractionMode.MINIMAL,
            ingestion_schedule = None,
            ingestion_permission_options = ["rbacScope"]
        )
    )
)

index_client.create_or_update_knowledge_source(knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")

Reference:SearchIndexClient

### Create a blob knowledge source
PUT {{search-endpoint}}/knowledgesources/my-blob-ks?api-version=2026-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
  "name": "my-blob-ks",
  "kind": "azureBlob",
  "description": "This knowledge source pulls from a blob storage container.",
  "encryptionKey": null,
  "azureBlobParameters": {
    "connectionString": "ResourceId=<storage-resource-id>",
    "containerName": "<blob-container-name>",
    "folderPath": null,
    "isADLSGen2": false,
    "ingestionParameters": {
        "networkAccessMode": "public",
        "identity": null,
        "disableImageVerbalization": null,
        "chatCompletionModel": {
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
                "resourceUri": "{{aoai-endpoint}}",
                "deploymentId": "{{aoai-gpt-deployment}}",
                "modelName": "{{aoai-gpt-model}}"
            }
        },
        "embeddingModel": {
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
                "resourceUri": "{{aoai-endpoint}}",
                "deploymentId": "{{aoai-embedding-deployment}}",
                "modelName": "{{aoai-embedding-model}}"
            }
        },
        "contentExtractionMode": "minimal",
        "ingestionSchedule": null,
        "ingestionPermissionOptions": ["rbacScope"]
    }
  }
}

Referenz:Wissensquellen – Erstellen oder Aktualisieren

Konfigurieren des Erfassungszeitplans

Legen Sie fest ingestionParameters.ingestionSchedule , wie oft der generierte Indexer die Quelländerungen abruft. Berechtigte nicht abgeschlossene Aufnahme kann nach einem Ausführungszeitstopp automatisch fortgesetzt werden , ohne auf die nächste Abfrage zu warten.

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 Abrechnungs- und Bildbeschreibungssteuerelemente.

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 Blob-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. Unabhängige Vorschaufunktionen wie automatische Analyzer pro Sprache und die Bereitstellung von Bildern behalten ihre eigenen API-Anforderungen bei.

networkAccessMode ist standardmäßig auf public festgelegt, wodurch das bestehende 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 für den Zugriff auf die Azure Blob Storage- oder ADLS Gen2-Quellverbindung sowie auf unterstützte Azure-Abhängigkeiten, etwa Azure OpenAI-Modelle und Microsoft Foundry-Ressourcen.

So konfigurieren und überprüfen Sie den privaten Netzwerkzugriff:

  1. Erfüllen Sie die Voraussetzungen für das private Netzwerk.

  2. Setzen Sie private in der Anfrage zum Erstellen der Wissensquelle auf networkAccessMode. Sie können diese Eigenschaft nur während der Erstellung festlegen, einschließlich in der stabilen 2026-10-01 API. 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.

  3. Vergewissern Sie sich, dass parameters.configuration.executionEnvironment des generierten Indexers private ist.

  4. 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.

  5. Fragen Sie den Status der Wissensquelle ab, bis lastSynchronizationState.endTime einen Wert hat. Vergewissern Sie sich, dass itemsUpdatesFailed0 ist, und überprüfen Sie dann den connectorspezifischen Quellinhalt. Die Synchronisierung schlägt fehl, wenn eine Abhängigkeit nicht erreichbar ist.

Verwenden Sie automatische sprachspezifische Analysatoren (Vorschau)

Ab der 2026-08-01-preview-API-Version stehen automatische Sprachanalysetools für Blob, indizierte OneLake- und indizierte SharePoint-Wissensquellen zur Verfügung. Wenn aktiviert, erkennt Foundry IQ (Azure KI-Suche) die Sprache jedes Quelldokuments und wendet automatisch einen passenden Microsoft Sprachanalysator an. Sie geben keinen Analyzer in der Wissensquelldefinition oder in einer Abfrage an.

Um automatische sprachspezifische Analyzer zu aktivieren, setzen Sie contentExtractionMode auf minimal und konfigurieren Sie ingestionParameters.aiServices in der Wissensquelldefinition.

Für die schlüssellose Authentifizierung müssen aiServices.apiKey Sie die Rolle "Cognitive Services User" auf Ihrer Microsoft Foundry-Ressource der verwalteten Identität Ihres Foundry IQ-Diensts zuweisen. Für die schlüsselbasierte Authentifizierung setzen Sie aiServices.apiKey auf einen gültigen Schlüssel für Ihre Foundry-Ressource.

Die folgenden Sprachen werden unterstützt:

  • Englisch
  • Japanese
  • Französisch
  • Spanisch
  • Deutsch
  • Dutch
  • Italienisch
  • Portugiesisch (Brasilien)
  • Europäisches Portugiesisch
  • Vereinfachtes Chinesisch
  • Traditionelles Chinesisch
  • Korean

Für mehrsprachige Inhalte wählt Foundry IQ anhand der überwiegend erkannten Sprache einen Analysator aus. Er verwendet den Standardanalysator, wenn die Sprache nicht unterstützt oder unsicher ist.

Wenn Sie automatische sprachspezifische Analysatoren aktivieren, fügt Foundry IQ dem generierten Indexschema sprachspezifische Inhaltsfelder für jede unterstützte Sprache hinzu, unabhängig davon, ob Ihre Daten Dokumente in diesen Sprachen enthalten. Während der Aufnahme werden Dokumente basierend auf ihrer erkannten Sprache an das entsprechende sprachspezifische Feld weitergeleitet.

Nicht verwendete Sprachfelder enthalten keinen indizierten Inhalt und haben minimale Speicherauswirkungen, bleiben aber Teil des Indexschemas und zählen zur Indexfeldgrenze. Berücksichtigen Sie die zusätzlichen Felder, wenn Sie den Indexentwurf, die Feldanzahl und die Speicheranforderungen planen. Weitere Informationen finden Sie unter Indexlimits und Kapazität des Foundry IQ-Diensts schätzen und verwalten.

Sprachenerkennung ist nach dem kostenlosen Kontingent für KI-Anreicherungen kostenpflichtig. Weitere Informationen finden Sie unter "Freie Anreicherungen".

Überprüfen Sie nach der Datenaufnahme das Sprachrouting, ohne die generierten Objekte zu bearbeiten:

  1. Überprüfen Sie das generierte Indexschema. Vergewissern Sie sich, dass sprachspezifische Felder über die entsprechenden Analyzer verfügen, z. B. snippet_en mit en.microsoft, und dass snippet_default den Standard-Analyzer-Fallback bereitstellt.
  2. Vergewissern Sie sich, dass die generierte semantische Konfiguration die sprachspezifischen Inhaltsfelder und snippet_default auflistet.
  3. Überprüfen Sie indizierte Blöcke für ein Dokument, das in einer unterstützten Sprache erkannt wurde. Der Text jedes Abschnitts gehört in das entsprechende Sprachfeld. Bei nicht unterstützter oder unsicherer Erkennung wird Text an snippet_default weitergeleitet.
  4. Lesen Sie Inhalte aus dem Feld für die ausgefüllte Sprache oder dem Fallback-Feld. In diesem Modus enthält das generierte Schema kein separates snippet Feld.

Wenn das Schema oder die Ergebnisse nicht übereinstimmen, überprüfen Sie die oben aufgeführten Aktivierungseinstellungen, und überprüfen Sie die Indizierungsfehler. Diese Prüfungen definieren keine Aktualisierungs- oder Migrationsverfahren für einen vorhandenen generierten Index.

Ü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 auf eine Anforderung, die Aufnahmeparameter enthält und aktiv Inhalte erfasst, kann folgendermaßen 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
  }
}

Hinweis

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 Regenerierung können die Überschreibung überschreiben.

Sie können das Azure Portal verwenden, um die Objekterstellung zu überprüfen. Der Workflow lautet:

  1. Überprüfen Sie den Indexer auf Erfolgs- oder Fehlermeldungen. Hier werden Verbindungs- oder Kontingentfehler angezeigt.

  2. Ü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.

  3. Wenn ein Skillset generiert wird, überprüfen Sie die Anreicherungs- und Vektorisierungseinstellungen. SQL-Wissensquellen generieren nur dann ein Skillset, wenn Sie angeben embeddingColumns.

  4. Ü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.

Behandeln Sie die generierte Datenquelle, den Indexer, den Index und das Skillset, sofern vorhanden, als eine Aufnahmekonfiguration. Beschränken Sie, wer diese Konfiguration ändern oder Dokumente im zugehörigen Index veröffentlichen kann. Generierte Bezeichner und Berechtigungsfeldnamen richten keinen Dokumentbesitz ein oder machen gewöhnlichen Inhalt zu einer autorisierten Quelle von Berechtigungen. Befolgen Sie die Anleitung zur präventiven Ingestion und die dokumentierten Anpassungsgrenzen; verwenden Sie keine beliebigen direkten Bearbeitungen an generierten Schlüsseln oder Zuordnungen als Eigentumssteuerung.

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 Abrufen-Aktion oder den MCP-Endpunkt auf, um die Wissensquelle abzufragen. Wählen Sie die Konfiguration aus, die Ihrem Szenario entspricht.

Erzwingen von Berechtigungen auf Dokumentebene

Verwenden Sie die Standardextraktionsoption (contentExtractionMode: "minimal") oder die Content-Understanding-basierte Standardextraktion (contentExtractionMode: "standard"), sofern unterstützt. Jeder generierte Block behält die Berechtigungsmetadaten des Quellelements und den Quellkontext des Quellelements bei. Berechtigungen auf Dokumentebene unterstützen keine speziellen vom Kunden ausgewählten Parsingmodi. Siehe Unterstützte Analyse und Inhaltsextraktion für die Aufnahme von Berechtigungen. Konfigurieren Sie diese Optionen für die Wissensquelle; ändern Sie die generierten Parsereinstellungen nicht.

Legen Sie fest ingestionPermissionOptions , wenn Sie die Wissensquelle mit DER REST-API 2026-10-01erstellen:

  • Legen Sie für Standard-Blob Storage die Einstellung auf false und die Anforderung rbacScopefestisADLSGen2. Sehen Sie sich die vollständige Blob-REST-Konfiguration an.
  • Für ADLS Gen2 setzen Sie true auf userIds und fordern Sie isADLSGen2, groupIds und rbacScope an. Beginnen Sie mit der ADLS-REST-Konfiguration, und fügen Sie rbacScope zu ihrem ingestionPermissionOptions-Array hinzu, um sowohl ACLs als auch Container-RBAC-Bereiche aufzunehmen.

Der generierte Index enthält metadata_storage_path und die konfigurierten Berechtigungsfelder mit Zuordnungen zu projizierten Blöcken. Der Pfad ist für die Erfassung von ADLS-Berechtigungen erforderlich, einschließlich der ausschließlichen RBAC-Erfassung. Sein Vorhandensein in einem generierten Standard-Blob-Schema macht es nicht zu einer Anforderung, den Containerbereich eines direkten Blob-Indexers zu berechnen.

Überprüfen Sie den generierten Index, die Skillset-Projektionen und den Indexer zusammen. Behalten Sie den Quellpfadkontext und autoritative Berechtigungszuordnungen für jeden geschützten Block bei. Bei vorhandenen Datensätzen mit fehlenden Werten werden beim Korrigieren des Schemas keine Metadaten zurückgefüllt; Folgen Sie den Schritten zur Schema- und Projektionsbehebung.

Generierte ADLS-Indexer folgen den Automatischen ACL-Aktualisierungseinstellungen und -häufigkeiten. Konfigurieren sie parameters.configuration.refreshAllAcls für den generierten Indexer. Verwenden Sie für eine On-Demand-Aktualisierung den Namen dieses Indexers in der Prozedur zum erneuten Synchronisieren von Berechtigungen.

Fügen Sie das Zugriffstoken des delegierten Benutzers in die Abrufanforderung ein. Informationen zu den Anforderungsheadern finden Sie unter Erzwingen von Berechtigungen zur Abfragezeit.

Surface in Dokumente eingebettete Bilder (Vorschau)

Um in Antworten der Antwortsynthese in Dokumente eingebettete Bilder (z. B. Diagramme oder Scans) anzuzeigen, konfigurieren Sie assetStore für diese Wissensquelle, und aktivieren Sie dann die Bildbereitstellung für die Wissensdatenbank. Die Bereitstellung von Bildern wird nicht unterstützt, wenn ingestionPermissionOptions konfiguriert ist. Weitere Informationen finden Sie unter In Dokumente eingebettete Bilder im Agent-Abruf anzeigen (Vorschau).

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:

  1. 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"
         }
         ]
     }
    
  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
     }
    
  3. 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

  4. Löschen Sie die Wissensquelle.

    await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName);
    System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");
    

    Reference:SearchIndexClient

  1. 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"
         }
         ]
     }
    
  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"
       }
     }
    
  3. 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

  4. 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

  1. 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"
         }
         ]
     }
    
  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"
       }
     }
    
  3. 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

  4. 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