Compartilhar via

Criar uma fonte de conhecimento de blob

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.

Uma fonte de conhecimento de blob especifica todas as informações necessárias para indexar e consultar conteúdo de blob multimodal do Azure em um pipeline por meio de agente da Pesquisa de IA do Azure. Ela é criada de forma independente e, em seguida, referenciada por um agente de conhecimento e usada no momento da consulta quando um agente ou chatbot chama uma ação de recuperação.

Em contraste com 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 (um contêiner de blob) além de modelos e propriedades que são usadas para criar um pipeline de enriquecimento inteiro:

  • A fonte de dados gerada especifica o contêiner de blob
  • O conjunto de habilidades gerado agrupa e vetoriza o conteúdo multimodal
  • O índice gerado armazena conteúdo indexado e atende aos critérios de recuperação por meio de agentes
  • O indexador gerado impulsiona o pipeline de indexação e enriquecimento

O índice gerado fornece o conteúdo usado por um agente de conhecimento.

As fontes de conhecimento são novas na versão 2025-08-01-preview.

Pré-requisitos

Para experimentar os exemplos neste artigo, recomendamos o Visual Studio Code com um cliente REST para enviar chamadas à API REST de prévia para a Pesquisa de IA do Azure. Não há suporte no portal atualmente.

Verificar se há fontes de conhecimento existentes

Uma fonte de conhecimento é um objeto reutilizável de nível superior. Todas as fontes de conhecimento devem ser nomeadas exclusivamente na coleção de fontes de conhecimento. É útil conhecer as fontes de conhecimento existentes para reutilização ou para nomear novos objetos.

A solicitação a seguir lista as fontes de conhecimento por nome e tipo.

# List knowledge sources by name and type
GET {{search-url}}/knowledgeSources?api-version=2025-08-01-preview&$select=name,kind
api-key: {{api-key}}
Content-Type: application/json

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-08-01-preview
api-key: {{api-key}}
Content-Type: application/json

Uma resposta para a fonte de conhecimento de blob pode ser semelhante ao exemplo a seguir.

{
  "name": "earth-at-night-blob-ks",
  "kind": "azureBlob",
  "description": "This knowledge source pull from a blob storage container containing pages from the Earth at Night PDF.",
  "encryptionKey": null,
  "searchIndexParameters": null,
  "azureBlobParameters": {
    "connectionString": "<REDACTED>",
    "folderPath": null,
    "disableImageVerbalization": null,
    "identity": null,
    "embeddingModel": {
      "name": "demo-blob-embedding-vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "<REDACTED>",
        "deploymentId": "text-embedding-ada-002",
        "apiKey": "<REDACTED>",
        "modelName": "text-embedding-ada-002",
        "authIdentity": null
      },
      "customWebApiParameters": null,
      "aiServicesVisionParameters": null,
      "amlParameters": null
    },
    "chatCompletionModel": {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "<REDACTED>",
        "deploymentId": "gpt-4o-mini",
        "apiKey": "<REDACTED>",
        "modelName": "gpt-4o-mini",
        "authIdentity": null
      }
    },
    "ingestionSchedule": null,
    "createdResources": {
      "datasource": "earth-at-night-blob-ks-datasource",
      "indexer": "earth-at-night-blob-ks-indexer",
      "skillset": "earth-at-night-blob-ks-skillset",
      "index": "earth-at-night-blob-ks-index"
    }
  },
  "webParameters": null
}

Observação

Informações confidenciais são rasuradas. Os recursos gerados aparecem no final da resposta. A propriedade webParameters não está operacional nesta versão prévia e está reservada para uso futuro.

Criar uma fonte de conhecimento

Para criar uma fonte de conhecimento, use a API REST do plano de dados 2025-08-01-preview ou um pacote de visualização do SDK do Azure que fornece funcionalidade equivalente.

Uma fonte de conhecimento pode conter exatamente uma das seguintes opções: searchIndexParametersouazureBlobParameters. A propriedade webParameters não tem suporte nesta versão. Se você especificar azureBlobParameters, então searchIndexParameters deve ser nulo.

Para azureBlobParameters:

  • Fornecer uma conexão com a Pesquisa de IA do Azure
  • Fornecer uma cadeia de conexão de acesso completo para o Armazenamento do Microsoft Azure e o nome do contêiner
  • Forneça um modelo de incorporação de texto. Esse modelo é usado para vetorizar conteúdo de texto durante indexação e consultas.
  • Forneça um modelo de conclusão de chat usado para descrever o conteúdo da imagem.
  • Forneça uma chave de criptografia para criptografar informações confidenciais duplamente nesta fonte de conhecimento e nos recursos gerados.

Os modelos são referenciados no conjunto de habilidades e como vetor para codificar cadeias de caracteres de texto no momento da consulta.

Uma fonte de conhecimento de blob pode incluir uma ingestionSchedule que adiciona informações de agendamento a um indexador. Você também pode adicionar um agendamento mais tarde se quiser automatizar a atualização de dados

  1. Use a API REST Criar ou atualizar fonte de conhecimento de prévia.

  2. Defina variáveis de ambiente na parte superior do arquivo.

    @search-url=<YOUR SEARCH SERVICE URL>
@api-key=<YOUR SEARCH ADMIN API KEY>
@connection-string=<YOUR FULL ACCESS CONNECTION STRING TO AZURE STORAGE>
@aoai-endpoint=<YOUR AZURE OPENAI ENDPOINT>
@aoai-key=<YOUR AZURE OPENAI API KEY>

  3. Formule a solicitação e depois Envie.

    PUT {{search-url}}/knowledgeSources/earth-at-night-blob-ks?api-version=2025-08-01-preview
api-key: {{api-key}}
Content-Type: application/json

{
  "name": "earth-at-night-blob-ks",
  "kind": "azureBlob",
  "description": "This knowledge source pull from a blob storage container containing pages from the Earth at Night PDF.",
  "encryptionKey": null,
  "azureBlobParameters": {
    "connectionString": "{{connection-string}}",
    "containerName": "nasa-ebook",
    "folderPath": null,
    "disableImageVerbalization": null,
    "identity": null,
    "embeddingModel": {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "{{aoai-endpoint}}",
        "deploymentId": "text-embedding-3-small",
        "apiKey": "{{aoai-key}}",
        "modelName": "text-embedding-3-small",
        "authIdentity": null
      },
      "customWebApiParameters": null,
      "aiServicesVisionParameters": null,
      "amlParameters": null
    },
    "chatCompletionModel": {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "{{aoai-endpoint}}",
        "deploymentId": "gpt-4o-mini",
        "apiKey": "{{aoai-key}}",
        "modelName": "gpt-4o-mini",
        "authIdentity": null
      }
    },
    "ingestionSchedule": {
      "interval": "P1D",
      "startTime": "2025-01-07T19:30:00Z"
    }
  }
}

Se surgir algum erro, verifique se o modelo de incorporação e os modelos de preenchimento de chat existem no ponto de extremidade fornecido.

Verificar saída

Quando você cria uma fonte de conhecimento de blob, o serviço de pesquisa também cria os seguintes objetos: um indexador, uma fonte de dados, um conjunto de habilidades e um índice. Tenha cuidado ao editar esses objetos porque você pode interromper o pipeline se introduzir um erro ou incompatibilidade.

A resposta na criação da fonte de dados de conhecimento lista os recursos criados. Os objetos são criados de acordo com um modelo fixo e a nomenclatura é baseada na 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.

  1. Verifique se há mensagens de sucesso ou falha no indexador. Erros de conexão ou cota aparecem aqui. Se o indexador falhar, tente redefinir e executar novamente.

  2. Verifique o índice para obter conteúdo pesquisável. Use o Gerenciador de Pesquisa para executar suas consultas.

  3. Verifique o conjunto de habilidades para saber mais sobre como seu conteúdo é agrupado e vetorizado.

  4. Modifique a fonte de dados se quiser alterar os detalhes da conexão, como autenticação e autorização. O exemplo usa chaves de API para simplificar, mas você pode usar a autenticação do Microsoft Entra ID e o acesso baseado em função.

Atribuir a um agente de conhecimento

Se você estiver satisfeito com o índice, prossiga para a próxima etapa: especifique a fonte de conhecimento em um agente de conhecimento.

No agente de conhecimento, há mais propriedades a serem definidas na fonte de conhecimento específicas para operações de consulta.

Depois que o agente de conhecimento for configurado, use a ação de recuperação para consultar a fonte de conhecimento.

Excluir uma fonte de conhecimento

Se você não precisar mais da fonte de conhecimento ou se precisar recria-la no serviço de pesquisa, use essa solicitação para excluir o objeto atual.

# Delete agent
DELETE {{search-url}}/knowledgeSources/{{ks-name}}?api-version=2025-08-01-preview
api-key: {{api-key}}

Importante

Antes de excluir uma fonte de conhecimento, primeiro você deve atualizar o agente de conhecimento para remover todas as referências à fonte de conhecimento.

Excluir uma fonte de conhecimento de blob também exclui os objetos que ela criou. O indexador, a fonte de dados, o conjunto de habilidades e o índice são excluídos automaticamente quando a fonte de conhecimento do blob é excluída.

Saiba Mais