Compartir a través de

Creación de un origen de conocimiento de blobs desde Azure Blob Storage y ADLS Gen2

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 un origen de conocimiento de blob para indexar y consultar el contenido de blobs de Azure en una canalización de recuperación con agente. 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.

A diferencia de un origen de conocimiento de índice de búsqueda, que especifica un índice existente y calificado, un origen de conocimiento de blobs especifica un origen de datos externo, modelos y propiedades para generar automáticamente los siguientes objetos de Azure AI Search:

  • Origen de datos que representa un contenedor de blobs.
  • Conjunto de habilidades que fragmenta y, opcionalmente, vectoriza el contenido multimodal del contenedor.
  • Í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.

Nota:

Si se especifica el acceso de usuario a nivel de documento (blob) en Azure Storage, un origen de conocimiento puede transferir los metadatos de permisos al contenido indexado en Azure AI Search. Para obtener más información, consulte Metadatos de permisos de ADLS Gen2 o los Alcances de RBAC para Blobs.

Prerrequisitos

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 blobs.

{
  "name": "my-blob-ks",
  "kind": "azureBlob",
  "description": "A sample blob knowledge source.",
  "encryptionKey": null,
  "azureBlobParameters": {
    "connectionString": "<REDACTED>",
    "containerName": "blobcontainer",
    "folderPath": null,
    "isADLSGen2": false,
    "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",
          "authIdentity": null
        }
      },
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "gpt-5-mini",
          "apiKey": "<REDACTED>",
          "modelName": "gpt-5-mini",
          "authIdentity": null
        }
      },
      "ingestionSchedule": null,
      "assetStore": null,
      "aiServices": {
        "uri": "<REDACTED>",
        "apiKey": "<REDACTED>"
      }
    },
    "createdResources": {
      "datasource": "my-blob-ks-datasource",
      "indexer": "my-blob-ks-indexer",
      "skillset": "my-blob-ks-skillset",
      "index": "my-blob-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 blobs.

// Create a blob 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 blobParams = new AzureBlobKnowledgeSourceParameters(
    connectionString: connectionString,
    containerName: containerName
)
{
    IsAdlsGen2 = false,
    IngestionParameters = ingestionParams
};

var knowledgeSource = new AzureBlobKnowledgeSource(
    name: "my-blob-ks",
    azureBlobParameters: blobParams
)
{
    Description = "This knowledge source pulls from a blob storage container."
};

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 una fuente de datos de tipo blob.

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 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
chatCompletionParams Parámetros específicos de los modelos de finalización de chat usados para la planificación de consultas y la síntesis opcional de respuestas cuando el esfuerzo de razonamiento de recuperación es bajo o medio. Objeto No
embeddingParams Parámetros específicos de la inserción de modelos usados si desea vectorizar fragmentos de contenido. Objeto No
azureBlobParameters Parámetros específicos de los orígenes de conocimiento de blobs: connectionString, containerName, folderPathy isAdlsGen2. Objeto No
connectionString Una cadena de conexión basada en claves o, si usa una identidad administrada, el identificador de recurso. String No Sí
containerName Nombre del contenedor de almacenamiento de blobs. String No Sí
folderPath Una carpeta dentro del contenedor. String No No
isAdlsGen2 El valor predeterminado es False. Establézcalo en True si está utilizando una cuenta de almacenamiento de ADLS Gen2. Boolean 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 indicación 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ézcala en standard para el avanzado descifrado de documentos y la fragmentación mediante la habilidad comprensión de contenidos de Azure, 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 blobs, 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:

  1. Compruebe si el indexador tiene mensajes correctos o erróneos. Los errores de conexión o cuota aparecen aquí.
  2. Compruebe el índice para ver el contenido que se puede buscar. Use el Explorador de búsqueda para ejecutar consultas.
  3. Compruebe el conjunto de aptitudes para obtener información sobre cómo se fragmenta el contenido y opcionalmente, como se vectoriza.
  4. 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.

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:

  1. 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

  2. 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
 }

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

  4. 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 un origen de conocimiento de blob para indexar y consultar el contenido de blobs de Azure en una canalización de recuperación con agente. 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.

A diferencia de un origen de conocimiento de índice de búsqueda, que especifica un índice existente y calificado, un origen de conocimiento de blobs especifica un origen de datos externo, modelos y propiedades para generar automáticamente los siguientes objetos de Azure AI Search:

  • Origen de datos que representa un contenedor de blobs.
  • Conjunto de habilidades que fragmenta y, opcionalmente, vectoriza el contenido multimodal del contenedor.
  • Í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.

Nota:

Si se especifica el acceso de usuario a nivel de documento (blob) en Azure Storage, un origen de conocimiento puede transferir los metadatos de permisos al contenido indexado en Azure AI Search. Para obtener más información, consulte Metadatos de permisos de ADLS Gen2 o los Alcances de RBAC para Blobs.

Prerrequisitos

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 blobs.

{
  "name": "my-blob-ks",
  "kind": "azureBlob",
  "description": "A sample blob knowledge source.",
  "encryptionKey": null,
  "azureBlobParameters": {
    "connectionString": "<REDACTED>",
    "containerName": "blobcontainer",
    "folderPath": null,
    "isADLSGen2": false,
    "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",
          "authIdentity": null
        }
      },
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "gpt-5-mini",
          "apiKey": "<REDACTED>",
          "modelName": "gpt-5-mini",
          "authIdentity": null
        }
      },
      "ingestionSchedule": null,
      "assetStore": null,
      "aiServices": {
        "uri": "<REDACTED>",
        "apiKey": "<REDACTED>"
      }
    },
    "createdResources": {
      "datasource": "my-blob-ks-datasource",
      "indexer": "my-blob-ks-indexer",
      "skillset": "my-blob-ks-skillset",
      "index": "my-blob-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 blobs.

# Create a blob knowledge source
from azure.core.credentials import AzureKeyCredential
from azure.search.documents.indexes import SearchIndexClient
from azure.search.documents.indexes.models import AzureBlobKnowledgeSource, AzureBlobKnowledgeSourceParameters, KnowledgeBaseAzureOpenAIModel, AzureOpenAIVectorizerParameters, KnowledgeSourceAzureOpenAIVectorizer, KnowledgeSourceContentExtractionMode, KnowledgeSourceIngestionParameters

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

knowledge_source = AzureBlobKnowledgeSource(
    name = "my-blob-ks",
    description = "This knowledge source pulls from a blob storage container.",
    encryption_key = None,
    azure_blob_parameters = AzureBlobKnowledgeSourceParameters(
        connection_string = "blob_connection_string",
        container_name = "blob_container_name",
        folder_path = None,
        is_adls_gen2 = False,
        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 una fuente de datos de tipo blob.

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 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
azure_blob_parameters Parámetros específicos de los orígenes de conocimiento de blobs: connection_string, container_name, folder_pathy is_adls_gen2. Objeto No
connection_string Una cadena de conexión basada en claves o, si usa una identidad administrada, el identificador de recurso. String No Sí
container_name Nombre del contenedor de almacenamiento de blobs. String No Sí
folder_path Una carpeta dentro del contenedor. String No No
is_adls_gen2 El valor predeterminado es False. Establézcalo en True si está utilizando una cuenta de almacenamiento de ADLS Gen2. Boolean 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 indicación 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ézcala en standard para el avanzado descifrado de documentos y la fragmentación mediante la habilidad comprensión de contenidos de Azure, 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 blobs, 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:

  1. Compruebe si el indexador tiene mensajes correctos o erróneos. Los errores de conexión o cuota aparecen aquí.
  2. Compruebe el índice para ver el contenido que se puede buscar. Use el Explorador de búsqueda para ejecutar consultas.
  3. Compruebe el conjunto de aptitudes para obtener información sobre cómo se fragmenta el contenido y opcionalmente, como se vectoriza.
  4. 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.

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:

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

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

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

  4. 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 un origen de conocimiento de blob para indexar y consultar el contenido de blobs de Azure en una canalización de recuperación con agente. 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.

A diferencia de un origen de conocimiento de índice de búsqueda, que especifica un índice existente y calificado, un origen de conocimiento de blobs especifica un origen de datos externo, modelos y propiedades para generar automáticamente los siguientes objetos de Azure AI Search:

  • Origen de datos que representa un contenedor de blobs.
  • Conjunto de habilidades que fragmenta y, opcionalmente, vectoriza el contenido multimodal del contenedor.
  • Í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.

Nota:

Si se especifica el acceso de usuario a nivel de documento (blob) en Azure Storage, un origen de conocimiento puede transferir los metadatos de permisos al contenido indexado en Azure AI Search. Para obtener más información, consulte Metadatos de permisos de ADLS Gen2 o los Alcances de RBAC para Blobs.

Prerrequisitos

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 blobs.

{
  "name": "my-blob-ks",
  "kind": "azureBlob",
  "description": "A sample blob knowledge source.",
  "encryptionKey": null,
  "azureBlobParameters": {
    "connectionString": "<REDACTED>",
    "containerName": "blobcontainer",
    "folderPath": null,
    "isADLSGen2": false,
    "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",
          "authIdentity": null
        }
      },
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "<REDACTED>",
          "deploymentId": "gpt-5-mini",
          "apiKey": "<REDACTED>",
          "modelName": "gpt-5-mini",
          "authIdentity": null
        }
      },
      "ingestionSchedule": null,
      "assetStore": null,
      "aiServices": {
        "uri": "<REDACTED>",
        "apiKey": "<REDACTED>"
      }
    },
    "createdResources": {
      "datasource": "my-blob-ks-datasource",
      "indexer": "my-blob-ks-indexer",
      "skillset": "my-blob-ks-skillset",
      "index": "my-blob-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

Utilice Fuentes de Conocimiento: Crear o Actualizar (API REST) para crear una fuente de conocimiento de blobs.

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

{
  "name": "my-blob-ks",
  "kind": "azureBlob",
  "description": "This knowledge source pulls from a blob storage container.",
  "encryptionKey": null,
  "azureBlobParameters": {
    "connectionString": "<YOUR AZURE STORAGE CONNECTION STRING>",
    "containerName": "<YOUR BLOB CONTAINER NAME>",
    "folderPath": null,
    "isADLSGen2": false,
    "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 una fuente de datos de tipo blob.

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 No Sí
kind El tipo de origen de conocimiento, que es azureBlob 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
azureBlobParameters Parámetros específicos de los orígenes de conocimiento de blobs: connectionString, containerName, folderPathy isADLSGen2. Objeto No
connectionString Una cadena de conexión basada en claves o, si usa una identidad administrada, el identificador de recurso. String No Sí
containerName Nombre del contenedor de almacenamiento de blobs. String No Sí
folderPath Una carpeta dentro del contenedor. String No No
isADLSGen2 El valor predeterminado es false. Establézcalo en true si está utilizando una cuenta de almacenamiento de ADLS Gen2. Boolean 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 indicación 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ézcala en standard para el avanzado descifrado de documentos y la fragmentación mediante la habilidad comprensión de contenidos de Azure, 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

Use Orígenes de Conocimiento: estado (API de 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 blobs, 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:

  1. Compruebe si el indexador tiene mensajes correctos o erróneos. Los errores de conexión o cuota aparecen aquí.
  2. Compruebe el índice para ver el contenido que se puede buscar. Use el Explorador de búsqueda para ejecutar consultas.
  3. Compruebe el conjunto de aptitudes para obtener información sobre cómo se fragmenta el contenido y opcionalmente, como se vectoriza.
  4. 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.

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:

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

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

  3. 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}}

  4. 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}}

Contenido relacionado

  • Last updated on