Creación de una fuente de conocimiento del índice de búsqueda

Nota:

Esta característica actualmente está en su versión preliminar pública. Esta versión preliminar se ofrece sin contrato de nivel de servicio y no es aconsejable usarla en las cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que tengan sus funcionalidades limitadas. Para obtener más información, vea Supplemental Terms of Use for Microsoft Azure Previews.

Un fuente de conocimiento del índice de búsqueda especifica una conexión a un índice de Búsqueda de Azure AI que proporciona contenido buscable en una canalización de recuperación dinámica. Los orígenes de conocimiento se crean de forma independiente, se hace referencia en una base de conocimiento y se usan como datos de base cuando un agente o bot de chat llama a una acción de recuperación en el momento de la consulta.

Soporte de uso

Azure Portal	portal Microsoft Foundry	SDK de .NET	SDK de Python	SDK de Java	SDK de JavaScript	REST API
✔️	✔️	✔️	✔️	✔️	✔️	✔️

Prerrequisitos

Búsqueda de Azure AI en cualquier región que proporcione recuperación agente. Debe tener habilitado el clasificador semántico.
Índice de búsqueda que contiene texto sin formato o contenido vectorial con una configuración semántica. Revise los criterios de índice para la recuperación por agentes. El índice debe estar en el mismo servicio de búsqueda que la base de conocimiento.
Permiso para crear y usar objetos en Búsqueda de Azure AI. Se recomienda el acceso basado en roles, pero 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.

El paquete de versión preliminar Azure.Search.Documents más reciente: dotnet add package Azure.Search.Documents --prerelease

El paquete de versión preliminar azure-search-documents más reciente: pip install --pre azure-search-documents

La versión 2025-11-01-preview de las API REST del servicio de búsqueda.

Comprobación de fuentes de conocimiento existentes

Una fuente de conocimiento es un objeto reutilizable de nivel superior. Conocer los orígenes de conocimiento existentes resulta útil para reutilizar o asignar nombres a nuevos objetos.

Ejecute el código siguiente para enumerar los orígenes de conocimiento por nombre y tipo.

// List knowledge sources by name and type
using Azure.Search.Documents.Indexes;

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

Console.WriteLine("Knowledge Sources:");

await foreach (var ks in knowledgeSources)
{
    Console.WriteLine($"  Name: {ks.Name}, Type: {ks.GetType().Name}");
}

También puede devolver una única fuente 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 source name to retrieve
string ksNameToGet = "earth-knowledge-source";

// Get its definition
var knowledgeSourceResponse = await indexClient.GetKnowledgeSourceAsync(ksNameToGet);
var ks = knowledgeSourceResponse.Value;

// Serialize to JSON for display
var jsonOptions = new JsonSerializerOptions 
{ 
    WriteIndented = true,
    DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.Never
};
Console.WriteLine(JsonSerializer.Serialize(ks, ks.GetType(), jsonOptions));

Una fuente de conocimiento es un objeto reutilizable de nivel superior. Conocer los orígenes de conocimiento existentes resulta útil para reutilizar o asignar nombres a nuevos objetos.

Ejecute el código siguiente para enumerar los orígenes de conocimiento por nombre y tipo.

# List knowledge sources by name and type
import requests
import json

endpoint = "{search_url}/knowledgesources"
params = {"api-version": "2025-11-01-preview", "$select": "name, kind"}
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 fuente de conocimiento por nombre para revisar su definición json.

# Get a knowledge source definition
import requests
import json

endpoint = "{search_url}/knowledgesources/{knowledge_source_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))

Una fuente de conocimiento es un objeto reutilizable de nivel superior. Conocer los orígenes de conocimiento existentes resulta útil para reutilizar o asignar nombres a nuevos objetos.

Usar Fuentes de conocimiento - Obtener (API REST) para listar las fuentes de conocimiento por nombre y tipo.

### List knowledge sources by name and type
GET {{search-url}}/knowledgesources?api-version=2025-11-01-preview&$select=name,kind
api-key: {{api-key}}

También puede devolver una única fuente de conocimiento por nombre para revisar su definición json.

### Get a knowledge source definition
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}

El siguiente JSON es una respuesta de ejemplo para una fuente de conocimiento de un índice de búsqueda. Observe que la fuente de conocimiento especifica un nombre de índice único y los campos del índice que se van a incluir en la consulta.

{
  "name": "my-search-index-ks",
  "kind": "searchIndex",
  "description": "A sample search index knowledge source.",
  "encryptionKey": null,
  "searchIndexParameters": {
    "searchIndexName": "my-search-index",
    "semanticConfigurationName": null,
    "sourceDataFields": [],
    "searchFields": []
  }
}

Creación de una fuente de conocimiento

Ejecute el código siguiente para crear un origen de conocimiento del índice de búsqueda.

// Create a search index knowledge source
using Azure.Search.Documents.Indexes;
using Azure.Search.Documents.Indexes.Models;
using Azure;

var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));

var indexKnowledgeSource = new SearchIndexKnowledgeSource(
    name: knowledgeSourceName,
    searchIndexParameters: new SearchIndexKnowledgeSourceParameters(searchIndexName: indexName)
    {
        SourceDataFields = { new SearchIndexFieldReference(name: "id"), new SearchIndexFieldReference(name: "page_chunk"), new SearchIndexFieldReference(name: "page_number") }
    }
);

await indexClient.CreateOrUpdateKnowledgeSourceAsync(indexKnowledgeSource);
Console.WriteLine($"Knowledge source '{knowledgeSourceName}' created or updated successfully.");

Ejecute el código siguiente para crear un origen de conocimiento del índice de búsqueda.

# Create a search index knowledge source
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import SearchIndexKnowledgeSource, SearchIndexKnowledgeSourceParameters, SearchIndexFieldReference

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

knowledge_source = SearchIndexKnowledgeSource(
    name = "my-search-index-ks",
    description= "This knowledge source pulls from an existing index designed for agentic retrieval.",
    encryption_key = None,
    search_index_parameters = SearchIndexKnowledgeSourceParameters(
        search_index_name = "search_index_name",
        semantic_configuration_name = "semantic_configuration_name",
        source_data_fields = [
            SearchIndexFieldReference(name="description"),
            SearchIndexFieldReference(name="category"),
        ],
        search_fields = [
            SearchIndexFieldReference(name="id")
        ],
    )
)

index_client.create_or_update_knowledge_source(knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")

Use fuentes de conocimiento: crear o actualizar (API REST) para crear una fuente de conocimiento para el índice de búsqueda.

PUT {{search-url}}/knowledgesources/my-search-index-ks?api-version=2025-11-01-preview
api-key: {{api-key}}
Content-Type: application/json

{
    "name": "my-search-index-ks",
    "kind": "searchIndex",
    "description": "This knowledge source pulls from an existing index designed for agentic retrieval.",
    "encryptionKey": null,
    "searchIndexParameters": {
        "searchIndexName": "<YOUR INDEX NAME>",
        "semanticConfigurationName": "my-semantic-config",
        "sourceDataFields": [
          { "name": "description" },
          { "name": "category" }
        ]
    }
}

Propiedades específicas del origen

Puede pasar las siguientes propiedades para crear una fuente de conocimiento del índice de búsqueda.

Nombre	Description	Tipo	Modificable	Obligatorio
`Name`	El nombre de la fuente de conocimiento, que debe ser único dentro de la colección de fuentes de conocimiento y seguir las directrices de nombres para los objetos en Búsqueda de Azure AI.	String	No	Sí
`Description`	Descripción del origen de conocimiento.	String	Sí	No
`EncryptionKey`	Clave administrada por el cliente para cifrar información confidencial tanto en el origen de conocimiento como en los objetos generados.	Objeto	Sí	No
`SearchIndexParameters`	Parámetros específicos de los orígenes de conocimiento del índice de búsqueda: `SearchIndexName`, `SemanticConfigurationName`, `SourceDataFields`y `SearchFields`.	Objeto	Sí	Sí
`SearchIndexName`	Nombre del índice de búsqueda existente.	String	Sí	Sí
`SemanticConfigurationName`	Invalida la configuración semántica predeterminada para el índice de búsqueda.	String	Sí	No
`SourceDataFields`	Los campos de índice devueltos al especificar `IncludeReferenceSourceData` en la definición de la base de conocimiento. Estos campos se usan para las citas y deben ser `retrievable`. Algunos ejemplos son el nombre del documento, el nombre de archivo, los números de página o los números de capítulo.	Array	Sí	No
`SearchFields`	Campos de índice en los que se va a buscar específicamente. Cuando no se especifica, se busca en todos los campos.	Array	Sí	No

Nombre	Description	Tipo	Modificable	Obligatorio
`name`	El nombre de la fuente de conocimiento, que debe ser único dentro de la colección de fuentes de conocimiento y seguir las directrices de nombres para los objetos en Búsqueda de Azure AI.	String	No	Sí
`description`	Descripción del origen de conocimiento.	String	Sí	No
`encryption_key`	Clave administrada por el cliente para cifrar información confidencial tanto en el origen de conocimiento como en los objetos generados.	Objeto	Sí	No
`search_index_parameters`	Parámetros específicos de los orígenes de conocimiento del índice de búsqueda: `search_index_name`, `semantic_configuration_name`, `source_data_fields`y `search_fields`.	Objeto	Sí	Sí
`search_index_name`	Nombre del índice de búsqueda existente.	String	Sí	Sí
`semantic_configuration_name`	Invalida la configuración semántica predeterminada para el índice de búsqueda.	String	Sí	No
`source_data_fields`	Los campos de índice devueltos al especificar `include_reference_source_data` en la definición de la base de conocimiento. Estos campos se usan para las citas y deben ser `retrievable`. Algunos ejemplos son el nombre del documento, el nombre de archivo, los números de página o los números de capítulo.	Array	Sí	No
`search_fields`	Campos de índice en los que se va a buscar específicamente. Cuando no se especifica, se busca en todos los campos.	Array	Sí	No

Nombre	Description	Tipo	Modificable	Obligatorio
`name`	El nombre de la fuente de conocimiento, que debe ser único dentro de la colección de fuentes de conocimiento y seguir las directrices de nombres para los objetos en Búsqueda de Azure AI.	String	No	Sí
`kind`	El tipo de origen de conocimiento, que es `searchIndex` en este caso.	String	No	Sí
`description`	Descripción del origen de conocimiento.	String	Sí	No
`encryptionKey`	Clave administrada por el cliente para cifrar información confidencial tanto en el origen de conocimiento como en los objetos generados.	Objeto	Sí	No
`searchIndexParameters`	Parámetros específicos de los orígenes de conocimiento del índice de búsqueda: `searchIndexName`, `semanticConfigurationName`, `sourceDataFields`y `searchFields`.	Objeto	Sí	Sí
`searchIndexName`	Nombre del índice de búsqueda existente.	String	Sí	Sí
`semanticConfigurationName`	Invalida la configuración semántica predeterminada para el índice de búsqueda.	String	Sí	No
`sourceDataFields`	Los campos de índice devueltos al especificar `includeReferenceSourceData` en la definición de la base de conocimiento. Estos campos se usan para las citas y deben ser `retrievable`. Algunos ejemplos son el nombre del documento, el nombre de archivo, los números de página o los números de capítulo.	Array	Sí	No
`searchFields`	Campos de índice en los que se va a buscar específicamente. Cuando no se especifica, se busca en todos los campos.	Array	Sí	No

Asignar a una base de conocimiento

Si está satisfecho con el origen de conocimiento, continúe con el paso siguiente: especifique el origen de conocimiento en una base de conocimiento.

Una vez configurada la base de conocimiento, use la acción recuperar para consultar el origen de conocimiento.

Eliminación de una fuente de conocimiento

Para poder eliminar un origen de conocimiento, debe eliminar cualquier base de conocimiento que haga referencia a ella o actualizar la definición de la base de conocimiento para quitar la referencia. En el caso de los orígenes de conocimiento que generan una canalización de índice e indexador, también se eliminan todos los objetos generados . Sin embargo, si usó un índice existente para crear un origen de conocimiento, el índice no se eliminará.

Si intenta eliminar un origen de conocimiento que está en uso, se produce un error en la acción y devuelve una lista de bases de conocimiento afectadas.

Para eliminar un origen de conocimiento:

Obtenga una lista de todas las bases de conocimiento del servicio de búsqueda.

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

Una respuesta de ejemplo podría ser similar a la siguiente:

 Knowledge Bases:
   - earth-knowledge-base
   - hotels-sample-knowledge-base
   - my-demo-knowledge-base

Obtenga una definición de base de conocimiento individual para comprobar si hay referencias de origen de conocimiento.

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

Una respuesta de ejemplo podría ser similar a la siguiente:

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

Elimine la base de conocimiento o actualice la base de conocimiento para quitar el origen de conocimiento si tiene varios orígenes. En este ejemplo se muestra la eliminación.

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

Elimine la fuente de conocimiento.

await indexClient.DeleteKnowledgeSourceAsync(knowledgeSourceName);
System.Console.WriteLine($"Knowledge source '{knowledgeSourceName}' deleted successfully.");

Si intenta eliminar un origen de conocimiento que está en uso, se produce un error en la acción y devuelve una lista de bases de conocimiento afectadas.

Para eliminar un origen de conocimiento:

Obtenga una lista de todas las bases de conocimiento del servicio de búsqueda.

# Get knowledge bases
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))

Una respuesta de ejemplo podría ser similar a la siguiente:

 {
     "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
     "value": [
     {
         "name": "my-kb"
     },
     {
         "name": "my-kb-2"
     }
     ]
 }

Obtenga una definición de base de conocimiento individual para comprobar si hay referencias de origen de conocimiento.

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

Una respuesta de ejemplo podría ser similar a la siguiente:

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

Elimine la base de conocimiento o actualice la base de conocimiento para quitar el origen de conocimiento si tiene varios orígenes. En este ejemplo se muestra la eliminación.

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

Elimine la fuente de conocimiento.

# Delete a knowledge source
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_source("knowledge_source_name")
print(f"Knowledge source deleted successfully.")

Si intenta eliminar un origen de conocimiento que está en uso, se produce un error en la acción y devuelve una lista de bases de conocimiento afectadas.

Para eliminar un origen de conocimiento:

Obtenga una lista de todas las bases de conocimiento del servicio de búsqueda.

### Get knowledge bases
GET {{search-endpoint}}/knowledgebases?api-version=2025-11-01-preview&$select=name
api-key: {{api-key}}

Una respuesta de ejemplo podría ser similar a la siguiente:

 {
     "@odata.context": "https://my-search-service.search.windows.net/$metadata#knowledgebases(name)",
     "value": [
     {
         "name": "my-kb"
     },
     {
         "name": "my-kb-2"
     }
     ]
 }

Obtenga una definición de base de conocimiento individual para comprobar si hay referencias de origen de conocimiento.

### Get a knowledge base definition
GET {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}

Una respuesta de ejemplo podría ser similar a la siguiente:

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

Elimine la base de conocimiento o actualice la base de conocimiento quitando el origen de conocimiento si tiene varios orígenes. En este ejemplo se muestra la eliminación.
```
### Delete a knowledge base
DELETE {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}
```

Elimine la fuente de conocimiento.

### Delete a knowledge source
DELETE {{search-endpoint}}/knowledgesources/{{knowledge-source-name}}?api-version=2025-11-01-preview
api-key: {{api-key}}

Comentarios

¿Le ha resultado útil esta página?

Last updated on 2026-04-15

Creación de una fuente de conocimiento del índice de búsqueda

Soporte de uso

Prerrequisitos

Comprobación de fuentes de conocimiento existentes

Creación de una fuente de conocimiento

Propiedades específicas del origen

Asignar a una base de conocimiento

Eliminación de una fuente de conocimiento

Contenido relacionado

Comentarios

Recursos adicionales