Erstellen einer Dateiwissensquelle (Vorschau)

Note

Azure KI-Suche ist über das Azure Portal, REST-APIs und Azure SDKs verfügbar. Es unterstützt auch Foundry IQ, die verwaltete Wissensschicht, die Unternehmensinhalte in wiederverwendbare, berechtigungsfähige Wissensbasen für Agenten im Microsoft Foundry-Portal transformiert.

Important

Diese Features und Funktionen sind Teil der REST-API 2026-08-01-Preview. Die Vorschau 2026-08-01 wird Ihnen als Teil Ihres Azure-Abonnements lizenziert und unterliegt den Bedingungen für "Vorschauen" in den Microsoft Produktbedingungen, dem Microsoft Produkt- und Dienstdatenschutzzusatz ("DPA") und den ergänzenden Nutzungsbedingungen für Microsoft Azure Previews.

Die Vorschau-APIs unterstützen Verbindungen zu anderen Microsoft-Dienste und Drittanbieterdiensten. Die Nutzung dieser Dienste unterliegt den jeweiligen Bestimmungen und kann dazu führen, dass Daten außerhalb der Azure-Compliancegrenze verarbeitet oder gespeichert werden und dass Daten in die Azure-Compliancegrenze fließen.

Es liegt in Ihrer Verantwortung, zu verwalten, ob Ihre Daten außerhalb der Compliance- und geografischen Grenzen Ihrer Organisation und alle damit verbundenen Auswirkungen fließen und dass entsprechende Berechtigungen, Grenzen und Genehmigungen bereitgestellt werden.

Sie sind dafür verantwortlich, Anwendungen, die Sie im Kontext Ihrer spezifischen Anwendungsfälle erstellen, sorgfältig zu überprüfen und zu testen und alle geeigneten Entscheidungen und Anpassungen zu treffen. Dazu gehört die Implementierung ihrer eigenen verantwortungsvollen KI-Entschärfungen, wie Metaprompts, Inhaltsfilter oder andere Sicherheitssysteme, und sicherzustellen, dass Ihre Anwendungen angemessene Qualität, Zuverlässigkeit, Sicherheit und Vertrauenswürdigkeitsstandards erfüllen. Weitere Informationen finden Sie im Azure KI-Suche Transparenzhinweis.

Eine Datei-Wissensquelle (Vorschau) lädt kleine bis mittlere Dateisätze direkt auf Azure KI-Suche für den agentischen Abruf hoch. Wissensquellen werden unabhängig erstellt, in einer Wissensbasis referenziert und als Erdungsdaten verwendet, wenn die Wissensbasis zur Laufzeit abgefragt wird.

Dateibasierte Wissensquellen sind nützlich, wenn Sie eine verwaltete Uploadumgebung wünschen, anstatt Azure Storage bereitzustellen, den Zugriff zu konfigurieren und eine Indexerpipeline für einen externen Container zu erstellen. Azure KI-Suche verarbeitet hochgeladene Dateien, sodass ihre extrahierten Inhalte aus einer Wissensbasis abgerufen werden können.

Verwenden Sie stattdessen eine Blob-Wissensquelle, wenn sich Ihre Dateien bereits in Azure Blob Storage oder Azure Data Lake Storage Gen2 befinden, wenn Ihr Dateisatz die Grenzwerte der Dateiwissensquelle überschreitet oder voraussichtlich überschreiten wird oder wenn Sie eine geplante Erfassung benötigen. Verwenden Sie auch eine Blob-Wissensquelle, wenn Sie Quell-Blobs mit Azure Blob Storage Lebenszyklusverwaltungsrichtlinien verwalten möchten oder wenn Sie Berechtigungen auf Dokumentebene (Vorschau) basierend auf Berechtigungen in Azure Storage benötigen.

Nutzungssupport

Azure Portal Microsoft Foundry Portal .NET SDK Python SDK Java SDK JavaScript SDK REST-API
❌ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Voraussetzungen

  • Einen Azure KI-Suche Dienst in einer beliebigen Region, der agentischen Abruf bereitstellt. Dateibasierte Wissensquellen unterstützen sowohl die Preismodelle „Dedicated“ als auch „Serverless“. Einzelheiten zu Modell und Dienstebene finden Sie unter Ein Preismodell und eine Dienstebene auswählen.

  • Prüfen Sie die Kosten für Azure KI-Suche. Modellaufrufe, Vektorisierung und andere KI-Verarbeitungen können separate Gebühren verursachen.

  • Bei Serverless verbrauchen erfolgreiche Dateiaufnahmevorgänge eine abrechnungsfähige Berechnung. Für fehlgeschlagene Uploads fallen keine Serverless-Compute-Gebühren an.

  • Wenn Sie einen kostenpflichtigen agentischen Abruf über das monatliche kostenlose Freigeld hinaus benötigen, aktivieren Sie den standardmäßigen agentischen Abrufplan. Die knowledgeRetrieval=standard Einstellung unterscheidet sich von Serverless Compute- und Speichergebühren und wählt kein Preismodell aus.

  • Dateien in einem unterstützten Format.

  • Berechtigung zum Erstellen von Wissensquellen. Konfigurieren Sie die schlüssellose Authentifizierung mit der Rolle "Mitwirkender des Suchdiensts ", die Ihrem Benutzerkonto zugewiesen ist (empfohlen), oder verwenden Sie einen Administrator-API-Schlüssel.

  • Wenn die Wissensquelle ein Azure OpenAI-Modell für Einbettungen angibt, muss der Suchdienst über eine managed Identity mit Cognitive Services UserBerechtigungen für die ressource Microsoft Findry verfügen.

    • Wenn die Foundry-Ressource den Zugriff auf das öffentliche Netzwerk deaktiviert hat, erstellen Sie einen foundry_accountfreigegebenen privaten Link vom Suchdienst zur Foundry-Ressource, und behalten Sie die Einstellung "Zulassen Azure-Dienste der Ressource in der Listeneinstellung "vertrauenswürdige Dienste" aktiviert.

  • Wenn die Wissensquelle den standard Inhaltsextraktionsmodus angibt, überprüfen Sie die Anforderungen für die Azure Fähigkeit zum Inhaltsverständnis.

    • Die Nutzung wird gemäß der Preisgestaltung von Azure Content Understanding in Foundry Tools der über aiServices konfigurierten Foundry-Ressource in Rechnung gestellt.

    • Das tägliche Freikontingent von 20 kostenlosen Dokumenten, das für einige integrierte Skills verfügbar ist, gilt nicht.

    • Für das Beispiel in diesem Artikel benötigen Sie den Foundry-Ressourcenendpunkt und den Schlüssel sowie Azure OpenAI-Einbettungs- und Chatabschlussmodellinformationen.

  • Das neueste Azure.Search.Documents Vorschaupaket: dotnet add package Azure.Search.Documents --prerelease

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

  • Das neueste azure-search-documents Vorschaupaket: pip install --pre azure-search-documents

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

Dateiunterstützung und -beschränkungen

Bevor Sie eine Dateiwissensquelle erstellen, überprüfen Sie die Anforderungen und Grenzwerte, die sich auf das Hochladen, Extrahieren und Verwalten von Dateien auswirken.

Unterstützte Inhaltstypen

Dateiwissensquellen akzeptieren Dateien basierend auf dem erkannten Inhaltstyp. Ein vom Aufrufer bereitgestellter Inhaltstyp überschreibt die Erkennung nicht.

Folgende Inhaltstypen werden unterstützt:

  • PDF
  • Word (.doc, .docx)
  • PowerPoint (.ppt, .pptx)
  • Excel (.xls, .xlsx)
  • JSON
  • Shell-Skripte
  • Als text/* erkannter Inhalt, wie .txt, .md, .html und .csv

Unterstützte Extraktionsmodi

  • Für die aufgeführten Inhaltstypen unterstützen sowohl 2026-05-01-preview als auch 2026-08-01-previewminimal. standard ist nur in 2026-08-01-preview.

  • Inhalt, der als image/* erkannt wurde, wird in 2026-05-01-preview nicht unterstützt. Verwenden Sie in 2026-08-01-preview die Extraktion standard. minimal Die Extraktion gibt den HTTP-Status 415 in beiden Versionen zurück.

Grenzwerte und Dateivorgänge

Grenzwerte und unterstützte Dateivorgänge unterscheiden sich je nach API-Version.

Fähigkeit 2026-05-01-preview 2026-08-01-preview
Maximale Anzahl von Dateien pro Wissensquelle 100 200
Maximale Dateigröße 50 MB auf allen unterstützten Preisniveaus 50 MB in Free und Basic; 100 MB in anderen unterstützten Dedicated-Tarifen und in Serverless
Verarbeitungsdauer Der Upload kann bis zu 180 Sekunden lang ausgeführt werden. Upload und Update können bis zu 180 Sekunden lang ausgeführt werden.
Hochladen von Inhalten und Metadaten Unformatierter Dateiinhalt Rohdateiinhalte oder mehrteilige Inhalte mit Metadaten
Auflisten hochgeladener Dateien Dateien auflisten Filtern nach Pfad- oder Dateinamen und Zurückgeben umfangreicherer Dateidetails
Vorhandene Dateiinhalte ersetzen Löschen und erneutes Hochladen Aktualisierungsvorgang verwenden
Browserzugriff auf Dateivorgänge CORS ist nicht verfügbar Konfigurieren von CORS

Note

  • Der generierte Suchindex speichert den hochgeladenen Inhalt. Informationen zu Gesamtspeicherlimits nach Preisniveau finden Sie unter Dienstgrenzwerte.
  • Wenn Sie die Dateiwissensquelle so konfigurieren, dass hochgeladene Inhalte geblockt oder vektorisiert werden, gelten auch Modell- und Downstreamverarbeitungsgrenzwerte.

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

{
  "name": "my-file-ks",
  "kind": "file",
  "description": "A sample file knowledge source.",
  "encryptionKey": null,
  "fileParameters": {
    "ingestionParameters": {
      "contentExtractionMode": "minimal",
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "text-embedding-3-large",
          "modelName": "text-embedding-3-large"
        }
      }
    }
  }
}

Erstellen einer Wissensquelle

Erstellen Sie eine Dateiwissensquelle, die das Einbettungsmodell angibt, das zum Vektorisieren von hochgeladenen Inhalten verwendet wird.

Jede dateibasierte Wissensquelle erstellt einen Index, aber keinen Indexer oder Zeitplan. Sie müssen das fileParameters.ingestionParameters Objekt einschließen. Der Dienst lehnt Anfragen ab, die networkAccessMode angeben.

using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.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
{
    ContentExtractionMode = "minimal",
    EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
    {
        AzureOpenAIParameters = embeddingParams
    }
};

var fileParams = new FileKnowledgeSourceParameters
{
    IngestionParameters = ingestionParams
};

var knowledgeSource = new FileKnowledgeSource(
    name: "my-file-ks",
    fileParameters: fileParams
)
{
    Description = "This knowledge source uses directly uploaded product manuals."
};

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

Reference:SearchIndexClient

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
    AzureOpenAIVectorizerParameters,
    FileKnowledgeSource,
    FileKnowledgeSourceParameters,
)
from azure.search.documents.knowledgebases.models import (
    KnowledgeSourceAzureOpenAIVectorizer,
    KnowledgeSourceIngestionParameters,
)

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(
    content_extraction_mode="minimal",
    embedding_model=KnowledgeSourceAzureOpenAIVectorizer(
        azure_open_ai_parameters=embedding_params
    ),
)

knowledge_source = FileKnowledgeSource(
    name="my-file-ks",
    description="This knowledge source uses directly uploaded product manuals.",
    file_parameters=FileKnowledgeSourceParameters(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

PUT {{search-endpoint}}/knowledgesources/my-file-ks?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json
Prefer: return=representation

{
  "name": "my-file-ks",
  "kind": "file",
  "description": "This knowledge source uses directly uploaded product manuals.",
  "encryptionKey": null,
  "fileParameters": {
    "ingestionParameters": {
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "{{aoai-endpoint}}",
          "deploymentId": "{{aoai-embedding-deployment}}",
          "modelName": "{{aoai-embedding-model}}"
        }
      },
      "contentExtractionMode": "minimal"
    }
  }
}

Referenz:Wissensquellen – Erstellen oder Aktualisieren

Konfigurieren der Standardextraktion

Ab der API-Version standard verwendet die 2026-08-01-preview-Extraktion Content Understanding, um hochgeladene Dateien zu extrahieren, semantisch zu segmentieren und anzureichern. Azure KI-Suche verwaltet diese Verarbeitung als Teil der Wissensquelle, und Gebühren für Content Understanding fallen separat an.

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 embeddingParameters = new AzureOpenAIVectorizerParameters
{
  ResourceUri = new Uri(aoaiEndpoint),
  DeploymentName = aoaiEmbeddingDeployment,
  ModelName = aoaiEmbeddingModel
};

var ingestionParameters = new KnowledgeSourceIngestionParameters
{
  ContentExtractionMode = KnowledgeSourceContentExtractionMode.Standard,
  AiServices = new AIServices(new Uri(foundryEndpoint)) { ApiKey = foundryKey },
  EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
  {
    AzureOpenAIParameters = embeddingParameters
  },
  ChatCompletionModel = new KnowledgeBaseAzureOpenAIModel(
    new AzureOpenAIVectorizerParameters
    {
      ResourceUri = new Uri(aoaiEndpoint),
      DeploymentName = aoaiChatDeployment,
      ModelName = aoaiChatModel
    })
};

var knowledgeSource = new FileKnowledgeSource(
  "my-file-ks",
  new FileKnowledgeSourceParameters { IngestionParameters = ingestionParameters });

await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Configured standard extraction for '{knowledgeSource.Name}'.");

Reference:SearchIndexClient

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
  AzureOpenAIVectorizerParameters,
  FileKnowledgeSource,
  FileKnowledgeSourceParameters,
  KnowledgeBaseAzureOpenAIModel,
)
from azure.search.documents.knowledgebases.models import (
  AIServices,
  KnowledgeSourceAzureOpenAIVectorizer,
  KnowledgeSourceIngestionParameters,
)

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

embedding_parameters = AzureOpenAIVectorizerParameters(
  resource_url="<aoai-endpoint>",
  deployment_name="<aoai-embedding-deployment>",
  model_name="<aoai-embedding-model>",
)
ingestion_parameters = KnowledgeSourceIngestionParameters(
  content_extraction_mode="standard",
  ai_services=AIServices(
    uri="<foundry-resource-endpoint>",
    api_key="<foundry-resource-key>",
  ),
  embedding_model=KnowledgeSourceAzureOpenAIVectorizer(
    azure_open_ai_parameters=embedding_parameters
  ),
  chat_completion_model=KnowledgeBaseAzureOpenAIModel(
    azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
      resource_url="<aoai-endpoint>",
      deployment_name="<aoai-gpt-deployment>",
      model_name="<aoai-gpt-model>",
    )
  ),
)
knowledge_source = FileKnowledgeSource(
  name="my-file-ks",
  file_parameters=FileKnowledgeSourceParameters(
    ingestion_parameters=ingestion_parameters
  ),
)

index_client.create_or_update_knowledge_source(knowledge_source)
print(f"Configured standard extraction for '{knowledge_source.name}'.")

Reference:SearchIndexClient

PUT {{search-endpoint}}/knowledgesources/my-file-ks?api-version=2026-08-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}
Prefer: return=representation

{
  "name": "my-file-ks",
  "kind": "file",
  "description": "This knowledge source uses standard extraction.",
  "fileParameters": {
    "ingestionParameters": {
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "{{aoai-endpoint}}",
          "deploymentId": "{{aoai-embedding-deployment}}",
          "modelName": "{{aoai-embedding-model}}"
        }
      },
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "{{aoai-endpoint}}",
          "deploymentId": "{{aoai-gpt-deployment}}",
          "modelName": "{{aoai-gpt-model}}"
        }
      },
      "contentExtractionMode": "standard",
      "aiServices": {
        "uri": "{{foundry-resource-endpoint}}",
        "apiKey": "{{foundry-resource-key}}"
      }
    }
  }
}

Referenz:Wissensquellen – Erstellen oder Aktualisieren

CORS für Dateivorgänge

Um browserbasierte Dateivorgänge zuzulassen, legen Sie für die Dateiwissensquelle mit den vertrauenswürdigen Ursprüngen und der maximalen Cachedauer für preflight für Ihre Anwendung fest corsOptions .

Important

In der 2026-08-01-preview API-Version gilt corsOptions für Endpunkte zum Hochladen, Auflisten, Aktualisieren und Löschen von Dateien, unabhängig vom Extraktionsmodus. Wenn Sie corsOptions weglassen, hat die Datei-Wissensquelle keine Cross-Origin-Richtlinie des Browsers. CORS autorisiert keine Anfragen. Das Aktivieren von Quellen kann Dienstvorgänge und Daten in einem Browserkontext offenlegen und Sicherheitsrisiken mit sich bringen. Geben Sie nur vertrauenswürdige Quellen an, und verwenden Sie in Produktionsumgebungen keine Platzhalter-Quelle. Verwenden Sie für Browseranforderungen die Microsoft Entra-Tokenauthentifizierung mit der minimal erforderlichen Rolle. Stellen Sie niemals Zugriffstoken oder Dienstschlüssel im Browsercode zur Verfügung.

Dateien hochladen

Nachdem Sie die Wissensquelle erstellt haben, laden Sie Dateien direkt darauf hoch. Jeder Upload ist ein synchroner Aufruf: Azure KI-Suche Inhalte extrahiert, Blöcke extrahiert, bei Bedarf Einbettungen erstellt, die Blöcke indiziert und Dateimetadaten beibehalten, bevor der Aufruf zurückgegeben wird. Sie müssen keine separate Aufnahmepipeline konfigurieren oder ausführen.

Hilfe bei Fehlern im Zusammenhang mit dem Hochladen und Verwalten von Dateien finden Sie unter Problembehandlung bei Dateivorgängen.

Hochladen einer Rohdatei

Bei einem unformatierten Upload stammt die aufgelistete fileName Datei aus der Content-Disposition: attachment; filename="..." Kopfzeile. REST-Aufrufe und das .NET SDK legen diesen Header direkt fest, während das Python SDK einen filename-Parameter akzeptiert und den Header automatisch erstellt. Wenn Sie keinen Dateinamen angeben, weist der Dienst eine automatisch generierte fileNameZuweisung zu.

Dateinamen können einen relativen Pfad enthalten, wie z. B. manuals/installation-guide.pdf. Der Dienst normalisiert Backslashes zu Schrägstrichen. Es lehnt absolute Pfade, leere Pfadsegmente oder .. Segmente, . Doppelpunkt-enthaltende Segmente und ungültige Dateinamenzeichen mit HTTP-Status 400ab.

using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

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

string fileName = "installation-guide.pdf";
byte[] fileBytes = await File.ReadAllBytesAsync(fileName);
string contentDisposition = $"attachment; filename=\"{fileName}\"";

KnowledgeSourceFile uploadedFile = (await indexClient.UploadKnowledgeSourceFileAsync(
    "my-file-ks",
    contentDisposition,
    BinaryData.FromBytes(fileBytes))).Value;

Console.WriteLine($"Uploaded file ID: {uploadedFile.FileId}");

Reference:SearchIndexClient.UploadKnowledgeSourceFileAsync

from pathlib import Path

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient

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

file_path = Path("installation-guide.pdf")
uploaded_file = index_client.upload_knowledge_source_file(
    "my-file-ks",
    file_path.read_bytes(),
    filename=file_path.name,
)
print(f"Uploaded file ID: {uploaded_file.file_id}")

Verweis:SearchIndexClient.upload_knowledge_source_file

POST {{search-endpoint}}/knowledgesources/my-file-ks/files?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/octet-stream
Content-Disposition: attachment; filename="installation-guide.pdf"

<binary file content>

Referenz:Wissensquellen – Datei hochladen

Hochladen einer Datei mit optionalen Metadaten

Verwenden Sie ab der 2026-08-01-preview API-Version eine mehrteilige Anforderung, um eine Binärdatei mit optionalen benutzerdefinierten Metadaten hochzuladen. Die Anforderung enthält genau einen content Teil und einen optionalen JSON-Teil metadata .

Wenn beide Namen angegeben sind, metadata.fileName hat dies Vorrang vor dem Dateinamen des content Teils. Wenn keines angegeben ist, weist der Dienst einen automatisch generierten Dateinamen zu.

using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
var metadata = new FileUploadMetadata
{
  FileName = "installation-guide.pdf",
  Metadata =
  {
    ["department"] = "support",
    ["product"] = "contoso-100"
  }
};

#pragma warning disable SCME0004
var request = new UploadKnowledgeSourceFileMultipartRequest(
  metadata,
  "installation-guide.pdf");
KnowledgeSourceFile uploadedFile = (await indexClient
  .UploadKnowledgeSourceFileMultipartAsync("my-file-ks", request)).Value;
#pragma warning restore SCME0004

Console.WriteLine($"Uploaded file ID: {uploadedFile.FileId}");

Referenz:SearchIndexClient.UploadKnowledgeSourceFileMultipartAsync

from pathlib import Path

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
  FileUploadMetadata,
  UploadKnowledgeSourceFileMultipartRequest,
)

index_client = SearchIndexClient(endpoint="<search-endpoint>", credential=DefaultAzureCredential())
file_path = Path("installation-guide.pdf")
request = UploadKnowledgeSourceFileMultipartRequest(
  metadata=FileUploadMetadata(
    file_name=file_path.name,
    metadata={"department": "support", "product": "contoso-100"},
  ),
  content=(file_path.name, file_path.read_bytes(), "application/pdf"),
)

uploaded_file = index_client.upload_knowledge_source_file_multipart(
  name="my-file-ks",
  body=request,
)
print(f"Uploaded file ID: {uploaded_file.file_id}")

Reference:SearchIndexClient.upload_knowledge_source_file_multipart

POST {{search-endpoint}}/knowledgesources('my-file-ks')/files?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: multipart/form-data; boundary=file-boundary

--file-boundary
Content-Disposition: form-data; name="metadata"
Content-Type: application/json

{
  "fileName": "installation-guide.pdf",
  "metadata": {
    "department": "support",
    "product": "contoso-100"
  }
}
--file-boundary
Content-Disposition: form-data; name="content"; filename="installation-guide.pdf"
Content-Type: application/octet-stream

< ./installation-guide.pdf
--file-boundary--

Referenz:Wissensquellen – Datei hochladen

Note

Durch das Hochladen einer Datei wird keine vorhandene Datei ersetzt, auch wenn Sie dasselbe fileNamewiederverwenden. Jeder erfolgreiche Upload erstellt eine neue Datei mit einer eigenen fileId, sodass die Liste der hochgeladenen Dateien mehrere Einträge enthalten kann, die sich ein fileName teilen.

Mit 2026-05-01-preview ersetzen Sie Inhalte, indem Sie die vorherige Datei löschen und die Ersatzdatei hochladen. Mit 2026-08-01-preview verwenden Sie den Aktualisierungsvorgang.

Auflisten hochgeladener Dateien

Auflisten von Dateien in der Wissensquelle, um den hochgeladenen Dateisatz zu prüfen.

using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

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

await foreach (KnowledgeSourceFile file in indexClient.GetKnowledgeSourceFilesAsync("my-file-ks"))
{
    Console.WriteLine($"{file.FileName} ({file.FileSizeBytes} bytes) error={file.ErrorMessage}");
}

Reference:SearchIndexClient.GetKnowledgeSourceFilesAsync

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient

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

for file in index_client.list_knowledge_source_files("my-file-ks"):
    print(f"{file.file_name} ({file.file_size_bytes} bytes) error={file.error_message}")

Referenz:SearchIndexClient.list_knowledge_source_files

GET {{search-endpoint}}/knowledgesources/my-file-ks/files?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}

Referenz:Wissensquellen - Dateien auflisten

Die Antwort enthält Metadaten für jede hochgeladene Datei. Erfolgreich aufgelistete Dateien haben einen errorMessage Wert von null.

{
  "value": [
    {
      "fileId": "file-abc123",
      "fileName": "installation-guide.pdf",
      "fileSizeBytes": 1048576,
      "createdAt": "2026-05-07T18:10:00Z",
      "lastUpdatedAt": "2026-05-07T18:14:00.803Z",
      "errorMessage": null
    }
  ]
}

Wenn ein neuer Upload fehlschlägt, gibt die Anforderung einen Fehler zurück und erstellt keinen Dateimetadatensatz. Der fehlgeschlagene Upload wird in späteren Listenergebnissen nicht angezeigt und wird nicht in Rechnung gestellt.

Wenn ein Fehler beim Modellzugriff auftritt und die Foundry-Ressource, auf der das Einbettungsmodell gehostet wird, private Netzwerke nutzt, vergewissern Sie sich, dass der foundry_account freigegebene private Link genehmigt ist und der Bypass für vertrauenswürdige Dienste aktiviert ist. Ein deaktivierter Bypass gibt 403 Public access is disabled zurück. Details zum Setup finden Sie unter "Voraussetzungen".

Auflisten und Filtern von Dateien

Ab API-Version 2026-08-01-preview verwenden Sie prefix, um Dateien nach relativem Pfad zu filtern, oder search, um nach dem Dateinamenpräfix zu filtern. Legen Sie fest pageSize , um die Anzahl der Ergebnisse zu steuern.

using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

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

await foreach (KnowledgeSourceFile file in indexClient.GetKnowledgeSourceFilesAsync(
  "my-file-ks",
  prefix: "manuals/",
  pageSize: 100))
{
  Console.WriteLine($"{file.FileName} ({file.FileId})");
}

Reference:SearchIndexClient.GetKnowledgeSourceFilesAsync

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient

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

files = index_client.list_knowledge_source_files(
  "my-file-ks",
  prefix="manuals/",
  page_size=100,
)
for file in files:
  print(f"{file.file_name} ({file.file_id})")

Referenz:SearchIndexClient.list_knowledge_source_files

GET {{search-endpoint}}/knowledgesources('my-file-ks')/files?api-version=2026-08-01-preview&prefix=manuals/&pageSize=100
Authorization: Bearer {{search-access-token}}

Referenz:Wissensquellen - Dateien auflisten

Die Antwort umfasst vom Dienst ausgewählte Analyse- und Extraktionsmodi sowie Benutzermetadaten für die Dateiverwaltung. Benutzermetadaten können nicht durchsucht oder gefiltert werden.

{
  "value": [
    {
      "fileId": "file-abc123",
      "fileName": "manuals/installation-guide.md",
      "prefix": "manuals/",
      "metadata": {
        "department": "support",
        "product": "contoso-100"
      },
      "parsingMode": "markdown",
      "extractionMode": "minimal",
      "fileSizeBytes": 1048576,
      "createdAt": "2026-08-03T18:10:00Z",
      "lastUpdatedAt": "2026-08-03T18:14:00Z",
      "errorMessage": null
    }
  ],
  "@odata.nextLink": "<service-generated continuation URL>"
}

Um alle Ergebnisse abzurufen, verwenden Sie @odata.nextLink, bis es nicht mehr vorhanden ist. Senden Sie die vollständige URL genau wie zurückgegeben, ohne die Abfrageparameter zu ändern.

Aktualisieren einer hochgeladenen Datei

Aktualisieren Sie ab der 2026-08-01-preview API-Version eine Datei anhand der zugehörigen fileId. Für die mehrteilige Anforderung ist der binäre content Teil erforderlich. Der JSON-Teil der Metadaten ist optional, sodass ein Nur-Inhalt-Update unterstützt wird. Ein Update nur mit Metadaten wird nicht unterstützt.

using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
var metadata = new FileUploadMetadata
{
  FileName = "installation-guide.pdf",
  Metadata =
  {
    ["department"] = "support",
    ["product"] = "contoso-200"
  }
};

#pragma warning disable SCME0004
var request = new UpdateKnowledgeSourceFileRequest(
  metadata,
  "installation-guide.pdf");
KnowledgeSourceFile updatedFile = (await indexClient.UpdateKnowledgeSourceFileAsync(
  fileId,
  "my-file-ks",
  request)).Value;
#pragma warning restore SCME0004

Console.WriteLine($"Updated file ID: {updatedFile.FileId}");

Reference:SearchIndexClient.UpdateKnowledgeSourceFileAsync

from pathlib import Path

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
  FileUploadMetadata,
  UpdateKnowledgeSourceFileRequest,
)

index_client = SearchIndexClient(endpoint="<search-endpoint>", credential=DefaultAzureCredential())
file_path = Path("installation-guide.pdf")
request = UpdateKnowledgeSourceFileRequest(
  metadata=FileUploadMetadata(
    file_name=file_path.name,
    metadata={"department": "support", "product": "contoso-200"},
  ),
  content=(file_path.name, file_path.read_bytes(), "application/pdf"),
)

updated_file = index_client.update_knowledge_source_file(
  name="my-file-ks",
  file_id=file_id,
  body=request,
)
print(f"Updated file ID: {updated_file.file_id}")

Referenz:SearchIndexClient.update_knowledge_source_file

PUT {{search-endpoint}}/knowledgesources('my-file-ks')/files('{{file-id}}')?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: multipart/form-data; boundary=file-boundary

--file-boundary
Content-Disposition: form-data; name="metadata"
Content-Type: application/json

{
  "fileName": "installation-guide.pdf",
  "metadata": {
    "department": "support",
    "product": "contoso-200"
  }
}
--file-boundary
Content-Disposition: form-data; name="content"; filename="installation-guide.pdf"
Content-Type: application/octet-stream

< ./installation-guide.pdf
--file-boundary--

Referenz:Wissensquellen – Datei aktualisieren

Wenn ein Update fehlschlägt, bleibt der vorherige Metadatendatensatz erhalten. Gehen Sie nicht davon aus, dass eine Aktualisierung indizierte Inhalte transaktional ändert.

Löschen hochgeladener Dateien

Löschen Sie Dateien aus der Wissensquelle, wenn sie nicht mehr zum Abrufen verfügbar sein sollen.

using Azure.Identity;
using Azure.Search.Documents.Indexes;

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

await indexClient.DeleteKnowledgeSourceFileAsync("my-file-ks", "file-abc123");

Reference:SearchIndexClient.DeleteKnowledgeSourceFileAsync

from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient

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

index_client.delete_knowledge_source_file("my-file-ks", "file-abc123")

Referenz:SearchIndexClient.delete_knowledge_source_file

DELETE {{search-endpoint}}/knowledgesources/my-file-ks/files/file-abc123?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}

Referenz:Wissensquellen - Datei löschen

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:

  1. Erhalten Sie eine Liste aller Wissensdatenbanken für Ihren Suchdienst.

    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 Wissensdatenbanken für Ihren Suchdienst.

    # 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 Wissensdatenbanken für Ihren Suchdienst.

    ### 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 Basen - 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

Problembehandlung bei Dateivorgängen

Die folgenden Statuscodes sind spezifisch für Datei-Wissensquellenvorgänge.

Statuscode Ursache und Aktion
400 Die Datei ist leer, enthält keinen extrahierenden Text, hat einen unsicheren relativen Pfad oder eine ungültige Fortsetzungsanforderung. Überprüfen Sie, ob die Datei unterstützte, lesbare Inhalte und einen gültigen Dateinamen unterstützt hat. Verwenden Sie für Listenoperationen @odata.nextLink genau in der zurückgegebenen Form. Kombinieren Sie nicht $skiptoken mit search oder pageSize.
409 Die Dateiwissensquelle hat den Dateigrenzwert für die API-Version erreicht. Löschen Sie Dateien, bevor Sie mehr hochladen.
415 Der Dienst hat einen nicht unterstützten MIME-Typ erkannt oder ein Bild erkannt, während die Wissensquelle minimale Extraktionen verwendet. Verwenden Sie ein unterstütztes Format. Verwenden Sie für Bilder die Standardextraktion. Das Ändern nur des vom Aufrufer bereitgestellten Inhaltstyps setzt die Erkennung nicht außer Kraft.
429 Die Verarbeitungswarteschlange ist voll. Verwenden Sie gebundenen Parallelismus, und versuchen Sie es mit exponentiellem Backoff. Der Dienst garantiert keinen Retry-After Header.
504 Die Verarbeitung hat beim Hochladen oder Aktualisieren der Datei 180 Sekunden überschritten. Verringern Sie die Dateigröße oder Komplexität, und versuchen Sie es erneut.

Verwandte Inhalte

  • Last updated on