Criar uma base de conhecimento em arquivo (versão prévia)

Note

Pesquisa de IA do Azure  está disponível por meio do portal Azure, APIs REST e SDKs do Azure. Ele também sustenta o IQ do Foundry, a camada de conhecimento gerenciado que transforma o conteúdo da empresa em bases de conhecimento reutilizáveis e com reconhecimento de permissão para agentes no portal do Microsoft Foundry.

Importante

Recursos, funcionalidades ou propriedades marcados como (versão prévia) não são cobertos por um contrato de nível de serviço (SLA), não são recomendados para cargas de trabalho de produção e podem mudar ou ser restringidos antes da disponibilidade geral. Os termos de visualização do Pesquisa de IA do Azure  se aplicam a toda funcionalidade em visualização, seja autônoma ou parte de um recurso de disponibilidade geral.

Uma fonte de conhecimento baseada em arquivos (versão prévia) envia conjuntos de arquivos pequenos a médios diretamente para o Pesquisa de IA do Azure  para recuperação agêntica. As fontes de conhecimento são criadas de forma independente, referenciadas em uma base de dados de conhecimento e usadas como dados de aterramento quando a base de dados de conhecimento é consultada em runtime.

Fontes de conhecimento de arquivo são úteis quando você deseja uma experiência de carregamento gerenciada em vez de provisionar Armazenamento do Azure, configurar o acesso e criar um pipeline de indexador em um contêiner externo. Pesquisa de IA do Azure  processa arquivos carregados para que o conteúdo extraído possa ser recuperado de uma base de dados de conhecimento.

Em vez disso, use uma fonte de conhecimento de Blobs quando os arquivos já estiverem no Armazenamento de Blobs do Azure ou no Azure Data Lake Storage Gen2, quando o conjunto de arquivos exceder ou provavelmente exceder os limites da fonte de conhecimento de arquivos ou quando você precisar de ingestão agendada. Use também uma fonte de conhecimento de blob quando quiser gerenciar os blobs de origem com políticas de gerenciamento do ciclo de vida do Armazenamento de Blobs do Azure ou quando precisar de permissões no nível do documento (versão preliminar) com base nas permissões do Armazenamento do Azure.

Suporte de uso

Portal do Azure Portal Foundry da Microsoft SDK do .NET SDK do Python SDK do Java SDK do JavaScript REST API
❌ ✔️ ✔️ ✔️ ✔️ ✔️ ✔️

Pré-requisitos

  • Um serviço de Pesquisa de IA do Azure em qualquer região que forneça recuperação agêntica. As fontes de conhecimento do arquivo dão suporte aos modelos de preço dedicados e sem servidor. Para obter detalhes do modelo e da camada, consulte Escolher um modelo de preços e uma camada de serviço.

  • Analise os custos do Pesquisa de IA do Azure . Chamadas de modelo, vetorização e outros processamentos de IA podem gerar cobranças separadas.

  • No modo sem servidor, as operações bem-sucedidas de ingestão de arquivos consomem recursos computacionais faturáveis. Uploads com falha não incorrem em encargos de computação sem servidor.

  • Se você precisar de recuperação agêntica paga além da franquia gratuita mensal, habilite o plano padrão de recuperação agêntica. A knowledgeRetrieval=standard configuração é separada dos encargos de computação e armazenamento sem servidor e não seleciona um modelo de preços.

  • Arquivos em um formato com suporte.

  • Permissão para criar fontes de conhecimento. Configure a autenticação sem chave com a função Colaborador do Serviço de Pesquisa atribuída à sua conta de usuário (recomendada) ou use uma chave de API de administrador.

  • Se a fonte de conhecimento especificar um modelo do OpenAI do Azure para incorporações ou verbalização de imagem, o serviço Pesquisa deve ter uma identidade gerenciada com permissões de Usuário dos Serviços Cognitivos no recurso do Microsoft Foundry.

    • Se o recurso Foundry tiver o acesso à rede pública desabilitado, crie um foundry_accountlink privado compartilhado do serviço de pesquisa para o recurso Foundry e mantenha habilitada a configuração Permitir serviços do Azure na lista de serviços confiáveis do recurso.

  • Se a fonte de conhecimento especificar o standard modo de extração de conteúdo, examine os requisitos da habilidade Azure Content Understanding.

    • O uso é cobrado em Compreensão de Conteúdo do Azure com preços do Foundry Tools para o recurso do Foundry configurado usando aiServices.

    • A franquia diária gratuita de 20 documentos disponível para algumas habilidades integradas não se aplica.

    • Para o exemplo deste artigo, você precisa do endpoint e da chave do recurso Foundry, além das informações sobre os modelos de incorporação e de conclusão de chat do Azure OpenAI.

  • O pacote de versão prévia Azure.Search.Documents mais recente: dotnet add package Azure.Search.Documents --prerelease

  • Para autenticação sem chave, o Azure.Identity pacote: dotnet add package Azure.Identity

  • O pacote de versão prévia azure-search-documents mais recente: pip install --pre azure-search-documents

  • Para autenticação sem chave, o azure-identity pacote: pip install azure-identity

Suporte e limites de arquivo

Antes de criar uma fonte de conhecimento de arquivo, examine os requisitos e os limites que afetam o upload, a extração e o gerenciamento de arquivos.

Tipos de conteúdo com suporte

Fontes de conhecimento de arquivo aceitam arquivos com base no tipo de conteúdo detectado. Um tipo de conteúdo fornecido pelo chamador não substitui a detecção.

Os tipos de conteúdo com suporte incluem:

  • PDF
  • Word (.doc, .docx)
  • PowerPoint (.ppt, .pptx)
  • Excel (.xls, .xlsx)
  • JSON
  • Scripts de shell
  • Conteúdo detectado como text/*, como .txt, .md, .html e .csv

Modos de extração com suporte

  • Para os tipos de conteúdo listados, ambos 2026-05-01-preview e 2026-08-01-preview oferecem suporte a minimal. standard está disponível apenas em 2026-08-01-preview.

  • O conteúdo detectado como image/* não tem suporte em 2026-05-01-preview. Em 2026-08-01-preview, use a extração standard. minimal A extração retorna o status 415 HTTP em ambas as versões.

Limites e operações de arquivo

Os limites e as operações de arquivo com suporte diferem pela versão da API.

Capacidade 2026-05-01-preview 2026-08-01-preview
Máximo de arquivos por fonte de conhecimento 100 200
Tamanho máximo do arquivo 50 MB em todos os planos de preços compatíveis 50 MB em Gratuito e Básico; 100 MB em outras camadas dedicadas com suporte e sem servidor
Duração do processamento O upload pode ser executado por até 180 segundos O carregamento e a atualização podem ser executados por até 180 segundos
Carregar conteúdo e metadados Conteúdo bruto do arquivo Conteúdo de arquivo bruto ou conteúdo de várias partes com metadados
Listar arquivos carregados Listar arquivos Filtrar por caminho ou nome de arquivo e retornar detalhes mais avançados do arquivo
Substituir o conteúdo do arquivo existente Excluir e recarregar Use a operação de atualização
Acesso do navegador a operações de arquivo O CORS não está disponível Configurar o CORS

Note

  • O índice de pesquisa gerado armazena o conteúdo carregado. Para obter limites totais de armazenamento por tipo de preço, consulte os limites de serviço.
  • Se você configurar a fonte de conhecimento de arquivos para dividir em blocos ou vetorizar o conteúdo enviado, os limites do modelo e do processamento posterior também se aplicam.

Verificar se há fontes de conhecimento existentes

Uma fonte de conhecimento é um objeto reutilizável de nível superior. Saber sobre fontes de conhecimento existentes é útil para reutilizar ou nomear novos objetos.

Execute o código a seguir para listar fontes de conhecimento por nome e tipo.

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

Reference:Knowledge Sources – List

Você também pode retornar uma única fonte de conhecimento por nome para revisar sua definição de JSON.

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

Reference:Fontes de Conhecimento – Obter

O JSON a seguir é uma resposta de exemplo para uma fonte de conhecimento de arquivo.

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

Criar uma fonte de conhecimento

Crie uma fonte de conhecimento de arquivo que especifique o modelo de inserção usado para vetorizar o conteúdo carregado.

Cada fonte de conhecimento de arquivo cria um índice, mas não um indexador ou agendamento. Você deve incluir o fileParameters.ingestionParameters objeto. O serviço rejeita solicitações que especificam 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"
    }
  }
}

Reference:Knowledge Sources – Criar ou atualizar

Configurar a extração padrão

A partir da versão da API standard, a extração 2026-08-01-preview usa o Content Understanding para extrair, dividir semanticamente em blocos e enriquecer os arquivos carregados. Pesquisa de IA do Azure  gerencia esse processamento como parte da fonte de conhecimento e os encargos de Compreensão de Conteúdo se aplicam separadamente.

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

Reference:Knowledge Sources – Criar ou atualizar

CORS para operações de arquivo

Para permitir operações de arquivo baseadas em navegador, defina corsOptions na fonte de conhecimento do arquivo com as origens confiáveis e a duração máxima do cache de pré-vôo para seu aplicativo.

Importante

Na versão da API 2026-08-01-preview, corsOptions aplica-se aos endpoints de upload de arquivos, listagem, atualização e exclusão, independentemente do modo de extração. Se você omitir corsOptions, a fonte de conhecimento do arquivo não terá política entre origens do navegador. O CORS não autoriza solicitações. Habilitar origens pode expor operações de serviço e dados em um contexto de navegador e introduzir riscos de segurança. Especifique apenas origens confiáveis e não use uma origem curinga na produção. Para solicitações do navegador, use a autenticação por token do Microsoft Entra com a função mínima necessária. Nunca exponha tokens de acesso ou chaves de serviço no código do navegador.

Carregar arquivos

Depois de criar a fonte de conhecimento, carregue arquivos diretamente nele. Cada upload é uma chamada síncrona: Pesquisa de IA do Azure  extrai conteúdo, o agrupa, cria inserções quando necessário, indexa as partes e persiste os metadados de arquivo antes que a chamada retorne. Você não precisa configurar ou executar um pipeline de ingestão separado.

Para obter ajuda com erros relacionados ao carregamento e ao gerenciamento de arquivos, consulte Solucionar problemas de operações de arquivo.

Carregar um arquivo bruto

Para um upload raw, o valor listado fileName vem do cabeçalho Content-Disposition: attachment; filename="...". As chamadas REST e o SDK .NET definem esse cabeçalho diretamente, enquanto o SDK do Python aceita um parâmetro filename e cria o cabeçalho automaticamente. Se você não fornecer um nome de arquivo, o serviço atribuirá um gerado automaticamente fileName.

Os nomes de arquivo podem incluir um caminho relativo, como manuals/installation-guide.pdf. O serviço normaliza barras invertidas para barras. Ele rejeita caminhos absolutos, segmentos de caminho vazios, segmentos . ou .., segmentos que contêm dois-pontos e caracteres inválidos em nomes de arquivo com o status 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}")

Referência: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>

Referência:Fontes de conhecimento - Carregar arquivo

Carregar um arquivo com metadados opcionais

Começando com a versão da 2026-08-01-preview API, use uma solicitação de várias partes para carregar um arquivo binário com metadados personalizados opcionais. A solicitação inclui exatamente uma content parte e uma parte JSON metadata opcional.

Se ambos os nomes forem especificados, metadata.fileName terá precedência sobre o nome do arquivo na content parte. Se nenhum dos dois for especificado, o serviço atribuirá um nome de arquivo gerado automaticamente.

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

Referência: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}")

Referência: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--

Referência:Fontes de conhecimento - Carregar arquivo

Note

Carregar um arquivo não substitui um arquivo existente, mesmo se você reutilizar o mesmo fileName. Cada carregamento bem-sucedido cria um novo arquivo com seu próprio fileId, assim, a lista de arquivos carregados pode conter várias entradas que compartilham um fileName.

Com 2026-05-01-preview, substitua o conteúdo excluindo o arquivo anterior e carregando a substituição. Com 2026-08-01-preview, use a operação de atualização.

Listar arquivos carregados

Liste arquivos na fonte de dados de conhecimento para inspecionar o conjunto de arquivos carregado.

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

Referência:SearchIndexClient.list_knowledge_source_files

GET {{search-endpoint}}/knowledgesources/my-file-ks/files?api-version=2026-08-01-preview
Authorization: Bearer {{search-access-token}}

Referência:Fontes de Conhecimento – Listar Arquivos

A resposta inclui metadados para cada arquivo carregado. Os arquivos listados com êxito têm um valor errorMessage de 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
    }
  ]
}

Se um novo upload falhar, a solicitação retornará um erro e não criará um registro de metadados de arquivo. O upload com falha não aparece nos resultados da lista posterior e não é cobrado.

Se ocorrer uma falha no acesso ao modelo e o recurso do Foundry que hospeda o modelo de incorporações usar rede privada, confirme se o foundry_account link privado compartilhado foi aprovado e se a opção de bypass dos serviços confiáveis está habilitada. Um bypass desabilitado retorna 403 Public access is disabled. Para obter detalhes de instalação, consulte Pré-requisitos.

Listar e filtrar arquivos

Começando com a versão da 2026-08-01-preview API, use prefix para filtrar arquivos por caminho relativo ou search para filtrar por prefixo de nome de arquivo. Defina pageSize para controlar o número de resultados.

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

Referência: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}}

Referência:Fontes de Conhecimento – Listar Arquivos

A resposta inclui modos de análise e extração selecionados pelo serviço, bem como metadados de usuário para gerenciamento de arquivos. Os metadados do usuário não são pesquisáveis ou filtrados.

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

Para recuperar todos os resultados, siga @odata.nextLink até que ele não esteja mais presente. Envie a URL completa exatamente como retornado, sem alterar os parâmetros de consulta.

Atualizar um arquivo carregado

A partir da versão da API 2026-08-01-preview, atualize um arquivo usando fileId. A solicitação de várias partes requer a parte binária content . A parte JSON de metadados é opcional, portanto, há suporte para uma atualização somente conteúdo. Não há suporte para uma atualização somente de metadados.

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

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

Referência: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:Knowledge Sources – Update File

Se uma atualização falhar, o registro de metadados anterior permanecerá. Não suponha que uma atualização altere o conteúdo indexado transacionalmente.

Excluir arquivos carregados

Exclua arquivos da fonte de conhecimento quando você não quiser mais que eles fiquem disponíveis para recuperação.

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

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

Referência: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}}

Referência:Fontes de conhecimento - Excluir arquivo

Atribuir a uma base de dados de conhecimento

Se você estiver satisfeito com a fonte de conhecimento, adicione-a a uma base de dados de conhecimento.

Consultar uma base de dados de conhecimento

Depois que a base de conhecimento estiver configurada, chame a ação Retrieve ou o endpoint MCP para consultar a fonte de conhecimento.

Excluir uma fonte de conhecimento

Antes de excluir uma fonte de conhecimento, exclua qualquer base de dados de conhecimento que faça referência a ela ou atualize a definição da base de dados de conhecimento para remover a referência. Para fontes de conhecimento que geram um pipeline de índice e indexador, todos os objetos gerados também são excluídos . No entanto, se você usou um índice existente para criar uma fonte de conhecimento, seu índice não será excluído.

Se você tentar excluir uma fonte de conhecimento que está em uso, a ação falhará e retornará uma lista de bases de dados de conhecimento afetadas.

Para excluir uma fonte de conhecimento:

  1. Obtenha uma lista de todas as bases de dados de conhecimento em seu serviço de pesquisa.

    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

    Uma resposta de exemplo pode ser semelhante à seguinte:

     {
     "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
     "value": [
     {
         "name": "my-kb"
     },
     {
         "name": "my-kb-2"
     }
     ]
 }

  2. Obtenha uma definição individual de base de conhecimento para verificar referências de fontes de conhecimento.

    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

    Uma resposta de exemplo pode ser semelhante à seguinte:

     {
   "Name": "earth-knowledge-base",
   "KnowledgeSources": [
     {
       "Name": "earth-knowledge-source"
     }
   ],
   "Models": [
     {}
   ],
   "RetrievalReasoningEffort": {},
   "OutputMode": {},
   "ETag": "\u00220x8DE278629D782B3\u0022",
   "EncryptionKey": null,
   "Description": null,
   "RetrievalInstructions": null,
   "AnswerInstructions": null
 }

  3. Exclua a base de dados de conhecimento ou, se você tiver várias fontes de conhecimento, atualize a base de dados de conhecimento para remover a origem. Este exemplo mostra a exclusão.

    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. Exclua a fonte de conhecimento.

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

    Reference:SearchIndexClient

  1. Obtenha uma lista de todas as bases de dados de conhecimento em seu serviço de pesquisa.

    # 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

    Uma resposta de exemplo pode ser semelhante à seguinte:

     {
     "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
     "value": [
     {
         "name": "my-kb"
     },
     {
         "name": "my-kb-2"
     }
     ]
 }

  2. Obtenha uma definição individual de base de conhecimento para verificar referências de fontes de conhecimento.

    # 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

    Uma resposta de exemplo pode ser semelhante à seguinte:

     {
   "name": "my-kb",
   "description": null,
   "retrievalInstructions": null,
   "answerInstructions": null,
   "outputMode": null,
   "knowledgeSources": [
     {
       "name": "my-blob-ks"
     }
   ],
   "models": [],
   "encryptionKey": null,
   "retrievalReasoningEffort": {
     "kind": "low"
   }
 }

  3. Exclua a base de dados de conhecimento ou, se você tiver várias fontes de conhecimento, atualize a base de dados de conhecimento para remover a origem. Este exemplo mostra a exclusão.

    # 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. Exclua a fonte de conhecimento.

    # 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. Obtenha uma lista de todas as bases de dados de conhecimento em seu serviço de pesquisa.

    ### Get knowledge bases
GET {{search-url}}/knowledgebases?api-version={{api-version}}&$select=name
Authorization: Bearer {{token}}

    Referência:Bases de Dados de Conhecimento – Lista

    Uma resposta de exemplo pode ser semelhante à seguinte:

     {
     "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
     "value": [
     {
         "name": "my-kb"
     },
     {
         "name": "my-kb-2"
     }
     ]
 }

  2. Obtenha uma definição individual de base de conhecimento para verificar referências de fontes de conhecimento.

    ### Get a knowledge base definition
GET {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
Authorization: Bearer {{token}}

    Referência:Bases de Conhecimento – Obter

    Uma resposta de exemplo pode ser semelhante à seguinte:

     {
   "name": "my-kb",
   "description": null,
   "retrievalInstructions": null,
   "answerInstructions": null,
   "outputMode": null,
   "knowledgeSources": [
     {
       "name": "my-blob-ks"
     }
   ],
   "models": [],
   "encryptionKey": null,
   "retrievalReasoningEffort": {
     "kind": "low"
   }
 }

  3. Exclua a base de dados de conhecimento ou, se você tiver várias fontes de conhecimento, atualize a base de dados de conhecimento para remover a origem. Este exemplo mostra a exclusão.

    ### Delete a knowledge base
DELETE {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version={{api-version}}
Authorization: Bearer {{token}}

    Referência:Bases de Dados de Conhecimento – Excluir

  4. Exclua a fonte de conhecimento.

    ### Delete a knowledge source
DELETE {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version={{api-version}}
Authorization: Bearer {{token}}

    Reference:Fontes de Conhecimento - Excluir

Solucionar problemas com operações de arquivo

Os códigos de status a seguir são específicos para operações de fonte de conhecimento de arquivo.

Código de status Causa e ação
400 O arquivo está vazio, não contém texto extraível, tem um caminho relativo não seguro ou tem uma solicitação de continuação inválida. Verifique se o arquivo tem suporte, conteúdo legível e um nome de arquivo válido. Para operações em listas, siga @odata.nextLink exatamente como retornado. Não combine $skiptoken com search ou pageSize.
409 A fonte de conhecimento de arquivo atingiu o limite de arquivos para a versão da API. Exclua arquivos antes de carregar mais.
415 O serviço detectou um tipo MIME sem suporte ou detectou uma imagem enquanto a fonte de conhecimento usa extração mínima. Use um formato com suporte. Para imagens, use a extração padrão. Alterar apenas o tipo de conteúdo fornecido pelo chamador não substitui a detecção.
429 A fila de processamento está cheia. Use paralelismo limitado e tente novamente com recuo exponencial. O serviço não garante um Retry-After cabeçalho.
504 O processamento excedeu 180 segundos durante o upload ou atualização do arquivo. Reduza o tamanho ou a complexidade do arquivo e tente novamente.

Conteúdo relacionado

  • Last updated on