Crie uma base de conhecimento no Azure AI Search

No Azure AI Search, uma base de conhecimento é um objeto de topo que orquestra a recuperação agêntica. Define quais as fontes de conhecimento a consultar e o comportamento padrão para as operações de recuperação. No momento da consulta, o método de recuperação dirige-se à base de conhecimento para executar o pipeline de recuperação configurado.

Pode criar uma base de conhecimento numa carga de trabalho Foundry IQ no portal Microsoft Foundry (novo). Também precisa de uma base de conhecimento em quaisquer soluções agenticas que crie usando as APIs de Pesquisa de IA do Azure.

Uma base de conhecimento especifica:

• Uma ou mais fontes de conhecimento que apontam para conteúdos pesquisáveis.
• Um LLM opcional que fornece capacidades de raciocínio para planeamento de consultas e formulação de respostas.
• Um processo de raciocínio de recuperação que determina se um LLM é invocado e gere o custo, a latência e a qualidade.
• Propriedades personalizadas que controlam o encaminhamento, seleção da fonte, formato de saída e encriptação de objetos.

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

Pré-requisitos

• Azure AI Search em qualquer região que forneça recuperação agentiva. Deve ter o ranker semântico ativado. Se estiver a usar uma identidade gerida para acesso baseado em funções a modelos implementados, o seu serviço de pesquisa deve estar no escalão de preços Básico ou superior.

• Azure OpenAI com uma implementação de LLM suportada .

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

• Permissão para criar e usar objetos no Azure AI Search. Recomendamos o acesso baseado em funções. O Search Service Contributor pode criar e gerir uma base de conhecimento. O Leitor de Dados de Índice de Pesquisa pode executar consultas. Em alternativa, podes usar chaves API se uma atribuição de funções não for viável. Para mais informações, consulte Ligar-se a um serviço de pesquisa.

• A versão mais recente de pré-visualização da azure-search-documents biblioteca cliente para Python.

Modelos suportados

Use um dos seguintes LLMs do Azure OpenAI ou um modelo de open-source equivalente. Para instruções de implementação, consulte Deploy Azure OpenAI models with 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 ao LLM através do Azure OpenAI. Recomendamos o Microsoft Entra ID para autenticação e acesso baseado em função para autorização. Para atribuir funções, deve ser Proprietário ou Administrador de Acesso ao Utilizador. Se não conseguires usar funções, usa a autenticação baseada em chaves.

Verifique se existem bases de conhecimento existentes

Conhecer bases de conhecimento existentes é útil tanto para as reutilizar como para nomear novos objetos. Quaisquer agentes de conhecimento da versão de pré-visualização de 2025-08-01 são devolvidos na coleção de bases de conhecimento.

Execute o seguinte código para listar as bases 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}");
  }

Também pode devolver uma única base de conhecimento pelo nome para rever a sua definição em 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 seguinte é um exemplo de base 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
}

Criar uma base de dados de conhecimento

Uma base de conhecimento orienta o pipeline de recuperação agentica. No código da aplicação, é chamado por outros agentes ou chatbots.

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

Execute o código seguinte para criar uma base 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 conhecimento

Passe as seguintes propriedades para criar uma base de conhecimento.

Consultar uma base de dados de conhecimento

Configura as instruções e mensagens para enviar ao 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 }
    }
};

Ligue a ação retrieve na base de conhecimento para verificar a conexão com o LLM e retorne os resultados. Para mais informações sobre o retrieve esquema de pedido e resposta, consulte Recuperar dados usando uma base de conhecimento no Azure AI Search.

Substitua "Onde é que o oceano parece verde?" por uma cadeia de consulta válida para as 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 o pedido de recuperação.

• Esforço de Raciocínio é necessário. Ao defini-lo minimal, exclui-los dos LLMs do pipeline de consulta e apenas as intenções são usadas para a entrada da consulta. O padrão é low e suporta planeamento de consultas baseado em LLM e síntese de respostas com mensagens e contexto.

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

A resposta à consulta de exemplo pode ser o seguinte exemplo:

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

Eliminar uma base de dados de conhecimento

Se já não precisa da base de conhecimento ou precisa de a reconstruir no seu serviço de pesquisa, use este pedido para eliminar 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 topo que orquestra a recuperação agêntica. Define quais as fontes de conhecimento a consultar e o comportamento padrão para as operações de recuperação. No momento da consulta, o método de recuperação dirige-se à base de conhecimento para executar o pipeline de recuperação configurado.

Pode criar uma base de conhecimento numa carga de trabalho Foundry IQ no portal Microsoft Foundry (novo). Também precisa de uma base de conhecimento em quaisquer soluções agenticas que crie usando as APIs de Pesquisa de IA do Azure.

Uma base de conhecimento especifica:

• Uma ou mais fontes de conhecimento que apontam para conteúdos pesquisáveis.
• Um LLM opcional que fornece capacidades de raciocínio para planeamento de consultas e formulação de respostas.
• Um processo de raciocínio de recuperação que determina se um LLM é invocado e gere o custo, a latência e a qualidade.
• Propriedades personalizadas que controlam o encaminhamento, seleção da fonte, formato de saída e encriptação de objetos.

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

Pré-requisitos

• Azure AI Search em qualquer região que forneça recuperação agentiva. Deve ter o ranker semântico ativado. Se estiver a usar uma identidade gerida para acesso baseado em funções a modelos implementados, o seu serviço de pesquisa deve estar no escalão de preços Básico ou superior.

• Azure OpenAI com uma implementação de LLM suportada .

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

• Permissão para criar e usar objetos no Azure AI Search. Recomendamos o acesso baseado em funções. O Search Service Contributor pode criar e gerir uma base de conhecimento. O Leitor de Dados de Índice de Pesquisa pode executar consultas. Em alternativa, podes usar chaves API se uma atribuição de funções não for viável. Para mais informações, consulte Ligar-se a um serviço de pesquisa.

• A versão mais recente de pré-visualização da azure-search-documents biblioteca cliente para Python.

Modelos suportados

Use um dos seguintes LLMs do Azure OpenAI ou um modelo de open-source equivalente. Para instruções de implementação, consulte Deploy Azure OpenAI models with 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 ao LLM através do Azure OpenAI. Recomendamos o Microsoft Entra ID para autenticação e acesso baseado em função para autorização. Deve ser Proprietário ou Administrador de Acesso ao Utilizador para atribuir funções. Se as funções não forem viáveis, use autenticação baseada em chaves.

Verifique se existem bases de conhecimento existentes

Conhecer bases de conhecimento existentes é útil tanto para reutilizar como para nomear novos objetos. Quaisquer agentes de conhecimento da versão de pré-visualização de 2025-08-01 são devolvidos na coleção de bases de conhecimento.

Execute o seguinte código para listar as bases 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))

Também pode devolver uma única base de conhecimento pelo nome para rever a sua definição em 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 seguinte é uma resposta de exemplo para uma base 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"
  }
}

Criar uma base de dados de conhecimento

Uma base de conhecimento orienta o pipeline de recuperação agentica. No código da aplicação, é chamado por outros agentes ou chatbots.

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

Execute o código seguinte para criar uma base 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 conhecimento

Passe as seguintes propriedades para criar uma base de conhecimento.

Consultar uma base de dados de conhecimento

Ligue a ação retrieve na base de conhecimento para verificar a conexão com o LLM e retorne os resultados. Para mais informações sobre o retrieve esquema de pedido e resposta, consulte Recuperar dados usando uma base de conhecimento no Azure AI Search.

Substitua "Onde é que o oceano parece verde?" por uma cadeia de consulta válida para as 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 é obrigatório, mas pode executar este exemplo usando apenas a funcionalidade user que disponibiliza a consulta.

• knowledge_source_params especifica um ou mais alvos de consulta. Para cada fonte de conhecimento, pode especificar quanta informação incluir no resultado.

A resposta à consulta de exemplo pode ser o seguinte exemplo:

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

Eliminar uma base de dados de conhecimento

Se já não precisa da base de conhecimento ou precisa de a reconstruir no seu serviço de pesquisa, use este pedido para eliminar 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 topo que orquestra a recuperação agêntica. Define quais as fontes de conhecimento a consultar e o comportamento padrão para as operações de recuperação. No momento da consulta, o método de recuperação dirige-se à base de conhecimento para executar o pipeline de recuperação configurado.

Pode criar uma base de conhecimento numa carga de trabalho Foundry IQ no portal Microsoft Foundry (novo). Também precisa de uma base de conhecimento em quaisquer soluções agenticas que crie usando as APIs de Pesquisa de IA do Azure.

Uma base de conhecimento especifica:

• Uma ou mais fontes de conhecimento que apontam para conteúdos pesquisáveis.
• Um LLM opcional que fornece capacidades de raciocínio para planeamento de consultas e formulação de respostas.
• Um processo de raciocínio de recuperação que determina se um LLM é invocado e gere o custo, a latência e a qualidade.
• Propriedades personalizadas que controlam o encaminhamento, seleção da fonte, formato de saída e encriptação de objetos.

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

Pré-requisitos

• Azure AI Search em qualquer região que forneça recuperação agentiva. Deve ter o ranker semântico ativado. Se estiver a usar uma identidade gerida para acesso baseado em funções a modelos implementados, o seu serviço de pesquisa deve estar no escalão de preços Básico ou superior.

• Azure OpenAI com uma implementação de LLM suportada .

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

• Permissão para criar e usar objetos no Azure AI Search. Recomendamos o acesso baseado em funções. O Search Service Contributor pode criar e gerir uma base de conhecimento. O Leitor de Dados de Índice de Pesquisa pode executar consultas. Em alternativa, podes usar chaves API se uma atribuição de funções não for viável. Para mais informações, consulte Ligar-se a um serviço de pesquisa.

• A versão de pré-visualização mais recente da Azure.Search.Documents biblioteca cliente para o SDK .NET.

Modelos suportados

Use um dos seguintes LLMs do Azure OpenAI ou um modelo de open-source equivalente. Para instruções de implementação, consulte Deploy Azure OpenAI models with 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 ao LLM através do Azure OpenAI. Recomendamos o Microsoft Entra ID para autenticação e acesso baseado em função para autorização. Para atribuir funções, deve ser Proprietário ou Administrador de Acesso ao Utilizador. Se não conseguires usar funções, usa a autenticação baseada em chaves.

Verifique se existem bases de conhecimento existentes

Uma base de conhecimento é um objeto de topo e reutilizável. Conhecer bases de conhecimento existentes é útil tanto para reutilizar como para nomear novos objetos. Quaisquer agentes de conhecimento da versão de pré-visualização de 2025-08-01 são devolvidos na coleção de bases de conhecimento.

Use Knowledge Bases - List (API REST) para listar as bases 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}}

Também pode devolver uma única base de conhecimento pelo nome para rever a sua definição em 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 seguinte é uma resposta de exemplo para uma base 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"
  }
}

Criar uma base de dados de conhecimento

Uma base de conhecimento orienta o pipeline de recuperação agentica. No código da aplicação, é chamado por outros agentes ou chatbots.

Uma base de conhecimento liga fontes de conhecimento (conteúdo pesquisável) a uma implementação de LLM a partir do Azure OpenAI. As propriedades do LLM estabelecem a ligação, enquanto as propriedades da fonte de conhecimento definem predefinições que guiam a execução da consulta e a resposta.

Use Knowledge Bases - Create or Update (API REST) para formular o pedido.

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

Passe as seguintes propriedades para criar uma base de conhecimento.

Consultar uma base de dados de conhecimento

Ligue a ação retrieve na base de conhecimento para verificar a conexão com o LLM e retorne os resultados. Para mais informações sobre o retrieve esquema de pedido e resposta, consulte Recuperar dados usando uma base de conhecimento no Azure AI Search.

Use Knowledge Retrieval - Retrieve (API REST) para formular o pedido. Substitua "Onde é que o oceano parece verde?" por uma cadeia de consulta válida para as 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 é obrigatório, mas pode executar este exemplo usando apenas a funcionalidade user que disponibiliza a consulta.

• knowledgeSourceParams especifica um ou mais alvos de consulta. Para cada fonte de conhecimento, pode especificar quanta informação incluir no resultado.

A resposta à consulta de exemplo pode ser o seguinte exemplo:

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

Eliminar uma base de dados de conhecimento

Se já não precisa da base de conhecimento ou precisa de a reconstruir no seu serviço de pesquisa, use este pedido para eliminar o objeto.

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