Poznámka:
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
Note
Azure AI Vyhledávač je k dispozici prostřednictvím portálu Azure, rozhraní REST API a Sady Azure SDK. Podporuje také Foundry IQ, spravovanou znalostní vrstvu, která transformuje podnikový obsah na opakovaně použitelné znalostní báze s podporou oprávnění pro agenty na portálu Microsoft Foundry.
Important
Na funkce, možnosti nebo vlastnosti označené jako (Preview) se nevztahuje smlouva o úrovni služeb, nejsou doporučené pro produkční úlohy a mohou se změnit nebo být omezeny dříve, než budou obecně k dispozici. Podmínky Azure AI Vyhledávač Preview platí pro všechny funkce ve verzi Preview, ať už jsou samostatné nebo součástí obecně dostupné funkce.
Znalostní zdroj souborů (Preview) nahrává malé až středně velké sady souborů přímo do Azure AI Vyhledávač pro agentní vyhledávání. Zdroje znalostí se vytvářejí nezávisle, odkazují na znalostní bázi a používají se jako podkladová data při dotazování znalostní báze za běhu.
Zdroje znalostí souborů jsou užitečné, když chcete mít spravované prostředí pro nahrávání místo zřizování Azure Storage, konfiguraci přístupu a vytvoření kanálu indexeru přes externí kontejner. Azure AI Vyhledávač zpracovává nahrané soubory, aby se jejich extrahovaný obsah mohl načíst ze znalostní báze.
Místo toho použijte znalostní zdroj blobu, pokud jsou vaše soubory už v Azure Blob Storage nebo Azure Data Lake Storage Gen2, pokud vaše sada souborů překračuje nebo pravděpodobně překročí limity znalostního zdroje pro soubory, nebo pokud potřebujete plánovaný příjem dat. Pokud chcete spravovat zdrojové objekty blob pomocí zásad správy životního cyklu Azure Blob Storage nebo potřebujete oprávnění na úrovni dokumentu (Preview) na základě oprávnění v Azure Storage, použijte také zdroj znalostí objektů blob.
Podpora využití
| Azure Portal | Portál Microsoft Foundry | .NET SDK | Python SDK | Java SDK | JavaScript SDK | REST API |
|---|---|---|---|---|---|---|
| ❌ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
Předpoklady
Služba Azure AI Vyhledávač v jakékoli oblasti, která poskytuje agentní vyhledávání. Zdroje znalostí souborů podporují cenové modely Dedicated i Bezserverové. Podrobnosti o modelu a vrstvě najdete v tématu Volba cenového modelu a úrovně služby.
Zkontrolujte náklady na Azure AI Vyhledávač. Za volání modelů, vektorizaci a další zpracování pomocí AI mohou být účtovány samostatné poplatky.
V režimu Serverless úspěšné operace ingestace souborů spotřebovávají zpoplatněný výpočetní výkon. Za nezdařená nahrání se neúčtují poplatky za bezserverové výpočetní prostředky.
Pokud potřebujete placené agentní načítání nad rámec měsíčního bezplatného limitu, aktivujte standardní tarif agentního načítání. Nastavení
knowledgeRetrieval=standardje oddělené od poplatků za výpočetní prostředky bez serveru a úložiště a nevybíreje cenový model.Soubory v podporovaném formátu
Oprávnění k vytváření zdrojů znalostí Nakonfigurujte ověřování bez klíčů s rolí Přispěvatel vyhledávací služby přiřazenou k vašemu uživatelskému účtu (doporučeno) nebo použijte klíč rozhraní API pro správu.
Pokud zdroj znalostí specifikuje model Azure OpenAI pro embeddingy, vyhledávací služba musí mít managed identity s oprávněními Cognitive Services User pro prostředek Microsoft Foundry.
- Pokud má prostředek Foundry zakázaný veřejný přístup k síti, vytvořte
foundry_accountsdílené privátní propojení ze služby Search k prostředku Foundry a ponechte u prostředku povolené nastavení Povolit služby Azure v seznamu důvěryhodných služeb.
- Pokud má prostředek Foundry zakázaný veřejný přístup k síti, vytvořte
Pokud zdroj znalostí určuje
standardrežim extrakce obsahu, zkontrolujte požadavky na dovednosti Azure Porozumění obsahu.Použití se účtuje podle cen Azure Content Understanding v nástrojích Foundry u prostředku Foundry nakonfigurovaného prostřednictvím
aiServices.Bezplatný denní limit 20 dokumentů, který je k dispozici u některých předdefinovaných funkcí, se nevztahuje.
Pro příklad v tomto článku potřebujete koncový bod a klíč prostředku Foundry a také informace o modelech Azure OpenAI pro vektorizaci a dokončování chatu.
Nejnovější balíček
Azure.Search.Documentsve verzi Preview:dotnet add package Azure.Search.Documents --prereleaseBalíček
Azure.Identitypro bezklíčové ověřování:dotnet add package Azure.Identity
Nejnovější balíček
azure-search-documentsve verzi Preview:pip install --pre azure-search-documentsBalíček
azure-identitypro bezklíčové ověřování:pip install azure-identity
Verze 2026-08-01-preview rozhraní REST API vyhledávací služby.
Pro bezklíčové ověřování uveďte v
Authorizationhlavičce každého požadavku HTTP token Microsoft Entra ID.
Podpora a omezení souborů
Před vytvořením zdroje znalostí si projděte požadavky a omezení, které mají vliv na nahrávání, extrahování a správu souborů.
Podporované typy obsahu
Zdroje znalostí souborů přijímají soubory na základě zjištěného typu obsahu. Typ obsahu poskytnutý volajícím nepřepíše detekci.
Mezi podporované typy obsahu patří:
- soubor PDF
- Word (
.doc,.docx) - PowerPoint (
.ppt,.pptx) - Excel (
.xls,.xlsx) - JSON
- Shellové skripty
- Obsah byl rozpoznán jako
text/*, například.txt,.html,.mda.csv
Podporované režimy extrakce
U uvedených typů obsahu podporují jak
2026-05-01-preview, tak2026-08-01-previewminimal.standardje k dispozici pouze v2026-08-01-preview.Obsah rozpoznaný jako
image/*není v2026-05-01-previewpodporován. V2026-08-01-previewpoužijte extrakcistandard.minimalextrakce vrátí stav415HTTP v obou verzích.
Omezení a operace se soubory
Omezení a podporované operace se soubory liší podle verze rozhraní API.
| Schopnost | 2026-05-01-preview |
2026-08-01-preview |
|---|---|---|
| Maximální počet souborů na zdroj znalostí | 100 | 200 |
| Maximální velikost souboru | 50 MB na všech podporovaných cenových úrovních | 50 MB na Free a Basic; 100 MB na jiných podporovaných vyhrazených úrovních a bezserverových úrovních |
| Doba zpracování | Nahrávání může běžet až 180 sekund. | Nahrávání a aktualizace může běžet až 180 sekund. |
| Nahrání obsahu a metadat | Nezpracovaný obsah souboru | Nezpracovaný obsah souboru nebo vícedílný obsah s metadaty |
| Výpis nahraných souborů | Seznam souborů | Filtrování podle cesty nebo názvu souboru a vrácení podrobnějších podrobností o souboru |
| Nahrazení existujícího obsahu souboru | Odstranění a opětovné nahrání | Použití operace aktualizace |
| Přístup k prohlížeči k operacím se soubory | CORS není k dispozici | Konfigurace CORS |
Note
- Vygenerovaný index vyhledávání ukládá nahraný obsah. Celkové limity úložiště podle cenové úrovně najdete v tématu Limity služeb.
- Pokud nakonfigurujete znalostní zdroj souborů tak, aby rozděloval nahraný obsah na bloky nebo ho vektorizoval, platí také omezení modelu a následného zpracování.
Kontrola existujících zdrojů znalostí
Zdroj znalostí je objekt nejvyšší úrovně, který lze opakovaně použít. Znalost existujících zdrojů znalostí je užitečná pro opakované použití nebo pojmenování nových objektů.
Spuštěním následujícího kódu zobrazíte seznam zdrojů znalostí podle názvu a typu.
// List knowledge sources by name and type
using Azure.Search.Documents.Indexes;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var knowledgeSources = indexClient.GetKnowledgeSourcesAsync();
Console.WriteLine("Knowledge Sources:");
await foreach (var ks in knowledgeSources)
{
Console.WriteLine($" Name: {ks.Name}, Type: {ks.GetType().Name}");
}
Reference:SearchIndexClient
# List knowledge sources by name and type
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
for ks in index_client.list_knowledge_sources():
print(f" - {ks.name} ({ks.kind})")
Reference:SearchIndexClient
### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version={{api-version}}&$select=name,kind
Authorization: Bearer {{token}}
Referenční informace:Zdroje znalostí – seznam
Pokud chcete zkontrolovat jeho definici JSON, můžete také vrátit jeden zdroj znalostí podle názvu.
using Azure.Search.Documents.Indexes;
using System.Text.Json;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
// Specify the knowledge source name to retrieve
string ksNameToGet = "earth-knowledge-source";
// Get its definition
var knowledgeSourceResponse = await indexClient.GetKnowledgeSourceAsync(ksNameToGet);
var ks = knowledgeSourceResponse.Value;
// Serialize to JSON for display
var jsonOptions = new JsonSerializerOptions
{
WriteIndented = true,
DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.Never
};
Console.WriteLine(JsonSerializer.Serialize(ks, ks.GetType(), jsonOptions));
Reference:SearchIndexClient
# Get a knowledge source definition
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
import json
index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
ks = index_client.get_knowledge_source("knowledge_source_name")
print(json.dumps(ks.as_dict(), indent = 2))
Reference:SearchIndexClient
### Get a knowledge source definition
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}}
Authorization: Bearer {{token}}
Referenční informace:Zdroje znalostí – Získání
Následující JSON je ukázková odpověď pro zdroj znalostí souboru.
{
"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"
}
}
}
}
}
Vytvoření zdroje znalostí
Vytvořte zdroj znalostí souboru, který určuje vložený model použitý k vektorizaci nahraného obsahu.
Každý zdroj znalostí souboru vytvoří index, ale ne indexer nebo plán. Musíte zahrnout objekt fileParameters.ingestionParameters. Služba odmítne požadavky, které určují 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.");
Reference:SearchIndexClient
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
AzureOpenAIVectorizerParameters,
FileKnowledgeSource,
FileKnowledgeSourceParameters,
)
from azure.search.documents.knowledgebases.models import (
KnowledgeSourceAzureOpenAIVectorizer,
KnowledgeSourceIngestionParameters,
)
index_client = SearchIndexClient(endpoint="<search-endpoint>", credential=DefaultAzureCredential())
embedding_params = AzureOpenAIVectorizerParameters(
resource_url="<aoai-endpoint>",
deployment_name="<aoai-embedding-deployment>",
model_name="<aoai-embedding-model>",
)
ingestion_params = KnowledgeSourceIngestionParameters(
content_extraction_mode="minimal",
embedding_model=KnowledgeSourceAzureOpenAIVectorizer(
azure_open_ai_parameters=embedding_params
),
)
knowledge_source = FileKnowledgeSource(
name="my-file-ks",
description="This knowledge source uses directly uploaded product manuals.",
file_parameters=FileKnowledgeSourceParameters(ingestion_parameters=ingestion_params),
)
index_client.create_or_update_knowledge_source(knowledge_source=knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")
Reference:SearchIndexClient
PUT {{search-endpoint}}/knowledgesources/my-file-ks?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json
Prefer: return=representation
{
"name": "my-file-ks",
"kind": "file",
"description": "This knowledge source uses directly uploaded product manuals.",
"encryptionKey": null,
"fileParameters": {
"ingestionParameters": {
"embeddingModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "{{aoai-endpoint}}",
"deploymentId": "{{aoai-embedding-deployment}}",
"modelName": "{{aoai-embedding-model}}"
}
},
"contentExtractionMode": "minimal"
}
}
}
Referenční informace:Zdroje znalostí – Vytvoření nebo aktualizace
Konfigurace standardní extrakce
Počínaje verzí rozhraní API 2026-08-01-preview používá extrakce standard službu Content Understanding k extrahování, sémantickému rozdělování na části a obohacování nahraných souborů. Azure AI Vyhledávač toto zpracování spravuje jako součást zdroje znalostí a poplatky za službu Content Understanding platí samostatně.
using Azure.Identity;
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new DefaultAzureCredential());
var embeddingParameters = new AzureOpenAIVectorizerParameters
{
ResourceUri = new Uri(aoaiEndpoint),
DeploymentName = aoaiEmbeddingDeployment,
ModelName = aoaiEmbeddingModel
};
var ingestionParameters = new KnowledgeSourceIngestionParameters
{
ContentExtractionMode = KnowledgeSourceContentExtractionMode.Standard,
AiServices = new AIServices(new Uri(foundryEndpoint)) { ApiKey = foundryKey },
EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
{
AzureOpenAIParameters = embeddingParameters
},
ChatCompletionModel = new KnowledgeBaseAzureOpenAIModel(
new AzureOpenAIVectorizerParameters
{
ResourceUri = new Uri(aoaiEndpoint),
DeploymentName = aoaiChatDeployment,
ModelName = aoaiChatModel
})
};
var knowledgeSource = new FileKnowledgeSource(
"my-file-ks",
new FileKnowledgeSourceParameters { IngestionParameters = ingestionParameters });
await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Configured standard extraction for '{knowledgeSource.Name}'.");
Reference:SearchIndexClient
from azure.identity import DefaultAzureCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import (
AzureOpenAIVectorizerParameters,
FileKnowledgeSource,
FileKnowledgeSourceParameters,
KnowledgeBaseAzureOpenAIModel,
)
from azure.search.documents.knowledgebases.models import (
AIServices,
KnowledgeSourceAzureOpenAIVectorizer,
KnowledgeSourceIngestionParameters,
)
index_client = SearchIndexClient(endpoint="<search-endpoint>", credential=DefaultAzureCredential())
embedding_parameters = AzureOpenAIVectorizerParameters(
resource_url="<aoai-endpoint>",
deployment_name="<aoai-embedding-deployment>",
model_name="<aoai-embedding-model>",
)
ingestion_parameters = KnowledgeSourceIngestionParameters(
content_extraction_mode="standard",
ai_services=AIServices(
uri="<foundry-resource-endpoint>",
api_key="<foundry-resource-key>",
),
embedding_model=KnowledgeSourceAzureOpenAIVectorizer(
azure_open_ai_parameters=embedding_parameters
),
chat_completion_model=KnowledgeBaseAzureOpenAIModel(
azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
resource_url="<aoai-endpoint>",
deployment_name="<aoai-gpt-deployment>",
model_name="<aoai-gpt-model>",
)
),
)
knowledge_source = FileKnowledgeSource(
name="my-file-ks",
file_parameters=FileKnowledgeSourceParameters(
ingestion_parameters=ingestion_parameters
),
)
index_client.create_or_update_knowledge_source(knowledge_source)
print(f"Configured standard extraction for '{knowledge_source.name}'.")
Reference:SearchIndexClient
PUT {{search-endpoint}}/knowledgesources/my-file-ks?api-version=2026-08-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}
Prefer: return=representation
{
"name": "my-file-ks",
"kind": "file",
"description": "This knowledge source uses standard extraction.",
"fileParameters": {
"ingestionParameters": {
"embeddingModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "{{aoai-endpoint}}",
"deploymentId": "{{aoai-embedding-deployment}}",
"modelName": "{{aoai-embedding-model}}"
}
},
"chatCompletionModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "{{aoai-endpoint}}",
"deploymentId": "{{aoai-gpt-deployment}}",
"modelName": "{{aoai-gpt-model}}"
}
},
"contentExtractionMode": "standard",
"aiServices": {
"uri": "{{foundry-resource-endpoint}}",
"apiKey": "{{foundry-resource-key}}"
}
}
}
}
Referenční informace:Zdroje znalostí – Vytvoření nebo aktualizace
CORS pro operace se soubory
Pokud chcete povolit operace se soubory založenými na prohlížeči, nastavte corsOptions na zdroj znalostí souboru s důvěryhodnými zdroji a maximální dobu trvání předběžné mezipaměti pro vaši aplikaci.
Important
Ve verzi rozhraní API 2026-08-01-preview se corsOptions vztahuje na koncové body pro nahrávání souborů, výpis, aktualizaci a odstranění nezávisle na režimu extrakce. Pokud vynecháte corsOptions, znalostní zdroj souboru nemá žádnou zásadu prohlížeče pro různé zdroje původu. CORS neautorizuje žádosti. Povolení původu může zpřístupnit operace služeb a data v kontextu prohlížeče a zavést bezpečnostní rizika. Zadejte pouze důvěryhodné zdroje a v produkci nepoužívejte zdroj se zástupným znakem. Pro požadavky z prohlížeče použijte ověřování pomocí tokenu Microsoft Entra s minimální požadovanou rolí. V kódu prohlížeče nikdy nezpřístupňujte přístupové tokeny ani klíče služby.
Odeslat soubory
Po vytvoření zdroje znalostí nahrajte soubory přímo do něj. Každé nahrání je synchronní volání: Azure AI Vyhledávač extrahuje obsah, rozdělí jej na části, v případě potřeby vytvoří embeddingy, zaindexuje tyto části a uloží metadata souboru před dokončením volání. Nemusíte konfigurovat ani spouštět samostatný kanál příjmu dat.
Nápovědu k chybám souvisejícím s nahráváním a správou souborů najdete v tématu Řešení potíží s operacemi se soubory.
Nahrání nezpracovaného souboru
U nezpracovaného nahrání pochází uvedené Content-Disposition: attachment; filename="..." z hlavičky fileName. Volání REST a sada .NET SDK tuto hlavičku nastavují přímo, zatímco sada Python SDK přijímá parametr filename a automaticky sestaví hlavičku. Pokud nezadáte název souboru, služba přiřadí automaticky vygenerovaný fileNamesoubor .
Názvy souborů mohou obsahovat relativní cestu, například manuals/installation-guide.pdf. Služba převádí zpětná lomítka na běžná lomítka. Odmítá absolutní cesty, prázdné segmenty cesty, segmenty .. nebo ., segmenty obsahující dvojtečku a neplatné znaky v názvu souboru se stavem HTTP 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}")
Referenční informace: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>
Reference:Zdroje znalostí – Nahrání souboru
Nahrání souboru s volitelnými metadaty
Počínaje verzí rozhraní API 2026-08-01-preview použijte k nahrání jednoho binárního souboru s volitelnými vlastními metadaty vícedílný požadavek. Požadavek zahrnuje přesně jednu content část a volitelnou část JSON metadata .
Pokud jsou zadány oba názvy, metadata.fileName má přednost před názvem souboru v content části. Pokud není zadána žádná, služba přiřadí automaticky vygenerovaný název souboru.
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}");
Referenční informace: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}")
Referenční informace: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--
Reference:Zdroje znalostí – Nahrání souboru
Note
Nahrání souboru nenahrazuje existující soubor, i když stejný soubor znovu použijete fileName. Každé úspěšné nahrání vytvoří nový soubor s vlastním fileIdsouborem , takže seznam nahraných souborů může obsahovat více položek, které sdílejí fileName.
Pomocí 2026-05-01-preview nahraďte obsah odstraněním předchozího souboru a nahráním náhradního souboru. S 2026-08-01-preview použijte operaci aktualizace.
Výpis nahraných souborů
Vytvořte seznam souborů ve zdroji znalostí a zkontrolujte sadu nahraných souborů.
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}")
Referenční informace:SearchIndexClient.list_knowledge_source_files
GET {{search-endpoint}}/knowledgesources/my-file-ks/files?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}
Reference:Zdroje znalostí – Výpis souborů
Odpověď obsahuje metadata pro každý nahraný soubor. Úspěšně vypsané soubory mají u errorMessage hodnotu 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
}
]
}
Pokud se nové nahrání nezdaří, požadavek vrátí chybu a nevytvoří záznam metadat souboru. Neúspěšné nahrání se nezobrazuje v pozdějších výsledcích seznamu a neúčtuje se.
Pokud dojde k selhání přístupu k modelu a prostředek Foundry, který hostuje model pro vkládání, používá privátní síť, ověřte, že je sdílené privátní propojení foundry_account schválené a že je povoleno obcházení důvěryhodných služeb. Zakázaný bypass vrátí 403 Public access is disabled. Podrobnosti o nastavení najdete v tématu Požadavky.
Výpis a filtrování souborů
Od verze rozhraní API 2026-08-01-preview použijte prefix k filtrování souborů podle relativní cesty nebo search k filtrování souborů podle předpony názvu souboru. Nastavte pageSize, chcete-li určit počet výsledků.
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})")
Referenční informace: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}}
Reference:Zdroje znalostí – Výpis souborů
Odpověď zahrnuje režimy analýzy a extrakce vybrané službou a také metadata uživatelů pro správu souborů. Metadata uživatelů se nedají prohledávat ani filtrovat.
{
"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>"
}
Chcete-li načíst všechny výsledky, pokračujte podle @odata.nextLink, dokud se nepřestane zobrazovat. Odešle úplnou adresu URL přesně tak, jak je vrácena, aniž byste měnili parametry dotazu.
Aktualizace nahraného souboru
Počínaje verzí rozhraní API 2026-08-01-preview aktualizujte soubor pomocí jeho fileId. Vícedílný požadavek vyžaduje binární content část. Část JSON metadat je volitelná, takže se podporuje pouze aktualizace obsahu. Aktualizace jen pro metadata není podporovaná.
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}");
Referenční informace: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}")
Referenční informace: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--
Reference:Zdroje znalostí – Aktualizace souboru
Pokud se aktualizace nezdaří, zůstane předchozí záznam metadat. Nepředpokládejte, že aktualizace mění indexovaný obsah transakčně.
Odstranění nahraných souborů
Soubory ze zdroje znalostí odstraňte, pokud už je nechcete mít k dispozici pro načtení.
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");
Referenční informace: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")
Referenční informace: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}}
Reference:Zdroje znalostí – Odstranění souboru
Přiřazení ke znalostní bázi
Pokud jste s zdrojem znalostí spokojení, přidejte ho do znalostní báze.
Dotazování znalostní báze
Po nakonfigurování znalostní báze zavolejte akci načtení nebo koncový bod MCP a dotazujte se na zdroj znalostí.
Odstranění zdroje znalostí
Než budete moct odstranit zdroj znalostí, musíte odstranit jakoukoli znalostní bázi, která na ni odkazuje, nebo aktualizovat definici znalostní báze, aby se odkaz odebral. Pro zdroje znalostí, které generují index a potrubí indexeru, se odstraní také všechny vygenerované objekty. Pokud jste ale k vytvoření zdroje znalostí použili existující index, index se neodstraní.
Pokud se pokusíte odstranit zdroj znalostí, který se používá, akce selže a vrátí seznam ovlivněných znalostních bází.
Odstranění zdroje znalostí:
Získejte seznam všech znalostních bází ve vyhledávací službě.
using Azure.Search.Documents.Indexes; var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential); var knowledgeBases = indexClient.GetKnowledgeBasesAsync(); Console.WriteLine("Knowledge Bases:"); await foreach (var kb in knowledgeBases) { Console.WriteLine($" - {kb.Name}"); }Reference:SearchIndexClient
Příklad odpovědi může vypadat takto:
{ "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)", "value": [ { "name": "my-kb" }, { "name": "my-kb-2" } ] }Získejte individuální definici znalostní báze a zkontrolujte odkazy na zdroje znalostí.
using Azure.Search.Documents.Indexes; using System.Text.Json; var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential); // Specify the knowledge base name to retrieve string kbNameToGet = "earth-knowledge-base"; // Get a specific knowledge base definition var knowledgeBaseResponse = await indexClient.GetKnowledgeBaseAsync(kbNameToGet); var kb = knowledgeBaseResponse.Value; // Serialize to JSON for display string json = JsonSerializer.Serialize(kb, new JsonSerializerOptions { WriteIndented = true }); Console.WriteLine(json);Reference:SearchIndexClient
Příklad odpovědi může vypadat takto:
{ "Name": "earth-knowledge-base", "KnowledgeSources": [ { "Name": "earth-knowledge-source" } ], "Models": [ {} ], "RetrievalReasoningEffort": {}, "OutputMode": {}, "ETag": "\u00220x8DE278629D782B3\u0022", "EncryptionKey": null, "Description": null, "RetrievalInstructions": null, "AnswerInstructions": null }Odstraňte znalostní bázi nebo pokud máte více zdrojů znalostí, aktualizujte znalostní bázi tak, aby zdroj odebral. Tento příklad ukazuje odstranění.
using Azure.Search.Documents.Indexes; var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential); await indexClient.DeleteKnowledgeBaseAsync(knowledgeBaseName); System.Console.WriteLine($"Knowledge base '{knowledgeBaseName}' deleted successfully.");Reference:SearchIndexClient
Odstraňte zdroj znalostí.
await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName); System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");Reference:SearchIndexClient
Získejte seznam všech znalostních bází ve vyhledávací službě.
# Get knowledge bases from azure.core.credentials import AzureKeyCredential from azure.search.documents.indexes import SearchIndexClient index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key")) print("Knowledge Bases:") for kb in index_client.list_knowledge_bases(): print(f" - {kb.name}")Reference:SearchIndexClient
Příklad odpovědi může vypadat takto:
{ "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)", "value": [ { "name": "my-kb" }, { "name": "my-kb-2" } ] }Získejte individuální definici znalostní báze a zkontrolujte odkazy na zdroje znalostí.
# Get a knowledge base definition from azure.core.credentials import AzureKeyCredential from azure.search.documents.indexes import SearchIndexClient index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key")) kb = index_client.get_knowledge_base("knowledge_base_name") print(kb)Reference:SearchIndexClient
Příklad odpovědi může vypadat takto:
{ "name": "my-kb", "description": null, "retrievalInstructions": null, "answerInstructions": null, "outputMode": null, "knowledgeSources": [ { "name": "my-blob-ks" } ], "models": [], "encryptionKey": null, "retrievalReasoningEffort": { "kind": "low" } }Odstraňte znalostní bázi nebo pokud máte více zdrojů znalostí, aktualizujte znalostní bázi tak, aby zdroj odebral. Tento příklad ukazuje odstranění.
# Delete a knowledge base from azure.core.credentials import AzureKeyCredential from azure.search.documents.indexes import SearchIndexClient index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key")) index_client.delete_knowledge_base("knowledge_base_name") print(f"Knowledge base deleted successfully.")Reference:SearchIndexClient
Odstraňte zdroj znalostí.
# Delete a knowledge source from azure.core.credentials import AzureKeyCredential from azure.search.documents.indexes import SearchIndexClient index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key")) index_client.delete_knowledge_source("knowledge_source_name") print(f"Knowledge source deleted successfully.")Reference:SearchIndexClient
Získejte seznam všech znalostních bází ve vyhledávací službě.
### Get knowledge bases GET {{search-url}}/knowledgebases?api-version={{api-version}}&$select=name Authorization: Bearer {{token}}Referenční informace:Znalostní báze – seznam
Příklad odpovědi může vypadat takto:
{ "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)", "value": [ { "name": "my-kb" }, { "name": "my-kb-2" } ] }Získejte individuální definici znalostní báze a zkontrolujte odkazy na zdroje znalostí.
### Get a knowledge base definition GET {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}} Authorization: Bearer {{token}}Referenční informace:Znalostní báze – Získat
Příklad odpovědi může vypadat takto:
{ "name": "my-kb", "description": null, "retrievalInstructions": null, "answerInstructions": null, "outputMode": null, "knowledgeSources": [ { "name": "my-blob-ks" } ], "models": [], "encryptionKey": null, "retrievalReasoningEffort": { "kind": "low" } }Odstraňte znalostní bázi nebo pokud máte více zdrojů znalostí, aktualizujte znalostní bázi tak, aby zdroj odebral. Tento příklad ukazuje odstranění.
### Delete a knowledge base DELETE {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}} Authorization: Bearer {{token}}Referenční informace:Znalostní báze – Odstranění
Odstraňte zdroj znalostí.
### Delete a knowledge source DELETE {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}} Authorization: Bearer {{token}}Referenční informace:Zdroje znalostí – Odstranění
Řešení problémů s operacemi se soubory
Následující stavové kódy jsou specifické pro operace se zdrojem znalostí souborů.
| Stavový kód | Příčina a akce |
|---|---|
400 |
Soubor je prázdný, neobsahuje extrahovatelný text, má nebezpečnou relativní cestu nebo má neplatný požadavek na pokračování. Ověřte, že soubor obsahuje podporovaný a čitelný obsah a má platný název. Při operacích se seznamem postupujte podle @odata.nextLink přesně tak, jak bylo vráceno. Nekombinujte $skiptoken s search ani pageSize. |
409 |
Zdroj znalostí souboru dosáhl limitu pro verzi rozhraní API. Před nahráním dalších souborů odstraňte soubory. |
415 |
Služba zjistila nepodporovaný typ MIME nebo zjistila obrázek, zatímco zdroj znalostí používá minimální extrakci. Použijte podporovaný formát. Pro obrázky použijte standardní extrakci. Pouhá změna typu obsahu zadaného volajícím nepřepíše výsledek detekce. |
429 |
Fronta zpracování je plná. Použijte omezený paralelismus a opakujte pokusy s exponenciálně prodlužovanými intervaly. Služba nezaručuje hlavičku Retry-After . |
504 |
Zpracování během nahrávání nebo aktualizace souboru překročilo 180 sekund. Zmenšete velikost souboru nebo složitost a zkuste to znovu. |