Skapa en kunskapskälla för filer (förhandsversion)

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 kunskapskällan anger innehållsextraheringsläget standard granskar 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.Documents förhandsversionspaketet: dotnet add package Azure.Search.Documents --prerelease

  • För nyckellös autentisering, paketet Azure.Identity: dotnet add package Azure.Identity

  • Det senaste azure-search-documents förhandsversionspaketet: pip install --pre azure-search-documents

  • För nyckellös autentisering, paketet azure-identity: pip install azure-identity

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:

  • PDF
  • 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-preview och minimal2026-08-01-preview. standard är endast tillgängligt i 2026-08-01-preview.

  • Innehåll som identifieras som image/* stöds inte i 2026-05-01-preview. I 2026-08-01-previewanvänder du standard extrahering. minimal extrahering returnerar HTTP-status 415 i 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"
    }
  }
}

Referens:Kunskapskällor – Skapa eller uppdatera

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

Referens:Kunskapskällor – Skapa eller uppdatera

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

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

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

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

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

Referens:SearchIndexClient.list_knowledge_source_files

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

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

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

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

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

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

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

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

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

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:

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

  4. Ta bort kunskapskällan.

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

    Referens:SearchIndexClient

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

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

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

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