Vytvořit souborový zdroj znalostí (verze Preview)

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=standard je 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 zdroj znalostí určuje standard rež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.Documents ve verzi Preview: dotnet add package Azure.Search.Documents --prerelease

  • Balíček Azure.Identity pro bezklíčové ověřování: dotnet add package Azure.Identity

  • Nejnovější balíček azure-search-documents ve verzi Preview: pip install --pre azure-search-documents

  • Balíček azure-identity pro bezklíčové ověřování: pip install azure-identity

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, .md a .csv

Podporované režimy extrakce

  • U uvedených typů obsahu podporují jak 2026-05-01-preview, tak 2026-08-01-previewminimal. standard je k dispozici pouze v 2026-08-01-preview.

  • Obsah rozpoznaný jako image/* není v 2026-05-01-preview podporován. V 2026-08-01-preview použijte extrakci standard. minimal extrakce vrátí stav 415 HTTP 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}");

Reference:SearchIndexClient.UploadKnowledgeSourceFileAsync

from pathlib import Path

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

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

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

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

Reference:SearchIndexClient.GetKnowledgeSourceFilesAsync

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

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

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

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

Reference:SearchIndexClient.GetKnowledgeSourceFilesAsync

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

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

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

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

  1. 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"
         }
         ]
     }
    
  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
     }
    
  3. 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

  4. Odstraňte zdroj znalostí.

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

    Reference:SearchIndexClient

  1. 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"
         }
         ]
     }
    
  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"
       }
     }
    
  3. 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

  4. 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

  1. 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"
         }
         ]
     }
    
  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"
       }
     }
    
  3. 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í

  4. 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.