Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
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 más información, consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.
Use una fuente de conocimiento de OneLake para indexar y consultar archivos de Microsoft OneLake en una canalización de recuperación con agentes. 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.
Al crear un origen de conocimiento de OneLake, especifique un origen de datos externo, modelos y propiedades para generar automáticamente los siguientes objetos de Azure AI Search:
- Un origen de datos que representa un almacén de lago de datos.
- Conjunto de habilidades que fragmenta y, opcionalmente, vectoriza el contenido multimodal del almacén de lago de datos.
- Índice que almacena contenido enriquecido y cumple los criterios para la recuperación agencial.
- Un indexador que utiliza los objetos previos para impulsar la canalización de indexación y enriquecimiento.
El indexador generado se ajusta al indexador oneLake, cuyos requisitos previos, tareas admitidas, formatos de documento admitidos, accesos directos admitidos y limitaciones también se aplican a los orígenes de conocimiento de OneLake. Para obtener más información, consulte la documentación del indexador oneLake.
Prerrequisitos
Azure AI Search en cualquier región que proporcione recuperación agente. Debe tener habilitado el clasificador semántico.
Finalización de los requisitos previos del indexador de OneLake.
Finalización de la preparación de datos del indexador de OneLake.
La versión preliminar más reciente de la
azure-search-documentsbiblioteca cliente para C#.Permiso para crear y usar objetos en Azure AI Search. 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.
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));
El siguiente json es una respuesta de ejemplo para un origen de conocimiento de OneLake.
{
"name": "my-onelake-ks",
"kind": "indexedOneLake",
"description": "A sample indexed OneLake knowledge source.",
"encryptionKey": null,
"indexedOneLakeParameters": {
"fabricWorkspaceId": "<REDACTED>",
"lakehouseId": "<REDACTED>",
"targetPath": null,
"ingestionParameters": {
"disableImageVerbalization": false,
"ingestionPermissionOptions": [],
"contentExtractionMode": "standard",
"identity": null,
"embeddingModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "<REDACTED>",
"deploymentId": "text-embedding-3-large",
"apiKey": "<REDACTED>",
"modelName": "text-embedding-3-large"
}
},
"chatCompletionModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "<REDACTED>",
"deploymentId": "gpt-5-mini",
"apiKey": "<REDACTED>",
"modelName": "gpt-5-mini"
}
},
"ingestionSchedule": null,
"aiServices": {
"uri": "<REDACTED>",
"apiKey": "<REDACTED>"
}
},
"createdResources": {
"datasource": "my-onelake-ks-datasource",
"indexer": "my-onelake-ks-indexer",
"skillset": "my-onelake-ks-skillset",
"index": "my-onelake-ks-index"
}
}
}
Nota:
La información confidencial se redacta. Los recursos generados aparecen al final de la respuesta.
Creación de una fuente de conocimiento
Ejecute el código siguiente para crear un origen de conocimiento de OneLake.
// Create an IndexedOneLake knowledge source
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 chatCompletionParams = new AzureOpenAIVectorizerParameters
{
ResourceUri = new Uri(aoaiEndpoint),
DeploymentName = aoaiGptDeployment,
ModelName = aoaiGptModel
};
var embeddingParams = new AzureOpenAIVectorizerParameters
{
ResourceUri = new Uri(aoaiEndpoint),
DeploymentName = aoaiEmbeddingDeployment,
ModelName = aoaiEmbeddingModel
};
var ingestionParams = new KnowledgeSourceIngestionParameters
{
DisableImageVerbalization = false,
ChatCompletionModel = new KnowledgeBaseAzureOpenAIModel(azureOpenAIParameters: chatCompletionParams),
EmbeddingModel = new KnowledgeSourceAzureOpenAIVectorizer
{
AzureOpenAIParameters = embeddingParams
}
};
var oneLakeParams = new IndexedOneLakeKnowledgeSourceParameters(
fabricWorkspaceId: fabricWorkspaceId,
lakehouseId: lakehouseId)
{
IngestionParameters = ingestionParams
};
var knowledgeSource = new IndexedOneLakeKnowledgeSource(
name: "my-onelake-ks",
indexedOneLakeParameters: oneLakeParams)
{
Description = "This knowledge source pulls content from a lakehouse."
};
await indexClient.CreateOrUpdateKnowledgeSourceAsync(knowledgeSource);
Console.WriteLine($"Knowledge source '{knowledgeSource.Name}' created or updated successfully.");
Propiedades específicas del origen
Puede pasar las siguientes propiedades para crear un origen de conocimiento de OneLake.
| Nombre | Description | Tipo | Modificable | Obligatorio |
|---|---|---|---|---|
Name |
El nombre del origen de conocimiento, que debe ser único dentro de la colección de orígenes de conocimiento y seguir las directrices de nomenclatura de los objetos de Azure AI Search. | String | Sí | 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 |
IndexedOneLakeKnowledgeSourceParameters |
Parámetros específicos de los orígenes de conocimiento de OneLake: fabricWorkspaceId, lakehouseIdy targetPath. |
Objeto | Sí | |
fabricWorkspaceId |
GUID del área de trabajo que contiene almacén de lago de datos. | String | No | Sí |
lakehouseId |
El identificador único global (GUID) de la casa de lago. | String | No | Sí |
targetPath |
Carpeta o acceso directo dentro del almacén de lago de datos. Cuando no se especifica, se indexa todo el almacén de lago de datos. | String | No | No |
propiedades de ingestionParameters
Solo para las fuentes de conocimiento indexadas, puede pasar las siguientes ingestionParameters propiedades para controlar el modo en que se ingiere y procesa el contenido.
| Nombre | Description | Tipo | Modificable | Obligatorio |
|---|---|---|---|---|
Identity |
Identidad administrada que se va a usar en el indexador generado. | Objeto | Sí | No |
DisableImageVerbalization |
Habilita o deshabilita el uso de la verbalización de imágenes. El valor predeterminado es False, que permite la verbalización de imágenes. Establézcalo en True para deshabilitar la verbalización de imágenes. |
Boolean | No | No |
ChatCompletionModel |
Un modelo de finalización de chat que verbaliza imágenes o extrae contenido. Los modelos admitidos son gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-minigpt-4.1-nano, , gpt-5, , gpt-5-miniy gpt-5-nano. La habilidad de solicitud de GenAI se incluirá en el conjunto de habilidades generado. Establecer este parámetro también requiere que disable_image_verbalization se establezca en False. |
Objeto | Solo api_key y deployment_name son editables |
No |
EmbeddingModel |
Modelo de inserción de texto que vectoriza el contenido de texto e imagen durante la indexación y en el momento de la consulta. Los modelos admitidos son text-embedding-ada-002, text-embedding-3-smally text-embedding-3-large. La aptitud de inserción de Azure OpenAI se incluirá en el conjunto de aptitudes generado y el vectorizador de Azure OpenAI se incluirá en el índice generado. |
Objeto | Solo api_key y deployment_name son editables |
No |
ContentExtractionMode |
Controla cómo se extrae el contenido de los archivos. El valor predeterminado es minimal, que usa la extracción de contenido estándar para texto e imágenes. Establézcalo en standard para el avanzado descifrado de documentos y la fragmentación mediante la habilidad Azure Content Understanding, que se incluirá en el conjunto de habilidades generado. Solo para standard , se pueden especificar los AiServices parámetros y AssetStore . |
String | No | No |
AiServices |
Un recurso de Microsoft Foundry para acceder a Azure Content Understanding en Foundry Tools. Establecer este parámetro requiere que ContentExtractionMode se establezca en standard. |
Objeto | Solo api_key se puede editar |
Sí |
IngestionSchedule |
Agrega información de programación al indexador generado. También puede agregar una programación más adelante para automatizar la actualización de datos. | Objeto | Sí | No |
IngestionPermissionOptions |
Permisos de nivel de documento para ingerir desde orígenes de conocimiento seleccionados: ADLS Gen2 o SharePoint indexado. Si especifica user_ids, group_idso rbac_scope, el indexador de ADLS Gen2 generado o el indexador de SharePoint incluirán los permisos ingeridos. |
Array | No | No |
Comprobación del estado de la ingesta
Ejecute el código siguiente para supervisar el estado y el progreso de la ingesta, incluido elestado del indexador para los orígenes de conocimiento que generan una canalización de indexador y rellenan un índice de búsqueda.
// Get knowledge source ingestion status
using Azure.Search.Documents.Indexes;
using System.Text.Json;
var indexClient = new SearchIndexClient(new Uri(searchEndpoint), new AzureKeyCredential(apiKey));
// Get the knowledge source status
var statusResponse = await indexClient.GetKnowledgeSourceStatusAsync(knowledgeSourceName);
var status = statusResponse.Value;
// Serialize to JSON for display
var json = JsonSerializer.Serialize(status, new JsonSerializerOptions { WriteIndented = true });
Console.WriteLine(json);
Una respuesta para una solicitud que incluye parámetros de ingesta y que está ingeriendo contenido activamente podría ser similar al ejemplo siguiente.
{
"synchronizationStatus": "active", // creating, active, deleting
"synchronizationInterval" : "1d", // null if no schedule
"currentSynchronizationState" : { // spans multiple indexer "runs"
"startTime": "2025-10-27T19:30:00Z",
"itemUpdatesProcessed": 1100,
"itemsUpdatesFailed": 100,
"itemsSkipped": 1100,
},
"lastSynchronizationState" : { // null on first sync
"startTime": "2025-10-27T19:30:00Z",
"endTime": "2025-10-27T19:40:01Z", // this value appears on the activity record on each /retrieve
"itemUpdatesProcessed": 1100,
"itemsUpdatesFailed": 100,
"itemsSkipped": 1100,
},
"statistics": { // null on first sync
"totalSynchronization": 25,
"averageSynchronizationDuration": "00:15:20",
"averageItemsProcessedPerSynchronization" : 500
}
}
Revisión de los objetos creados
Al crear un origen de conocimiento de OneLake, el servicio de búsqueda también crea un indexador, un índice, un conjunto de aptitudes y un origen de datos. No se recomienda editar estos objetos, ya que introducir un error o incompatibilidad puede interrumpir la canalización.
Después de crear un origen de conocimiento, la respuesta enumera los objetos creados. Estos objetos se crean según una plantilla fija y sus nombres se basan en el nombre del origen de conocimiento. No se pueden cambiar los nombres de objeto.
Se recomienda usar Azure Portal para validar la creación de la salida. El flujo de trabajo es:
- Compruebe si el indexador tiene mensajes correctos o erróneos. Los errores de conexión o cuota aparecen aquí.
- Compruebe el índice para ver el contenido que se puede buscar. Use el Explorador de búsqueda para ejecutar consultas.
- Compruebe el conjunto de aptitudes para obtener información sobre cómo se fragmenta el contenido y opcionalmente, como se vectoriza.
- Compruebe el origen de datos para obtener los detalles de la conexión. En nuestro ejemplo se usan claves de API para simplificar, pero puede usar microsoft Entra ID para la autenticación y el control de acceso basado en rol para la autorización.
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.
Para cualquier base de conocimiento que especifique un origen de conocimiento de OneLake, asegúrese de establecer includeReferenceSourceData en true. Este paso es necesario para extraer la dirección URL del documento de origen en la cita.
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-baseObtenga 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.");
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 más información, consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.
Use una fuente de conocimiento de OneLake para indexar y consultar archivos de Microsoft OneLake en una canalización de recuperación con agentes. 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.
Al crear un origen de conocimiento de OneLake, especifique un origen de datos externo, modelos y propiedades para generar automáticamente los siguientes objetos de Azure AI Search:
- Un origen de datos que representa un almacén de lago de datos.
- Conjunto de habilidades que fragmenta y, opcionalmente, vectoriza el contenido multimodal del almacén de lago de datos.
- Índice que almacena contenido enriquecido y cumple los criterios para la recuperación agencial.
- Un indexador que utiliza los objetos previos para impulsar la canalización de indexación y enriquecimiento.
El indexador generado se ajusta al indexador oneLake, cuyos requisitos previos, tareas admitidas, formatos de documento admitidos, accesos directos admitidos y limitaciones también se aplican a los orígenes de conocimiento de OneLake. Para obtener más información, consulte la documentación del indexador oneLake.
Prerrequisitos
Azure AI Search en cualquier región que proporcione recuperación agente. Debe tener habilitado el clasificador semántico.
Finalización de los requisitos previos del indexador de OneLake.
Finalización de la preparación de datos del indexador de OneLake.
La versión preliminar más reciente de la
azure-search-documentsbiblioteca cliente para Python.Permiso para crear y usar objetos en Azure AI Search. 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.
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
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))
El siguiente json es una respuesta de ejemplo para un origen de conocimiento de OneLake.
{
"name": "my-onelake-ks",
"kind": "indexedOneLake",
"description": "A sample indexed OneLake knowledge source.",
"encryptionKey": null,
"indexedOneLakeParameters": {
"fabricWorkspaceId": "<REDACTED>",
"lakehouseId": "<REDACTED>",
"targetPath": null,
"ingestionParameters": {
"disableImageVerbalization": false,
"ingestionPermissionOptions": [],
"contentExtractionMode": "standard",
"identity": null,
"embeddingModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "<REDACTED>",
"deploymentId": "text-embedding-3-large",
"apiKey": "<REDACTED>",
"modelName": "text-embedding-3-large"
}
},
"chatCompletionModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "<REDACTED>",
"deploymentId": "gpt-5-mini",
"apiKey": "<REDACTED>",
"modelName": "gpt-5-mini"
}
},
"ingestionSchedule": null,
"aiServices": {
"uri": "<REDACTED>",
"apiKey": "<REDACTED>"
}
},
"createdResources": {
"datasource": "my-onelake-ks-datasource",
"indexer": "my-onelake-ks-indexer",
"skillset": "my-onelake-ks-skillset",
"index": "my-onelake-ks-index"
}
}
}
Nota:
La información confidencial se redacta. Los recursos generados aparecen al final de la respuesta.
Creación de una fuente de conocimiento
Ejecute el código siguiente para crear un origen de conocimiento de OneLake.
# Create a OneLake knowledge source
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import IndexedOneLakeKnowledgeSource, IndexedOneLakeKnowledgeSourceParameters, KnowledgeBaseAzureOpenAIModel, AzureOpenAIVectorizerParameters, KnowledgeSourceAzureOpenAIVectorizer, KnowledgeSourceContentExtractionMode, KnowledgeSourceIngestionParameters
index_client = SearchIndexClient(endpoint = "search_url", credential = AzureKeyCredential("api_key"))
knowledge_source = IndexedOneLakeKnowledgeSource(
name = "my-onelake-ks",
description= "This knowledge source pulls content from a lakehouse.",
encryption_key = None,
indexed_one_lake_parameters = IndexedOneLakeKnowledgeSourceParameters(
fabric_workspace_id = "fabric_workspace_id",
lakehouse_id = "lakehouse_id",
target_path = None,
ingestion_parameters = KnowledgeSourceIngestionParameters(
identity = None,
disable_image_verbalization = False,
chat_completion_model = KnowledgeBaseAzureOpenAIModel(
azure_open_ai_parameters = AzureOpenAIVectorizerParameters(
# TRIMMED FOR BREVITY
)
),
embedding_model = KnowledgeSourceAzureOpenAIVectorizer(
azure_open_ai_parameters=AzureOpenAIVectorizerParameters(
# TRIMMED FOR BREVITY
)
),
content_extraction_mode = KnowledgeSourceContentExtractionMode.MINIMAL,
ingestion_schedule = None,
ingestion_permission_options = None
)
)
)
index_client.create_or_update_knowledge_source(knowledge_source)
print(f"Knowledge source '{knowledge_source.name}' created or updated successfully.")
Propiedades específicas del origen
Puede pasar las siguientes propiedades para crear un origen de conocimiento de OneLake.
| Nombre | Description | Tipo | Modificable | Obligatorio |
|---|---|---|---|---|
name |
El nombre del origen de conocimiento, que debe ser único dentro de la colección de orígenes de conocimiento y seguir las directrices de nomenclatura de los objetos de Azure AI Search. | String | Sí | Sí |
description |
Descripción del origen de conocimiento. | String | Sí | No |
encryption |
Clave administrada por el cliente para cifrar información confidencial tanto en el origen de conocimiento como en los objetos generados. | Objeto | Sí | No |
indexed_one_lake_parameters |
Parámetros específicos de los orígenes de conocimiento de OneLake: fabric_workspace_id, lakehouse_idy target_path. |
Objeto | Sí | |
fabric_workspace_id |
GUID del área de trabajo que contiene almacén de lago de datos. | String | No | Sí |
lakehouse_id |
El identificador único global (GUID) de la casa de lago. | String | No | Sí |
target_path |
Carpeta o acceso directo dentro del almacén de lago de datos. Cuando no se especifica, se indexa todo el almacén de lago de datos. | String | No | No |
propiedades de ingestionParameters
Solo para las fuentes de conocimiento indexadas, puede pasar las siguientes ingestionParameters propiedades para controlar el modo en que se ingiere y procesa el contenido.
| Nombre | Description | Tipo | Modificable | Obligatorio |
|---|---|---|---|---|
identity |
Identidad administrada que se va a usar en el indexador generado. | Objeto | Sí | No |
disable_image_verbalization |
Habilita o deshabilita el uso de la verbalización de imágenes. El valor predeterminado es False, que permite la verbalización de imágenes. Establézcalo en True para deshabilitar la verbalización de imágenes. |
Boolean | No | No |
chat_completion_model |
Un modelo de finalización de chat que verbaliza imágenes o extrae contenido. Los modelos admitidos son gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-minigpt-4.1-nano, , gpt-5, , gpt-5-miniy gpt-5-nano. La habilidad de solicitud de GenAI se incluirá en el conjunto de habilidades generado. Establecer este parámetro también requiere que disable_image_verbalization se establezca en False. |
Objeto | Solo api_key y deployment_name son editables |
No |
embedding_model |
Modelo de inserción de texto que vectoriza el contenido de texto e imagen durante la indexación y en el momento de la consulta. Los modelos admitidos son text-embedding-ada-002, text-embedding-3-smally text-embedding-3-large. La aptitud de inserción de Azure OpenAI se incluirá en el conjunto de aptitudes generado y el vectorizador de Azure OpenAI se incluirá en el índice generado. |
Objeto | Solo api_key y deployment_name son editables |
No |
content_extraction_mode |
Controla cómo se extrae el contenido de los archivos. El valor predeterminado es minimal, que usa la extracción de contenido estándar para texto e imágenes. Establézcalo en standard para el avanzado descifrado de documentos y la fragmentación mediante la habilidad Azure Content Understanding, que se incluirá en el conjunto de habilidades generado. Solo para standard , se pueden especificar los ai_services parámetros y asset_store . |
String | No | No |
ai_services |
Un recurso de Microsoft Foundry para acceder a Azure Content Understanding en Foundry Tools. Establecer este parámetro requiere que content_extraction_mode se establezca en standard. |
Objeto | Solo api_key se puede editar |
Sí |
asset_store |
Un contenedor de blobs para almacenar imágenes extraídas. Establecer este parámetro requiere que content_extraction_mode se establezca en standard. |
Objeto | No | No |
ingestion_schedule |
Agrega información de programación al indexador generado. También puede agregar una programación más adelante para automatizar la actualización de datos. | Objeto | Sí | No |
ingestion_permission_options |
Permisos de nivel de documento para ingerir desde orígenes de conocimiento seleccionados: ADLS Gen2 o SharePoint indexado. Si especifica user_ids, group_idso rbac_scope, el indexador de ADLS Gen2 generado o el indexador de SharePoint incluirán los permisos ingeridos. |
Array | No | No |
Comprobación del estado de la ingesta
Ejecute el siguiente código para supervisar el progreso y la salud de la ingesta, incluido el estado del indexador para los orígenes de conocimiento que generan una canalización de indexador y pueblan un índice de búsqueda.
# Check knowledge source ingestion status
import requests
import json
endpoint = "{search_url}/knowledgesources/{knowledge_source_name}/status"
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 para una solicitud que incluye parámetros de ingesta y que está ingeriendo contenido activamente podría ser similar al ejemplo siguiente.
{
"synchronizationStatus": "active", // creating, active, deleting
"synchronizationInterval" : "1d", // null if no schedule
"currentSynchronizationState" : { // spans multiple indexer "runs"
"startTime": "2025-10-27T19:30:00Z",
"itemUpdatesProcessed": 1100,
"itemsUpdatesFailed": 100,
"itemsSkipped": 1100,
},
"lastSynchronizationState" : { // null on first sync
"startTime": "2025-10-27T19:30:00Z",
"endTime": "2025-10-27T19:40:01Z", // this value appears on the activity record on each /retrieve
"itemUpdatesProcessed": 1100,
"itemsUpdatesFailed": 100,
"itemsSkipped": 1100,
},
"statistics": { // null on first sync
"totalSynchronization": 25,
"averageSynchronizationDuration": "00:15:20",
"averageItemsProcessedPerSynchronization" : 500
}
}
Revisión de los objetos creados
Al crear un origen de conocimiento de OneLake, el servicio de búsqueda también crea un indexador, un índice, un conjunto de aptitudes y un origen de datos. No se recomienda editar estos objetos, ya que introducir un error o incompatibilidad puede interrumpir la canalización.
Después de crear un origen de conocimiento, la respuesta enumera los objetos creados. Estos objetos se crean según una plantilla fija y sus nombres se basan en el nombre del origen de conocimiento. No se pueden cambiar los nombres de objeto.
Se recomienda usar Azure Portal para validar la creación de la salida. El flujo de trabajo es:
- Compruebe si el indexador tiene mensajes correctos o erróneos. Los errores de conexión o cuota aparecen aquí.
- Compruebe el índice para ver el contenido que se puede buscar. Use el Explorador de búsqueda para ejecutar consultas.
- Compruebe el conjunto de aptitudes para obtener información sobre cómo se fragmenta el contenido y opcionalmente, como se vectoriza.
- Compruebe el origen de datos para obtener los detalles de la conexión. En nuestro ejemplo se usan claves de API para simplificar, pero puede usar microsoft Entra ID para la autenticación y el control de acceso basado en rol para la autorización.
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.
Para cualquier base de conocimiento que especifique un origen de conocimiento de OneLake, asegúrese de establecer includeReferenceSourceData en true. Este paso es necesario para extraer la dirección URL del documento de origen en la cita.
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.
# 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.")
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 más información, consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.
Use una fuente de conocimiento de OneLake para indexar y consultar archivos de Microsoft OneLake en una canalización de recuperación con agentes. 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.
Al crear un origen de conocimiento de OneLake, especifique un origen de datos externo, modelos y propiedades para generar automáticamente los siguientes objetos de Azure AI Search:
- Un origen de datos que representa un almacén de lago de datos.
- Conjunto de habilidades que fragmenta y, opcionalmente, vectoriza el contenido multimodal del almacén de lago de datos.
- Índice que almacena contenido enriquecido y cumple los criterios para la recuperación agencial.
- Un indexador que utiliza los objetos previos para impulsar la canalización de indexación y enriquecimiento.
El indexador generado se ajusta al indexador oneLake, cuyos requisitos previos, tareas admitidas, formatos de documento admitidos, accesos directos admitidos y limitaciones también se aplican a los orígenes de conocimiento de OneLake. Para obtener más información, consulte la documentación del indexador oneLake.
Prerrequisitos
Azure AI Search en cualquier región que proporcione recuperación agente. Debe tener habilitado el clasificador semántico.
Finalización de los requisitos previos del indexador de OneLake.
Finalización de la preparación de datos del indexador de OneLake.
La versión 2025-11-01-preview de las API REST del servicio de búsqueda.
Permiso para crear y usar objetos en Azure AI Search. 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.
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.
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 un origen de conocimiento de OneLake.
{
"name": "my-onelake-ks",
"kind": "indexedOneLake",
"description": "A sample indexed OneLake knowledge source.",
"encryptionKey": null,
"indexedOneLakeParameters": {
"fabricWorkspaceId": "<REDACTED>",
"lakehouseId": "<REDACTED>",
"targetPath": null,
"ingestionParameters": {
"disableImageVerbalization": false,
"ingestionPermissionOptions": [],
"contentExtractionMode": "standard",
"identity": null,
"embeddingModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "<REDACTED>",
"deploymentId": "text-embedding-3-large",
"apiKey": "<REDACTED>",
"modelName": "text-embedding-3-large"
}
},
"chatCompletionModel": {
"kind": "azureOpenAI",
"azureOpenAIParameters": {
"resourceUri": "<REDACTED>",
"deploymentId": "gpt-5-mini",
"apiKey": "<REDACTED>",
"modelName": "gpt-5-mini"
}
},
"ingestionSchedule": null,
"aiServices": {
"uri": "<REDACTED>",
"apiKey": "<REDACTED>"
}
},
"createdResources": {
"datasource": "my-onelake-ks-datasource",
"indexer": "my-onelake-ks-indexer",
"skillset": "my-onelake-ks-skillset",
"index": "my-onelake-ks-index"
}
}
}
Nota:
La información confidencial se redacta. Los recursos generados aparecen al final de la respuesta.
Creación de una fuente de conocimiento
Usar orígenes de conocimiento: crear o actualizar (API REST) para crear un origen de conocimiento de OneLake.
PUT {{search-url}}/knowledgesources/my-onelake-ks?api-version=2025-11-01-preview
api-key: {{api-key}}
Content-Type: application/json
{
"name": "my-onelake-ks",
"kind": "indexedOneLake",
"description": "This knowledge source pulls content from a lakehouse.",
"indexedOneLakeParameters": {
"fabricWorkspaceId": "<YOUR FABRIC WORKSPACE GUID>",
"lakehouseId": "<YOUR LAKEHOUSE GUID>",
"targetPath": null,
"ingestionParameters": {
"identity": null,
"disableImageVerbalization": null,
"chatCompletionModel": { TRIMMED FOR BREVITY },
"embeddingModel": { TRIMMED FOR BREVITY },
"contentExtractionMode": "minimal",
"ingestionSchedule": null,
"ingestionPermissionOptions": []
}
}
}
Propiedades específicas del origen
Puede pasar las siguientes propiedades para crear un origen de conocimiento de OneLake.
| Nombre | Description | Tipo | Modificable | Obligatorio |
|---|---|---|---|---|
name |
El nombre del origen de conocimiento, que debe ser único dentro de la colección de orígenes de conocimiento y seguir las directrices de nomenclatura de los objetos de Azure AI Search. | String | Sí | Sí |
kind |
El tipo de origen de conocimiento, que es indexedOneLake 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 |
indexedOneLakeParameters |
Parámetros específicos de los orígenes de conocimiento de OneLake: fabricWorkspaceId, lakehouseIdy targetPath. |
Objeto | Sí | |
fabricWorkspaceId |
GUID del área de trabajo que contiene almacén de lago de datos. | String | No | Sí |
lakehouseId |
El identificador único global (GUID) de la casa de lago. | String | No | Sí |
targetPath |
Carpeta o acceso directo dentro del almacén de lago de datos. Cuando no se especifica, se indexa todo el almacén de lago de datos. | String | No | No |
propiedades de ingestionParameters
Solo para las fuentes de conocimiento indexadas, puede pasar las siguientes ingestionParameters propiedades para controlar el modo en que se ingiere y procesa el contenido.
| Nombre | Description | Tipo | Modificable | Obligatorio |
|---|---|---|---|---|
identity |
Identidad administrada que se va a usar en el indexador generado. | Objeto | Sí | No |
disableImageVerbalization |
Habilita o deshabilita el uso de la verbalización de imágenes. El valor predeterminado es false, que permite la verbalización de imágenes. Establézcalo en true para deshabilitar la verbalización de imágenes. |
Boolean | No | No |
chatCompletionModel |
Un modelo de finalización de chat que verbaliza imágenes o extrae contenido. Los modelos admitidos son gpt-4o, gpt-4o-mini, gpt-4.1, gpt-4.1-minigpt-4.1-nano, , gpt-5, , gpt-5-miniy gpt-5-nano. La habilidad de solicitud de GenAI se incluirá en el conjunto de habilidades generado. Establecer este parámetro también requiere que disableImageVerbalization se establezca en false. |
Objeto | Solo apiKey y deploymentId son editables |
No |
embeddingModel |
Modelo de inserción de texto que vectoriza el contenido de texto e imagen durante la indexación y en el momento de la consulta. Los modelos admitidos son text-embedding-ada-002, text-embedding-3-smally text-embedding-3-large. La aptitud de inserción de Azure OpenAI se incluirá en el conjunto de aptitudes generado y el vectorizador de Azure OpenAI se incluirá en el índice generado. |
Objeto | Solo apiKey y deploymentId son editables |
No |
contentExtractionMode |
Controla cómo se extrae el contenido de los archivos. El valor predeterminado es minimal, que usa la extracción de contenido estándar para texto e imágenes. Establézcalo en standard para el avanzado descifrado de documentos y la fragmentación mediante la habilidad Azure Content Understanding, que se incluirá en el conjunto de habilidades generado. Solo para standard , se pueden especificar los aiServices parámetros y assetStore . |
String | No | No |
aiServices |
Un recurso de Microsoft Foundry para acceder a Azure Content Understanding en Foundry Tools. Establecer este parámetro requiere que contentExtractionMode se establezca en standard. |
Objeto | Solo apiKey se puede editar |
Sí |
assetStore |
Un contenedor de blobs para almacenar imágenes extraídas. Establecer este parámetro requiere que contentExtractionMode se establezca en standard. |
Objeto | No | No |
ingestionSchedule |
Agrega información de programación al indexador generado. También puede agregar una programación más adelante para automatizar la actualización de datos. | Objeto | Sí | No |
ingestionPermissionOptions |
Permisos de nivel de documento para ingerir desde orígenes de conocimiento seleccionados: ADLS Gen2 o SharePoint indexado. Si especifica userIds, groupIdso rbacScope, el indexador de ADLS Gen2 generado o el indexador de SharePoint incluirán los permisos ingeridos. |
Array | No | No |
Comprobación del estado de la ingesta
Usar Orígenes de Conocimiento: estado (API REST) para supervisar el progreso y la salud de la ingesta, incluido el estado del indexador para los orígenes de conocimiento que generan una canalización de indexador y pueblan un índice de búsqueda.
### Check knowledge source ingestion status
GET {{search-url}}/knowledgesources/{{knowledge-source-name}}/status?api-version=2025-11-01-preview
api-key: {{api-key}}
Content-Type: application/json
Una respuesta para una solicitud que incluye parámetros de ingesta y que está ingeriendo contenido activamente podría ser similar al ejemplo siguiente.
{
"synchronizationStatus": "active", // creating, active, deleting
"synchronizationInterval" : "1d", // null if no schedule
"currentSynchronizationState" : { // spans multiple indexer "runs"
"startTime": "2025-10-27T19:30:00Z",
"itemUpdatesProcessed": 1100,
"itemsUpdatesFailed": 100,
"itemsSkipped": 1100,
},
"lastSynchronizationState" : { // null on first sync
"startTime": "2025-10-27T19:30:00Z",
"endTime": "2025-10-27T19:40:01Z", // this value appears on the activity record on each /retrieve
"itemUpdatesProcessed": 1100,
"itemsUpdatesFailed": 100,
"itemsSkipped": 1100,
},
"statistics": { // null on first sync
"totalSynchronization": 25,
"averageSynchronizationDuration": "00:15:20",
"averageItemsProcessedPerSynchronization" : 500
}
}
Revisión de los objetos creados
Al crear un origen de conocimiento de OneLake, el servicio de búsqueda también crea un indexador, un índice, un conjunto de aptitudes y un origen de datos. No se recomienda editar estos objetos, ya que introducir un error o incompatibilidad puede interrumpir la canalización.
Después de crear un origen de conocimiento, la respuesta enumera los objetos creados. Estos objetos se crean según una plantilla fija y sus nombres se basan en el nombre del origen de conocimiento. No se pueden cambiar los nombres de objeto.
Se recomienda usar Azure Portal para validar la creación de la salida. El flujo de trabajo es:
- Compruebe si el indexador tiene mensajes correctos o erróneos. Los errores de conexión o cuota aparecen aquí.
- Compruebe el índice para ver el contenido que se puede buscar. Use el Explorador de búsqueda para ejecutar consultas.
- Compruebe el conjunto de aptitudes para obtener información sobre cómo se fragmenta el contenido y opcionalmente, como se vectoriza.
- Compruebe el origen de datos para obtener los detalles de la conexión. En nuestro ejemplo se usan claves de API para simplificar, pero puede usar microsoft Entra ID para la autenticación y el control de acceso basado en rol para la autorización.
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.
Para cualquier base de conocimiento que especifique un origen de conocimiento de OneLake, asegúrese de establecer includeReferenceSourceData en true. Este paso es necesario para extraer la dirección URL del documento de origen en la cita.
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.
### 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}}