Criar uma origem de conhecimento baseada em ficheiro (pré-visualização)

Note

O Pesquisa de IA do Azure está disponível através do portal Azure, APIs REST e SDKs do Azure. Também sustenta o Foundry IQ, a camada de conhecimento gerida que transforma conteúdos empresariais em bases de conhecimento reutilizáveis e conscientes de permissões para agentes no portal Microsoft Foundry.

Importante

Estas funcionalidades e capacidades fazem parte da versão de pré-visualização de 2026-08-01 da API REST. A pré-visualização de 2026-08-01-está licenciada a si como parte da sua subscrição do Azure e está sujeita aos termos aplicáveis a "Pré-visualizações" nos Termos de Produto Microsoft, no Adendo de Proteção de Dados de Produtos e Serviços Microsoft ("DPA") e nos Termos Suplementares de Utilização para Pré-visualizações do Microsoft Azure.

As APIs de pré-visualização suportam ligações a outros serviços da serviços Microsoft e serviços de terceiros. A utilização destes serviços está sujeita aos respetivos termos e pode resultar no processamento ou armazenamento de dados fora do limite de conformidade do Azure, bem como no fluxo de dados para o limite de conformidade do Azure.

É sua responsabilidade gerir se os seus dados irão fluir para além dos limites de conformidade e geográficos da sua organização e quaisquer implicações relacionadas, e garantir que as permissões, limites e aprovações apropriadas sejam providenciadas.

És responsável por rever e testar cuidadosamente as aplicações que constróis no contexto dos teus casos de uso específicos e por tomar todas as decisões e personalizações apropriadas. Isto inclui implementar as suas próprias mitigações de IA responsável, como metaprompts, filtros de conteúdo ou outros sistemas de segurança, e assegurar que as suas aplicações cumprem os padrões adequados de qualidade, fiabilidade, segurança e confiabilidade. Para mais informações, consulte a Nota de Transparência Pesquisa de IA do Azure.

Uma origem de conhecimento de ficheiros (pré-visualização) permite carregar conjuntos de ficheiros de pequena e média dimensão diretamente para o Pesquisa de IA do Azure para recuperação por agentes. As fontes de conhecimento são criadas de forma independente, referenciadas numa base de conhecimento e usadas como dados de base quando a base é consultada em tempo de execução.

As fontes de conhecimento de ficheiros são úteis quando se pretende uma experiência de upload gerida em vez de provisionar Armazenamento do Azure, configurar o acesso e criar um pipeline de indexação sobre um contentor externo. O Pesquisa de IA do Azure processa ficheiros carregados para que o conteúdo extraído possa ser recuperado de uma base de conhecimento.

Use antes uma fonte de conhecimento de blob quando os seus ficheiros já estiverem no Armazenamento de Blobs do Azure ou no Azure Data Lake Storage Gen2, quando o seu conjunto de ficheiros exceder ou provavelmente ultrapassar os limites da fonte de conhecimento do ficheiro, ou quando precisar de uma ingestão agendada. Utilize também uma fonte de conhecimento de blobs quando pretender gerir blobs de origem com políticas de gestão do ciclo de vida do Armazenamento de Blobs do Azure ou quando precisar de permissões ao nível de documentos (pré-visualização) com base nas permissões no Armazenamento do Azure.

Suporte de utilização

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

Pré-requisitos

  • Um serviço Pesquisa de IA do Azure em qualquer região que forneça recuperação proativa. As fontes de conhecimento baseadas em ficheiros suportam os modelos de preços Dedicated e Serverless. Para detalhes de modelos e níveis, consulte Escolher um modelo de preços e um nível de serviço.

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

  • No Serverless, operações bem-sucedidas de ingestão de ficheiros consomem computação faturável. Os carregamentos falhados não implicam custos de computação serverless.

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

  • Ficheiros num formato suportado.

  • Permissão para criar fontes de conhecimento. Configure a autenticação sem chave com o papel de Contribuidor do Serviço de Pesquisa atribuído à sua conta de utilizador (recomendado) ou utilize uma chave API de administrador.

  • Se a fonte de conhecimento especificar um modelo do Azure OpenAI para gerar embeddings, o serviço de pesquisa tem de ter uma identidade gerida com permissões Cognitive Services User no recurso do Microsoft Foundry.

    • Se o recurso do Foundry tiver o acesso à rede pública desativado, crie um foundry_accountlink privado partilhado do serviço de pesquisa para o recurso do Foundry e mantenha ativada a definição Permitir serviços Azure do recurso na lista de serviços de confiança.

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

    • A utilização é cobrada de acordo com os preços de Azure Content Understanding no Foundry Tools ao recurso Foundry configurado através de aiServices.

    • O limite diário gratuito de 20 documentos disponível para algumas competências integradas não se aplica.

    • Para o exemplo deste artigo, vai precisar do endpoint e da chave do recurso Foundry, bem como das informações sobre os modelos de embedding e de conclusão de chat do Azure OpenAI.

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

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

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

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

Suporte e limites de ficheiros

Antes de criar uma fonte de conhecimento de ficheiros, reveja os requisitos e limites que afetam o carregamento, extração e gestão de ficheiros.

Tipos de conteúdo suportados

As fontes de conhecimento de ficheiros aceitam ficheiros com base no tipo de conteúdo detetado. Um tipo de conteúdo fornecido pelo chamador não substitui a deteção.

Os tipos de conteúdo suportados incluem:

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

Modos de extração suportados

  • Para os tipos de conteúdo listados, tanto 2026-05-01-preview como minimal suportam 2026-08-01-preview. standard está disponível apenas em 2026-08-01-preview.

  • Conteúdo detetado como image/* não é suportado em 2026-05-01-preview. Em 2026-08-01-preview, utilize standard extração. minimal a extração devolve o código de estado HTTP 415 em ambas as versões.

Limites e operações de ficheiro

Os limites e as operações de ficheiros suportados variam consoante a versão da API.

Capacidade 2026-05-01-preview 2026-08-01-preview
Ficheiros máximos por fonte de conhecimento 100 200
Tamanho máximo do ficheiro 50 MB em todos os escalões de preços suportados 50 MB em Livre e Básico; 100 MB noutros níveis Dedicados suportados e Serverless
Duração do processamento O upload pode durar até 180 segundos O upload e atualização podem durar até 180 segundos
Carregar conteúdo e metadados Conteúdo bruto do ficheiro Conteúdo bruto do ficheiro ou conteúdo multiparte com metadados
Lista de ficheiros carregados Listar ficheiros Filtre por caminho ou nome de ficheiro e devolve detalhes mais ricos do ficheiro
Substituir o conteúdo existente do ficheiro Apagar e voltar a carregar Utilizar a operação de atualização
Acesso do navegador às operações de ficheiros O CORS não está disponível Configurar CORS

Note

  • O índice de pesquisa gerado armazena o conteúdo carregado. Para limites totais de armazenamento por escalão de preço, veja Limites de Serviço.
  • Se configurares a origem de conhecimento de ficheiros para segmentar ou vetorizar o conteúdo carregado, os limites do modelo e do processamento subsequente também se aplicam.

Verifique se há fontes de conhecimento existentes

Uma fonte de conhecimento é um objeto reutilizável de nível superior. Conhecer as fontes de conhecimento existentes é útil tanto para reutilizar como para nomear novos objetos.

Execute o seguinte código para listar as 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}");
}

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

Referência:SearchIndexClient

### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version={{api-version}}&$select=name,kind
Authorization: Bearer {{token}}

Referência:Fontes de Conhecimento - Lista

Você também pode retornar uma única fonte de conhecimento pelo nome para revisar sua definição 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));

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

Referência:SearchIndexClient

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

Referência:Fontes de Conhecimento - Obter

O JSON seguinte é uma resposta de exemplo para uma fonte de conhecimento de ficheiros.

{
  "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 ficheiro que especifique o modelo de embedding usado para vetorizar o conteúdo carregado.

Cada fonte de conhecimento do ficheiro cria um índice, mas não um indexador ou agendamento. Deve incluir o objeto fileParameters.ingestionParameters. O serviço rejeita pedidos 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.");

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

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

Referência:Fontes de Conhecimento - Criar ou Atualizar

Configurar extração padrão

A partir da 2026-08-01-preview versão da API, a standard extração utiliza o Content Understanding para extrair, segmentar semanticamente e enriquecer ficheiros carregados. O Pesquisa de IA do Azure gere este processamento como parte da fonte de conhecimento, e as taxas de Compreensão de Conteúdo aplicam-se 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}'.");

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

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

Referência:Fontes de Conhecimento - Criar ou Atualizar

CORS para operações de ficheiros

Para permitir operações de ficheiros baseadas em browser, defina corsOptions a fonte de conhecimento do ficheiro com as origens confiáveis e a duração máxima da cache pré-voo para a sua aplicação.

Importante

Na 2026-08-01-preview versão da API, corsOptions aplica-se a endpoints de upload, listagem, atualização e eliminação de ficheiros independentemente do modo de extração. Se omitires corsOptions, a fonte de conhecimento do ficheiro não tem política de cross-origin do navegador. O CORS não autoriza pedidos. Ativar origens pode expor operações de serviço e dados num contexto de navegador e introduzir riscos de segurança. Especifica apenas origens confiáveis e não uses uma origem com caráter universal (*) em produção. Para pedidos do browser, utilize a autenticação com 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 ficheiros

Depois de criares a fonte de conhecimento, carrega os ficheiros diretamente para ela. Cada upload é uma chamada síncrona: o Pesquisa de IA do Azure extrai conteúdo, fragmenta-o, cria embeddings quando necessário, indexa os chunks e mantém os metadados do ficheiro antes da chamada regressar. Não tens de configurar ou executar um pipeline de ingestão separado.

Para obter ajuda com erros relacionados com o carregamento e a gestão de ficheiros, consulte Resolver problemas de operações de ficheiros.

Carregar um ficheiro raw

Para um carregamento em bruto, o fileName indicado provém do cabeçalho Content-Disposition: attachment; filename="...". Chamadas REST e o SDK .NET definem este cabeçalho diretamente, enquanto o SDK Python aceita um parâmetro filename e constrói o cabeçalho automaticamente. Se não fornecer um nome de ficheiro, o serviço atribui um fileName gerado automaticamente.

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

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

Carregar um ficheiro com metadados opcionais

A partir da 2026-08-01-preview versão da API, use um pedido multiparte para carregar um ficheiro binário com metadados personalizados opcionais. O pedido inclui exatamente uma content parte e uma parte JSON metadata opcional.

Se ambos os nomes forem especificados, metadata.fileName tem precedência sobre o nome do ficheiro na content peça. Se nenhum deles for especificado, o serviço atribui um nome de ficheiro 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 ficheiro

Note

O carregamento de um ficheiro não substitui um ficheiro existente, mesmo que reutilize o mesmo fileName. Cada upload bem-sucedido cria um novo ficheiro com o seu próprio fileId, pelo que a lista de ficheiros carregados pode conter múltiplas entradas que partilham um fileName.

Com 2026-05-01-preview, substitui o conteúdo eliminando o ficheiro anterior e carregando o substituto. Com 2026-08-01-preview, utilize a operação de atualização.

Lista de ficheiros carregados

Lista ficheiros na fonte de conhecimento para inspecionar o conjunto de ficheiros 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}");
}

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

A resposta inclui metadados para cada ficheiro carregado. Os ficheiros listados com sucesso têm um errorMessage valor 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 carregamento falhar, o pedido devolve um erro e não cria um registo de metadados do ficheiro. O carregamento falhado não aparece nos resultados posteriores da lista e não é faturado.

Se ocorrer uma falha de acesso ao modelo e o recurso Foundry que aloja o modelo de incorporações utilizar rede privada, confirme que a foundry_account ligação privada partilhada está aprovada e que a exceção para serviços fidedignos está ativada. Um bypass desativado retorna 403 Public access is disabled. Para detalhes de configuração, veja Pré-requisitos.

Listar e filtrar ficheiros

A partir da 2026-08-01-preview versão da API, utilize-se prefix para filtrar ficheiros por caminho relativo ou search por prefixo de nome de ficheiro. Definir 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})");
}

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

A resposta inclui modos de análise e extração selecionados pelo serviço, bem como metadados do utilizador para gestão de ficheiros. Os metadados do utilizador não são pesquisáveis nem filtráveis.

{
  "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 obter todos os resultados, siga o @odata.nextLink até este deixar de estar presente. Envie a URL completa exatamente como retornada, sem alterar os parâmetros da consulta.

Atualizar um ficheiro carregado

A partir da versão 2026-08-01-preview da API, atualize um ficheiro através do seu fileId. O pedido multiparte requer a parte binária content . A parte JSON de metadados é opcional, por isso é suportada uma atualização apenas de conteúdo. Uma atualização apenas com metadados não é suportada.

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

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

Referência:Fontes de Conhecimento - Ficheiro de Atualização

Se uma atualização falhar, o registo de metadados anterior mantém-se. Não presuma que uma atualização altera o conteúdo indexado de forma transacional.

Eliminar ficheiros carregados

Apague ficheiros da fonte de conhecimento quando já não quiser que estejam 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");

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

Atribuir a uma base de conhecimento

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

Consultar uma base de conhecimento

Depois de a base de conhecimento estar configurada, chame a ação de recuperação ou o endpoint MCP para consultar a fonte de conhecimento.

Eliminar uma fonte de conhecimento

Antes de poder eliminar uma fonte de conhecimento, deve eliminar qualquer base de conhecimento que a faça referência ou atualizar a definição da base 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 eliminados. No entanto, se usou um índice existente para criar uma fonte de conhecimento, o seu índice não é eliminado.

Se tentar eliminar uma fonte de conhecimento que está em uso, a ação falha e devolve uma lista das bases de conhecimento afetadas.

Para eliminar uma fonte de conhecimento:

  1. Obtenha uma lista de todas as bases de conhecimento do 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}");
}

    Referência:SearchIndexClient

    Um exemplo de resposta pode ter a seguinte aparência:

     {
     "@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 da 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);

    Referência:SearchIndexClient

    Um exemplo de resposta pode ter a seguinte aparência:

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

  3. Ou apagas a base de conhecimento ou, se tiveres várias fontes de conhecimento, atualizas a base de conhecimento para remover a fonte. 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.");

    Referência:SearchIndexClient

  4. Exclua a fonte de conhecimento.

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

    Referência:SearchIndexClient

  1. Obtenha uma lista de todas as bases de conhecimento do 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}")

    Referência:SearchIndexClient

    Um exemplo de resposta pode ter a seguinte aparência:

     {
     "@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 da 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)

    Referência:SearchIndexClient

    Um exemplo de resposta pode ter a seguinte aparência:

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

  3. Ou apagas a base de conhecimento ou, se tiveres várias fontes de conhecimento, atualizas a base de conhecimento para remover a fonte. 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.")

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

    Referência:SearchIndexClient

  1. Obtenha uma lista de todas as bases de conhecimento do 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 Conhecimento - Lista

    Um exemplo de resposta pode ter a seguinte aparência:

     {
     "@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 da 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

    Um exemplo de resposta pode ter a seguinte aparência:

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

  3. Ou apagas a base de conhecimento ou, se tiveres várias fontes de conhecimento, atualizas a base de conhecimento para remover a fonte. 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 Conhecimento - Eliminar

  4. Exclua a fonte de conhecimento.

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

    Referência:Fontes de Conhecimento - Eliminar

Resolver problemas de operações de ficheiros

Os seguintes códigos de estado são específicos para operações de fonte de conhecimento de ficheiros.

Código de estado Causa e ação
400 O ficheiro está vazio, não contém texto extraível, tem um caminho relativo inseguro ou tem um pedido de continuação inválido. Verifique se o ficheiro tem conteúdo suportado, legível e um nome válido. Para operações em listas, siga @odata.nextLink exatamente tal como é devolvido. Não combine $skiptoken com search ou pageSize.
409 A fonte de conhecimento do ficheiro atingiu o limite de ficheiros para a versão da API. Apaga ficheiros antes de carregares mais.
415 O serviço detetou um tipo MIME não suportado, ou detetou uma imagem enquanto a fonte de conhecimento usa extração mínima. Use um formato suportado. Para imagens, use extração padrão. Alterar apenas o tipo de conteúdo fornecido pelo chamador não anula a deteção.
429 A fila de processamento está cheia. Use paralelismo limitado e tente novamente com retrocesso exponencial. O serviço não garante um Retry-After cabeçalho.
504 O processamento ultrapassava os 180 segundos durante o upload ou atualização do ficheiro. Reduza o tamanho ou a complexidade do ficheiro e tente novamente.

Conteúdo relacionado

  • Last updated on