Criar uma fonte de conhecimento OneLake indexada

Nota

Esta funcionalidade de recuperação pelo agente está geralmente disponível a partir de 01-04-2026 na versão da API REST via acesso programático. Os portais Azure e Microsoft Foundry continuam a fornecer acesso exclusivamente em pré-visualização a todas as funcionalidades de recuperação de dados através de agentes. Para orientações sobre migração, consulte Migrar código de recuperação agential para a versão mais recente.

Utilizar uma fonte de conhecimento OneLake indexada para indexar e consultar ficheiros Microsoft OneLake num pipeline de recuperação agêntica. As fontes de conhecimento são criadas de forma independente, referenciadas numa base de conhecimento e usadas como dados de base quando um agente ou chatbot chama uma ação de recuperação no momento da consulta.

Quando cria uma fonte de conhecimento OneLake indexada, especifica uma fonte de dados externa, modelos e propriedades para gerar automaticamente os seguintes objetos Pesquisa de IA do Azure:

  • Uma fonte de dados que representa uma casa de lago.
  • Um conjunto de competências que segmenta e vetoriza opcionalmente conteúdos multimodais da lakehouse.
  • Um índice que armazena conteúdo enriquecido e cumpre os critérios para a recuperação agêntica.
  • Um indexador que utiliza os objetos anteriores para gerir o pipeline de indexação e enriquecimento.

O indexador gerado conforma-se com o indexador OneLake, cujos pré-requisitos, tarefas suportadas, formatos de documentos suportados, atalhos suportados e limitações também se aplicam às fontes de conhecimento OneLake. Para mais informações, consulte a documentação do indexador OneLake.

Suporte de utilização

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

Pré-requisitos

  • Obrigatório pacote Azure.Search.Documents:

    • Para as funcionalidades de pré-visualização de 2025-11-01, o pacote de pré-visualização mais recente: dotnet add package Azure.Search.Documents --prerelease

    • Para as funcionalidades de 01/04/2026, o pacote estável mais recente: dotnet add package Azure.Search.Documents

  • Pacote azure-search-documents obrigatório:

    • Para as funcionalidades de pré-visualização de 2025-11-01, o pacote de pré-visualização mais recente: pip install azure-search-documents --pre

    • Para as funcionalidades de 01/04/2026, o pacote estável mais recente: pip install azure-search-documents

Verifique fontes de conhecimento existentes

Uma fonte de conhecimento é um objeto de topo e reutilizável. 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
api-key: {{api-key}}

Referência:Fontes de Conhecimento - Lista

Também pode devolver uma única fonte de conhecimento pelo nome para rever a sua definição em 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}}
api-key: {{api-key}}

Referência:Fontes de Conhecimento - Obter

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

{
  "name": "my-onelake-ks",
  "kind": "indexedOneLake",
  "description": "A sample indexed OneLake knowledge source.",
  "encryptionKey": null,
  "indexedOneLakeParameters": {
    "fabricWorkspaceId": "<REDACTED>",
    "lakehouseId": "<REDACTED>",
    "targetPath": null,
    "ingestionParameters": {
      "disableImageVerbalization": false,
      "ingestionPermissionOptions": [],
      "contentExtractionMode": "standard",
      "identity": null,
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "text-embedding-3-large",
          "apiKey": "<REDACTED>",
          "modelName": "text-embedding-3-large"
        }
      },
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "gpt-5-mini",
          "apiKey": "<REDACTED>",
          "modelName": "gpt-5-mini"
        }
      },
      "ingestionSchedule": null,
      "aiServices": {
        "uri": "<REDACTED>",
        "apiKey": "<REDACTED>"
      }
    },
    "createdResources": {
    "datasource": "my-onelake-ks-datasource",
    "indexer": "my-onelake-ks-indexer",
    "skillset": "my-onelake-ks-skillset",
    "index": "my-onelake-ks-index"
    }
  }
}

Nota

Informações sensíveis são censuradas. Os recursos gerados aparecem no final da resposta.

Criar uma fonte de conhecimento

Execute o código seguinte para criar uma fonte de conhecimento OneLake indexada.

// Create an indexed OneLake knowledge source
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.Models;
using Azure;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));

var chatCompletionParams = new AzureOpenAIVectorizerParameters
{
    ResourceUri = new Uri(aoaiEndpoint),
    DeploymentName = aoaiGptDeployment,
    ModelName = aoaiGptModel
};

var embeddingParams = new AzureOpenAIVectorizerParameters
{
    ResourceUri = new Uri(aoaiEndpoint),
    DeploymentName = aoaiEmbeddingDeployment,
    ModelName = aoaiEmbeddingModel
};

var ingestionParams = new KnowledgeSourceIngestionParameters
{
    DisableImageVerbalization = false,
    ChatCompletionModel = new KnowledgeBaseAzureOpenAIModel(azureOpenAIParameters: chatCompletionParams),
    EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
    {
        AzureOpenAIParameters = embeddingParams
    },
    IngestionPermissionOptions = new List<KnowledgeSourceIngestionPermissionOption>
    {
        KnowledgeSourceIngestionPermissionOption.UserIds,
        KnowledgeSourceIngestionPermissionOption.GroupIds
    }
};

var oneLakeParams = new IndexedOneLakeKnowledgeSourceParameters(
    fabricWorkspaceId: fabricWorkspaceId,
    lakehouseId: lakehouseId)
{
    IngestionParameters = ingestionParams
};

var knowledgeSource = new IndexedOneLakeKnowledgeSource(
    name: "my-onelake-ks",
    indexedOneLakeParameters: oneLakeParams)
{
    Description = "This knowledge source pulls content from a lakehouse."
};

await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Knowledge source '{knowledgeSource.Name}' created or updated successfully.");

Referência:SearchIndexClient, IndexedOneLakeKnowledgeSource

# Create an indexed OneLake knowledge source
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import IndexedOneLakeKnowledgeSource, IndexedOneLakeKnowledgeSourceParameters, KnowledgeBaseAzureOpenAIModel, AzureOpenAIVectorizerParameters, KnowledgeSourceAzureOpenAIVectorizer, KnowledgeSourceContentExtractionMode, KnowledgeSourceIngestionParameters

index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))

knowledge_source = IndexedOneLakeKnowledgeSource(
    name = "my-onelake-ks",
    description= "This knowledge source pulls content from a lakehouse.",
    encryption_key = None,
    indexed_one_lake_parameters = IndexedOneLakeKnowledgeSourceParameters(
        fabric_workspace_id = "fabric_workspace_id",
        lakehouse_id = "lakehouse_id",
        target_path = None,
        ingestion_parameters = KnowledgeSourceIngestionParameters(
            identity = None,
            disable_image_verbalization = False,
            chat_completion_model = KnowledgeBaseAzureOpenAIModel(
                azure_open_ai_parameters = AzureOpenAIVectorizerParameters(
                    resource_url = "aoai_endpoint",
                    deployment_name = "aoai_gpt_deployment",
                    model_name = "aoai_gpt_model",
                    api_key = "aoai_api_key"
                )
            ),
            embedding_model = KnowledgeSourceAzureOpenAIVectorizer(
                azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
                    resource_url = "aoai_endpoint",
                    deployment_name = "aoai_embedding_deployment",
                    model_name = "aoai_embedding_model",
                    api_key = "aoai_api_key"
                )
            ),
            content_extraction_mode = KnowledgeSourceContentExtractionMode.MINIMAL,
            ingestion_schedule = None,
            ingestion_permission_options = ["user_ids", "group_ids"]
        )
    )
)

index_client.create_or_update_knowledge_source(knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")

Referência:SearchIndexClient

### Create an indexed OneLake knowledge source
PUT {{search-url}}/knowledgesources/my-onelake-ks?api-version=2025-11-01-preview
api-key: {{api-key}}
Content-Type: application/json

{
    "name": "my-onelake-ks",
    "kind": "indexedOneLake",
    "description": "This knowledge source pulls content from a lakehouse.",
    "indexedOneLakeParameters": {
      "fabricWorkspaceId": "<YOUR FABRIC WORKSPACE GUID>",
      "lakehouseId": "<YOUR LAKEHOUSE GUID>",
      "targetPath": null,
      "ingestionParameters": {
        "identity": null,
        "disableImageVerbalization": null,
        "chatCompletionModel": {
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
                "resourceUri": "{{aoai-endpoint}}",
                "deploymentId": "{{aoai-gpt-deployment}}",
                "modelName": "{{aoai-gpt-model}}",
                "apiKey": "{{aoai-key}}"
            }
        },
        "embeddingModel": {
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
                "resourceUri": "{{aoai-endpoint}}",
                "deploymentId": "{{aoai-embedding-deployment}}",
                "modelName": "{{aoai-embedding-model}}",
                "apiKey": "{{aoai-key}}"
            }
        },
        "contentExtractionMode": "minimal",
        "ingestionSchedule": null,
        "ingestionPermissionOptions": ["userIds", "groupIds"]
    }
  }
}

Referência:Fontes de Conhecimento - Criar ou Atualizar

Nota

A aplicação de permissões ao nível do documento com ingestionPermissionOptions requer a versão de API em pré-visualização datada de 2025-11-01. 2026-04-01 não suporta esta funcionalidade.

Propriedades específicas da fonte

Para as versões da API 2025-11-01-preview e 2026-04-01, pode passar as seguintes propriedades para criar uma fonte de conhecimento OneLake indexada.

Nome Descrição Tipo Editável Obrigatório
Name O nome da fonte de conhecimento, que deve ser único dentro da coleção de fontes de conhecimento e seguir as diretrizes nomeação para objetos em Pesquisa de IA do Azure. Corda Não Sim
Description Uma descrição da fonte de conhecimento. Corda Sim Não
EncryptionKey Uma chave gerida pelo cliente para encriptar informação sensível tanto na fonte de conhecimento como nos objetos gerados. Objetivo Sim Não
IndexedOneLakeKnowledgeSourceParameters Parâmetros específicos para fontes de conhecimento OneLake: FabricWorkspaceId, LakehouseId, e TargetPath. Objetivo Sim
FabricWorkspaceId O Identificador Global Único (GUID) do espaço de trabalho que contém o Lakehouse. Corda Não Sim
LakehouseId O GUID da casa do lago. Corda Não Sim
TargetPath Uma pasta ou atalho dentro do lakehouse. Quando não especificado, toda a casa do lago é indexada. Corda Não Não
Nome Descrição Tipo Editável Obrigatório
name O nome da fonte de conhecimento, que deve ser único dentro da coleção de fontes de conhecimento e seguir as diretrizes nomeação para objetos em Pesquisa de IA do Azure. Corda Não Sim
description Uma descrição da fonte de conhecimento. Corda Sim Não
encryption_key Uma chave gerida pelo cliente para encriptar informação sensível tanto na fonte de conhecimento como nos objetos gerados. Objetivo Sim Não
indexed_one_lake_parameters Parâmetros específicos para fontes de conhecimento OneLake: fabric_workspace_id, lakehouse_id, e target_path. Objetivo Sim
fabric_workspace_id O GUID do espaço de trabalho que contém a casa do lago. Corda Não Sim
lakehouse_id O GUID da casa do lago. Corda Não Sim
target_path Uma pasta ou atalho dentro de um lakehouse. Quando não especificado, toda a casa do lago é indexada. Corda Não Não
Nome Descrição Tipo Editável Obrigatório
name O nome da fonte de conhecimento, que deve ser único dentro da coleção de fontes de conhecimento e seguir as diretrizes nomeação para objetos em Pesquisa de IA do Azure. Corda Não Sim
kind O tipo de fonte de conhecimento, que é indexedOneLake neste caso. Corda Não Sim
description Uma descrição da fonte de conhecimento. Corda Sim Não
encryptionKey Uma chave gerida pelo cliente para encriptar informação sensível tanto na fonte de conhecimento como nos objetos gerados. Objetivo Sim Não
indexedOneLakeParameters Parâmetros específicos para fontes de conhecimento OneLake: fabricWorkspaceId, lakehouseId, e targetPath. Objetivo Sim
fabricWorkspaceId O GUID do espaço de trabalho que contém a casa do lago. Corda Não Sim
lakehouseId O GUID da casa do lago. Corda Não Sim
targetPath Uma pasta ou atalho dentro de um lakehouse. Quando não especificado, toda a casa do lago é indexada. Corda Não Não

Propriedades dos parâmetros de ingestão

Apenas para fontes de conhecimento indexadas, pode passar as seguintes ingestionParameters propriedades para controlar como o conteúdo é ingerido e processado.

Nome Descrição Tipo Editável Obrigatório
Identity Uma identidade gerida para usar no indexador gerado. Objetivo Sim Não
DisableImageVerbalization Permite ou desativa o uso da verbalização de imagens. O padrão é False, que permite a verbalização da imagem. Defina para True para desativar a verbalização de imagens. booleano Não Não
ChatCompletionModel Um modelo de conclusão de chat que verbaliza imagens ou extrai conteúdo. Os modelos suportados são gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-5, gpt-5-mini, e gpt-5-nano. A competência GenAI Prompt está incluída no conjunto de competências gerado. Definir este parâmetro também requer que seja DisableImageVerbalization definido como False. Objetivo Apenas ApiKey e DeploymentName são editáveis Não
EmbeddingModel Um modelo de incorporação de texto que vetoriza o texto e o conteúdo de imagens durante a indexação e no momento da consulta. Os modelos suportados são text-embedding-ada-002, text-embedding-3-small, e text-embedding-3-large. A competência Azure OpenAI Embedding está incluída no conjunto de competências geradas, e o vetorizador OpenAI Azure está incluído no índice gerado. Objetivo Apenas ApiKey e DeploymentName são editáveis Não
ContentExtractionMode Controla como o conteúdo é extraído dos ficheiros. O padrão é minimal, que utiliza extração padrão de conteúdo para texto e imagens. Definido para standard para quebrar e fragmentar documentos avançados usando a funcionalidade Azure Content Understanding, que está incluído no conjunto de funcionalidades gerado. Para standard apenas, o AiServices parâmetro é especificável. Corda Não Não
AiServices Um recurso da Microsoft Foundry para aceder ao Azure Content Understanding no Foundry Tools. Definir este parâmetro requer que ContentExtractionMode seja definido como standard. Objetivo Só ApiKey é editável Não
IngestionSchedule Adiciona informação de agendamento ao indexador gerado. Também pode adicionar um horário mais tarde para automatizar a atualização dos dados. Objetivo Sim Não
IngestionPermissionOptions As permissões ao nível do documento para integrar junto com o conteúdo. Especifique UserIds, GroupIds ou RbacScope para armazenar metadados de permissão no índice. Para orientações específicas por código-fonte, veja Ingerir permissões RBAC a partir do armazenamento de blob e Ingerir ACLs a partir da ADLS Gen2. Para fazer cumprir estas permissões no momento da consulta, veja Impor permissões no momento da consulta. Array Não Não
Nome Descrição Tipo Editável Obrigatório
identity Uma identidade gerida para usar no indexador gerado. Objetivo Sim Não
disable_image_verbalization Permite ou desativa o uso da verbalização de imagens. O padrão é False, que permite a verbalização da imagem. Defina para True para desativar a verbalização de imagens. booleano Não Não
chat_completion_model Um modelo de conclusão de chat que verbaliza imagens ou extrai conteúdo. Os modelos suportados são gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-5, gpt-5-mini, e gpt-5-nano. A competência GenAI Prompt está incluída no conjunto de competências gerado. Definir este parâmetro também requer que seja disable_image_verbalization definido como False. Objetivo Apenas api_key e deployment_name são editáveis Não
embedding_model Um modelo de incorporação de texto que vetoriza o texto e o conteúdo de imagens durante a indexação e no momento da consulta. Os modelos suportados são text-embedding-ada-002, text-embedding-3-small, e text-embedding-3-large. A competência Azure OpenAI Embedding está incluída no conjunto de competências geradas, e o vetorizador OpenAI Azure está incluído no índice gerado. Objetivo Apenas api_key e deployment_name são editáveis Não
content_extraction_mode Controla como o conteúdo é extraído dos ficheiros. O padrão é minimal, que utiliza extração padrão de conteúdo para texto e imagens. Definido para standard para quebrar e fragmentar documentos avançados usando a funcionalidade Azure Content Understanding, que está incluído no conjunto de funcionalidades gerado. Para standard apenas, o ai_services parâmetro é especificável. Corda Não Não
ai_services Um recurso da Microsoft Foundry para aceder ao Azure Content Understanding no Foundry Tools. Definir este parâmetro requer que content_extraction_mode seja definido como standard. Objetivo Só api_key é editável Não
ingestion_schedule Adiciona informação de agendamento ao indexador gerado. Também pode adicionar um horário mais tarde para automatizar a atualização dos dados. Objetivo Sim Não
ingestion_permission_options As permissões ao nível do documento para integrar junto com o conteúdo. Especifique user_ids, group_ids ou rbac_scope para armazenar metadados de permissão no índice. Para orientações específicas por código-fonte, veja Ingerir permissões RBAC a partir do armazenamento de blob e Ingerir ACLs a partir da ADLS Gen2. Para fazer cumprir estas permissões no momento da consulta, veja Impor permissões no momento da consulta. Array Não Não
Nome Descrição Tipo Editável Obrigatório
identity Uma identidade gerida para usar no indexador gerado. Objetivo Sim Não
disableImageVerbalization Permite ou desativa o uso da verbalização de imagens. O padrão é false, que permite a verbalização da imagem. Defina para true para desativar a verbalização de imagens. booleano Não Não
chatCompletionModel Um modelo de conclusão de chat que verbaliza imagens ou extrai conteúdo. Os modelos suportados são gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-mini, gpt-4.1-nano, gpt-5, gpt-5-mini, e gpt-5-nano. A competência GenAI Prompt está incluída no conjunto de competências gerado. Definir este parâmetro também requer que seja disableImageVerbalization definido como false. Objetivo Apenas apiKey e deploymentId são editáveis Não
embeddingModel Um modelo de incorporação de texto que vetoriza o texto e o conteúdo de imagens durante a indexação e no momento da consulta. Os modelos suportados são text-embedding-ada-002, text-embedding-3-small, e text-embedding-3-large. A competência Azure OpenAI Embedding está incluída no conjunto de competências geradas, e o vetorizador OpenAI Azure está incluído no índice gerado. Objetivo Apenas apiKey e deploymentId são editáveis Não
contentExtractionMode Controla como o conteúdo é extraído dos ficheiros. O padrão é minimal, que utiliza extração padrão de conteúdo para texto e imagens. Definido para standard para quebrar e fragmentar documentos avançados usando a funcionalidade Azure Content Understanding, que está incluído no conjunto de funcionalidades gerado. Para standard apenas, o aiServices parâmetro é especificável. Corda Não Não
aiServices Um recurso da Microsoft Foundry para aceder ao Azure Content Understanding no Foundry Tools. Definir este parâmetro requer que contentExtractionMode seja definido como standard. Objetivo Só apiKey é editável Não
ingestionSchedule Adiciona informação de agendamento ao indexador gerado. Também pode adicionar um horário mais tarde para automatizar a atualização dos dados. Objetivo Sim Não
ingestionPermissionOptions As permissões ao nível do documento para integrar junto com o conteúdo. Especifique userIds, groupIds ou rbacScope para armazenar metadados de permissão no índice. Para orientações específicas por código-fonte, veja Ingerir permissões RBAC a partir do armazenamento de blob e Ingerir ACLs a partir da ADLS Gen2. Para fazer cumprir estas permissões no momento da consulta, veja Impor permissões no momento da consulta. Array Não Não

Verificar o estado da ingestão

Execute o seguinte código para monitorizar o progresso da ingestão e a saúde, incluindo o tipo de fonte de conhecimento e erros detalhados de indexação para fontes de conhecimento que geram um pipeline de indexadores e preenchem um índice de pesquisa.

using Azure.Search.Documents.Indexes;
using System.Text.Json;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));

// Get knowledge source ingestion status
var statusResponse = await indexClient.GetKnowledgeSourceStatusAsync(knowledgeSourceName);
var status = statusResponse.Value;

// Serialize to JSON for display
var json = JsonSerializer.Serialize(status, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(json);

Referência:SearchIndexClient

# Check knowledge source ingestion status
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"))

status = index_client.get_knowledge_source_status("knowledge_source_name")
print(json.dumps(status.as_dict(), indent=2))

Referência:SearchIndexClient

### Check knowledge source ingestion status
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}/status?api-version={{api-version}}
api-key: {{api-key}}
Content-Type: application/json

Referência:Fontes de Conhecimento - Obter Estado

Uma resposta a um pedido que inclui parâmetros de ingestão e que está a ingerir conteúdo ativamente pode assemelhar-se ao seguinte exemplo.

{
  "kind": "azureBlob",
  "synchronizationStatus": "active",
  "synchronizationInterval": "1d",
  "currentSynchronizationState": {
    "startTime": "2026-04-10T19:30:00Z",
    "itemUpdatesProcessed": 1100,
    "itemsUpdatesFailed": 100,
    "itemsSkipped": 1100,
    "errors": [
      {
        "key": "Item id 1",
        "docURL": "https://contoso.blob.core.windows.net/contracts/2024/Q4/doc-00023.csv",
        "statusCode": 400,
        "componentName": "DocumentExtraction.AzureBlob.MyDataSource",
        "errorMessage": "Could not read the value of column 'foo' at index '0'.",
        "details": "The file could not be parsed.",
        "documentationLink": "https://go.microsoft.com/fwlink/?linkid=2049388"
      }
    ]
  },
  "lastSynchronizationState": {
    "status": "partialSuccess",
    "startTime": "2026-04-09T19:30:00Z",
    "endTime": "2026-04-09T19:40:01Z",
    "itemUpdatesProcessed": 1100,
    "itemsUpdatesFailed": 100,
    "itemsSkipped": 1100,
    "errors": null
  },
  "statistics": {
    "totalSynchronizations": 25,
    "averageSynchronizationDuration": "00:15:20",
    "averageItemsProcessedPerSynchronization": 500
  }
}

Nota

A propriedade kind e o array currentSynchronizationState.errors[] com detalhes de erros ao nível do documento estão disponíveis a partir da versão da API de 2026-04-01. Para versões anteriores da API, estes campos não são devolvidos. O lastSynchronizationState.status campo também é novo em 01-04-2026.

Revise os objetos criados

Quando cria uma fonte de conhecimento OneLake indexada, o seu serviço de pesquisa também cria um indexador, índice, conjunto de habilidades e fonte de dados. Não recomendamos que edite estes objetos, pois introduzir um erro ou incompatibilidade pode quebrar o pipeline.

Depois de criares uma fonte de conhecimento, a resposta lista os objetos criados. Estes objetos são criados de acordo com um modelo fixo, e os seus nomes baseiam-se no nome da fonte de conhecimento. Não podes mudar os nomes dos objetos.

Recomendamos usar o portal do Azure para validar a criação da saída. O fluxo de trabalho é:

  1. Verifique o indexador para mensagens de sucesso ou fracasso. Erros de conexão ou de cota aparecem aqui.
  2. Consulte o índice para conteúdos pesquisáveis. Use o Explorador de Pesquisa para fazer consultas.
  3. Verifica o conjunto de competências para perceberes como o teu conteúdo é segmentado em blocos e, opcionalmente, vetorizado.
  4. Verifique a fonte dos dados para detalhes de conexão. O nosso exemplo usa chaves API para simplificar, mas pode usar o Microsoft Entra ID para autenticação e controlo de acesso baseado em funções para autorização.

Atribuir a uma base de conhecimento

Se estiver satisfeito com a fonte de conhecimento, continue para o passo seguinte: especifique a fonte de conhecimento numa base de conhecimento.

Para qualquer base de conhecimento que especifique uma fonte de conhecimento OneLake indexada, certifique-se de definir includeReferenceSourceData para true. Este passo é necessário para puxar a URL do documento de origem para a citação.

Depois de a base de conhecimento estar configurada, use a ação de recuperar para consultar a fonte de conhecimento.

Dica

Para impor permissões ao nível do documento, defina ingestionPermissionOptions ao criar esta fonte de informações e depois inclua o token de acesso do utilizador na solicitação de recuperação. Para mais informações, consulte Impor permissões no momento da consulta.

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

    Uma resposta de exemplo pode ser a seguinte:

     Knowledge Bases:
   - earth-knowledge-base
   - hotels-sample-knowledge-base
   - my-demo-knowledge-base

  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

    Uma resposta de exemplo pode ser a 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. 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 eliminaçã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. Apaga 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

    Uma resposta de exemplo pode ser a 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 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

    Uma resposta de exemplo pode ser a seguinte:

     {
   "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 eliminaçã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. Apaga 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
api-key: {{api-key}}

    Referência:Bases de Conhecimento - Lista

    Uma resposta de exemplo pode ser a 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 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}}
api-key: {{api-key}}

    Referência:Bases de Conhecimento - Obter

    Uma resposta de exemplo pode ser a seguinte:

     {
   "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 eliminação.

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

    Referência:Bases de Conhecimento - Eliminar

  4. Apaga a fonte de conhecimento.

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

    Referência:Fontes de Conhecimento - Eliminar

Conteúdo relacionado

  • Last updated on