Administración de una caché de enriquecimiento (versión preliminar)

Note

Búsqueda de Azure AI está disponible a través del portal de Azure, las API REST y los SDK de Azure. También respalda Foundry IQ, la capa de conocimiento administrada que transforma el contenido empresarial en bases de conocimiento reutilizables y compatibles con permisos para agentes en el portal de Microsoft Foundry.

Importante

Las características, funcionalidades o propiedades marcadas (versión preliminar) no están cubiertas por un contrato de nivel de servicio, no se recomiendan para cargas de trabajo de producción y pueden cambiar o restringirse antes de que estén disponibles con carácter general. Los términos de la versión preliminar Búsqueda de Azure AI se aplican a todas las funciones de vista previa, ya sea independiente o parte de una característica disponible con carácter general.

Una caché de enriquecimiento (versión preliminar) es una característica opcional que almacena el contenido enriquecido creado durante la ejecución del conjunto de aptitudes. Conserva el contenido entre ejecuciones para que solo las habilidades modificadas y los documentos deban reprocesarse. No es una copia de seguridad de los resultados del conjunto de habilidades, del estado del indexador ni de los documentos indexados.

La memoria caché de enriquecimiento se crea en Azure Storage. La caché contiene el resultado del descifrado de documentos, además de los resultados de cada habilidad para cada documento. Aunque el almacenamiento en caché es facturable (usa Azure Storage), el costo total del enriquecimiento se reduce porque los costos de almacenamiento son menores que la extracción de imágenes y el procesamiento de inteligencia artificial.

Si configura una caché de enriquecimiento, en este artículo se explica cómo administrar las actualizaciones de aptitudes y orígenes de datos para obtener la máxima utilidad de los enriquecimientos almacenados en caché.

Requisitos previos

Limitaciones

Precaución

Si usa el indizador de SharePoint (versión preliminar), evite el enriquecimiento incremental. En determinadas circunstancias, la memoria caché deja de ser válida. Para volver a cargarlo, realice un restablecimiento del indexador y recompilación completa.

Los orígenes de datos de gran tamaño tienen una limitación adicional de la memoria caché.

Precaución

En el caso de fuentes de datos de gran tamaño, una caché de enriquecimiento puede aumentar el reprocesamiento total cuando se producen habilidades de larga duración, interrupciones repetidas o errores frecuentes de las habilidades. El indexador prioriza la corrección frente a minimizar el reprocesamiento, por lo que una acumulación en la caché provocada por interrupciones repetidas amplifica el comportamiento de reintento.

Para recuperarse de un trabajo pendiente de caché creciente, particione el origen de datos en contenedores o carpetas virtuales más pequeños. A continuación, use indizadores paralelos que apuntan al mismo índice. Para desasociar la memoria caché, establezca la cache propiedad en null en el indexador.

Configuración de caché

Físicamente, la memoria caché se almacena en un contenedor de blobs y tablas de la cuenta de Azure Storage, una por indexador. A cada indexador se le asigna un identificador de caché único e inmutable que corresponde al contenedor que usa.

La memoria caché se crea al especificar la cache propiedad y ejecutar el indexador. Solo se puede almacenar en caché el contenido enriquecido. Si el indexador no tiene un conjunto de aptitudes adjunto, no se aplica el almacenamiento en caché.

En el ejemplo siguiente se muestra un indexador con el almacenamiento en caché habilitado. Consulte Configurar el almacenamiento en caché de enriquecimiento para obtener las instrucciones completas.

POST https://[YOUR-SEARCH-SERVICE-NAME].search.windows.net/indexers?api-version=2026-08-01-preview
    {
        "name": "myIndexerName",
        "targetIndexName": "myIndex",
        "dataSourceName": "myDatasource",
        "skillsetName": "mySkillset",
        "cache" : {
            "storageConnectionString" : "<Your storage account connection string>",
            "enableReprocessing": true
        },
        "fieldMappings" : [],
        "outputFieldMappings": [],
        "parameters": []
    }

Administración de caché

El indexador administra el ciclo de vida de la memoria caché. Si elimina un indexador, también eliminará su caché. Si establece la propiedad del cache indexador en null o cambia el cadena de conexión, la caché existente se elimina durante la siguiente ejecución del indexador.

Aunque el enriquecimiento incremental está diseñado para detectar y responder a los cambios sin intervención en su parte, puede establecer parámetros para invocar comportamientos específicos:

Dar prioridad a los nuevos documentos

La cache propiedad incluye un enableReprocessing parámetro que controla si se vuelve a procesar el contenido almacenado en caché. Cuando es true (valor predeterminado), el indexador vuelve a procesar los documentos almacenados en caché al volver a ejecutarlos si una actualización de aptitudes las afecta.

Cuando es false, el indexador no vuelve a procesar los documentos existentes, lo que da prioridad al nuevo contenido. Ponga enableReprocessing en falso solo temporalmente. Mantener la validez la mayor parte del tiempo garantiza que los documentos nuevos y existentes sigan siendo válidos para la definición actual de las competencias.

Omitir evaluación del conjunto de aptitudes

Modificar una habilidad suele ir de la mano de reprocesar esa habilidad. Sin embargo, algunos cambios en una aptitud no deben desencadenar el reprocesamiento. Por ejemplo, implementar una aptitud personalizada en una nueva ubicación o con una nueva clave de acceso. Estos cambios suelen ser modificaciones periféricas que no afectan a la esencia del resultado de la habilidad.

Si sabe que un cambio en la aptitud es superficial, invalide la evaluación de aptitudes estableciendo el disableCacheReprocessingChangeDetection parámetro en true:

  1. Llame a Actualizar Skillset y modifique la definición del conjunto de aptitudes.
  2. Anexe el disableCacheReprocessingChangeDetection=true parámetro en la solicitud.
  3. Envíe el cambio.

Al establecer este parámetro, solo se confirman las actualizaciones de la definición del conjunto de aptitudes. El cambio no se evalúa para ver los efectos en la caché existente. Use una versión preliminar de la API, 2020-06-30-Preview o posterior. Use la API de versión preliminar más reciente.

PUT https://[servicename].search.windows.net/skillsets/[skillset name]?api-version=2026-08-01-preview&disableCacheReprocessingChangeDetection

Omitir comprobaciones de validación del origen de datos

La mayoría de los cambios en una definición de origen de datos invalidan la memoria caché. Sin embargo, en escenarios en los que sabe que un cambio no debe invalidar la memoria caché, como cambiar una cadena de conexión o cambiar la clave de la cuenta de almacenamiento, anexe el parámetro ignoreResetRequirement en la actualización del origen de datos. Establezca este parámetro en true para permitir que la confirmación pase, sin desencadenar una condición de restablecimiento que daría lugar a que todos los objetos se vuelvan a compilar y rellenar desde cero.

PUT https://[search service].search.windows.net/datasources/[data source name]?api-version=2026-08-01-preview&ignoreResetRequirement

Forzar la evaluación de las habilidades

El propósito de la memoria caché es evitar el procesamiento innecesario. Pero supongamos que realiza un cambio en una aptitud que el indexador no detecta (por ejemplo, cambiar algo en código externo, como una aptitud personalizada).

En este caso, use la API Reset Skills para forzar el reprocesamiento de una habilidad concreta, incluidas las habilidades posteriores que dependan de la salida de esa habilidad. Esta API acepta una solicitud POST con una lista de aptitudes que se deben invalidar y marcar para el reprocesamiento. Después de restablecer las aptitudes, siga con una solicitud para ejecutar el indizador para invocar el procesamiento de la canalización.

Volver a almacenar en caché documentos específicos

Si restablece un indexador, se vuelven a procesar todos los documentos del corpus de búsqueda.

En escenarios en los que solo algunos documentos necesitan volver a procesarse, use Restablecer documentos (versión preliminar) para forzar el reprocesamiento de documentos específicos. Al restablecer un documento, el indexador invalida la memoria caché de ese documento. A continuación, el indexador vuelve a procesar el documento leyéndolo desde el origen de datos. Para obtener más información, vea Ejecutar o restablecer indizadores, funciones y documentos.

Para restablecer documentos específicos, incluya una lista de claves de documento como se lee en el índice de búsqueda de la solicitud. Si la clave corresponde a un campo del origen de datos externo, use el valor del índice de búsqueda.

Según cómo invoque a la API, la solicitud añade, sobrescribe o encola la lista de claves:

  • Al llamar a la API varias veces con claves diferentes, se anexan las nuevas claves a la lista de claves de documento que se van a restablecer.

  • Al llamar a la API con el parámetro de cadena de consulta overwrite establecido en true, se sobrescribe la lista actual de claves de documentos para restablecerla con la carga útil de la solicitud.

  • Al llamar a la API, se agregan las claves de documento a la cola de trabajo que procesa el indexador. Cuando el indexador se invoca a continuación, ya sea como programado o a petición, prioriza el procesamiento de las claves de documento de restablecimiento antes de cualquier otro cambio del origen de datos.

En el ejemplo siguiente se muestra una solicitud de documento de restablecimiento:

POST https://[search service name].search.windows.net/indexers/[indexer name]/resetdocs?api-version=2026-08-01-preview
    {
        "documentKeys" : [
            "key1",
            "key2",
            "key3"
        ]
    }

Cambios que invalidan la memoria caché

Al habilitar una caché, el indexador comprueba si hay cambios en la composición de la canalización para decidir qué contenido puede reutilizar y qué contenido necesita volver a procesar. En esta sección se enumeran los cambios que invalidan la memoria caché, seguidos de los cambios que desencadenan el procesamiento incremental.

Un cambio de invalidación es uno en el que toda la memoria caché deja de ser válida. Por ejemplo, actualizar el origen de datos constituye un cambio que invalida. Esta es la lista completa de cambios en cualquier parte de la canalización del indexador que invalide la memoria caché:

  • Cambio del tipo de origen de datos
  • Cambio del contenedor de origen de datos
  • Cambio de las credenciales del origen de datos
  • Cambio de la directiva de detección de cambios del origen de datos
  • Cambio de directiva de detección de eliminación de orígenes de datos
  • Cambiar las asignaciones de campos del indexador
  • Cambio de parámetros del indexador:
    • Modo de análisis
    • Extensiones de nombre de archivo excluidas
    • Extensiones de nombres de archivos indexados
    • Metadatos de almacenamiento de índices solo para documentos sobredimensionados
    • Encabezados de texto delimitados
    • Delimitador de texto delimitado
    • Raíz del documento
    • Acción de imagen (cambios en cómo se extraen las imágenes)

Cambios que desencadenan el procesamiento incremental

El procesamiento incremental evalúa la definición del conjunto de habilidades y determina qué habilidades deben volver a ejecutarse. Actualiza selectivamente las partes afectadas del árbol de documentos. Esta es la lista completa de cambios que dan lugar al enriquecimiento incremental:

  • Cambio del tipo de aptitud (actualización del tipo OData de la aptitud)
  • Actualización de parámetros específicos de la aptitud, como una dirección URL, valores predeterminados u otros parámetros
  • Cambio de las salidas de la habilidad, como cuando la habilidad genera salidas adicionales o diferentes
  • Cambiar las entradas de una habilidad que den lugar a una ascendencia o un encadenamiento de habilidades diferentes
  • Cualquier invalidación de una habilidad anterior, si actualizas una habilidad que proporciona una entrada a esta habilidad
  • Actualización de la ubicación de proyección del almacén de conocimiento, lo que da como resultado la nueva proyección de documentos
  • Cambio de las proyecciones del almacén de conocimiento, lo que da como resultado la nueva proyección de documentos
  • Cambiar las asignaciones de campos de salida en un indexador, lo que da como resultado volver a proyectar documentos en el índice

API usadas para el almacenamiento en caché

Las API en versión preliminar proporcionan propiedades adicionales en los indexadores. Use la API de versión preliminar más reciente.

Utiliza la versión disponible de forma general para conjuntos de habilidades y fuentes de datos. Además de la documentación de referencia, consulte Configuración del almacenamiento en caché para el enriquecimiento incremental para obtener más información sobre el orden de las operaciones.

  • Last updated on