Compartilhar via

Criar uma fonte de conhecimento de blobs do Azure Blob Storage e do ADLS Gen2

Observação

Esse recurso está atualmente em versão prévia pública. Essa visualização é fornecida sem um contrato de nível de serviço e não é recomendada para utilização em produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares para Versões Prévias do Microsoft Azure.

Use uma fonte de conhecimento de blob para indexar e consultar o conteúdo do blob do Azure em um pipeline de recuperação por meio de agentes. As fontes de conhecimento são criadas de forma independente, referenciadas em uma base de dados de conhecimento e usadas como dados de aterramento quando 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 agrupa 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 usa os objetos anteriores para conduzir o pipeline de indexação e enriquecimento.

Observação

Se o acesso do usuário for especificado no nível do documento (blob) no Armazenamento do Azure, uma fonte de conhecimento poderá levar metadados de permissão para o conteúdo indexado no Azure AI Search. Para obter mais informações, consulte metadados de permissão do ADLS Gen2 ou escopos de RBAC do Blob.

Pré-requisitos

Verificar se há fontes de conhecimento existentes

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

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

// List knowledge sources by name and type
using Azure.Search.Documents.Indexes;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var knowledgeSources = indexClient.GetKnowledgeSourcesAsync();

Console.WriteLine("Knowledge Sources:");

await foreach (var ks in knowledgeSources)
{
    Console.WriteLine($"  Name: {ks.Name}, Type: {ks.GetType().Name}");
}

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

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

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Specify the knowledge source name to retrieve
string ksNameToGet = "earth-knowledge-source";

// Get its definition
var knowledgeSourceResponse = await indexClient.GetKnowledgeSourceAsync(ksNameToGet);
var ks = knowledgeSourceResponse.Value;

// Serialize to JSON for display
var jsonOptions = new JsonSerializerOptions 
{ 
    WriteIndented = true,
    DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.Never
};
Console.WriteLine(JsonSerializer.Serialize(ks, ks.GetType(), jsonOptions));

O JSON a seguir é uma resposta de exemplo para uma fonte de dados 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

Informações confidenciais são rasuradas. Os recursos gerados aparecem no final da resposta.

Criar uma fonte de conhecimento

Execute o código a seguir para criar uma fonte de conhecimento 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 origem

Você pode passar as seguintes propriedades para criar uma fonte de conhecimento de blobs.

Nome Description Tipo Editável Obrigatório
name O nome da fonte de conhecimento, que deve ser exclusivo na coleção de fontes de conhecimento e seguir as diretrizes de nomenclatura para objetos no Azure AI Search. String Não Yes
Description Uma descrição da fonte de conhecimento. String Yes Não
encryptionKey Uma chave gerenciada pelo cliente para criptografar informações confidenciais na fonte de conhecimento e nos objetos gerados. Object Yes Não
chatCompletionParams Parâmetros específicos para modelos de conclusão de chat usados para planejamento de consultas e síntese de respostas opcionais quando o esforço de raciocínio de recuperação for baixo ou médio. Object Não
embeddingParams Parâmetros específicos para a inserção de modelos usados se você quiser vetorizar partes de conteúdo. Object Não
azureBlobParameters Parâmetros específicos para fontes de conhecimento de blob: connectionString, containerName, folderPath e isAdlsGen2. Object Não
connectionString Uma cadeia de conexão baseada em chave ou, se você estiver usando uma identidade gerenciada, a ID do recurso. String Não Yes
containerName O nome do contêiner de armazenamento de blobs. String Não Yes
folderPath Uma pasta dentro do contêiner. String Não Não
isAdlsGen2 O padrão é False. Defina como True se você estiver usando uma conta de armazenamento do ADLS Gen2. booleano Não Não

ingestionParameters propriedades

Somente para fontes de conhecimento indexadas, você pode passar as propriedades a seguir ingestionParameters para controlar como o conteúdo é ingerido e processado.

Nome Description Tipo Editável Obrigatório
Identity Uma identidade gerenciada a ser usada no indexador gerado. Object Yes Não
DisableImageVerbalization Habilita ou desabilita o uso da verbalização de imagem. O padrão é False, que permite a verbalização da imagem. Defina para True para desabilitar a verbalização da imagem. booleano Não Não
ChatCompletionModel Um modelo de conclusão de chat que verbaliza imagens ou extrai conteúdo. Os modelos com suporte 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 habilidade do Prompt do GenAI será incluída no conjunto de habilidades gerado. Definir esse parâmetro também requer que disable_image_verbalization seja definido como False. Object Somente api_key e deployment_name são editáveis Não
EmbeddingModel Um modelo de inserção de texto que vetorializa o conteúdo de texto e imagem durante a indexação e no momento da consulta. Os modelos com suporte são text-embedding-ada-002, text-embedding-3-smalle text-embedding-3-large. A habilidade do Azure OpenAI Embedding será incluída no conjunto de habilidades gerado e o vetor do Azure OpenAI será incluído no índice gerado. Object Somente api_key e deployment_name são editáveis Não
ContentExtractionMode Controla como o conteúdo é extraído dos arquivos. O padrão é minimal, que usa a extração de conteúdo padrão para texto e imagens. Defina como standard para quebra e quebra de documentos avançadas usando a habilidade de Compreensão de Conteúdo do Azure, que será incluída no conjunto de habilidades gerado. Somente para standard, os parâmetros AiServices e AssetStore são especificáveis. String Não Não
AiServices Um recurso do Microsoft Foundry para acessar o Azure Content Understanding nas Ferramentas Foundry. Definir esse parâmetro requer que ContentExtractionMode seja definido como standard. Object Somente api_key é editável Yes
IngestionSchedule Adiciona informações de agendamento ao indexador gerado. Você também pode adicionar um agendamento posteriormente para automatizar a atualização de dados. Object Yes Não
IngestionPermissionOptions As permissões de documento para ingerir de fontes de conhecimento selecionadas: ADLS Gen2 ou SharePoint indexado. Se você especificar user_ids, group_idsou rbac_scope, o indexador do ADLS Gen2 gerado ou o indexador do SharePoint incluirá as permissões ingeridas. Array Não Não

Verificar o status da ingestão

Execute o código a seguir para monitorar o andamento e a integridade da ingestão, incluindo o status do indexador para fontes de conhecimento que geram um pipeline de indexador e populam 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 para uma solicitação que inclui parâmetros de ingestão e está ingerindo conteúdo ativamente pode ser semelhante ao exemplo a seguir.

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

Examinar os objetos criados

Ao criar uma fonte de conhecimento de blob, seu serviço de pesquisa também cria um indexador, índice, conjunto de habilidades e fonte de dados. Não recomendamos que você edite esses objetos, pois a introdução de um erro ou incompatibilidade pode interromper 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.

É recomendável 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 obter conteúdo pesquisável. Use o Gerenciador de Pesquisa para executar consultas.
  3. Verifique o conjunto de habilidades para saber como o conteúdo é agrupado e, opcionalmente, vetorizado.
  4. Verifique a fonte de dados para obter detalhes da conexão. Nosso exemplo usa chaves de API para simplificar, mas você pode usar a ID do Microsoft Entra para autenticação e controle de acesso baseado em função para autorização.

Atribuir a uma base de dados de conhecimento

Se você estiver satisfeito com a fonte de conhecimento, prossiga para a próxima etapa: especifique a fonte de conhecimento em uma base de dados de conhecimento.

Depois que a base de dados de conhecimento estiver configurada, use a ação de recuperação para consultar a fonte de conhecimento.

Excluir uma fonte de conhecimento

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

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

Para excluir uma fonte de conhecimento:

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

    using Azure.Search.Documents.Indexes;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);
var knowledgeBases = indexClient.GetKnowledgeBasesAsync();

Console.WriteLine("Knowledge Bases:");

await foreach (var kb in knowledgeBases)
{
    Console.WriteLine($"  - {kb.Name}");
}

    Uma resposta de exemplo pode ser semelhante à seguinte:

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

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

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

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), credential);

// Specify the knowledge base name to retrieve
string kbNameToGet = "earth-knowledge-base";

// Get a specific knowledge base definition
var knowledgeBaseResponse = await indexClient.GetKnowledgeBaseAsync(kbNameToGet);
var kb = knowledgeBaseResponse.Value;

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

    Uma resposta de exemplo pode ser semelhante à seguinte:

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

  3. Exclua a base de dados de conhecimento ou atualize a base de dados de conhecimento para remover a fonte de conhecimento se você tiver 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

Esse recurso está atualmente em versão prévia pública. Essa visualização é fornecida sem um contrato de nível de serviço e não é recomendada para utilização em produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares para Versões Prévias do Microsoft Azure.

Use uma fonte de conhecimento de blob para indexar e consultar o conteúdo do blob do Azure em um pipeline de recuperação por meio de agentes. As fontes de conhecimento são criadas de forma independente, referenciadas em uma base de dados de conhecimento e usadas como dados de aterramento quando 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 agrupa 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 usa os objetos anteriores para conduzir o pipeline de indexação e enriquecimento.

Observação

Se o acesso do usuário for especificado no nível do documento (blob) no Armazenamento do Azure, uma fonte de conhecimento poderá levar metadados de permissão para o conteúdo indexado no Azure AI Search. Para obter mais informações, consulte metadados de permissão do ADLS Gen2 ou escopos de RBAC do Blob.

Pré-requisitos

Verificar se há fontes de conhecimento existentes

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

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

# List knowledge sources by name and type
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 por nome para revisar sua definição de 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 JSON a seguir é uma resposta de exemplo para uma fonte de dados 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

Informações confidenciais são rasuradas. Os recursos gerados aparecem no final da resposta.

Criar uma fonte de conhecimento

Execute o código a seguir para criar uma fonte de conhecimento de 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 origem

Você pode passar as seguintes propriedades para criar uma fonte de conhecimento de blobs.

Nome Description Tipo Editável Obrigatório
name O nome da fonte de conhecimento, que deve ser exclusivo na coleção de fontes de conhecimento e seguir as diretrizes de nomenclatura para objetos no Azure AI Search. String Não Yes
description Uma descrição da fonte de conhecimento. String Yes Não
encryption_key Uma chave gerenciada pelo cliente para criptografar informações confidenciais na fonte de conhecimento e nos objetos gerados. Object Yes Não
azure_blob_parameters Parâmetros específicos para fontes de conhecimento de blob: connection_string, container_name, folder_path e is_adls_gen2. Object Não
connection_string Uma cadeia de conexão baseada em chave ou, se você estiver usando uma identidade gerenciada, a ID do recurso. String Não Yes
container_name O nome do contêiner de armazenamento de blobs. String Não Yes
folder_path Uma pasta dentro do contêiner. String Não Não
is_adls_gen2 O padrão é False. Defina como True se você estiver usando uma conta de armazenamento do ADLS Gen2. booleano Não Não

ingestionParameters propriedades

Somente para fontes de conhecimento indexadas, você pode passar as propriedades a seguir ingestionParameters para controlar como o conteúdo é ingerido e processado.

Nome Description Tipo Editável Obrigatório
identity Uma identidade gerenciada a ser usada no indexador gerado. Object Yes Não
disable_image_verbalization Habilita ou desabilita o uso da verbalização de imagem. O padrão é False, que permite a verbalização da imagem. Defina para True para desabilitar a verbalização da imagem. booleano Não Não
chat_completion_model Um modelo de conclusão de chat que verbaliza imagens ou extrai conteúdo. Os modelos com suporte 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 habilidade do Prompt do GenAI será incluída no conjunto de habilidades gerado. Definir esse parâmetro também requer que disable_image_verbalization seja definido como False. Object Somente api_key e deployment_name são editáveis Não
embedding_model Um modelo de inserção de texto que vetorializa o conteúdo de texto e imagem durante a indexação e no momento da consulta. Os modelos com suporte são text-embedding-ada-002, text-embedding-3-smalle text-embedding-3-large. A habilidade do Azure OpenAI Embedding será incluída no conjunto de habilidades gerado e o vetor do Azure OpenAI será incluído no índice gerado. Object Somente api_key e deployment_name são editáveis Não
content_extraction_mode Controla como o conteúdo é extraído dos arquivos. O padrão é minimal, que usa a extração de conteúdo padrão para texto e imagens. Defina como standard para quebra e quebra de documentos avançadas usando a habilidade de Compreensão de Conteúdo do Azure, que será incluída no conjunto de habilidades gerado. Somente para standard, os parâmetros ai_services e asset_store são especificáveis. String Não Não
ai_services Um recurso do Microsoft Foundry para acessar o Azure Content Understanding nas Ferramentas Foundry. Definir esse parâmetro requer que content_extraction_mode seja definido como standard. Object Somente api_key é editável Yes
asset_store Um contêiner de blob para armazenar imagens extraídas. Definir esse parâmetro requer que content_extraction_mode seja definido como standard. Object Não Não
ingestion_schedule Adiciona informações de agendamento ao indexador gerado. Você também pode adicionar um agendamento posteriormente para automatizar a atualização de dados. Object Yes Não
ingestion_permission_options As permissões de documento para ingerir de fontes de conhecimento selecionadas: ADLS Gen2 ou SharePoint indexado. Se você especificar user_ids, group_idsou rbac_scope, o indexador do ADLS Gen2 gerado ou o indexador do SharePoint incluirá as permissões ingeridas. Array Não Não

Verificar o status da ingestão

Execute o código a seguir para monitorar o progresso e a integridade da ingestão, incluindo o status do indexador para fontes de conhecimento que geram um pipeline de indexador 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 para uma solicitação que inclui parâmetros de ingestão e está ingerindo conteúdo ativamente pode ser semelhante ao exemplo a seguir.

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

Examinar os objetos criados

Ao criar uma fonte de conhecimento de blob, seu serviço de pesquisa também cria um indexador, índice, conjunto de habilidades e fonte de dados. Não recomendamos que você edite esses objetos, pois a introdução de um erro ou incompatibilidade pode interromper 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.

É recomendável 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 obter conteúdo pesquisável. Use o Gerenciador de Pesquisa para executar consultas.
  3. Verifique o conjunto de habilidades para saber como o conteúdo é agrupado e, opcionalmente, vetorizado.
  4. Verifique a fonte de dados para obter detalhes da conexão. Nosso exemplo usa chaves de API para simplificar, mas você pode usar a ID do Microsoft Entra para autenticação e controle de acesso baseado em função para autorização.

Atribuir a uma base de dados de conhecimento

Se você estiver satisfeito com a fonte de conhecimento, prossiga para a próxima etapa: especifique a fonte de conhecimento em uma base de dados de conhecimento.

Depois que a base de dados de conhecimento estiver configurada, use a ação de recuperação para consultar a fonte de conhecimento.

Excluir uma fonte de conhecimento

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

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

Para excluir uma fonte de conhecimento:

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

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

    Uma resposta de exemplo pode ser semelhante à seguinte:

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

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

    # Get a knowledge base definition
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))

    Uma resposta de exemplo pode ser semelhante à seguinte:

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

  3. Exclua a base de dados de conhecimento ou atualize a base de dados de conhecimento para remover a fonte de conhecimento se você tiver 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

Esse recurso está atualmente em versão prévia pública. Essa visualização é fornecida sem um contrato de nível de serviço e não é recomendada para utilização em produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares para Versões Prévias do Microsoft Azure.

Use uma fonte de conhecimento de blob para indexar e consultar o conteúdo do blob do Azure em um pipeline de recuperação por meio de agentes. As fontes de conhecimento são criadas de forma independente, referenciadas em uma base de dados de conhecimento e usadas como dados de aterramento quando 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 agrupa 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 usa os objetos anteriores para conduzir o pipeline de indexação e enriquecimento.

Observação

Se o acesso do usuário for especificado no nível do documento (blob) no Armazenamento do Azure, uma fonte de conhecimento poderá levar metadados de permissão para o conteúdo indexado no Azure AI Search. Para obter mais informações, consulte metadados de permissão do ADLS Gen2 ou escopos de RBAC do Blob.

Pré-requisitos

Verificar se há fontes de conhecimento existentes

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

Use 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 por nome para revisar sua definição de JSON.

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

O JSON a seguir é uma resposta de exemplo para uma fonte de dados 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

Informações confidenciais são rasuradas. 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 do tipo 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 origem

Você pode passar as seguintes propriedades para criar uma fonte de conhecimento de blobs.

Nome Description Tipo Editável Obrigatório
name O nome da fonte de conhecimento, que deve ser exclusivo na coleção de fontes de conhecimento e seguir as diretrizes de nomenclatura para objetos no Azure AI Search. String Não Yes
kind O tipo de fonte de conhecimento, que é azureBlob neste caso. String Não Yes
description Uma descrição da fonte de conhecimento. String Yes Não
encryptionKey Uma chave gerenciada pelo cliente para criptografar informações confidenciais na fonte de conhecimento e nos objetos gerados. Object Yes Não
azureBlobParameters Parâmetros específicos para fontes de conhecimento de blob: connectionString, containerName, folderPath e isADLSGen2. Object Não
connectionString Uma cadeia de conexão baseada em chave ou, se você estiver usando uma identidade gerenciada, a ID do recurso. String Não Yes
containerName O nome do contêiner de armazenamento de blobs. String Não Yes
folderPath Uma pasta dentro do contêiner. String Não Não
isADLSGen2 O padrão é false. Defina como true se você estiver usando uma conta de armazenamento do ADLS Gen2. booleano Não Não

ingestionParameters propriedades

Somente para fontes de conhecimento indexadas, você pode passar as propriedades a seguir ingestionParameters para controlar como o conteúdo é ingerido e processado.

Nome Description Tipo Editável Obrigatório
identity Uma identidade gerenciada a ser usada no indexador gerado. Object Yes Não
disableImageVerbalization Habilita ou desabilita o uso da verbalização de imagem. O padrão é false, que permite a verbalização da imagem. Defina para true para desabilitar a verbalização da imagem. booleano Não Não
chatCompletionModel Um modelo de conclusão de chat que verbaliza imagens ou extrai conteúdo. Os modelos com suporte 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 habilidade do Prompt do GenAI será incluída no conjunto de habilidades gerado. Definir esse parâmetro também requer que disableImageVerbalization seja definido como false. Object Somente apiKey e deploymentId são editáveis Não
embeddingModel Um modelo de inserção de texto que vetorializa o conteúdo de texto e imagem durante a indexação e no momento da consulta. Os modelos com suporte são text-embedding-ada-002, text-embedding-3-smalle text-embedding-3-large. A habilidade do Azure OpenAI Embedding será incluída no conjunto de habilidades gerado e o vetor do Azure OpenAI será incluído no índice gerado. Object Somente apiKey e deploymentId são editáveis Não
contentExtractionMode Controla como o conteúdo é extraído dos arquivos. O padrão é minimal, que usa a extração de conteúdo padrão para texto e imagens. Defina como standard para quebra e quebra de documentos avançadas usando a habilidade de Compreensão de Conteúdo do Azure, que será incluída no conjunto de habilidades gerado. Somente para standard, os parâmetros aiServices e assetStore são especificáveis. String Não Não
aiServices Um recurso do Microsoft Foundry para acessar o Azure Content Understanding nas Ferramentas Foundry. Definir esse parâmetro requer que contentExtractionMode seja definido como standard. Object Somente apiKey é editável Yes
assetStore Um contêiner de blob para armazenar imagens extraídas. Definir esse parâmetro requer que contentExtractionMode seja definido como standard. Object Não Não
ingestionSchedule Adiciona informações de agendamento ao indexador gerado. Você também pode adicionar um agendamento posteriormente para automatizar a atualização de dados. Object Yes Não
ingestionPermissionOptions As permissões de documento para ingerir de fontes de conhecimento selecionadas: ADLS Gen2 ou SharePoint indexado. Se você especificar userIds, groupIdsou rbacScope, o indexador do ADLS Gen2 gerado ou o indexador do SharePoint incluirá as permissões ingeridas. Array Não Não

Verificar o status da ingestão

Use Fontes de Conhecimento - Status (API REST) para monitorar o progresso e a saúde da ingestão, incluindo o status do indexador para fontes de conhecimento que geram um pipeline de indexação 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 para uma solicitação que inclui parâmetros de ingestão e está ingerindo conteúdo ativamente pode ser semelhante ao exemplo a seguir.

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

Examinar os objetos criados

Ao criar uma fonte de conhecimento de blob, seu serviço de pesquisa também cria um indexador, índice, conjunto de habilidades e fonte de dados. Não recomendamos que você edite esses objetos, pois a introdução de um erro ou incompatibilidade pode interromper 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.

É recomendável 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 obter conteúdo pesquisável. Use o Gerenciador de Pesquisa para executar consultas.
  3. Verifique o conjunto de habilidades para saber como o conteúdo é agrupado e, opcionalmente, vetorizado.
  4. Verifique a fonte de dados para obter detalhes da conexão. Nosso exemplo usa chaves de API para simplificar, mas você pode usar a ID do Microsoft Entra para autenticação e controle de acesso baseado em função para autorização.

Atribuir a uma base de dados de conhecimento

Se você estiver satisfeito com a fonte de conhecimento, prossiga para a próxima etapa: especifique a fonte de conhecimento em uma base de dados de conhecimento.

Depois que a base de dados de conhecimento estiver configurada, use a ação de recuperação para consultar a fonte de conhecimento.

Excluir uma fonte de conhecimento

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

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

Para excluir uma fonte de conhecimento:

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

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

    Uma resposta de exemplo pode ser semelhante à seguinte:

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

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

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

    Uma resposta de exemplo pode ser semelhante à seguinte:

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

  3. Exclua a base de dados de conhecimento ou atualize a base de dados de conhecimento removendo a fonte de conhecimento se você tiver várias 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