Een kennisbron voor bestanden maken (preview)

Opmerking

Azure AI Zoeken is beschikbaar via de Azure-portal, REST API's en Azure-SDK's. Het vormt ook een basis voor Foundry IQ, de beheerde kennislaag die bedrijfsinhoud transformeert in herbruikbare, machtigingsbewuste knowledge bases voor agents in de Microsoft Foundry-portal.

Important

Deze functies en functionaliteit maken deel uit van de REST API 2026-08-01-preview. De preview-versie van 2026-08-01 is aan u gelicentieerd als onderdeel van uw Azure-abonnement en is onderworpen aan de voorwaarden die van toepassing zijn op 'Previews' in de Microsoft Productvoorwaarden, de Microsoft Addendum voor producten en services voor gegevensbescherming ("DPA") en de aanvullende gebruiksvoorwaarden voor Microsoft Azure previews.

De preview-API's ondersteunen verbindingen met andere Microsoft-services en services van derden. Het gebruik van deze services is onderhevig aan hun respectieve voorwaarden en kan leiden tot gegevensverwerking of opslag buiten de grens van Azure naleving, evenals gegevens die naar de grens van de Azure naleving stromen.

Het is uw verantwoordelijkheid om te beheren of uw gegevens buiten de nalevings- en geografische grenzen van uw organisatie en eventuele gerelateerde implicaties stromen, en dat de juiste machtigingen, grenzen en goedkeuringen worden ingericht.

U bent verantwoordelijk voor het zorgvuldig beoordelen en testen van toepassingen die u bouwt in de context van uw specifieke use cases en het nemen van alle juiste beslissingen en aanpassingen. Dit omvat het implementeren van uw eigen verantwoorde AI-oplossingen, zoals metaprompts, inhoudsfilters of andere veiligheidssystemen, en ervoor zorgen dat uw toepassingen voldoen aan de juiste kwaliteit, betrouwbaarheid, beveiliging en betrouwbaarheidsstandaarden. Zie de Azure AI Zoeken Transparantienotitie voor meer informatie.

Een bestandskennisbron (preview) uploadt kleine tot middelgrote verzamelingen bestanden rechtstreeks naar Azure AI Zoeken voor retrieval door agents. Kennisbronnen worden onafhankelijk gemaakt, waarnaar wordt verwezen in een knowledge base en worden gebruikt als grondgegevens wanneer de knowledge base tijdens runtime wordt opgevraagd.

Bestandskennisbronnen zijn handig als u een beheerde uploadervaring wilt in plaats van Azure Storage in te richten, toegang te configureren en een indexeerpijplijn te maken via een externe container. Azure AI Zoeken verwerkt geüploade bestanden, zodat de geëxtraheerde inhoud uit een kennisbank kan worden opgehaald.

Gebruik in plaats daarvan een blob-kennisbron wanneer uw bestanden zich al in Azure Blob Storage of Azure Data Lake Storage Gen2 bevinden, wanneer uw bestandsset de limieten van de kennisbron voor bestanden overschrijdt of waarschijnlijk overschrijdt, of wanneer u geplande opname nodig hebt. Gebruik ook een blob-kennisbron als u bron-blobs wilt beheren met Azure Blob Storage levenscyclusbeheerbeleid of wanneer u machtigingen op documentniveau (preview) nodig hebt op basis van machtigingen in Azure Storage.

Gebruiksondersteuning

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

Prerequisites

  • Een Azure AI Zoeken-service in elke regio die op agent gebaseerde gegevensophaling biedt. Kennisbronnen voor bestanden ondersteunen zowel het Dedicated- als het Serverless-prijsmodel. Zie Een prijsmodel en servicelaag kiezen voor meer informatie over modellen en lagen.

  • Bekijk de kosten van Azure AI Zoeken. Modeloproepen, vectorisatie en andere AI-verwerking kunnen afzonderlijke kosten in rekening brengen.

  • In Serverless verbruiken geslaagde bestandsinvoerbewerkingen factureerbare rekenkracht. Voor mislukte uploads worden geen serverloze rekenkosten in rekening gebracht.

  • Als u betaalde agentische zoekopdrachten nodig hebt boven het maandelijkse gratis tegoed, schakel dan het standaardplan voor agentische zoekopdrachten in. De knowledgeRetrieval=standard instelling is gescheiden van serverloze reken- en opslagkosten en selecteert geen prijsmodel.

  • Bestanden in een ondersteunde indeling.

  • Machtiging voor het maken van kennisbronnen. Configureer sleutelloze verificatie met de rol Inzender voor zoekservice die is toegewezen aan uw gebruikersaccount (aanbevolen) of gebruik een beheer-API-sleutel.

  • Als de kennisbron een Azure OpenAI-model voor embeddings opgeeft, moet de zoekservice een beheerde identiteit hebben met Cognitive Services User-machtigingen op de Microsoft Foundry-resource.

    • Als de Foundry-resource openbare netwerktoegang heeft uitgeschakeld, maakt u een foundry_accountgedeelde privékoppeling aan van de zoekservice naar de Foundry-resource en zorgt u ervoor dat de instelling Azure-services op de lijst met vertrouwde services toestaan van de resource ingeschakeld blijft.
  • Als de kennisbron de standard modus voor inhoudextractie specificeert, controleert u de vereisten voor de vaardigheid Azure Inhoudskennis.

    • Kosten voor het gebruik worden in rekening gebracht tegen de tarieven voor Azure Content Understanding in Foundry Tools aan de Foundry-resource die is geconfigureerd via aiServices.

    • De dagelijkse gratis vergoeding van 20 documenten die beschikbaar is voor sommige ingebouwde vaardigheden, is niet van toepassing.

    • Voor het voorbeeld in dit artikel hebt u het eindpunt en de sleutel van de Foundry-resource nodig, plus Azure openAI-insluitings- en voltooiingsmodelgegevens voor chats.

  • Het nieuwste preview-pakket Azure.Search.Documents: dotnet add package Azure.Search.Documents --prerelease

  • Voor sleutelloze verificatie is het Azure.Identity pakket: dotnet add package Azure.Identity

  • Het nieuwste preview-pakket azure-search-documents: pip install --pre azure-search-documents

  • Voor sleutelloze verificatie is het azure-identity pakket: pip install azure-identity

Bestandsondersteuning en -limieten

Voordat u een kennisbron voor bestanden maakt, controleert u de vereisten en limieten die van invloed zijn op het uploaden, extraheren en beheren van bestanden.

Ondersteunde inhoudstypen

Bestandskennisbronnen accepteren bestanden op basis van het gedetecteerde inhoudstype. Een door een beller opgegeven inhoudstype overschrijft detectie niet.

Ondersteunde inhoudstypen zijn:

  • PDF
  • Word (.doc, .docx)
  • PowerPoint (.ppt, .pptx)
  • Excel (.xls, .xlsx)
  • JSON
  • Shell-scripts
  • Inhoud gedetecteerd als text/*, zoals .txt, .md, .html en .csv

Ondersteunde extractiemodi

  • Voor de vermelde inhoudstypen ondersteunen zowel 2026-05-01-preview als 2026-08-01-previewminimal. standard is alleen beschikbaar in 2026-08-01-preview.

  • Inhoud gedetecteerd zoals image/* wordt niet ondersteund in 2026-05-01-preview. Gebruik in standard2026-08-01-preview-extractie. minimal extractie retourneert HTTP-status 415 in beide versies.

Limieten en bestandsbewerkingen

Limieten en ondersteunde bestandsbewerkingen verschillen per API-versie.

Vermogen 2026-05-01-preview 2026-08-01-preview
Maximum aantal bestanden per kennisbron 100 200
Maximale bestandsgrootte 50 MB voor alle ondersteunde prijscategorieën 50 MB op Gratis en Basic; 100 MB op andere ondersteunde Dedicated-lagen en Serverloos
Verwerkingsduur Uploaden kan maximaal 180 seconden duren Uploaden en bijwerken kan maximaal 180 seconden worden uitgevoerd
Inhoud en metagegevens uploaden Onbewerkte bestandsinhoud Onbewerkte bestandsinhoud of inhoud met meerdere onderdelen met metagegevens
Geüploade bestanden weergeven Bestanden in een lijst weergeven Filteren op pad of bestandsnaam en uitgebreidere bestandsgegevens retourneren
Bestaande bestandsinhoud vervangen Verwijderen en opnieuw uploaden Updatebewerking gebruiken
Browsertoegang tot bestandsbewerkingen CORS is niet beschikbaar CORS configureren

Opmerking

  • De gegenereerde zoekindex slaat de geüploade inhoud op. Zie Servicelimieten voor de totale opslaglimieten per prijscategorie.
  • Als u de kennisbron voor bestanden configureert om geüploade inhoud te segmenteren of te vectoriseren, gelden ook model- en downstreamverwerkingslimieten.

Controleren op bestaande kennisbronnen

Een kennisbron is een herbruikbaar object op het hoogste niveau. Kennis over bestaande kennisbronnen is handig voor het opnieuw gebruiken of benoemen van nieuwe objecten.

Voer de volgende code uit om kennisbronnen op naam en type weer te geven.

// 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}");
}

Naslaginformatie: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})")

Naslaginformatie:SearchIndexClient

### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version={{api-version}}&$select=name,kind
Authorization: Bearer {{token}}

Naslaginformatie:Kennisbronnen - Lijst

U kunt ook één kennisbron op naam retourneren om de JSON-definitie ervan te controleren.

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));

Naslaginformatie: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))

Naslaginformatie:SearchIndexClient

### Get a knowledge source definition
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}}
Authorization: Bearer {{token}}

Naslaginformatie:Kennisbronnen ophalen

De volgende JSON is een voorbeeldantwoord voor een kennisbron voor bestanden.

{
  "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"
        }
      }
    }
  }
}

Een kennisbron maken

Maak een kennisbron voor bestanden waarmee het insluitmodel wordt opgegeven dat wordt gebruikt om geüploade inhoud te vectoriseren.

Elke bestandskennisbron maakt een index, maar geen indexeerfunctie of -planning. U moet het fileParameters.ingestionParameters object opnemen. De service weigert verzoeken die networkAccessMode vermelden.

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.");

Naslaginformatie: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.")

Naslaginformatie: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"
    }
  }
}

Naslaginformatie:Kennisbronnen - Maken of bijwerken

Standaardextractie configureren

Vanaf de 2026-08-01-preview API-versie standard maakt extractie gebruik van Content Understanding om geüploade bestanden te extraheren, semantisch te segmenteren en te verrijken. Azure AI Zoeken beheert deze verwerking als onderdeel van de kennisbron en kosten voor Content Understanding zijn afzonderlijk van toepassing.

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}'.");

Naslaginformatie: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}'.")

Naslaginformatie: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}}"
      }
    }
  }
}

Naslaginformatie:Kennisbronnen - Maken of bijwerken

CORS voor bestandsbewerkingen

Als u browsergebaseerde bestandsbewerkingen wilt toestaan, stelt u corsOptions in op de bestandskennisbron met de vertrouwde herkomsten en de maximale duur van de preflight-cache voor uw applicatie.

Important

In de 2026-08-01-preview API-versie corsOptions is dit van toepassing op eindpunten voor het uploaden, weergeven, bijwerken en verwijderen van bestanden, onafhankelijk van de extractiemodus. Als u weglaat corsOptions, heeft de kennisbron van het bestand geen beleid voor meerdere browsers. CORS autoriseert geen aanvragen. Het inschakelen van origins kan servicebewerkingen en -gegevens beschikbaar maken in een browsercontext en beveiligingsrisico's veroorzaken. Specificeer alleen vertrouwde herkomsten en gebruik geen wildcard-herkomst in productie. Gebruik voor browseraanvragen Microsoft Entra tokenverificatie met de minimaal vereiste rol. Maak nooit toegangstokens of servicesleutels beschikbaar in browsercode.

Bestanden uploaden

Nadat u de kennisbron hebt gemaakt, uploadt u bestanden rechtstreeks naar de bron. Elke upload is een synchrone aanroep: Azure AI Zoeken inhoud extraheert, segmenteert deze, maakt insluitingen indien nodig, indexeert de segmenten en bewaart bestandsmetagegevens voordat de aanroep wordt geretourneerd. U hoeft geen afzonderlijke opnamepijplijn te configureren of uit te voeren.

Zie Problemen met bestandsbewerkingen oplossen voor hulp bij fouten met betrekking tot het uploaden en beheren van bestanden.

Een onbewerkt bestand uploaden

Voor een onbewerkte upload is de lijst fileName afkomstig van de Content-Disposition: attachment; filename="..." koptekst. REST-aanroepen en de .NET SDK stellen deze header rechtstreeks in, terwijl de Python SDK een parameter filename accepteert en de header automatisch bouwt. Als u geen bestandsnaam opgeeft, wijst de service een automatisch gegenereerde fileNamenaam toe.

Bestandsnamen kunnen een relatief pad bevatten, zoals manuals/installation-guide.pdf. De service normaliseert backslashes naar slashes. Het weigert absolute paden, lege padsegmenten, .- of ..-segmenten, segmenten die een dubbele punt bevatten en ongeldige tekens in bestandsnamen met HTTP-status 400.

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}");

Referentie: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}")

Referentie: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>

Referentie:Kennisbronnen - Bestand uploaden

Een bestand uploaden met optionele metagegevens

Gebruik vanaf de 2026-08-01-preview API-versie een aanvraag met meerdere onderdelen om één binair bestand te uploaden met optionele aangepaste metagegevens. De aanvraag bevat precies één content deel en een optioneel JSON-onderdeel metadata .

Als beide namen zijn opgegeven, metadata.fileName heeft deze voorrang op de bestandsnaam van het content onderdeel. Als geen van beide is opgegeven, wijst de service een automatisch gegenereerde bestandsnaam toe.

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}");

Referentie: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}")

Verwijzing: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--

Referentie:Kennisbronnen - Bestand uploaden

Opmerking

Als u een bestand uploadt, wordt een bestaand bestand niet vervangen, zelfs niet als u hetzelfde fileNameopnieuw gebruikt. Elke geslaagde upload maakt een nieuw bestand met een eigen fileId, zodat de lijst met geüploade bestanden meerdere vermeldingen kan bevatten met dezelfde fileName.

Met 2026-05-01-preview vervangt u inhoud door het bestaande bestand te verwijderen en het vervangende bestand te uploaden. Met 2026-08-01-preview, gebruik je de updatebewerking.

Geüploade bestanden weergeven

Bestanden op de kennisbron weergeven om de geüploade bestandsset te controleren.

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}");
}

Referentie: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}")

Verwijzing:SearchIndexClient.list_knowledge_source_files

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

Referentie:Kennisbronnen - Bestanden weergeven

Het antwoord bevat metagegevens voor elk geüpload bestand. Succesvol weergegeven bestanden hebben een errorMessage-waarde van 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
    }
  ]
}

Als een nieuwe upload mislukt, retourneert de aanvraag een fout en wordt er geen bestandmetagegevensrecord gemaakt. De mislukte upload wordt niet weergegeven in latere lijstresultaten en wordt niet gefactureerd.

Als de toegang tot een model mislukt en de Foundry-resource die als host fungeert voor het embeddingmodel privénetwerken gebruikt, controleer dan of de gedeelde privékoppeling foundry_account is goedgekeurd en of de uitzondering voor vertrouwde services is ingeschakeld. Een uitgeschakelde bypass retourneert 403 Public access is disabled. Zie Vereisten voor meer informatie over de installatie.

Bestanden weergeven en filteren

Vanaf de API-versie 2026-08-01-preview gebruikt u prefix om bestanden te filteren op relatief pad of search om bestanden te filteren op voorvoegsel van de bestandsnaam. Instellen pageSize om het aantal resultaten te bepalen.

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})");
}

Referentie: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})")

Verwijzing: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}}

Referentie:Kennisbronnen - Bestanden weergeven

Het antwoord bevat door de service geselecteerde parserings- en extractiemodi, evenals metagegevens van gebruikers voor bestandsbeheer. Gebruikersmetagegevens kunnen niet worden doorzocht of gefilterd.

{
  "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>"
}

Als u alle resultaten wilt ophalen, volgt u @odata.nextLink totdat deze niet meer aanwezig is. Verzend de volledige URL precies zoals geretourneerd, zonder de queryparameters te wijzigen.

Een geüpload bestand bijwerken

Vanaf API-versie 2026-08-01-preview werkt u een bestand bij op basis van de fileId. Voor de aanvraag met meerdere onderdelen is het binaire content deel vereist. Het JSON-onderdeel metagegevens is optioneel, dus er wordt een update met alleen inhoud ondersteund. Een update voor alleen metagegevens wordt niet ondersteund.

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}");

Referentie: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}")

Verwijzing: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--

Naslaginformatie:Kennisbronnen - Bestand bijwerken

Als een update mislukt, blijft de vorige metagegevensrecord behouden. Stel niet dat een update transactioneel geïndexeerde inhoud wijzigt.

Geüploade bestanden verwijderen

Verwijder bestanden uit de kennisbron wanneer u ze niet meer beschikbaar wilt maken voor het ophalen.

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");

Referentie: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")

Verwijzing: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}}

Referentie:Kennisbronnen - Bestand verwijderen

Toewijzen aan een kennisbank

Als u tevreden bent met de kennisbron, voegt u deze toe aan een knowledge base.

Een query uitvoeren op een Knowledge Base

Nadat de knowledge base is geconfigureerd, roept u de actie ophalen of het MCP-eindpunt aan om een query uit te voeren op de kennisbron.

Een kennisbron verwijderen

Voordat u een kennisbron kunt verwijderen, moet u een knowledge base verwijderen die ernaar verwijst of de knowledge base-definitie bijwerken om de verwijzing te verwijderen. Voor kennisbronnen die een index- en indexeerpijplijn genereren, worden ook alle gegenereerde objecten verwijderd. Als u echter een bestaande index hebt gebruikt om een kennisbron te maken, wordt uw index niet verwijderd.

Als u probeert een kennisbron te verwijderen die in gebruik is, mislukt de actie en wordt een lijst met betrokken knowledge bases geretourneerd.

Een kennisbron verwijderen:

  1. Haal een lijst op met alle knowledge bases op uw zoekservice.

    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}");
    }
    

    Naslaginformatie:SearchIndexClient

    Een voorbeeld van een antwoord kan er als volgt uitzien:

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. Haal een afzonderlijke Knowledge Base-definitie op om te controleren op verwijzingen naar kennisbronnen.

    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);
    

    Naslaginformatie:SearchIndexClient

    Een voorbeeld van een antwoord kan er als volgt uitzien:

     {
       "Name": "earth-knowledge-base",
       "KnowledgeSources": [
         {
           "Name": "earth-knowledge-source"
         }
       ],
       "Models": [
         {}
       ],
       "RetrievalReasoningEffort": {},
       "OutputMode": {},
       "ETag": "\u00220x8DE278629D782B3\u0022",
       "EncryptionKey": null,
       "Description": null,
       "RetrievalInstructions": null,
       "AnswerInstructions": null
     }
    
  3. Verwijder de knowledge base of werk de knowledge base bij als u meerdere kennisbronnen hebt om de bron te verwijderen. In dit voorbeeld ziet u de verwijdering.

    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.");
    

    Naslaginformatie:SearchIndexClient

  4. Verwijder de kennisbron.

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

    Naslaginformatie:SearchIndexClient

  1. Haal een lijst op met alle knowledge bases op uw zoekservice.

    # 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}")
    

    Naslaginformatie:SearchIndexClient

    Een voorbeeld van een antwoord kan er als volgt uitzien:

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. Haal een afzonderlijke Knowledge Base-definitie op om te controleren op verwijzingen naar kennisbronnen.

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

    Naslaginformatie:SearchIndexClient

    Een voorbeeld van een antwoord kan er als volgt uitzien:

     {
       "name": "my-kb",
       "description": null,
       "retrievalInstructions": null,
       "answerInstructions": null,
       "outputMode": null,
       "knowledgeSources": [
         {
           "name": "my-blob-ks"
         }
       ],
       "models": [],
       "encryptionKey": null,
       "retrievalReasoningEffort": {
         "kind": "low"
       }
     }
    
  3. Verwijder de knowledge base of werk de knowledge base bij als u meerdere kennisbronnen hebt om de bron te verwijderen. In dit voorbeeld ziet u de verwijdering.

    # 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.")
    

    Naslaginformatie:SearchIndexClient

  4. Verwijder de kennisbron.

    # 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.")
    

    Naslaginformatie:SearchIndexClient

  1. Haal een lijst op met alle knowledge bases op uw zoekservice.

    ### Get knowledge bases
    GET {{search-url}}/knowledgebases?api-version={{api-version}}&$select=name
    Authorization: Bearer {{token}}
    

    Naslaginformatie:Knowledge Bases - Lijst

    Een voorbeeld van een antwoord kan er als volgt uitzien:

     {
         "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
         "value": [
         {
             "name": "my-kb"
         },
         {
             "name": "my-kb-2"
         }
         ]
     }
    
  2. Haal een afzonderlijke Knowledge Base-definitie op om te controleren op verwijzingen naar kennisbronnen.

    ### Get a knowledge base definition
    GET {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
    Authorization: Bearer {{token}}
    

    Naslaginformatie:Kennisbanken - Verkrijgen

    Een voorbeeld van een antwoord kan er als volgt uitzien:

     {
       "name": "my-kb",
       "description": null,
       "retrievalInstructions": null,
       "answerInstructions": null,
       "outputMode": null,
       "knowledgeSources": [
         {
           "name": "my-blob-ks"
         }
       ],
       "models": [],
       "encryptionKey": null,
       "retrievalReasoningEffort": {
         "kind": "low"
       }
     }
    
  3. Verwijder de knowledge base of werk de knowledge base bij als u meerdere kennisbronnen hebt om de bron te verwijderen. In dit voorbeeld ziet u de verwijdering.

    ### Delete a knowledge base
    DELETE {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
    Authorization: Bearer {{token}}
    

    Naslaginformatie:Knowledge Bases - Verwijderen

  4. Verwijder de kennisbron.

    ### Delete a knowledge source
    DELETE {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}}
    Authorization: Bearer {{token}}
    

    Naslaginformatie:Kennisbronnen - Verwijderen

Problemen met bestandsbewerkingen oplossen

De volgende statuscodes zijn specifiek voor bewerkingen van de kennisbron van bestanden.

Statuscode Oorzaak en actie
400 Het bestand is leeg, bevat geen extraheerbare tekst, heeft een onveilig relatief pad of heeft een ongeldig verzoek om voortzetting. Controleer of het bestand ondersteunde, leesbare inhoud en een geldige bestandsnaam heeft. Volg bij lijstbewerkingen @odata.nextLink precies zoals geretourneerd. Combineer niet $skiptoken met search of pageSize.
409 De bestandskennisbron heeft de bestandslimiet voor de API-versie bereikt. Verwijder bestanden voordat u meer uploadt.
415 De service heeft een niet-ondersteund MIME-type gedetecteerd of heeft een afbeelding gedetecteerd terwijl de kennisbron minimale extractie gebruikt. Gebruik een ondersteunde indeling. Gebruik voor afbeeldingen standaardextractie. Als alleen het door de aanroeper opgegeven inhoudstype wordt gewijzigd, wordt detectie niet overschreven.
429 De verwerkingswachtrij is vol. Gebruik begrensde paralleliteit en probeer opnieuw met exponentiële back-off. De service garandeert geen Retry-After-header.
504 De verwerking duurde langer dan 180 seconden tijdens het uploaden of bijwerken van een bestand. Verminder de bestandsgrootte of complexiteit en probeer het opnieuw.