Creación de una base de conocimiento en Azure AI Search

En Azure AI Search, una base de conocimiento es un objeto de nivel superior que organiza la recuperación por agentes. Define los orígenes de conocimiento que se van a consultar y el comportamiento predeterminado de las operaciones de recuperación. En el momento de la consulta, el método retrieve tiene como destino la base de conocimiento para ejecutar la canalización de recuperación configurada.

Puede crear una base de conocimiento en una carga de trabajo de Foundry IQ en el portal de Microsoft Foundry (nuevo). También necesita una base de conocimiento en cualquier solución agente que cree mediante las API de Azure AI Search.

Una base de conocimiento especifica:

• Uno o varios orígenes de conocimiento que apuntan al contenido que se puede buscar.
• Un LLM opcional que proporciona funcionalidades de razonamiento para la planificación de consultas y la formulación de respuestas.
• Un esfuerzo de razonamiento para la recuperación que evalúa la activación de un LLM y gestiona el costo, la latencia y la calidad.
• Propiedades personalizadas que controlan el enrutamiento, la selección de origen, el formato de salida y el cifrado de objetos.

Después de crear una base de conocimiento, puede actualizar sus propiedades en cualquier momento. Si la base de conocimiento está en uso, las actualizaciones surten efecto en la siguiente recuperación.

Prerrequisitos

• Búsqueda de Azure AI en cualquier región que proporcione recuperación agente. Debe tener habilitado el clasificador semántico. Si usa una identidad administrada para el acceso basado en roles a los modelos implementados, el servicio de búsqueda debe estar en el plan de tarifa Básico o superior.

• Azure OpenAI con una implementación Compatible de LLM.

• Uno o varios orígenes de conocimiento en el servicio de búsqueda.

• Permiso para crear y usar objetos en Azure AI Search. Se recomienda el acceso basado en roles. El colaborador del servicio de búsqueda puede crear y administrar una base de conocimiento. El Lector de datos de índice de búsqueda puede ejecutar consultas. Como alternativa, puede usar claves de API si una asignación de roles no es factible. Para obtener más información, consulte Conexión a un servicio de búsqueda.

• La versión preliminar más reciente de la azure-search-documents biblioteca cliente para Python.

Modelos compatibles

Use uno de los siguientes modelos de lenguaje extensos de Azure OpenAI o un modelo de código abierto equivalente. Para obtener instrucciones de implementación, consulte Implementación de modelos de Azure OpenAI con 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 el acceso

Azure AI Search necesita acceso al LLM desde Azure OpenAI. Se recomienda Microsoft Entra ID para la autenticación y el acceso basado en roles para la autorización. Para asignar roles, debe ser propietario o administrador de acceso de usuario. Si no puede usar roles, use la autenticación basada en claves en su lugar.

Comprobación de las bases de conocimiento existentes

Conocer las bases de conocimiento existentes es útil para reutilizarlas o asignar nombres a nuevos objetos. Los agentes de conocimiento 2025-08-01-preview se devuelven en la colección de bases de conocimiento.

Ejecute el código siguiente para enumerar las bases de conocimiento existentes por nombre.

// 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}");
  }

También puede devolver una única base de conocimiento por nombre para revisar su definición 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);

El siguiente JSON es un ejemplo de una base de conocimiento.

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

Creación de una base de conocimientos

Una base de conocimiento impulsa la canalización de recuperación de agentes. En el código de aplicación, otros agentes o bots de chat lo llaman.

Una base de conocimiento conecta orígenes de conocimiento (contenido que se puede buscar) a una implementación de LLM desde Azure OpenAI. Las propiedades del LLM establecen la conexión, mientras que las propiedades de la fuente de conocimiento establecen los valores predeterminados que afectan tanto la ejecución de la consulta como la respuesta.

Ejecute el código siguiente para crear una base de conocimiento.

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

Propiedades de la base de conocimiento

Pase las siguientes propiedades para crear una base de conocimiento.

Consulta de una base de conocimiento

Configure las instrucciones y los mensajes que se van a enviar al 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 }
    }
};

Llame a la acción retrieve en la base de conocimiento para comprobar la conexión LLM y devolver resultados. Para más información sobre el retrieve esquema de solicitud y respuesta, consulte Recuperación de datos mediante una base de conocimiento en Azure AI Search.

Reemplace "¿Dónde parece verde el océano?" por una consulta válida para sus fuentes de conocimiento.

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

Puntos clave:

• KnowledgeBaseRetrievalRequest es el contrato de entrada para la solicitud de recuperación.

• Se requiere RetrievalReasoningEffort. Si se pasa a minimal, se excluyen las LLM de la canalización de consulta y solo se usan intenciones para la entrada de consulta. El valor predeterminado es low y admite la planificación de consultas basada en LLM y la síntesis de respuestas con mensajes y contexto.

• knowledgeSourceParams se usan para sobrescribir los parámetros predeterminados en el momento de la consulta.

La respuesta a la consulta de ejemplo podría ser similar al ejemplo siguiente:

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

Eliminación de una base de conocimiento

Si ya no necesita la base de conocimiento o necesita recompilarla en el servicio de búsqueda, use esta solicitud para eliminar el 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.");

En Azure AI Search, una base de conocimiento es un objeto de nivel superior que organiza la recuperación por agentes. Define los orígenes de conocimiento que se van a consultar y el comportamiento predeterminado de las operaciones de recuperación. En el momento de la consulta, el método retrieve tiene como destino la base de conocimiento para ejecutar la canalización de recuperación configurada.

Puede crear una base de conocimiento en una carga de trabajo de Foundry IQ en el portal de Microsoft Foundry (nuevo). También necesita bases de conocimiento en todas las soluciones agenticas que cree mediante las API de Azure AI Search.

Una base de conocimiento especifica:

• Uno o varios orígenes de conocimiento que apuntan al contenido que se puede buscar.
• Un LLM opcional que proporciona funcionalidades de razonamiento para la planificación de consultas y la formulación de respuestas.
• Un esfuerzo de razonamiento para la recuperación que evalúa la activación de un LLM y gestiona el costo, la latencia y la calidad.
• Propiedades personalizadas que controlan el enrutamiento, la selección de origen, el formato de salida y el cifrado de objetos.

Después de crear una base de conocimiento, puede actualizar sus propiedades en cualquier momento. Si la base de conocimiento está en uso, las actualizaciones surten efecto en la siguiente recuperación.

Prerrequisitos

• Búsqueda de Azure AI en cualquier región que proporcione recuperación agente. Debe tener habilitado el clasificador semántico. Si usa una identidad administrada para el acceso basado en roles a los modelos implementados, el servicio de búsqueda debe estar en el plan de tarifa Básico o superior.

• Azure OpenAI con una implementación Compatible de LLM.

• Uno o varios orígenes de conocimiento en el servicio de búsqueda.

• Permiso para crear y usar objetos en Azure AI Search. Se recomienda el acceso basado en roles. El colaborador del servicio de búsqueda puede crear y administrar una base de conocimiento. El Lector de datos de índice de búsqueda puede ejecutar consultas. Como alternativa, puede usar claves de API si una asignación de roles no es factible. Para obtener más información, consulte Conexión a un servicio de búsqueda.

• La versión preliminar más reciente de la azure-search-documents biblioteca cliente para Python.

Modelos compatibles

Use uno de los siguientes modelos de lenguaje extensos de Azure OpenAI o un modelo de código abierto equivalente. Para obtener instrucciones de implementación, consulte Implementación de modelos de Azure OpenAI con 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 el acceso

Azure AI Search necesita acceso al LLM desde Azure OpenAI. Se recomienda Microsoft Entra ID para la autenticación y el acceso basado en roles para la autorización. Debe ser propietario o administrador de acceso para asignar roles. Si los roles no son factibles, use la autenticación basada en claves en su lugar.

Comprobación de las bases de conocimiento existentes

Conocer las bases de conocimiento existentes resulta útil para reutilizar o asignar nombres a nuevos objetos. Los agentes de conocimiento 2025-08-01-preview se devuelven en la colección de bases de conocimiento.

Ejecute el código siguiente para enumerar las bases de conocimiento existentes por nombre.

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

También puede devolver una única base de conocimiento por nombre para revisar su definición 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))

El siguiente JSON es una respuesta de ejemplo para una base de conocimiento.

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

Creación de una base de conocimientos

Una base de conocimiento impulsa la canalización de recuperación de agentes. En el código de aplicación, otros agentes o bots de chat lo llaman.

Una base de conocimiento conecta orígenes de conocimiento (contenido que se puede buscar) a una implementación de LLM desde Azure OpenAI. Las propiedades del LLM establecen la conexión, mientras que las propiedades de la fuente de conocimiento establecen los valores predeterminados que afectan tanto la ejecución de la consulta como la respuesta.

Ejecute el código siguiente para crear una base de conocimiento.

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

Propiedades de la base de conocimiento

Pase las siguientes propiedades para crear una base de conocimiento.

Consulta de una base de conocimiento

Llame a la acción retrieve en la base de conocimiento para comprobar la conexión LLM y devolver resultados. Para más información sobre el retrieve esquema de solicitud y respuesta, consulte Recuperación de datos mediante una base de conocimiento en Azure AI Search.

Reemplace "¿Dónde parece verde el océano?" por una consulta válida para sus fuentes de conocimiento.

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

Puntos clave:

• messages es necesario, pero puede ejecutar este ejemplo con solo el user rol que proporciona la consulta.

• knowledge_source_params especifica uno o varios destinos de consulta. Para cada origen de conocimiento, puede especificar la cantidad de información que se va a incluir en la salida.

La respuesta a la consulta de ejemplo podría ser similar al ejemplo siguiente:

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

Eliminación de una base de conocimiento

Si ya no necesita la base de conocimiento o necesita recompilarla en el servicio de búsqueda, use esta solicitud para eliminar el 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.")

En Azure AI Search, una base de conocimiento es un objeto de nivel superior que organiza la recuperación por agentes. Define los orígenes de conocimiento que se van a consultar y el comportamiento predeterminado de las operaciones de recuperación. En el momento de la consulta, el método retrieve tiene como destino la base de conocimiento para ejecutar la canalización de recuperación configurada.

Puede crear una base de conocimiento en una carga de trabajo de Foundry IQ en el portal de Microsoft Foundry (nuevo). También necesita una base de conocimiento en cualquier solución agente que cree mediante las API de Azure AI Search.

Una base de conocimiento especifica:

• Uno o varios orígenes de conocimiento que apuntan al contenido que se puede buscar.
• Un LLM opcional que proporciona funcionalidades de razonamiento para la planificación de consultas y la formulación de respuestas.
• Un esfuerzo de razonamiento para la recuperación que evalúa la activación de un LLM y gestiona el costo, la latencia y la calidad.
• Propiedades personalizadas que controlan el enrutamiento, la selección de origen, el formato de salida y el cifrado de objetos.

Después de crear una base de conocimiento, puede actualizar sus propiedades en cualquier momento. Si la base de conocimiento está en uso, las actualizaciones surten efecto en la siguiente recuperación.

Prerrequisitos

• Búsqueda de Azure AI en cualquier región que proporcione recuperación agente. Debe tener habilitado el clasificador semántico. Si usa una identidad administrada para el acceso basado en roles a los modelos implementados, el servicio de búsqueda debe estar en el plan de tarifa Básico o superior.

• Azure OpenAI con una implementación Compatible de LLM.

• Uno o varios orígenes de conocimiento en el servicio de búsqueda.

• Permiso para crear y usar objetos en Azure AI Search. Se recomienda el acceso basado en roles. El colaborador del servicio de búsqueda puede crear y administrar una base de conocimiento. El Lector de datos de índice de búsqueda puede ejecutar consultas. Como alternativa, puede usar claves de API si una asignación de roles no es factible. Para obtener más información, consulte Conexión a un servicio de búsqueda.

• La versión preliminar más reciente de la Azure.Search.Documents biblioteca cliente para el SDK de .NET.

Modelos compatibles

Use uno de los siguientes modelos de lenguaje extensos de Azure OpenAI o un modelo de código abierto equivalente. Para obtener instrucciones de implementación, consulte Implementación de modelos de Azure OpenAI con 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 el acceso

Azure AI Search necesita acceso al LLM desde Azure OpenAI. Se recomienda Microsoft Entra ID para la autenticación y el acceso basado en roles para la autorización. Para asignar roles, debe ser propietario o administrador de acceso de usuario. Si no puede usar roles, use la autenticación basada en claves en su lugar.

Comprobación de las bases de conocimiento existentes

Una base de conocimiento es un objeto reutilizable de nivel superior. Conocer las bases de conocimiento existentes resulta útil para reutilizar o asignar nombres a nuevos objetos. Los agentes de conocimiento 2025-08-01-preview se devuelven en la colección de bases de conocimiento.

Use Knowledge Base - List (API REST) para enumerar las bases de conocimiento por nombre y 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}}

También puede devolver una única base de conocimiento por nombre para revisar su definición 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}}

El siguiente JSON es una respuesta de ejemplo para una base de conocimiento.

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

Creación de una base de conocimientos

Una base de conocimiento impulsa la canalización de recuperación de agentes. En el código de aplicación, otros agentes o bots de chat lo llaman.

Una base de conocimiento conecta orígenes de conocimiento (contenido que se puede buscar) a una implementación de LLM desde Azure OpenAI. Las propiedades de LLM establecen la conexión, mientras que las propiedades del conjunto de orígenes de conocimiento establecen valores predeterminados que guían la ejecución de consultas y la respuesta.

Use Knowledge Base- Create or Update (REST API) para formular la solicitud.

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

Propiedades de la base de conocimiento

Pase las siguientes propiedades para crear una base de conocimiento.

Consulta de una base de conocimiento

Llame a la acción retrieve en la base de conocimiento para comprobar la conexión LLM y devolver resultados. Para más información sobre el retrieve esquema de solicitud y respuesta, consulte Recuperación de datos mediante una base de conocimiento en Azure AI Search.

Utiliza Recuperación de Conocimiento - Recuperar (API REST) para formular la solicitud. Reemplace "¿Dónde parece verde el océano?" por una consulta válida para sus fuentes de conocimiento.

# 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
        }
  ]
}

Puntos clave:

• messages es necesario, pero puede ejecutar este ejemplo con solo el user rol que proporciona la consulta.

• knowledgeSourceParams especifica uno o varios destinos de consulta. Para cada origen de conocimiento, puede especificar la cantidad de información que se va a incluir en la salida.

La respuesta a la consulta de ejemplo podría ser similar al ejemplo siguiente:

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

Eliminación de una base de conocimiento

Si ya no necesita la base de conocimiento o necesita recompilarla en el servicio de búsqueda, use esta solicitud para eliminar el objeto.

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