Habilitación del almacenamiento en caché para el enriquecimiento incremental en Azure AI Search
Importante
Esta característica se encuentra en versión preliminar pública en los Términos de uso complementarios. Las API de REST en versión preliminar admiten esta característica.
En este artículo se explica cómo agregar almacenamiento en caché a una canalización de enriquecimiento para que pueda modificar los pasos de enriquecimiento de niveles inferiores sin tener que volver a compilarlo todo cada vez. De forma predeterminada, un conjunto de aptitudes no tiene estado y el cambio de cualquier parte de su composición requiere una nueva ejecución completa del indexador. Con una caché de enriquecimiento, el indexador puede determinar qué partes del árbol de documentos se deben actualizar en función de los cambios detectados en las definiciones del conjunto de aptitudes o del indexador. La salida procesada existente se conserva y se reutiliza siempre que sea posible.
El contenido almacenado en caché se coloca en Azure Storage con la información de la cuenta proporcionada. El contenedor, denominado ms-az-search-indexercache-<alpha-numerc-string>, se crea al ejecutar el indexador. Debe considerarse como un componente interno administrado por el servicio de búsqueda y no debe modificarse.
Requisitos previos
Azure Storage para almacenar enriquecimientos en caché. La cuenta de almacenamiento debe ser de uso general v2.
Solo para la indexación de blobs, si necesita una eliminación sincronizada de documentos tanto de la caché como del índice cuando se eliminan blobs de su fuente de datos, active una directiva de eliminación en el indexador. Sin esta directiva, no es posible eliminar documentos de la caché.
Debería estar familiarizado con la configuración de indexadores. Comience con la información general del indexador y continúe con las conjunto de aptitudes para aprender sobre las canalizaciones de enriquecimiento. Para obtener más información sobre los conceptos clave, vea el tema sobre el enriquecimiento incremental.
Precaución
Si usa el indexador de SharePoint Online (versión preliminar), debe evitar el enriquecimiento incremental. En determinadas circunstancias, la memoria caché no es válida, lo que requiere un restablecimiento y ejecución del indexador, si decide volver a cargarla.
Habilitación en nuevos indizadores
Puede utilizar el Azure portal. las API de versión preliminar o los SDK beta de Azure para habilitar una caché de enriquecimiento en un indexador.
A la izquierda, seleccione Indexadores, y luego seleccione Agregar indexador.
Proporcione un nombre de indizador y un índice, una fuente de datos y un conjunto de aptitudes existentes.
Habilite el almacenamiento en caché incremental y configure la cuenta de Azure Storage.
Habilitación en indizadores existentes
Para los indizadores existentes que ya tienen un conjunto de aptitudes, siga estos pasos para agregar el almacenamiento en caché. Como operación única, restablezca y vuelva a ejecutar el indizador en su totalidad para cargar la memoria caché.
Paso 1: obtención de la definición del indexador
Comience con un indizador de trabajo válido que tenga estos componentes: origen de datos, conjunto de aptitudes, índice. Use un cliente de API para enviar una solicitud GET Indexer para recuperar el indizador. Cuando se usa la versión preliminar de la API para obtener el indizador, se agrega a la definición una propiedad “cache” definida como null automáticamente.
GET https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [YOUR-ADMIN-KEY]
Paso 2: Definir la propiedad de caché
En la definición del índice, modifique "cache" para incluir las siguientes propiedades obligatorias y opcionales:
- (Obligatorio)
storageConnectionStringdebe establecerse en una cadena de conexión de Azure Storage. - (Opcional) La propiedad booleana
enableReprocessing(truede forma predeterminada) indica que el enriquecimiento incremental está habilitado. Puede establecerla enfalsepara suspender el procesamiento incremental mientras se están llevando a cabo otras operaciones con un uso intensivo de recursos, como la indexación de nuevos documentos, y, a continuación, volver a ponerla entruemás adelante.
POST https://[service name].search.windows.net/indexers?api-version=2024-05-01-preview
{
"name": "<YOUR-INDEXER-NAME>",
"targetIndexName": "<YOUR-INDEX-NAME>",
"dataSourceName": "<YOUR-DATASOURCE-NAME>",
"skillsetName": "<YOUR-SKILLSET-NAME>",
"cache" : {
"storageConnectionString" : "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
"enableReprocessing": true
},
"fieldMappings" : [],
"outputFieldMappings": [],
"parameters": []
}
Paso 3: restablecimiento del indexador
El restablecimiento del indizador se requiere al configurar el enriquecimiento incremental de los indizadores existentes para asegurarse de que todos los documentos se encuentran en un estado coherente. Puede usar Azure Portal o un cliente de API para esta tarea.
POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/reset?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [YOUR-ADMIN-KEY]
Paso 4: Guardar el indizador
Indexador de actualización con una solicitud PUT, donde el cuerpo de la solicitud incluya "caché".
PUT https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [YOUR-ADMIN-KEY]
{
"name" : "<YOUR-INDEXER-NAME>",
...
"cache": {
"storageConnectionString": "<YOUR-STORAGE-ACCOUNT-CONNECTION-STRING>",
"enableReprocessing": true
}
}
Si ahora emite otra solicitud GET en el indexador, la respuesta del servicio incluye una propiedad ID en el objeto caché. La cadena se anexa al nombre del contenedor que incluirá todos los resultados almacenados en caché y el estado intermedio de cada documento procesado por este indexador. El Id. se utiliza para nombrar de forma única la caché en el almacenamiento Blob.
"cache": {
"ID": "<ALPHA-NUMERIC STRING>",
"enableReprocessing": true,
"storageConnectionString": "DefaultEndpointsProtocol=https;AccountName=<YOUR-STORAGE-ACCOUNT>;AccountKey=<YOUR-STORAGE-KEY>;EndpointSuffix=core.windows.net"
}
Paso 5: ejecución del indexador
Para ejecutar el indexador, puede usar Azure Portal o la API. En Azure Portal, en la lista de indexadores, seleccione el indexador y, después, Ejecutar. Una ventaja de usar Azure Portal es que puede supervisar el estado del indexador y anotar la duración del trabajo y el número de documentos que se procesan. Las páginas del portal se actualizan cada pocos minutos.
Como alternativa, puede usar REST para ejecutar el indexador:
POST https://[YOUR-SEARCH-SERVICE].search.windows.net/indexers/[YOUR-INDEXER-NAME]/run?api-version=2024-05-01-preview
Content-Type: application/json
api-key: [YOUR-ADMIN-KEY]
Nota:
Restablecer y volver a ejecutar el indexador produce una recompilación completa para que se pueda almacenar en caché el contenido. Todos los enriquecimientos cognitivos se volverán a ejecutar en todos los documentos. La reutilización del contenido enriquecido de la memoria caché empieza después de cargar la memoria caché.
Comprobación de la salida almacenada en caché
Busque la caché en Azure Storage, en Contenedor de blobs. ms-az-search-indexercache-<some-alphanumeric-string> es el nombre del contenedor.
Un indizador crea y usa una memoria caché. Su contenido no es legible para los humanos.
Para comprobar si la memoria caché está operativa, modifique un conjunto de aptitudes y ejecute el indizador. A continuación, compare las métricas antes y después del tiempo de ejecución y los recuentos de documentos.
Los conjuntos de aptitudes que incluyen el análisis de imágenes y el reconocimiento óptico de caracteres (OCR) de documentos digitalizados son buenos casos de prueba. Si modifica una habilidad de texto posterior o cualquier habilidad que no esté relacionada con la imagen, el indizador puede recuperar de la caché todo el contenido de imagen y OCR procesado previamente, actualizando y procesando solo los cambios relacionados con el texto indicados por sus ediciones. Normalmente, obtendrá menos documentos en el recuento de documentos de ejecución del indizador, tiempos de ejecución más cortos y menos cargos en la factura.
El conjunto de archivos que se usa en los tutoriales cog-search-demo es un caso de prueba útil porque contiene 14 archivos de varios formatos JPG, PNG, HTML, DOCX, PPTX y de otros tipos. Cambie en a es o a otro idioma en la aptitud de traducción de texto para realizar pruebas de concepto del enriquecimiento incremental.
Errores comunes
El siguiente error se produce si olvida especificar una versión preliminar de la API en la solicitud:
"The request is invalid. Details: indexer : A resource without a type name was found, but no expected type was specified. To allow entries without type information, the expected type must also be specified when the model is specified."
También se producirá un error 400 Bad Request si falta algún requisito del indexador. El mensaje de error especifica las dependencias que faltan.
Pasos siguientes
El enriquecimiento incremental se aplica a los indexadores que contienen conjuntos de aptitudes, lo que proporciona contenido reutilizable para los índices y los almacenes de conocimiento. Los siguientes vínculos proporcionan más información acerca del almacenamiento en caché y los conjuntos de aptitudes.