Criar uma base de dados de conhecimento no Azure AI Search

No Azure AI Search, uma base de conhecimento é um objeto de nível superior que orquestra a recuperação ativa. Ele define quais fontes de conhecimento consultar e o comportamento padrão para operações de recuperação. No momento da consulta, o método recuperar tem como alvo a base de dados de conhecimento para executar o pipeline de recuperação configurado.

Você pode criar uma base de conhecimento em uma carga de trabalho do IQ do Foundry no portal do Microsoft Foundry (novo). Você também precisa de uma base de dados de conhecimento em qualquer solução agente criada usando as APIs do Azure AI Search.

Uma base de dados de conhecimento especifica:

• Uma ou mais fontes de conhecimento que apontam para conteúdo pesquisável.
• Uma LLM opcional que fornece recursos de raciocínio para planejamento de consultas e formulação de resposta.
• Um esforço de raciocínio de recuperação que determina se um LLM é invocado e gerencia custo, latência e qualidade.
• Propriedades personalizadas que controlam roteamento, seleção de origem, formato de saída e criptografia de objeto.

Depois de criar uma base de dados de conhecimento, você pode atualizar suas propriedades a qualquer momento. Se a base de conhecimento estiver em uso, as atualizações entrarão em vigor na próxima recuperação.

Pré-requisitos

• Azure AI Search em qualquer região com recuperação por agente. Você deve ter o classificador semântico habilitado. Se você estiver usando uma identidade gerenciada para acesso baseado em função a modelos implantados, o serviço de pesquisa deverá estar no tipo de preço Básico ou superior.

• Serviço OpenAI do Azure com uma implantação de LLM com suporte.

• Uma ou mais fontes de conhecimento em seu serviço de pesquisa.

• Permissão para criar e usar objetos no Azure AI Search. Recomendamos o acesso baseado em função. O Colaborador do Serviço de Pesquisa pode criar e gerenciar uma base de dados de conhecimento. O Leitor de Dados do Índice de Pesquisa pode executar consultas. Como alternativa, você poderá usar chaves de API se uma atribuição de função não for viável. Para obter mais informações, consulte Conectar-se a um serviço de pesquisa.

• A versão prévia mais recente da azure-search-documents biblioteca de clientes para Python.

Modelos com suporte

Use uma das SEGUINTEs LLMs do Azure OpenAI ou um modelo de software livre equivalente. Para obter instruções de implantação, consulte Implantar modelos do Azure OpenAI com o Microsoft Foundry.

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

Configurar o acesso

O Azure AI Search precisa de acesso à LLM do Azure OpenAI. Recomendamos o Microsoft Entra ID para autenticação e acesso baseado em função para autorização. Para atribuir funções, você deve ser um Proprietário ou Administrador de Acesso do Usuário. Se você não puder usar funções, use a autenticação baseada em chave.

Verificar se há bases de dados de conhecimento existentes

Saber sobre as bases de dados de conhecimento existentes é útil para reutilizá-las ou nomear novos objetos. Qualquer agente de conhecimento 2025-08-01-preview será retornado na coleção de bases de dados de conhecimento.

Execute o código a seguir para listar as bases de dados de conhecimento existentes por nome.

// List knowledge bases by name
  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}");
  }

Você também pode retornar uma única base de dados 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 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);

O JSON a seguir é um exemplo de uma base de dados de conhecimento.

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

Como criar uma base de dados de conhecimento

Uma base de dados de conhecimento impulsiona o pipeline de recuperação por meio de agentes. No código do aplicativo, ele é chamado por outros agentes ou chatbots.

Uma base de dados de conhecimento conecta fontes de conhecimento (conteúdo pesquisável) a uma implantação de LLM do Azure OpenAI. As propriedades no LLM estabelecem a conexão, enquanto as propriedades na fonte de conhecimento estabelecem padrões que informam a execução da consulta e a resposta.

Execute o código a seguir para criar uma base de dados de conhecimento.

using Azure.Search.Documents.Indexes.Models;
using Azure.Search.Documents.KnowledgeBases.Models;

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

// Create a knowledge base
var knowledgeBase = new KnowledgeBase(
    name: knowledgeBaseName,
    knowledgeSources: new KnowledgeSourceReference[] { new KnowledgeSourceReference(knowledgeSourceName) }
)
{
    RetrievalReasoningEffort = new KnowledgeRetrievalLowReasoningEffort(),
    OutputMode = KnowledgeRetrievalOutputMode.AnswerSynthesis,
    Models = { model }
};
await indexClient.CreateOrUpdateKnowledgeBaseAsync(knowledgeBase);
Console.WriteLine($"Knowledge base '{knowledgeBaseName}' created or updated successfully.");

# Create a knowledge base
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 aoaiParams = new AzureOpenAIVectorizerParameters
{
    ResourceUri = new Uri(aoaiEndpoint),
    DeploymentName = aoaiGptDeployment,
    ModelName = aoaiGptModel
};

var knowledgeBase = new KnowledgeBase(
    name: "my-kb",
    knowledgeSources: new KnowledgeSourceReference[] 
    { 
        new KnowledgeSourceReference("hotels-sample-knowledge-source"),
        new KnowledgeSourceReference("earth-knowledge-source")
    }
)
{
    Description = "This knowledge base handles questions directed at two unrelated sample indexes.",
    RetrievalInstructions = "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
    AnswerInstructions = "Provide a two sentence concise and informative answer based on the retrieved documents.",
    OutputMode = KnowledgeRetrievalOutputMode.AnswerSynthesis,
    Models = { new KnowledgeBaseAzureOpenAIModel(azureOpenAIParameters: aoaiParams) },
    RetrievalReasoningEffort = new KnowledgeRetrievalLowReasoningEffort()
};

await indexClient.CreateOrUpdateKnowledgeBaseAsync(knowledgeBase);
Console.WriteLine($"Knowledge base '{knowledgeBase.Name}' created or updated successfully.");

Propriedades da base de dados de conhecimento

Passe as propriedades a seguir para criar uma base de dados de conhecimento.

Consultar uma base de dados de conhecimento

Configure as instruções e as mensagens a serem enviadas para a LLM.

string instructions = @"
Use the earth at night index to answer the question. If you can't find relevant content, say you don't know.
";

var messages = new List<Dictionary<string, string>>
{
    new Dictionary<string, string>
    {
        { "role", "system" },
        { "content", instructions }
    }
};

Chame a ação retrieve na base de dados de conhecimento para verificar a conexão LLM e retornar resultados. Para obter mais informações sobre o retrieve esquema de solicitação e resposta, consulte Recuperar dados usando uma base de dados de conhecimento no Azure AI Search.

Substitua "Onde o oceano parece verde?" por uma cadeia de caracteres de consulta válida para suas fontes de conhecimento.

using Azure.Search.Documents.KnowledgeBases;
using Azure.Search.Documents.KnowledgeBases.Models;

var baseClient = new KnowledgeBaseRetrievalClient(
    endpoint: new Uri(searchEndpoint),
    knowledgeBaseName: knowledgeBaseName,
    tokenCredential: new DefaultAzureCredential()
);

messages.Add(new Dictionary<string, string>
{
    { "role", "user" },
    { "content", @"Where does the ocean look green?" }
});

var retrievalRequest = new KnowledgeBaseRetrievalRequest();
foreach (Dictionary<string, string> message in messages) {
    if (message["role"] != "system") {
        retrievalRequest.Messages.Add(new KnowledgeBaseMessage(content: new[] { new KnowledgeBaseMessageTextContent(message["content"]) }) { Role = message["role"] });
    }
}
retrievalRequest.RetrievalReasoningEffort = new KnowledgeRetrievalLowReasoningEffort();
var retrievalResult = await baseClient.RetrieveAsync(retrievalRequest);

messages.Add(new Dictionary<string, string>
{
    { "role", "assistant" },
    { "content", (retrievalResult.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent).Text }
});

(retrievalResult.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent).Text 

// Print the response, activity, and references
Console.WriteLine("Response:");
Console.WriteLine((retrievalResult.Value.Response[0].Content[0] as KnowledgeBaseMessageTextContent)!.Text);

Pontos principais:

• KnowledgeBaseRetrievalRequest é o contrato de entrada para a solicitação de recuperação.

• RetrievalReasoningEffort é necessário. Configurá-lo como minimal exclui os LLMs do pipeline de consulta ocorre, e apenas intenções são utilizadas na entrada da consulta. O padrão é low e dá suporte ao planejamento de consultas baseado em LLM e à síntese de resposta com mensagens e contexto.

• knowledgeSourceParams são usados para substituir parâmetros padrão no momento da consulta.

A resposta à consulta de exemplo pode ser semelhante ao exemplo a seguir:

  "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]."
        }
      ]
    }
  ]

Excluir uma base de dados de conhecimento

Se você não precisar mais da base de dados de conhecimento ou precisar recompilá-la em seu serviço de pesquisa, use essa solicitação para excluir o objeto.

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

No Azure AI Search, uma base de conhecimento é um objeto de nível superior que orquestra a recuperação ativa. Ele define quais fontes de conhecimento consultar e o comportamento padrão para operações de recuperação. No momento da consulta, o método recuperar tem como alvo a base de dados de conhecimento para executar o pipeline de recuperação configurado.

Você pode criar uma base de dados de conhecimento em uma carga de trabalho de Qi do Foundry no portal do Microsoft Foundry (novo). Você também precisa de uma base de dados de conhecimento em qualquer solução agente criada usando as APIs do Azure AI Search.

Uma base de dados de conhecimento especifica:

• Uma ou mais fontes de conhecimento que apontam para conteúdo pesquisável.
• Uma LLM opcional que fornece recursos de raciocínio para planejamento de consultas e formulação de resposta.
• Um esforço de raciocínio de recuperação que determina se um LLM é invocado e gerencia custo, latência e qualidade.
• Propriedades personalizadas que controlam roteamento, seleção de origem, formato de saída e criptografia de objeto.

Depois de criar uma base de dados de conhecimento, você pode atualizar suas propriedades a qualquer momento. Se a base de conhecimento estiver em uso, as atualizações entrarão em vigor na próxima recuperação.

Pré-requisitos

• Azure AI Search em qualquer região com recuperação por agente. Você deve ter o classificador semântico habilitado. Se você estiver usando uma identidade gerenciada para acesso baseado em função a modelos implantados, o serviço de pesquisa deverá estar no tipo de preço Básico ou superior.

• Serviço OpenAI do Azure com uma implantação de LLM com suporte.

• Uma ou mais fontes de conhecimento em seu serviço de pesquisa.

• Permissão para criar e usar objetos no Azure AI Search. Recomendamos o acesso baseado em função. O Colaborador do Serviço de Pesquisa pode criar e gerenciar uma base de dados de conhecimento. O Leitor de Dados do Índice de Pesquisa pode executar consultas. Como alternativa, você poderá usar chaves de API se uma atribuição de função não for viável. Para obter mais informações, consulte Conectar-se a um serviço de pesquisa.

• A versão prévia mais recente da azure-search-documents biblioteca de clientes para Python.

Modelos com suporte

Use uma das SEGUINTEs LLMs do Azure OpenAI ou um modelo de software livre equivalente. Para obter instruções de implantação, consulte Implantar modelos do Azure OpenAI com o Microsoft Foundry.

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

Configurar o acesso

O Azure AI Search precisa de acesso à LLM do Azure OpenAI. Recomendamos o Microsoft Entra ID para autenticação e acesso baseado em função para autorização. Você deve ser um Proprietário ou Administrador de Acesso do Usuário para atribuir funções. Se as funções não forem viáveis, use autenticação baseada em chave.

Verificar se há bases de dados de conhecimento existentes

Saber sobre bases de dados de conhecimento existentes é útil para reutilizar ou nomear novos objetos. Qualquer agente de conhecimento 2025-08-01-preview será retornado na coleção de bases de dados de conhecimento.

Execute o código a seguir para listar as bases de dados de conhecimento existentes por nome.

# List knowledge bases by name
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))

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

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

O JSON a seguir é uma resposta de exemplo para uma base de dados de conhecimento.

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

Como criar uma base de dados de conhecimento

Uma base de dados de conhecimento impulsiona o pipeline de recuperação por meio de agentes. No código do aplicativo, ele é chamado por outros agentes ou chatbots.

Uma base de dados de conhecimento conecta fontes de conhecimento (conteúdo pesquisável) a uma implantação de LLM do Azure OpenAI. As propriedades no LLM estabelecem a conexão, enquanto as propriedades na fonte de conhecimento estabelecem padrões que informam a execução da consulta e a resposta.

Execute o código a seguir para criar uma base de dados de conhecimento.

# Create a knowledge base
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import KnowledgeBase, KnowledgeBaseAzureOpenAIModel, KnowledgeSourceReference, AzureOpenAIVectorizerParameters, KnowledgeRetrievalOutputMode, KnowledgeRetrievalLowReasoningEffort

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

aoai_params = AzureOpenAIVectorizerParameters(
    resource_url = "aoai_endpoint",
    api_key="aoai_api_key",
    deployment_name = "aoai_gpt_deployment",
    model_name = "aoai_gpt_model",
)

knowledge_base = KnowledgeBase(
    name = "my-kb",
    description = "This knowledge base handles questions directed at two unrelated sample indexes.",
    retrieval_instructions = "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
    answer_instructions = "Provide a two sentence concise and informative answer based on the retrieved documents.",
    output_mode = KnowledgeRetrievalOutputMode.ANSWER_SYNTHESIS,
    knowledge_sources = [
        KnowledgeSourceReference(name = "hotels-ks"),
        KnowledgeSourceReference(name = "earth-at-night-ks"),
    ],
    models = [KnowledgeBaseAzureOpenAIModel(azure_open_ai_parameters = aoai_params)],
    encryption_key = None,
    retrieval_reasoning_effort = KnowledgeRetrievalLowReasoningEffort,
)

index_client.create_or_update_knowledge_base(knowledge_base)
print(f"Knowledge base '{knowledge_base.name}' created or updated successfully.")

Propriedades da base de dados de conhecimento

Passe as propriedades a seguir para criar uma base de dados de conhecimento.

Consultar uma base de dados de conhecimento

Chame a ação retrieve na base de dados de conhecimento para verificar a conexão LLM e retornar resultados. Para obter mais informações sobre o retrieve esquema de solicitação e resposta, consulte Recuperar dados usando uma base de dados de conhecimento no Azure AI Search.

Substitua "Onde o oceano parece verde?" por uma cadeia de caracteres de consulta válida para suas fontes de conhecimento.

# Send grounding request
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
from azure.search.documents.knowledgebases.models import KnowledgeBaseMessage, KnowledgeBaseMessageTextContent, KnowledgeBaseRetrievalRequest, SearchIndexKnowledgeSourceParams

kb_client = KnowledgeBaseRetrievalClient(endpoint = "search_url", knowledge_base_name = "knowledge_base_name", credential = AzureKeyCredential("api_key"))

request = KnowledgeBaseRetrievalRequest(
    messages=[
        KnowledgeBaseMessage(
            role = "assistant",
            content = [KnowledgeBaseMessageTextContent(text = "Use the earth at night index to answer the question. If you can't find relevant content, say you don't know.")]
        ),
        KnowledgeBaseMessage(
            role = "user",
            content = [KnowledgeBaseMessageTextContent(text = "Where does the ocean look green?")]
        ),
    ],
    knowledge_source_params=[
        SearchIndexKnowledgeSourceParams(
            knowledge_source_name = "earth-at-night-ks",
            include_references = True,
            include_reference_source_data = True,
            always_query_source = False,
        )
    ],
    include_activity = True,
)

result = kb_client.retrieve(request)
print(result.response[0].content[0].text)

Pontos principais:

• messages é necessário, mas você pode executar este exemplo usando apenas a user função que fornece a consulta.

• knowledge_source_params especifica um ou mais destinos de consulta. Para cada fonte de conhecimento, você pode especificar quantas informações incluir na saída.

A resposta à consulta de exemplo pode ser semelhante ao exemplo a seguir:

  "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]."
        }
      ]
    }
  ]

Excluir uma base de dados de conhecimento

Se você não precisar mais da base de dados de conhecimento ou precisar recompilá-la em seu serviço de pesquisa, use essa solicitação para excluir o objeto.

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

No Azure AI Search, uma base de conhecimento é um objeto de nível superior que orquestra a recuperação ativa. Ele define quais fontes de conhecimento consultar e o comportamento padrão para operações de recuperação. No momento da consulta, o método recuperar tem como alvo a base de dados de conhecimento para executar o pipeline de recuperação configurado.

Você pode criar uma base de conhecimento em uma carga de trabalho Foundry IQ no portal do Microsoft Foundry (novo). Você também precisa de uma base de dados de conhecimento em qualquer solução agente criada usando as APIs do Azure AI Search.

Uma base de dados de conhecimento especifica:

• Uma ou mais fontes de conhecimento que apontam para conteúdo pesquisável.
• Uma LLM opcional que fornece recursos de raciocínio para planejamento de consultas e formulação de resposta.
• Um esforço de raciocínio de recuperação que determina se um LLM é invocado e gerencia custo, latência e qualidade.
• Propriedades personalizadas que controlam roteamento, seleção de origem, formato de saída e criptografia de objeto.

Depois de criar uma base de dados de conhecimento, você pode atualizar suas propriedades a qualquer momento. Se a base de conhecimento estiver em uso, as atualizações entrarão em vigor na próxima recuperação.

Pré-requisitos

• Azure AI Search em qualquer região com recuperação por agente. Você deve ter o classificador semântico habilitado. Se você estiver usando uma identidade gerenciada para acesso baseado em função a modelos implantados, o serviço de pesquisa deverá estar no tipo de preço Básico ou superior.

• Serviço OpenAI do Azure com uma implantação de LLM com suporte.

• Uma ou mais fontes de conhecimento em seu serviço de pesquisa.

• Permissão para criar e usar objetos no Azure AI Search. Recomendamos o acesso baseado em função. O Colaborador do Serviço de Pesquisa pode criar e gerenciar uma base de dados de conhecimento. O Leitor de Dados do Índice de Pesquisa pode executar consultas. Como alternativa, você poderá usar chaves de API se uma atribuição de função não for viável. Para obter mais informações, consulte Conectar-se a um serviço de pesquisa.

• A versão prévia mais recente da Azure.Search.Documents biblioteca de clientes para o SDK do .NET.

Modelos com suporte

Use uma das SEGUINTEs LLMs do Azure OpenAI ou um modelo de software livre equivalente. Para obter instruções de implantação, consulte Implantar modelos do Azure OpenAI com o Microsoft Foundry.

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

Configurar o acesso

O Azure AI Search precisa de acesso à LLM do Azure OpenAI. Recomendamos o Microsoft Entra ID para autenticação e acesso baseado em função para autorização. Para atribuir funções, você deve ser um Proprietário ou Administrador de Acesso do Usuário. Se você não puder usar funções, use a autenticação baseada em chave.

Verificar se há bases de dados de conhecimento existentes

Uma base de dados de conhecimento é um objeto reutilizável de nível superior. Saber sobre bases de dados de conhecimento existentes é útil para reutilizar ou nomear novos objetos. Qualquer agente de conhecimento 2025-08-01-preview será retornado na coleção de bases de dados de conhecimento.

Use Bases de Dados de Conhecimento – Lista (API REST) para listar bases de dados de conhecimento por nome e tipo.

# List knowledge bases
GET {{search-url}}/knowledgebases?api-version=2025-11-01-preview&$select=name
Content-Type: application/json
api-key: {{search-api-key}}

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

# Get knowledge base
GET {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{search-api-key}}

O JSON a seguir é uma resposta de exemplo para uma base de dados de conhecimento.

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

Como criar uma base de dados de conhecimento

Uma base de dados de conhecimento impulsiona o pipeline de recuperação por meio de agentes. No código do aplicativo, ele é chamado por outros agentes ou chatbots.

Uma base de dados de conhecimento conecta fontes de conhecimento (conteúdo pesquisável) a uma implantação de LLM do Azure OpenAI. As propriedades no LLM estabelecem a conexão, enquanto as propriedades na fonte de conhecimento definem padrões que orientam a execução da consulta e a resposta.

Use bases de dados de conhecimento – Criar ou atualizar (API REST) para formular a solicitação.

# Create a knowledge base
PUT {{search-url}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{search-api-key}}

{
    "name" : "my-kb",
    "description": "This knowledge base handles questions directed at two unrelated sample indexes.",
    "retrievalInstructions": "Use the hotels knowledge source for queries about where to stay, otherwise use the earth at night knowledge source.",
    "answerInstructions": null,
    "outputMode": "answerSynthesis",
    "knowledgeSources": [
        {
            "name": "hotels-ks"
        },
        {
            "name": "earth-at-night-ks"
        }
    ],
    "models" : [ 
        {
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
                "resourceUri": "{{model-provider-url}}",
                "apiKey": "{{model-api-key}}",
                "deploymentId": "gpt-4.1-mini",
                "modelName": "gpt-4.1-mini"
            }
        }
    ],
    "encryptionKey": null,
    "retrievalReasoningEffort": {
        "kind": "low"
    }
}

Propriedades da base de dados de conhecimento

Passe as propriedades a seguir para criar uma base de dados de conhecimento.

Consultar uma base de dados de conhecimento

Chame a ação retrieve na base de dados de conhecimento para verificar a conexão LLM e retornar resultados. Para obter mais informações sobre o retrieve esquema de solicitação e resposta, consulte Recuperar dados usando uma base de dados de conhecimento no Azure AI Search.

Use Knowledge Retrieval - Retrieve (REST API) para formular a solicitação. Substitua "Onde o oceano parece verde?" por uma cadeia de caracteres de consulta válida para suas fontes de conhecimento.

# Send grounding request
POST {{search-url}}/knowledgebases/{{knowledge-base-name}}/retrieve?api-version=2025-11-01-preview
Content-Type: application/json
api-key: {{search-api-key}}

{
    "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"
                }
            ]
        }
    ],
    "includeActivity": true,
    "knowledgeSourceParams": [
        {
            "knowledgeSourceName": "earth-at-night-ks",
            "kind": "searchIndex",
            "includeReferences": true,
            "includeReferenceSourceData": true,
            "alwaysQuerySource": false
        }
  ]
}

Pontos principais:

• messages é necessário, mas você pode executar este exemplo usando apenas a user função que fornece a consulta.

• knowledgeSourceParams especifica um ou mais destinos de consulta. Para cada fonte de conhecimento, você pode especificar quantas informações incluir na saída.

A resposta à consulta de exemplo pode ser semelhante ao exemplo a seguir:

  "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]."
        }
      ]
    }
  ]

Excluir uma base de dados de conhecimento

Se você não precisar mais da base de dados de conhecimento ou precisar recompilá-la em seu serviço de pesquisa, use essa solicitação para excluir o objeto.

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