Notitie
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen u aan te melden of de directory te wijzigen.
Voor toegang tot deze pagina is autorisatie vereist. U kunt proberen de mappen te wijzigen.
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=standardinstelling 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 Foundry-resource openbare netwerktoegang heeft uitgeschakeld, maakt u een
Als de kennisbron de
standardmodus 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 --prereleaseVoor sleutelloze verificatie is het
Azure.Identitypakket:dotnet add package Azure.Identity
Het nieuwste preview-pakket
azure-search-documents:pip install --pre azure-search-documentsVoor sleutelloze verificatie is het
azure-identitypakket:pip install azure-identity
De preview-versie 2026-08-01 van de REST API van de Search Service.
Neem voor sleutelloze verificatie een Microsoft Entra ID token op in de
Authorizationheader van elke HTTP-aanvraag.
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:
- Word (
.doc,.docx) - PowerPoint (
.ppt,.pptx) - Excel (
.xls,.xlsx) - JSON
- Shell-scripts
- Inhoud gedetecteerd als
text/*, zoals.txt,.md,.htmlen.csv
Ondersteunde extractiemodi
Voor de vermelde inhoudstypen ondersteunen zowel
2026-05-01-previewals2026-08-01-previewminimal.standardis alleen beschikbaar in2026-08-01-preview.Inhoud gedetecteerd zoals
image/*wordt niet ondersteund in2026-05-01-preview. Gebruik instandard2026-08-01-preview-extractie.minimalextractie retourneert HTTP-status415in 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}");
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}")
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}");
}
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}")
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})");
}
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})")
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}");
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}")
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");
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")
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:
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" } ] }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 }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
Verwijder de kennisbron.
await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName); System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");Naslaginformatie:SearchIndexClient
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" } ] }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" } }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
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
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" } ] }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" } }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
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. |