Partilhar via

Crie uma fonte de conhecimento de blobs a partir dos serviços Azure Blob Storage e ADLS Gen2.

Observação

Esta funcionalidade está atualmente em pré-visualização pública. Esta pré-visualização é fornecida sem um contrato de nível de serviço e não é recomendada para cargas de trabalho de produção. Algumas funcionalidades poderão não ser suportadas ou poderão ter capacidades limitadas. Para obter mais informações, veja Termos Suplementares de Utilização para Pré-visualizações do Microsoft Azure.

Utilize uma fonte de conhecimento de blob para indexar e consultar o conteúdo de blob do Azure em um pipeline de recuperação com agentes. 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.

Ao contrário de uma fonte de conhecimento de índice de pesquisa, que especifica um índice existente e qualificado, uma fonte de conhecimento de blob especifica uma fonte de dados externa, modelos e propriedades para gerar automaticamente os seguintes objetos do Azure AI Search:

  • Uma fonte de dados que representa um contêiner de blob.
  • Um conjunto de habilidades que fragmenta e, opcionalmente, vetoriza o conteúdo multimodal do contêiner.
  • Um índice que armazena conteúdo enriquecido e atende aos critérios de recuperação por agentes.
  • Um indexador que utiliza os objetos anteriores para dirigir o pipeline de indexação e enriquecimento.

Observação

Se o acesso do utilizador for especificado ao nível do documento (blob) no Azure Storage, uma fonte de conhecimento pode transportar metadados de permissão para conteúdos indexados no Azure AI Search. Para mais informações, consulte metadados de permissão ADLS Gen2 ou os escopos Blob RBAC.

Pré-requisitos

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

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

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

{
  "name": "my-blob-ks",
  "kind": "azureBlob",
  "description": "A sample blob knowledge source.",
  "encryptionKey": null,
  "azureBlobParameters": {
    "connectionString": "<REDACTED>",
    "containerName": "blobcontainer",
    "folderPath": null,
    "isADLSGen2": false,
    "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",
          "authIdentity": null
        }
      },
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "gpt-5-mini",
          "apiKey": "<REDACTED>",
          "modelName": "gpt-5-mini",
          "authIdentity": null
        }
      },
      "ingestionSchedule": null,
      "assetStore": null,
      "aiServices": {
        "uri": "<REDACTED>",
        "apiKey": "<REDACTED>"
      }
    },
    "createdResources": {
      "datasource": "my-blob-ks-datasource",
      "indexer": "my-blob-ks-indexer",
      "skillset": "my-blob-ks-skillset",
      "index": "my-blob-ks-index"
    }
  }
}

Observação

As informações confidenciais são eliminadas. Os recursos gerados aparecem no final da resposta.

Criar uma fonte de conhecimento

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

// Create a blob knowledge source
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.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
    }
};

var blobParams = new AzureBlobKnowledgeSourceParameters(
    connectionString: connectionString,
    containerName: containerName
)
{
    IsAdlsGen2 = false,
    IngestionParameters = ingestionParams
};

var knowledgeSource = new AzureBlobKnowledgeSource(
    name: "my-blob-ks",
    azureBlobParameters: blobParams
)
{
    Description = "This knowledge source pulls from a blob storage container."
};

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

Propriedades específicas da fonte

Pode passar as seguintes propriedades para criar um blob fonte de conhecimento.

Nome Description 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 de nomenclatura para objetos no Azure AI Search. Cordão Não Yes
Description Uma descrição da fonte de conhecimento. Cordão Yes Não
encryptionKey Uma chave gerida pelo cliente para encriptar informação sensível tanto na fonte de conhecimento como nos objetos gerados. Objeto Yes Não
chatCompletionParams Parâmetros específicos para modelos de conclusão de conversas usados para o planeamento de consultas e síntese opcional de respostas quando o esforço de raciocínio para recuperação é baixo ou médio. Objeto Não
embeddingParams Parâmetros específicos para modelos de embeddings utilizados se quiser vetorizar blocos de conteúdo. Objeto Não
azureBlobParameters Parâmetros específicos das fontes de conhecimento do blob: connectionString, containerName, folderPath, e isAdlsGen2. Objeto Não
connectionString Uma cadeia de ligação baseada em chaves ou, se estiver a usar uma identidade gerida, o ID do recurso. Cordão Não Yes
containerName O nome do contêiner de armazenamento de blob. Cordão Não Yes
folderPath Uma pasta dentro do contentor. Cordão Não Não
isAdlsGen2 A predefinição é False. Define para True se estiveres a usar uma conta de armazenamento ADLS Gen2. booleano Não Não

ingestionParameters propriedades

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

Nome Description Tipo Editável Obrigatório
Identity Uma identidade gerida para usar no indexador gerado. Objeto Yes 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 Truedesativar 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 será incluída no conjunto de competências gerado. Definir este parâmetro também requer que seja disable_image_verbalization definido como False. Objeto Apenas api_key e deployment_name 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 será incluída no conjunto de competências gerado, e o vetorizador Azure OpenAI será incluído no índice gerado. Objeto Apenas api_key e deployment_name 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. Defina para standard quebrar e fragmentar documentos avançados usando a competência Azure Content Understanding, que será incluída no conjunto de competências gerado. Para apenas standard, os parâmetros AiServices e AssetStore podem ser especificados. Cordão Não Não
AiServices Um recurso do Microsoft Foundry para aceder ao Azure Content Understanding no Foundry Tools. Definir este parâmetro requer que ContentExtractionMode seja definido como standard. Objeto Só api_key é editável Yes
IngestionSchedule Adiciona informação de agendamento ao indexador gerado. Você também pode adicionar uma agenda mais tarde para automatizar a atualização de dados. Objeto Yes Não
IngestionPermissionOptions As permissões ao nível de documento para a ingestão de fontes de conhecimento selecionadas: ADLS Gen2 ou SharePoint indexado. Se especificar user_ids, group_ids, ou rbac_scope, o indexador ADLS Gen2 ou SharePoint gerado incluirá as permissões ingeridas. Array Não Não

Verificar o estado de ingestão

Execute o seguinte código para monitorizar o progresso e a saúde da ingestão, incluindo o estado do indexador para fontes de conhecimento que geram um pipeline de indexadores e preenchem um índice de pesquisa.

// Get knowledge source ingestion status
using Azure.Search.Documents.Indexes;
using System.Text.Json;

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

// Get the knowledge source 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);

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.

{ 
  "synchronizationStatus": "active", // creating, active, deleting 
  "synchronizationInterval" : "1d", // null if no schedule 
  "currentSynchronizationState" : { // spans multiple indexer "runs" 
    "startTime": "2025-10-27T19:30:00Z", 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "lastSynchronizationState" : {  // null on first sync 
    "startTime": "2025-10-27T19:30:00Z", 
    "endTime": "2025-10-27T19:40:01Z", // this value appears on the activity record on each /retrieve 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "statistics": {  // null on first sync 
    "totalSynchronization": 25, 
    "averageSynchronizationDuration": "00:15:20", 
    "averageItemsProcessedPerSynchronization" : 500 
  } 
}

Revise os objetos criados

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

Depois de criar uma fonte de conhecimento, a resposta lista os objetos criados. Esses objetos são criados de acordo com um modelo fixo e seus nomes são baseados no nome da fonte de conhecimento. Não é possível alterar os nomes dos objetos.

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

  1. Verifique se há mensagens de sucesso ou falha no indexador. Erros de conexão ou cota aparecem aqui.
  2. Verifique o índice para conteúdo pesquisável. Use o Search Explorer para executar consultas.
  3. Verifique o conjunto de habilidades para saber como seu conteúdo é dividido e, opcionalmente, vetorizado.
  4. Verifique a fonte dos dados para detalhes da ligaçã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.

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

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

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

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

    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 apaga a base de conhecimento ou atualiza a base de conhecimento para remover a fonte de conhecimento se tiveres várias fontes. 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.");

  4. Exclua a fonte de conhecimento.

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

Observação

Esta funcionalidade está atualmente em pré-visualização pública. Esta pré-visualização é fornecida sem um contrato de nível de serviço e não é recomendada para cargas de trabalho de produção. Algumas funcionalidades poderão não ser suportadas ou poderão ter capacidades limitadas. Para obter mais informações, veja Termos Suplementares de Utilização para Pré-visualizações do Microsoft Azure.

Utilize uma fonte de conhecimento de blob para indexar e consultar o conteúdo de blob do Azure em um pipeline de recuperação com agentes. 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.

Ao contrário de uma fonte de conhecimento de índice de pesquisa, que especifica um índice existente e qualificado, uma fonte de conhecimento de blob especifica uma fonte de dados externa, modelos e propriedades para gerar automaticamente os seguintes objetos do Azure AI Search:

  • Uma fonte de dados que representa um contêiner de blob.
  • Um conjunto de habilidades que fragmenta e, opcionalmente, vetoriza o conteúdo multimodal do contêiner.
  • Um índice que armazena conteúdo enriquecido e atende aos critérios de recuperação por agentes.
  • Um indexador que utiliza os objetos anteriores para dirigir o pipeline de indexação e enriquecimento.

Observação

Se o acesso do utilizador for especificado ao nível do documento (blob) no Azure Storage, uma fonte de conhecimento pode transportar metadados de permissão para conteúdos indexados no Azure AI Search. Para mais informações, consulte metadados de permissão ADLS Gen2 ou os escopos Blob RBAC.

Pré-requisitos

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 para reutilizar ou 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
import requests
import json

endpoint = "{search_url}/knowledgesources"
params = {"api-version": "2025-11-01-preview", "$select": "name, kind"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

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

# Get a knowledge source definition
import requests
import json

endpoint = "{search_url}/knowledgesources/{knowledge_source_name}"
params = {"api-version": "2025-11-01-preview"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

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

{
  "name": "my-blob-ks",
  "kind": "azureBlob",
  "description": "A sample blob knowledge source.",
  "encryptionKey": null,
  "azureBlobParameters": {
    "connectionString": "<REDACTED>",
    "containerName": "blobcontainer",
    "folderPath": null,
    "isADLSGen2": false,
    "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",
          "authIdentity": null
        }
      },
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "gpt-5-mini",
          "apiKey": "<REDACTED>",
          "modelName": "gpt-5-mini",
          "authIdentity": null
        }
      },
      "ingestionSchedule": null,
      "assetStore": null,
      "aiServices": {
        "uri": "<REDACTED>",
        "apiKey": "<REDACTED>"
      }
    },
    "createdResources": {
      "datasource": "my-blob-ks-datasource",
      "indexer": "my-blob-ks-indexer",
      "skillset": "my-blob-ks-skillset",
      "index": "my-blob-ks-index"
    }
  }
}

Observação

As informações confidenciais são eliminadas. Os recursos gerados aparecem no final da resposta.

Criar uma fonte de conhecimento

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

# Create a blob knowledge source
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import AzureBlobKnowledgeSource, AzureBlobKnowledgeSourceParameters, KnowledgeBaseAzureOpenAIModel, AzureOpenAIVectorizerParameters, KnowledgeSourceAzureOpenAIVectorizer, KnowledgeSourceContentExtractionMode, KnowledgeSourceIngestionParameters

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

knowledge_source = AzureBlobKnowledgeSource(
    name = "my-blob-ks",
    description = "This knowledge source pulls from a blob storage container.",
    encryption_key = None,
    azure_blob_parameters = AzureBlobKnowledgeSourceParameters(
        connection_string = "blob_connection_string",
        container_name = "blob_container_name",
        folder_path = None,
        is_adls_gen2 = False,
        ingestion_parameters = KnowledgeSourceIngestionParameters(
            identity = None,
            disable_image_verbalization = False,
            chat_completion_model = KnowledgeBaseAzureOpenAIModel(
                azure_open_ai_parameters = AzureOpenAIVectorizerParameters(
                    # TRIMMED FOR BREVITY
                )
            ),
            embedding_model = KnowledgeSourceAzureOpenAIVectorizer(
                azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
                    # TRIMMED FOR BREVITY
                )
            ),
            content_extraction_mode = KnowledgeSourceContentExtractionMode.MINIMAL,
            ingestion_schedule = None,
            ingestion_permission_options = None
        )
    )
)

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

Propriedades específicas da fonte

Pode passar as seguintes propriedades para criar um blob fonte de conhecimento.

Nome Description 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 de nomenclatura para objetos no Azure AI Search. Cordão Não Yes
description Uma descrição da fonte de conhecimento. Cordão Yes Não
encryption_key Uma chave gerida pelo cliente para encriptar informação sensível tanto na fonte de conhecimento como nos objetos gerados. Objeto Yes Não
azure_blob_parameters Parâmetros específicos das fontes de conhecimento do blob: connection_string, container_name, folder_path, e is_adls_gen2. Objeto Não
connection_string Uma cadeia de ligação baseada em chaves ou, se estiver a usar uma identidade gerida, o ID do recurso. Cordão Não Yes
container_name O nome do contêiner de armazenamento de blob. Cordão Não Yes
folder_path Uma pasta dentro do contentor. Cordão Não Não
is_adls_gen2 A predefinição é False. Define para True se estiveres a usar uma conta de armazenamento ADLS Gen2. booleano Não Não

ingestionParameters propriedades

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

Nome Description Tipo Editável Obrigatório
identity Uma identidade gerida para usar no indexador gerado. Objeto Yes 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 Truedesativar 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 será incluída no conjunto de competências gerado. Definir este parâmetro também requer que seja disable_image_verbalization definido como False. Objeto 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 será incluída no conjunto de competências gerado, e o vetorizador Azure OpenAI será incluído no índice gerado. Objeto 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. Defina para standard quebrar e fragmentar documentos avançados usando a competência Azure Content Understanding, que será incluída no conjunto de competências gerado. Para apenas standard, os parâmetros ai_services e asset_store podem ser especificados. Cordão Não Não
ai_services Um recurso do Microsoft Foundry para aceder ao Azure Content Understanding no Foundry Tools. Definir este parâmetro requer que content_extraction_mode seja definido como standard. Objeto Só api_key é editável Yes
asset_store Um contentor de blob para armazenar imagens extraídas. Definir este parâmetro requer que content_extraction_mode seja definido como standard. Objeto Não Não
ingestion_schedule Adiciona informação de agendamento ao indexador gerado. Você também pode adicionar uma agenda mais tarde para automatizar a atualização de dados. Objeto Yes Não
ingestion_permission_options As permissões ao nível de documento para a ingestão de fontes de conhecimento selecionadas: ADLS Gen2 ou SharePoint indexado. Se especificar user_ids, group_ids, ou rbac_scope, o indexador ADLS Gen2 ou SharePoint gerado incluirá as permissões ingeridas. Array Não Não

Verificar o estado de ingestão

Execute o seguinte código para monitorizar o progresso e a saúde da ingestão, incluindo o estado do indexador para fontes de conhecimento que geram um pipeline de indexadores e preenchem um índice de pesquisa.

# Check knowledge source ingestion status
import requests
import json

endpoint = "{search_url}/knowledgesources/{knowledge_source_name}/status"
params = {"api-version": "2025-11-01-preview"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

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.

{ 
  "synchronizationStatus": "active", // creating, active, deleting 
  "synchronizationInterval" : "1d", // null if no schedule 
  "currentSynchronizationState" : { // spans multiple indexer "runs" 
    "startTime": "2025-10-27T19:30:00Z", 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "lastSynchronizationState" : {  // null on first sync 
    "startTime": "2025-10-27T19:30:00Z", 
    "endTime": "2025-10-27T19:40:01Z", // this value appears on the activity record on each /retrieve 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "statistics": {  // null on first sync 
    "totalSynchronization": 25, 
    "averageSynchronizationDuration": "00:15:20", 
    "averageItemsProcessedPerSynchronization" : 500 
  } 
}

Revise os objetos criados

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

Depois de criar uma fonte de conhecimento, a resposta lista os objetos criados. Esses objetos são criados de acordo com um modelo fixo e seus nomes são baseados no nome da fonte de conhecimento. Não é possível alterar os nomes dos objetos.

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

  1. Verifique se há mensagens de sucesso ou falha no indexador. Erros de conexão ou cota aparecem aqui.
  2. Verifique o índice para conteúdo pesquisável. Use o Search Explorer para executar consultas.
  3. Verifique o conjunto de habilidades para saber como seu conteúdo é dividido e, opcionalmente, vetorizado.
  4. Verifique a fonte dos dados para detalhes da ligaçã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.

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

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

    # Get knowledge bases
import requests
import json

endpoint = "{search_url}/knowledgebases"
params = {"api-version": "2025-11-01-preview", "$select": "name"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

    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
import requests
import json

endpoint = "{search_url}/knowledgebases/{knowledge_base_name}"
params = {"api-version": "2025-11-01-preview"}
headers = {"api-key": "{api_key}"}

response = requests.get(endpoint, params = params, headers = headers)
print(json.dumps(response.json(), indent = 2))

    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 apaga a base de conhecimento ou atualiza a base de conhecimento para remover a fonte de conhecimento se tiveres várias fontes. 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.")

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

Observação

Esta funcionalidade está atualmente em pré-visualização pública. Esta pré-visualização é fornecida sem um contrato de nível de serviço e não é recomendada para cargas de trabalho de produção. Algumas funcionalidades poderão não ser suportadas ou poderão ter capacidades limitadas. Para obter mais informações, veja Termos Suplementares de Utilização para Pré-visualizações do Microsoft Azure.

Utilize uma fonte de conhecimento de blob para indexar e consultar o conteúdo de blob do Azure em um pipeline de recuperação com agentes. 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.

Ao contrário de uma fonte de conhecimento de índice de pesquisa, que especifica um índice existente e qualificado, uma fonte de conhecimento de blob especifica uma fonte de dados externa, modelos e propriedades para gerar automaticamente os seguintes objetos do Azure AI Search:

  • Uma fonte de dados que representa um contêiner de blob.
  • Um conjunto de habilidades que fragmenta e, opcionalmente, vetoriza o conteúdo multimodal do contêiner.
  • Um índice que armazena conteúdo enriquecido e atende aos critérios de recuperação por agentes.
  • Um indexador que utiliza os objetos anteriores para dirigir o pipeline de indexação e enriquecimento.

Observação

Se o acesso do utilizador for especificado ao nível do documento (blob) no Azure Storage, uma fonte de conhecimento pode transportar metadados de permissão para conteúdos indexados no Azure AI Search. Para mais informações, consulte metadados de permissão ADLS Gen2 ou os escopos Blob RBAC.

Pré-requisitos

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 para reutilizar ou nomear novos objetos.

Usar Fontes de Conhecimento - Obter (API REST) para listar fontes de conhecimento por nome e tipo.

### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version=2025-11-01-preview&$select=name,kind
api-key: {{api-key}}

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

### Get a knowledge source definition
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}

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

{
  "name": "my-blob-ks",
  "kind": "azureBlob",
  "description": "A sample blob knowledge source.",
  "encryptionKey": null,
  "azureBlobParameters": {
    "connectionString": "<REDACTED>",
    "containerName": "blobcontainer",
    "folderPath": null,
    "isADLSGen2": false,
    "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",
          "authIdentity": null
        }
      },
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "gpt-5-mini",
          "apiKey": "<REDACTED>",
          "modelName": "gpt-5-mini",
          "authIdentity": null
        }
      },
      "ingestionSchedule": null,
      "assetStore": null,
      "aiServices": {
        "uri": "<REDACTED>",
        "apiKey": "<REDACTED>"
      }
    },
    "createdResources": {
      "datasource": "my-blob-ks-datasource",
      "indexer": "my-blob-ks-indexer",
      "skillset": "my-blob-ks-skillset",
      "index": "my-blob-ks-index"
    }
  }
}

Observação

As informações confidenciais são eliminadas. Os recursos gerados aparecem no final da resposta.

Criar uma fonte de conhecimento

Use Fontes de Conhecimento - Criar ou Atualizar (API REST) para criar uma fonte de conhecimento blob.

PUT {{search-url}}/knowledgesources/my-blob-ks?api-version=2025-11-01-preview
api-key: {{api-key}}
Content-Type: application/json

{
  "name": "my-blob-ks",
  "kind": "azureBlob",
  "description": "This knowledge source pulls from a blob storage container.",
  "encryptionKey": null,
  "azureBlobParameters": {
    "connectionString": "<YOUR AZURE STORAGE CONNECTION STRING>",
    "containerName": "<YOUR BLOB CONTAINER NAME>",
    "folderPath": null,
    "isADLSGen2": false,
    "ingestionParameters": {
        "identity": null,
        "disableImageVerbalization": null,
        "chatCompletionModel": { TRIMMED FOR BREVITY },
        "embeddingModel": { TRIMMED FOR BREVITY },
        "contentExtractionMode": "minimal",
        "ingestionSchedule": null,
        "ingestionPermissionOptions": []
    }
  }
}

Propriedades específicas da fonte

Pode passar as seguintes propriedades para criar um blob fonte de conhecimento.

Nome Description 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 de nomenclatura para objetos no Azure AI Search. Cordão Não Yes
kind O tipo de fonte de conhecimento, que é azureBlob neste caso. Cordão Não Yes
description Uma descrição da fonte de conhecimento. Cordão Yes Não
encryptionKey Uma chave gerida pelo cliente para encriptar informação sensível tanto na fonte de conhecimento como nos objetos gerados. Objeto Yes Não
azureBlobParameters Parâmetros específicos das fontes de conhecimento do blob: connectionString, containerName, folderPath, e isADLSGen2. Objeto Não
connectionString Uma cadeia de ligação baseada em chaves ou, se estiver a usar uma identidade gerida, o ID do recurso. Cordão Não Yes
containerName O nome do contêiner de armazenamento de blob. Cordão Não Yes
folderPath Uma pasta dentro do contentor. Cordão Não Não
isADLSGen2 A predefinição é false. Define para true se estiveres a usar uma conta de armazenamento ADLS Gen2. booleano Não Não

ingestionParameters propriedades

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

Nome Description Tipo Editável Obrigatório
identity Uma identidade gerida para usar no indexador gerado. Objeto Yes 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 truedesativar 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 será incluída no conjunto de competências gerado. Definir este parâmetro também requer que seja disableImageVerbalization definido como false. Objeto 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 será incluída no conjunto de competências gerado, e o vetorizador Azure OpenAI será incluído no índice gerado. Objeto 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. Defina para standard quebrar e fragmentar documentos avançados usando a competência Azure Content Understanding, que será incluída no conjunto de competências gerado. Para apenas standard, os parâmetros aiServices e assetStore podem ser especificados. Cordão Não Não
aiServices Um recurso do Microsoft Foundry para aceder ao Azure Content Understanding no Foundry Tools. Definir este parâmetro requer que contentExtractionMode seja definido como standard. Objeto Só apiKey é editável Yes
assetStore Um contentor de blob para armazenar imagens extraídas. Definir este parâmetro requer que contentExtractionMode seja definido como standard. Objeto Não Não
ingestionSchedule Adiciona informação de agendamento ao indexador gerado. Você também pode adicionar uma agenda mais tarde para automatizar a atualização de dados. Objeto Yes Não
ingestionPermissionOptions As permissões ao nível de documento para a ingestão de fontes de conhecimento selecionadas: ADLS Gen2 ou SharePoint indexado. Se especificar userIds, groupIds, ou rbacScope, o indexador ADLS Gen2 ou SharePoint gerado incluirá as permissões ingeridas. Array Não Não

Verificar o estado de ingestão

Use Knowledge Sources - Status (API REST) para monitorizar o progresso da ingestão e a saúde, incluindo o estado do indexador para fontes de conhecimento que geram um pipeline de indexadores e preenchem um índice de pesquisa.

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

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.

{ 
  "synchronizationStatus": "active", // creating, active, deleting 
  "synchronizationInterval" : "1d", // null if no schedule 
  "currentSynchronizationState" : { // spans multiple indexer "runs" 
    "startTime": "2025-10-27T19:30:00Z", 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "lastSynchronizationState" : {  // null on first sync 
    "startTime": "2025-10-27T19:30:00Z", 
    "endTime": "2025-10-27T19:40:01Z", // this value appears on the activity record on each /retrieve 
    "itemUpdatesProcessed": 1100, 
    "itemsUpdatesFailed": 100, 
    "itemsSkipped": 1100, 
  }, 
  "statistics": {  // null on first sync 
    "totalSynchronization": 25, 
    "averageSynchronizationDuration": "00:15:20", 
    "averageItemsProcessedPerSynchronization" : 500 
  } 
}

Revise os objetos criados

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

Depois de criar uma fonte de conhecimento, a resposta lista os objetos criados. Esses objetos são criados de acordo com um modelo fixo e seus nomes são baseados no nome da fonte de conhecimento. Não é possível alterar os nomes dos objetos.

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

  1. Verifique se há mensagens de sucesso ou falha no indexador. Erros de conexão ou cota aparecem aqui.
  2. Verifique o índice para conteúdo pesquisável. Use o Search Explorer para executar consultas.
  3. Verifique o conjunto de habilidades para saber como seu conteúdo é dividido e, opcionalmente, vetorizado.
  4. Verifique a fonte dos dados para detalhes da ligaçã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.

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

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

    ### Get knowledge bases
GET {{search-endpoint}}/knowledgebases?api-version=2025-11-01-preview&$select=name
api-key: {{api-key}}

    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-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}

    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 apaga a base de conhecimento ou atualiza a base de conhecimento removendo a fonte de conhecimento se tiveres múltiplas fontes. Este exemplo mostra a exclusão.

    ### Delete a knowledge base
DELETE {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}

  4. Exclua a fonte de conhecimento.

    ### Delete a knowledge source
DELETE {{search-endpoint}}/knowledgesources/{{knowledge-source-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}

Conteúdo relacionado

  • Last updated on