Kommentar
Åtkomst till den här sidan kräver auktorisering. Du kan prova att logga in eller ändra kataloger.
Åtkomst till den här sidan kräver auktorisering. Du kan prova att ändra kataloger.
Note
Azure AI-sökning är tillgängligt via Azure-portalen, REST-API:er och Azure-SDK:er. Den ligger också till grund för Foundry IQ, det hanterade kunskapsskiktet som omvandlar företagsinnehåll till återanvändbara, behörighetsmedvetna kunskapsbaser för agenter i Microsoft Foundry-portalen.
Important
Dessa funktioner och denna funktionalitet är en del av REST API-versionen 2026-08-01-preview. Förhandsversionen av 2026-08-01 är licensierad till dig som en del av din Azure-prenumeration och omfattas av de villkor som gäller för "förhandsversioner" i Microsoft Produktvillkor, Microsoft Products and Services Data Protection Addendum ("DPA") och tilläggsvillkoren för användning för Microsoft Azure förhandsversioner.
API:erna för förhandsversion stöder anslutningar till andra Microsoft-tjänster och tjänster från tredje part. Användningen av dessa tjänster omfattas av deras respektive villkor och kan resultera i databearbetning eller lagring utanför Azure efterlevnadsgräns, samt data som flödar till Azure efterlevnadsgräns.
Det är ditt ansvar att hantera om dina data kommer att flöda utanför organisationens efterlevnad och geografiska gränser och eventuella relaterade konsekvenser, och att lämpliga behörigheter, gränser och godkännanden etableras.
Du ansvarar för att noggrant granska och testa program som du skapar i samband med dina specifika användningsfall och fatta alla lämpliga beslut och anpassningar. Detta omfattar implementering av dina egna ansvarsfulla AI-åtgärder, till exempel metaprompter, innehållsfilter eller andra säkerhetssystem, och att se till att dina program uppfyller lämpliga kvalitets-, tillförlitlighets-, säkerhets- och tillförlitlighetsstandarder. Mer information finns i Azure AI-sökning Transparency Note.
En filkunskapskälla (förhandsversion) laddar upp små till medelstora filuppsättningar direkt till Azure AI-sökning för agentisk hämtning. Kunskapskällor skapas oberoende av varandra, refereras i en kunskapsbas och används som grunddata när kunskapsbasen efterfrågas vid körning.
Filkunskapskällor är användbara när du vill ha en hanterad uppladdningsupplevelse i stället för att etablera Azure Storage, konfigurera åtkomst och skapa en indexerarpipeline över en extern container. Azure AI-sökning bearbetar uppladdade filer så att deras extraherade innehåll kan hämtas från en kunskapsbas.
Använd en blob-kunskapskälla i stället när dina filer redan finns i Azure Blob Storage eller Azure Data Lake Storage Gen2, när filuppsättningen överskrider eller sannolikt kommer att överskrida filkunskapskällans gränser eller när du behöver schemalagd inmatning. Använd även en blob-kunskapskälla när du vill hantera källblobar med Azure Blob Storage livscykelhanteringsprinciper eller när du behöver behörigheter på dokumentnivå (förhandsversion) baserat på behörigheter i Azure Storage.
Användningsstöd
| Azure Portal | Microsoft Foundry-portalen | .NET SDK | Python SDK | Java SDK | JavaScript SDK | REST API |
|---|---|---|---|---|---|---|
| ❌ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
Förutsättningar
En Azure AI-sökning-tjänst i valfri region som tillhandahåller agentdriven hämtning. Filkunskapskällor stöder både dedikerade och serverlösa prismodeller. Information om modell och nivå finns i Välja en prismodell och tjänstnivå.
Granska kostnaderna för Azure AI-sökning. Modellanrop, vektorisering och annan AI-bearbetning kan medföra separata avgifter.
I Serverless förbrukar lyckade filinmatningsoperationer debiterbar beräkningskapacitet. Misslyckade uppladdningar medför inte serverlösa beräkningsavgifter.
Om du behöver betald agentisk hämtning utöver den månatliga kostnadsfria ersättningen aktiverar du standardplanen för agentisk hämtning. Inställningen
knowledgeRetrieval=standardär separat från serverlösa beräknings- och lagringsavgifter och väljer ingen prismodell.Filer i ett format som stöds.
Behörighet att skapa kunskapskällor. Konfigurera nyckellös autentisering med rollen Search Service-deltagare tilldelad till ditt användarkonto (rekommenderas) eller använd en administratörs-API-nyckel.
Om kunskapskällan anger en Azure OpenAI-modell för inbäddningar måste söktjänsten ha en hanterad identitet med Cognitive Services User behörigheter för resursen Microsoft Foundry.
- Om Foundry-resursen har inaktiverad åtkomst till offentligt nätverk skapar du en
foundry_accountdelad privat länk från söktjänsten till Foundry-resursen och behåller resursens inställningen Tillåt Azure tjänster i listan över betrodda tjänster aktiverad.
- Om Foundry-resursen har inaktiverad åtkomst till offentligt nätverk skapar du en
Om kunskapskällan anger innehållsextraheringsläget
standardgranskar du kraven för kunskapen Azure Content Understanding.Användning debiteras enligt prissättningen för Azure Content Understanding i Foundry Tools till den Foundry-resurs som konfigurerats via
aiServices.Den dagliga gratiskvoten på 20 dokument för vissa inbyggda funktioner är inte tillämplig.
I exemplet i den här artikeln behöver du slutpunkten och nyckeln för Foundry-resursen, plus Azure OpenAI-inbäddnings- och chattkompletteringsmodellinformation.
Det senaste
Azure.Search.Documentsförhandsversionspaketet:dotnet add package Azure.Search.Documents --prereleaseFör nyckellös autentisering, paketet
Azure.Identity:dotnet add package Azure.Identity
Det senaste
azure-search-documentsförhandsversionspaketet:pip install --pre azure-search-documentsFör nyckellös autentisering, paketet
azure-identity:pip install azure-identity
Versionen 2026-08-01-preview av REST-API:t för söktjänsten.
För nyckellös autentisering inkluderar du en Microsoft Entra ID token i rubriken för
Authorizationvarje HTTP-begäran.
Filstöd och begränsningar
Innan du skapar en filkunskapskälla bör du granska de krav och begränsningar som påverkar filuppladdning, extrahering och hantering.
Innehållstyper som stöds
Filkunskapskällor accepterar filer baserat på identifierad innehållstyp. En innehållstyp som tillhandahålls av anroparen åsidosätter inte identifieringen.
Innehållstyper som stöds är:
- Word (
.doc,.docx) - PowerPoint (
.ppt,.pptx) - Excel (
.xls,.xlsx) - JSON
- Skalskript
- Innehåll som identifierats som
text/*, till exempel.txt,.md,.htmloch.csv
Extraheringslägen som stöds
För de angivna innehållstyperna stöder både
2026-05-01-previewochminimal2026-08-01-preview.standardär endast tillgängligt i2026-08-01-preview.Innehåll som identifieras som
image/*stöds inte i2026-05-01-preview. I2026-08-01-previewanvänder dustandardextrahering.minimalextrahering returnerar HTTP-status415i båda versionerna.
Begränsningar och filoperationer
Begränsningar och filåtgärder som stöds skiljer sig åt beroende på API-version.
| Förmåga | 2026-05-01-preview |
2026-08-01-preview |
|---|---|---|
| Maximalt antal filer per kunskapskälla | 100 | 200 |
| Största filstorlek | 50 MB på alla prisnivåer som stöds | 50 MB på Free och Basic; 100 MB på andra dedikerade nivåer och Serverless som stöds |
| Bearbetningstid | Uppladdningen kan köras i upp till 180 sekunder | Uppladdning och uppdatering kan köras i upp till 180 sekunder |
| Ladda upp innehåll och metadata | Raw-filinnehåll | Råfilinnehåll eller innehåll med flera delar med metadata |
| Lista över uppladdade filer | Lista filer | Filtrera efter sökväg eller filnamn och returnera mer detaljerad filinformation |
| Ersätt befintligt filinnehåll | Ta bort och ladda upp igen | Använd uppdateringsåtgärden |
| Webbläsaråtkomst till filåtgärder | CORS är inte tillgängligt | Konfigurera CORS |
Note
- Det genererade sökindexet lagrar det uppladdade innehållet. Totalt antal lagringsgränser efter prisnivå finns i Tjänstgränser.
- Om du konfigurerar filkunskapskällan för att segmentera eller vektorisera uppladdat innehåll gäller även begränsningar för modell- och nedströmsbearbetning.
Sök efter befintliga kunskapskällor
En kunskapskälla är ett återanvändbart objekt på toppnivå. Att känna till befintliga kunskapskällor är användbart för återanvändning eller namngivning av nya objekt.
Kör följande kod för att lista kunskapskällor efter namn och typ.
// 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}");
}
Referens: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})")
Referens:SearchIndexClient
### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version={{api-version}}&$select=name,kind
Authorization: Bearer {{token}}
Referens:Kunskapskällor – lista
Du kan också returnera en enda kunskapskälla efter namn för att granska dess JSON-definition.
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));
Referens: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))
Referens:SearchIndexClient
### Get a knowledge source definition
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}}
Authorization: Bearer {{token}}
Referens:Kunskapskällor – Hämta
Följande JSON är ett exempelsvar för en filkunskapskälla.
{
"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"
}
}
}
}
}
Skapa en kunskapskälla
Skapa en filkunskapskälla som anger den inbäddningsmodell som används för att vektorisera uppladdat innehåll.
Varje filkunskapskälla skapar ett index, men inte en indexerare eller ett schema. Du måste inkludera objektet fileParameters.ingestionParameters . Tjänsten avvisar begäranden som anger networkAccessMode.
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.");
Referens: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.")
Referens: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"
}
}
}
Konfigurera standardextraktion
Från och med API-version 2026-08-01-preview använder standard extrahering Content Understanding för att extrahera, dela upp i semantiska segment och berika uppladdade filer. Azure AI-sökning hanterar den här bearbetningen som en del av kunskapskällan och avgifterna för Content Understanding tillämpas separat.
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}'.");
Referens: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}'.")
Referens: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}}"
}
}
}
}
CORS för filåtgärder
Om du vill tillåta webbläsarbaserade filåtgärder anger du corsOptions på filkunskapskällan med betrott ursprung och maximal preflight-cachevaraktighet för ditt program.
Important
I API-versionen 2026-08-01-previewcorsOptions gäller för filuppladdning, lista, uppdatering och borttagning av slutpunkter oberoende av extraheringsläget. Om du utelämnar corsOptions har filkunskapskällan ingen policy för korsande ursprung i webbläsaren. CORS auktoriserar inte begäranden. Aktivering av ursprung kan exponera tjänståtgärder och data i en webbläsarkontext och medföra säkerhetsrisker. Ange endast betrodda ursprung, och använd inte ett jokerursprung i produktionsmiljö. För webbläsarbegäranden använder du Microsoft Entra tokenautentisering med den minsta roll som krävs. Exponera aldrig åtkomsttoken eller tjänstnycklar i webbläsarkod.
Överför filer
När du har skapat kunskapskällan laddar du upp filer direkt till den. Varje uppladdning är ett synkront anrop: Azure AI-sökning extraherar innehåll, segmenterar det, skapar inbäddningar vid behov, indexerar segmenten och bevarar filmetadata innan anropet returneras. Du behöver inte konfigurera eller köra en separat inmatningspipeline.
Hjälp med fel som rör uppladdning och hantering av filer finns i Felsöka filåtgärder.
Ladda upp en raw-fil
För en rå uppladdning kommer det listade fileName från headern Content-Disposition: attachment; filename="...". REST-anrop och .NET-SDK:t ställer in det här sidhuvudet direkt, medan Python-SDK:t accepterar en parameter filename och bygger sidhuvudet automatiskt. Om du inte anger något filnamn tilldelar tjänsten en automatiskt genererad fileName.
Filnamn kan innehålla en relativ sökväg, till exempel manuals/installation-guide.pdf. Tjänsten normaliserar bakstreck till snedstreck. Den avvisar absoluta sökvägar, tomma sökvägssegment . eller .. segment, koloninnehållande segment och ogiltiga filnamnstecken med 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>
Referens:Kunskapskällor – Ladda upp fil
Ladda upp en fil med valfria metadata
Börja med 2026-08-01-preview API-versionen och använd en begäran med flera delar för att ladda upp en binär fil med valfria anpassade metadata. Begäran innehåller exakt en content del och en valfri JSON-del metadata .
Om båda namnen anges har metadata.fileName företräde framför filnamnet i delen content. Om inget av dem anges tilldelar tjänsten ett automatiskt genererat filnamn.
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}");
Referens: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}")
Referens: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--
Referens:Kunskapskällor – Ladda upp fil
Note
Att ladda upp en fil ersätter inte en befintlig fil, även om du återanvänder samma fileName. Varje lyckad uppladdning skapar en ny fil med en egen fileId, så listan över uppladdade filer kan innehålla flera poster som delar en fileName.
Med 2026-05-01-previewersätter du innehåll genom att ta bort den tidigare filen och ladda upp ersättningen. Med 2026-08-01-previewanvänder du uppdateringsåtgärden.
Lista över uppladdade filer
Lista filer på kunskapskällan för att granska den uppladdade filuppsättningen.
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}}
Referens:Kunskapskällor – Listfiler
Svaret innehåller metadata för varje uppladdad fil. Filer som har listats har värdet null för errorMessage.
{
"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
}
]
}
Om en ny uppladdning misslyckas returnerar begäran ett fel och skapar ingen filmetadatapost. Den misslyckade uppladdningen visas inte i senare listresultat och faktureras inte.
Om ett modellåtkomstfel inträffar och Foundry-resursen som är värd för inbäddningsmodellen använder privata nätverk kontrollerar du att den foundry_account delade privata länken är godkänd och att förbikopplingen av betrodda tjänster är aktiverad. En inaktiverad förbikoppling returnerar 403 Public access is disabled. Information om konfiguration finns i Krav.
Lista och filtrera filer
Från och med 2026-08-01-preview API-versionen använder du prefix för att filtrera filer efter relativ sökväg eller search för att filtrera efter filnamnsprefix. Ange pageSize för att kontrollera antalet resultat.
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}}
Referens:Kunskapskällor – Listfiler
Svaret innehåller tjänstvalda parsnings- och extraheringslägen samt användarmetadata för filhantering. Användarmetadata kan inte sökas eller filtreras.
{
"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>"
}
Om du vill hämta alla resultat följer du @odata.nextLink tills det saknas. Skicka den fullständiga URL:en exakt som returnerad, utan att ändra frågeparametrarna.
Uppdatera en uppladdad fil
Från och med API-versionen 2026-08-01-preview uppdaterar du en fil med dess fileId. Multipart-begäran kräver den binära content delen. Metadata-JSON-delen är valfri, så en innehållsuppdatering stöds. En uppdatering med endast metadata stöds inte.
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--
Referens:Kunskapskällor – Uppdatera fil
Om en uppdatering misslyckas finns den tidigare metadataposten kvar. Anta inte att en uppdatering ändrar indexerat innehåll transaktionsmässigt.
Ta bort uppladdade filer
Ta bort filer från kunskapskällan när du inte längre vill att de ska vara tillgängliga för hämtning.
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}}
Referens:Kunskapskällor – Ta bort fil
Tilldelas till en kunskapsbas
Om du är nöjd med kunskapskällan lägger du till den i en kunskapsbas.
Sök i en kunskapsbas
När kunskapsbasen har konfigurerats anropar du åtgärden hämta eller MCP-slutpunkten för att fråga kunskapskällan.
Ta bort en kunskapskälla
Innan du kan ta bort en kunskapskälla måste du ta bort alla kunskapsbaser som refererar till den eller uppdatera kunskapsbasdefinitionen för att ta bort referensen. För kunskapskällor som genererar en index- och indexeringspipeline tas även alla genererade objekt bort. Men om du använde ett befintligt index för att skapa en kunskapskälla tas inte ditt index bort.
Om du försöker ta bort en kunskapskälla som används misslyckas åtgärden och returnerar en lista över berörda kunskapsbaser.
Så här tar du bort en kunskapskälla:
Hämta en lista över alla kunskapsbaser i söktjänsten.
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}"); }Referens:SearchIndexClient
Ett exempelsvar kan se ut så här:
{ "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)", "value": [ { "name": "my-kb" }, { "name": "my-kb-2" } ] }Hämta en individuell kunskapsbasdefinition för att söka efter referenser till kunskapskällor.
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);Referens:SearchIndexClient
Ett exempelsvar kan se ut så här:
{ "Name": "earth-knowledge-base", "KnowledgeSources": [ { "Name": "earth-knowledge-source" } ], "Models": [ {} ], "RetrievalReasoningEffort": {}, "OutputMode": {}, "ETag": "\u00220x8DE278629D782B3\u0022", "EncryptionKey": null, "Description": null, "RetrievalInstructions": null, "AnswerInstructions": null }Ta antingen bort kunskapsbasen eller, om du har flera kunskapskällor, uppdatera kunskapsbasen för att ta bort källan. Det här exemplet visar borttagning.
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.");Referens:SearchIndexClient
Ta bort kunskapskällan.
await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName); System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");Referens:SearchIndexClient
Hämta en lista över alla kunskapsbaser i söktjänsten.
# 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}")Referens:SearchIndexClient
Ett exempelsvar kan se ut så här:
{ "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)", "value": [ { "name": "my-kb" }, { "name": "my-kb-2" } ] }Hämta en individuell kunskapsbasdefinition för att söka efter referenser till kunskapskällor.
# 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)Referens:SearchIndexClient
Ett exempelsvar kan se ut så här:
{ "name": "my-kb", "description": null, "retrievalInstructions": null, "answerInstructions": null, "outputMode": null, "knowledgeSources": [ { "name": "my-blob-ks" } ], "models": [], "encryptionKey": null, "retrievalReasoningEffort": { "kind": "low" } }Ta antingen bort kunskapsbasen eller, om du har flera kunskapskällor, uppdatera kunskapsbasen för att ta bort källan. Det här exemplet visar borttagning.
# 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.")Referens:SearchIndexClient
Ta bort kunskapskällan.
# 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.")Referens:SearchIndexClient
Hämta en lista över alla kunskapsbaser i söktjänsten.
### Get knowledge bases GET {{search-url}}/knowledgebases?api-version={{api-version}}&$select=name Authorization: Bearer {{token}}Referens:Kunskapsbaser – lista
Ett exempelsvar kan se ut så här:
{ "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)", "value": [ { "name": "my-kb" }, { "name": "my-kb-2" } ] }Hämta en individuell kunskapsbasdefinition för att söka efter referenser till kunskapskällor.
### Get a knowledge base definition GET {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}} Authorization: Bearer {{token}}Referens:Kunskapsbaser – Hämta
Ett exempelsvar kan se ut så här:
{ "name": "my-kb", "description": null, "retrievalInstructions": null, "answerInstructions": null, "outputMode": null, "knowledgeSources": [ { "name": "my-blob-ks" } ], "models": [], "encryptionKey": null, "retrievalReasoningEffort": { "kind": "low" } }Ta antingen bort kunskapsbasen eller, om du har flera kunskapskällor, uppdatera kunskapsbasen för att ta bort källan. Det här exemplet visar borttagning.
### Delete a knowledge base DELETE {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}} Authorization: Bearer {{token}}Referens:Kunskapsbaser – Ta bort
Ta bort kunskapskällan.
### Delete a knowledge source DELETE {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}} Authorization: Bearer {{token}}Referens:Kunskapskällor – Ta bort
Felsöka filoperationer
Följande statuskoder är specifika för filkunskapskällans åtgärder.
| Statuskod | Orsak och åtgärd |
|---|---|
400 |
Filen är tom, innehåller ingen extraherbar text, har en osäker relativ sökväg eller har en ogiltig fortsättningsbegäran. Kontrollera att filen har stöd för läsbart innehåll och ett giltigt filnamn. För liståtgärder ska du följa @odata.nextLink exakt så som det returnerades. Kombinera $skiptoken inte med search eller pageSize. |
409 |
Filkunskapskällan nådde filgränsen för API-versionen. Ta bort filer innan du laddar upp fler. |
415 |
Tjänsten identifierade en MIME-typ som inte stöds, eller så upptäckte den en avbildning medan kunskapskällan använder minimal extrahering. Använd ett format som stöds. För bilder, använd standardextraktion. Det går inte att åsidosätta identifieringen om du bara ändrar innehållstypen som tillhandahålls av anroparen. |
429 |
Bearbetningskö är full. Använd begränsad parallellitet och försök igen med exponentiell backoff. Tjänsten garanterar inte en Retry-After-header. |
504 |
Bearbetningen överskred 180 sekunder under filuppladdning eller uppdatering. Minska filstorleken eller komplexiteten och försök igen. |