Compartilhar via

Criar um agente de conhecimento no Azure AI Search

Note

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.

Na Pesquisa de IA do Azure, um agente de conhecimento é um recurso de nível superior que representa uma conexão com um modelo de conclusão de chat para uso em cargas de trabalho de recuperação agente. Um agente de conhecimento é usado pelo método de recuperação em um pipeline de recuperação de informações alimentado por LLM.

Um agente de conhecimento especifica:

  • Uma fonte de conhecimento (uma ou mais) que aponta para um conteúdo pesquisável
  • Um modelo de conclusão de chat que fornece recursos de raciocínio para planejamento de consultas e formulação de resposta
  • Propriedades para otimização de desempenho (restringir o tempo de processamento da consulta)

Depois de criar um agente de conhecimento, você pode atualizar suas propriedades a qualquer momento. Se o agente de conhecimento estiver em uso, as atualizações entrarão em vigor no próximo trabalho.

Important

2025-08-01-preview apresenta alterações significativas para agentes de conhecimento existentes. Esta versão de visualização requer uma ou mais knowledgeSource definições. Recomendamos migrar o código existente para as novas APIs assim que possível.

Prerequisites

Para seguir as etapas neste guia, recomendamos o Visual Studio Code com um cliente REST para enviar chamadas prévias da API REST para o Azure AI Search. T

Implantar um modelo para recuperação de agente

Verifique se você tem um modelo com suporte que o Azure AI Search pode acessar. As instruções a seguir pressupõem o Modelo de Descoberta de IA do Azure como o provedor.

  1. Entre no portal do Azure AI Foundry.

  2. Implante um modelo com suporte usando estas instruções.

  3. Verifique se a identidade gerenciada do serviço de pesquisa tem permissões de usuário dos Serviços Cognitivos no recurso Azure OpenAI.

    Se você estiver testando localmente, também precisará de permissões de usuário dos Serviços Cognitivos .

Modelos com suporte

Use o Azure OpenAI ou um modelo de software livre equivalente:

  • gpt-4o
  • gpt-4o-mini
  • gpt-4.1
  • gpt-4.1-nano
  • gpt-4.1-mini

Configurar o acesso

O Azure AI Search precisa de acesso ao modelo de conclusão do chat. Você pode usar a autenticação baseada em chave ou de função (recomendado).

Usar autenticação baseada em função

Se você estiver usando a autenticação baseada em função, em seu recurso do Azure OpenAI, atribua a função de Usuário dos Serviços Cognitivos a uma identidade gerenciada do serviço de pesquisa.

No Azure, você deve ter permissões de Proprietário ou Administrador de Acesso de Usuário no provedor de modelo para atribuir funções.

  1. Configurar a Pesquisa de IA do Azure para usar uma identidade gerenciada.

  2. Em seu provedor de modelo, como o Modelo da Fábrica, crie uma atribuição de função que forneça permissões de Usuário dos Serviços Cognitivos de identidade gerenciada do serviço de pesquisa. Se estiver testando localmente, atribua essa função a si mesmo.

  3. Para testes locais, siga as etapas no Início Rápido: conecte-se sem chaves para obter um token de acesso pessoal e garantir que você esteja conectado a uma assinatura e locatário específicos. Cole seu token de identidade pessoal na @accessToken variável. Uma solicitação que se conecta usando sua identidade pessoal deve ser semelhante ao exemplo a seguir:

    @search-url=<YOUR SEARCH SERVICE URL>
@accessToken=<YOUR PERSONAL ID>

# List Indexes
GET https://{{search-url}}/indexes?api-version=2025-08-01-preview
Authorization: Bearer {{accessToken}}

Important

Se você usar a autenticação baseada em função, remova todas as referências à chave de API em suas solicitações. Em uma solicitação que especifica ambas as abordagens, a chave de API é usada em vez de funções.

Usar a autenticação baseada em chave

Você pode usar chaves de API se não tiver permissão para criar atribuições de função.

  1. Copie uma chave de API de administrador do Azure AI Search e cole-a como uma api-key variável em seu arquivo HTTP ou REST: @api-key.

  2. Especifique uma chave de API em cada solicitação. Uma solicitação que se conecta usando uma chave de API deve ser semelhante ao exemplo a seguir:

     @search-url=<YOUR SEARCH SERVICE URL>
 @search-api-key=<YOUR SEARCH SERVICE ADMIN API KEY>

# List Indexes
GET {{search-url}}/indexes?api-version=2025-08-01-preview
   Content-Type: application/json
   @api-key: {{search-api-key}}

Verificar se há agentes de conhecimento existentes

A solicitação a seguir lista os agentes de conhecimento por nome. Na coleção de agentes de conhecimento, todos os agentes de conhecimento devem ter nomes únicos. É útil saber mais sobre os agentes de conhecimento existentes para reutilização ou para nomear novos agentes.

# List knowledge agents
GET {{search-url}}/agents?api-version=2025-08-01-preview
   Content-Type: application/json
   Authorization: Bearer {{accessToken}}

Você também pode retornar um único agente pelo nome para revisar sua definição de JSON.

# Get knowledge agent
GET {{search-url}}/agents/{{agent-name}}?api-version=2025-08-01-preview
   Content-Type: application/json
   Authorization: Bearer {{accessToken}}

Criar um agente de conhecimento

Um agente de conhecimento conduz o pipeline de recuperação agente. No código do aplicativo, ele é chamado por outros agentes ou chat bots.

Sua composição consiste em conexões entre fontes de conhecimento (conteúdo pesquisável) e modelos de conclusão de chat que você implantou no Azure OpenAI. As propriedades no modelo estabelecem a conexão. As propriedades na fonte de conhecimento estabelecem padrões que informam a execução da consulta e a resposta.

Para criar um agente, 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.

@search-url=<YOUR SEARCH SERVICE URL>
@agent-name=<YOUR AGENT NAME>
@index-name=<YOUR INDEX NAME>
@model-provider-url=<YOUR AZURE OPENAI RESOURCE URI>
@model-api-key=<YOUR AZURE OPENAI API KEY>
@accessToken = <a long GUID>

# Create knowledge agent
PUT {{search-url}}/agents/{{agent-name}}?api-version=2025-08-01-preview
   Content-Type: application/json
   Authorization: Bearer {{accessToken}}

{
    "name" : "{{agent-name}}",
    "description": "This knowledge agent handles questions directed at two unrelated sample indexes."
    "retrievalInstructions": "Use the hotels knowledge source only for queries about hotels or where to stay, otherwise use the earth at night knowledge source.",
    "knowledgeSources": [
        {
            "name": "earth-at-night-blob-ks",
            "alwaysQuerySource": false,
            "includeReferences": true,
            "includeReferenceSourceData": true,
            "maxSubQueries": 30,
            "rerankerThreshold": null
        },
        {
            "name": "hotels-index-ks",
            "alwaysQuerySource": false,
            "includeReferences": true,
            "includeReferenceSourceData": true,
            "maxSubQueries": 5,
            "rerankerThreshold": null
        }
    ],
    "models" : [ 
        {
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
                "resourceUri": "{{model-provider-url}}",
                "apiKey": "{{model-api-key}}",
                "deploymentId": "gpt-4o-mini",
                "modelName": "gpt-4o-mini"
            }
        }
    ],
    "outputConfiguration": {
        "modality": "extractiveData",
        "answerInstructions": "Provide a concise answer to the question.",
        "attemptFastPath": false,
        "includeActivity": true
    },
    "requestLimits": {
        "maxOutputSize": 5000,
        "maxRuntimeInSeconds": 60
    }
}

Pontos principais:

  • name deve ser exclusivo na coleção de agentes de conhecimento e seguir as diretrizes de nomenclatura para objetos no Azure AI Search.

  • description é recomendado para o planejamento de consultas. O LLM usa a descrição para informar o planejamento da consulta.

  • retrievalInstructions é recomendado para o planejamento de consultas quando você tem várias fontes de conhecimento. As instruções são passadas como um prompt para a LLM determinar se uma fonte de conhecimento deve estar no escopo de uma consulta. Esse campo influencia tanto a seleção da fonte de dados de conhecimento quanto a formulação de consulta. Por exemplo, as instruções podem acrescentar informações ou priorizar uma fonte de conhecimento. As instruções são passadas diretamente para a LLM, o que significa que é possível fornecer instruções que interrompem o planejamento de consultas (por exemplo, se as instruções resultarem em ignorar uma fonte de conhecimento essencial). Se você definir retrievalInstructions, certifique-se de que alwaysQuerySource está definido como false.

  • knowledgeSources é necessário para a criação do agente de conhecimento. Ele especifica os índices de pesquisa ou blobs do Azure usados pelo agente de conhecimento. Novo nesta versão prévia, a knowledgeSources matriz é uma matriz e substitui a matriz anterior targetIndexes .

    • name é uma referência a uma fonte de conhecimento de índice de pesquisa ou a uma fonte de conhecimento de blob.

    • alwaysQuerySource é um booliano que especifica se uma fonte de conhecimento deve ser sempre usada (true) ou usada somente se a etapa de planejamento de consulta determinar que ela é útil. O padrão é falso, o que significa que a seleção de origem pode ignorar essa fonte se o modelo não achar que a consulta precisa dela. Descrições de origem e instruções de recuperação são usadas nesta avaliação. Se você estiver usando attemptFastPath uma fonte de conhecimento específica, alwaysQuerySource deverá ser definido como true.

    • includeReferences é um booliano que determina se a parte de referência da resposta inclui dados de origem. Recomendamos começar com esse valor definido como true se você quiser moldar sua própria resposta usando a saída do mecanismo de pesquisa. Caso contrário, se você quiser usar a saída na cadeia de caracteres de resposta content , poderá defini-la como false.

    • maxSubQueries é o número máximo de consultas que a etapa de planejamento de consulta gerará. Cada consulta pode retornar até 50 documentos, que são reclassificados pelo classificador semântico. A maxSubQueries propriedade deve estar entre 2 e 40.

    • rerankerThreshold é a pontuação mínima de reclassificador semântico aceitável para inclusão em uma resposta. As pontuações de reclassificação vão de 1 a 4. Planeje revisar esse valor com base no teste e no que funciona para seu conteúdo.

  • models especifica uma ou mais conexões com um modelo gpt-4o ou gpt-4o-mini existente. Atualmente nesta versão prévia, os modelos podem conter apenas um modelo e o provedor de modelos deve ser o Azure OpenAI. Obtenha informações de modelo do portal do Azure AI Foundry ou de uma solicitação de linha de comando. Você pode usar o controle de acesso baseado em função em vez de chaves de API para a conexão do Azure AI Search com o modelo. Para obter mais informações, consulte Como implantar modelos do Azure OpenAI com o Azure AI Foundry.

  • outputConfiguration fornece controle sobre a lógica de execução de consulta e a saída.

    • modality determina a forma dos resultados. Os valores válidos são extractiveData (padrão) ou answerSynthesis (consulte Usar síntese de resposta para respostas com backup de citação).

    • answerInstructions é usado para formatação de respostas (consulte Usar síntese de resposta para respostas com backup de citação). O padrão é nulo.

    • attemptFastPath é um booliano que pode ser usado para habilitar um caminho rápido para a execução da consulta. Se trueo mecanismo de pesquisa ignorar o planejamento de consultas se a consulta for menor que 512 caracteres e a pontuação do classificador semântico na consulta pequena estiver acima de 1,9, indicando relevância suficiente. Se a consulta for maior ou a pontuação for menor, o planejamento de consulta será invocado. Você deve ter pelo menos uma fonte de conhecimento habilitada alwaysQuerySource . Se houver várias fontes de conhecimento, todas elas deverão ter alwaysQuerySource habilitado para serem consideradas para um caminho rápido. A consulta pequena é executada em todas elas. O padrão é false.

    • includeActivity indica se os resultados da recuperação devem incluir o plano de consulta. O padrão é true.

  • requestLimits define limites numéricos sobre o processamento de consulta.

    • maxOutputSize é o número máximo de tokens na cadeia de caracteres de resposta content , com 5.000 tokens como o valor mínimo e recomendado, e nenhum máximo explícito. As correspondências mais relevantes são preservadas, mas a resposta geral é truncada no último documento completo para se ajustar ao orçamento do token.

    • maxRuntimeInSeconds define a quantidade máxima de tempo de processamento para toda a solicitação, inclusive do Azure OpenAI e do Azure AI Search.

  • encryptionKey é opcional. Inclua uma definição de chave de criptografia se você estiver complementando com chaves gerenciadas pelo cliente.

Consultar o agente de conhecimento

Chame a ação de recuperação no objeto do agente de conhecimento para confirmar a conexão do modelo e retornar uma resposta. 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 para essa tarefa.

Substitua "onde o oceano parece verde?" por uma cadeia de caracteres de consulta válida para o índice de pesquisa.

# Send grounding request
POST {{search-url}}/agents/{{agent-name}}/retrieve?api-version=2025-08-01-preview
   Content-Type: application/json
   Authorization: Bearer {{accessToken}}

{
  "messages" : [
        { "role" : "assistant",
                "content" : [
                  { "type" : "text", "text" : "Use the earth at night index to answer the question. If you can't find relevant content, say you don't know." }
                ]
        },
        {
            "role" : "user",
            "content" : [
                {
                    "text" : "where does the ocean look green?",
                    "type" : "text"
                }
            ]
        }
    ],
  "knowledgeSourceParams": [
    {
      "filterAddOn": null,
      "knowledgeSourceName": "earth-at-night-blob-ks",
      "kind": "searchIndex"
    }
  ]
}

mensagens são necessárias, mas você pode executar este exemplo usando apenas a função de "usuário" que fornece a consulta.

knowledgeSourceParams é opcional. Especifique uma fonte de conhecimento se o agente estiver configurado para várias fontes e você quiser concentrar a ação de recuperação em apenas uma delas.

Uma especificação de fonte de conhecimento na ação de recuperação descreve o índice de pesquisa de destino no serviço de pesquisa. Portanto, mesmo que a fonte de conhecimento "kind" seja o blob do Azure, o valor válido aqui será searchIndex. Nesta primeira versão de visualização pública, knowledgeSourceParams.kind é sempre searchIndex.

A resposta à consulta anterior pode ter esta aparência:

  "response": [
    {
      "content": [
        {
          "type": "text",
          "text": "The ocean appears green off the coast of Antarctica due to phytoplankton flourishing in the water, particularly in Granite Harbor near Antarctica’s Ross Sea, where they can grow in large quantities during spring, summer, and even autumn under the right conditions [ref_id:0]. Additionally, off the coast of Namibia, the ocean can also look green due to blooms of phytoplankton and yellow-green patches of sulfur precipitating from bacteria in oxygen-depleted waters [ref_id:1]. In the Strait of Georgia, Canada, the waters turned bright green due to a massive bloom of coccolithophores, a type of phytoplankton [ref_id:5]. Furthermore, a milky green and blue bloom was observed off the coast of Patagonia, Argentina, where nutrient-rich waters from different currents converge [ref_id:6]. Lastly, a large bloom of cyanobacteria was captured in the Baltic Sea, which can also give the water a green appearance [ref_id:9]."
        }
      ]
    }
  ],

Para obter mais informações sobre a API de recuperação e a forma da resposta, consulte Recuperar dados usando um agente de conhecimento no Azure AI Search.

Excluir um agente

Se você não precisar mais do agente ou se precisar reconstruí-lo no serviço de pesquisa, use esta solicitação para excluir o objeto atual.

# Delete agent
DELETE {{search-url}}/agents/{{agent-name}}?api-version=2025-08-01-preview
   Authorization: Bearer {{accessToken}}

Conteúdo relacionado