Actualización o recompilación de un índice en Búsqueda de Azure AI

Artículo
09/03/2024

En este artículo se explica cómo actualizar un índice existente en Búsqueda de Azure AI con cambios de esquema o cambios de contenido a través de la indexación incremental. En él se explican las circunstancias en las que se requieren recompilaciones y se dan recomendaciones para mitigar el efecto de las recompilaciones en las solicitudes de consulta en curso.

Durante el desarrollo activo, es habitual quitar y volver a generar índices al iterar sobre el diseño de índices. La mayoría de los desarrolladores trabajan con una pequeña muestra representativa de sus datos para que la reindexación sea más rápida.

En el caso de cambios de esquema en las aplicaciones ya en producción, se recomienda crear y probar un nuevo índice que se ejecute en paralelo a un índice existente. Use un alias de índice para intercambiar en el nuevo índice y evitar al mismo tiempo cambios en el código de la aplicación.

Actualización del contenido

En la mayoría de las aplicaciones de búsqueda, es fundamental la indexación incremental y la sincronización de un índice con los cambios en los datos de origen. En esta sección se explica el flujo de trabajo para actualizar el contenido del campo en un índice de búsqueda.

Use las mismas técnicas para cargar documentos: Documents - Index (REST) o una API equivalente de los SDK de Azure. Para más información sobre las técnicas de indexación, consulte Carga de documentos.

Establezca el parámetro @search.action para determinar el efecto en los documentos existentes:

Action	Efecto
delete	Elimina todo el documento del índice. Si solo quiere quitar un campo individual, utilice merge en su lugar, estableciendo el campo en cuestión en NULL. Los documentos y campos eliminados no liberan espacio inmediatamente en el índice. Cada pocos minutos, un proceso en segundo plano realiza la eliminación física. Tanto si usa el portal como una API para devolver estadísticas de índice, cabría esperar un pequeño retraso antes de que la eliminación se refleje en el portal y mediante las API.
merge	Actualiza un documento que ya existe y produce un error en un documento si no se encuentra. La operación "merge" reemplaza los valores existentes. Por esta razón, asegúrese de comprobar que los campos de colección contengan varios valores, como los campos de tipo `Collection(Edm.String)`. Por ejemplo, si el campo `tags` empieza con un valor de `["budget"]` y ejecuta una operación "merge" con el valor `["economy", "pool"]`, el valor final del campo `tags` será `["economy", "pool"]`. No será `["budget", "economy", "pool"]`.
mergeOrUpload	Se comporta como merge si el documento existe, y como upload si el documento es nuevo. Esta es la acción más común para las actualizaciones incrementales.
upload	Similar a una operación "upsert", donde se inserta el documento si es nuevo, y se actualiza o reemplaza si ya existe. Si al documento le faltan valores que requiere el índice, el valor del campo de documento se establece en NULL.

Publique la actualización.

Las consultas continúan ejecutándose, pero si va a actualizar o quitar campos existentes, cabría esperar resultados mixtos y una mayor incidencia de limitación.

Sugerencias para la indexación incremental

Los indexadores automatizan la indexación incremental. Si puede usar un indexador y, si el origen de datos admite el seguimiento de cambios, puede ejecutar el indexador según una programación periódica para agregar, actualizar o sobrescribir contenido que se puede buscar para que se sincronice con los datos externos.
Si realiza llamadas de índice directamente a través de la API de inserción, use mergeOrUpload como acción de búsqueda.
La carga debe incluir las claves o identificadores de todos los documentos que desea agregar, actualizar o eliminar.
Si el índice incluye campos vectoriales y establece la propiedad stored en false, asegúrese de proporcionar el vector en la actualización parcial del documento, incluso si el valor no cambia. Un efecto secundario de establecer stored en false es que los vectores se quitan en una operación de reindexación. Proporcionar el vector en la carga de documentos impide que esto suceda.
Para actualizar el contenido de campos simples y subcampos de tipos complejos, enumere solo los campos que desea cambiar. Por ejemplo, si solo necesita actualizar un campo de descripción, la carga debe constar de la clave del documento y la descripción modificada. Si se omiten otros campos, se conservan sus valores existentes.
Para combinar los cambios insertados en la colección de cadenas, proporciona todo el valor. Recuerde el ejemplo del campo tags de la sección anterior. Los nuevos valores sobrescriben los valores antiguos para un campo completo y no hay ninguna combinación en el contenido de un campo.

Este es un ejemplo de API de REST que muestra estas sugerencias:

### Get Stay-Kay City Hotel by ID
GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2024-07-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

### Change the description, city, and tags for Stay-Kay City Hotel
POST {{baseUrl}}/indexes/hotels-vector-quickstart/docs/search.index?api-version=2024-07-01  HTTP/1.1
  Content-Type: application/json
  api-key: {{apiKey}}

    {
        "value": [
            {
            "@search.action": "mergeOrUpload",
            "HotelId": "1",
            "Description": "I'm overwriting the description for Stay-Kay City Hotel.",
            "Tags": ["my old item", "my new item"],
            "Address": {
                "City": "Gotham City"
                }
            }
        ]
    }
       
### Retrieve the same document, confirm the overwrites and retention of all other values
GET  {{baseUrl}}/indexes/hotels-vector-quickstart/docs('1')?api-version=2024-07-01  HTTP/1.1
    Content-Type: application/json
    api-key: {{apiKey}}

Cambio de un esquema de índice

El esquema de índice define las estructuras de datos físicas creadas en el servicio de búsqueda, por lo que no hay muchos cambios de esquema que pueda realizar sin incurrir en una recompilación completa. En la lista siguiente se enumeran los cambios de esquema que se pueden introducir fácilmente en un índice existente. Por lo general, la lista incluye nuevos campos y funcionalidades que se usan durante la ejecución de la consulta.

Agregar un campo nuevo
Establecer el atributo retrievable en un campo existente
Actualizar searchAnalyzer en un campo que tiene un elemento indexAnalyzer ya existente
Adición de una nueva definición de analizador en un índice (que se puede aplicar a nuevos campos)
Adición, actualización o eliminación de los perfiles de puntuación
Adición, actualización o eliminación de configuraciones CORS
Adición, actualización o eliminación de synonymMaps
Adición, actualización o eliminación de configuraciones semánticas

El orden de las operaciones es:

Obtener la definición del índice.
Revisar el esquema con actualizaciones de la lista anterior.
Actualizar el esquema de índice en el servicio de búsqueda.
Actualizar el contenido del índice para que coincida con el esquema revisado si ha agregado un nuevo campo. Para todos los demás cambios, el contenido indexado existente se usa tal cual.

Al actualizar un esquema de índice, para incluir un nuevo campo, los documentos existentes en el índice reciben un valor null para ese campo. En el siguiente trabajo de indexación, los valores de los datos de origen externo reemplazan los valores null agregados por Búsqueda de Azure AI.

No debe haber interrupciones en las consultas durante las actualizaciones, pero los resultados de las consultas variarán a medida que se apliquen las actualizaciones.

Anulación y recompilación de índices

Algunas modificaciones requieren una eliminación y recompilación de índices, reemplazando un índice actual por uno nuevo.

Acción	Descripción
Eliminar un campo	Para quitar físicamente todos los rastros de un campo, tendrá que recompilar el índice. Cuando una recompilación inmediata no es práctica, puede modificar el código de la aplicación para redirigir el acceso fuera de un campo obsoleto o usar los parámetros de consulta searchFields y select para elegir qué campos se buscan y devuelven. Físicamente, el contenido y la definición del campo permanecen en el índice hasta la próxima recompilación, cuando aplica un esquema que omite el campo en cuestión.
Cambiar la definición de un campo	Las revisiones del nombre, el tipo de datos o los atributos de índice específicos (si se pueden buscar, filtrar, ordenar, clasificar) de un campo requiere una recompilación completa.
Asignar un analizador a un campo	Los analizadores se definen en un índice, se asignan a campos y, a continuación, se invocan durante la indexación para informar sobre cómo se crean los tokens. Puede agregar una nueva definición de analizador a un índice en cualquier momento, pero solo puede asignar un analizador cuando se crea el campo. Esto es así tanto para la propiedad analyzer como para la propiedad indexAnalyzer. La propiedad searchAnalyzer es una excepción (puede asignar esta propiedad a un campo existente).
Actualizar o eliminar una definición de analizador en un índice	No puede eliminar ni cambiar una configuración de analizador existente (analizador, tokenizador, filtro de token o filtro de caracteres) en el índice, a menos que recompile todo el índice.
Agregar un campo a un proveedor de sugerencias	Si ya existe un campo y desea agregarlo a una construcción de proveedor de sugerencias, recompile el índice.
Cambiar los niveles	No se admiten las actualizaciones locales. Si necesita más capacidad, cree otro servicio y recompilar los índices desde cero. Para ayudar a automatizar este proceso, puede usar el código de ejemplo index-backup-restore de este repositorio de ejemplo .NET de Azure AI Search. Esta aplicación hace una copia de seguridad del índice en una serie de archivos JSON y luego vuelve a crear el índice en un servicio de búsqueda que especifique.

El orden de las operaciones es:

Obtén una definición de índice, por si la necesitas para futuras referencias o para usarla como base para una versión nueva.
Considere la posibilidad de usar una solución de copia de seguridad y restauración para conservar una copia del contenido del índice. Hay soluciones en C# y en Python. Se recomienda la versión de Python porque está más actualizada.

Si tienes capacidad en el servicio de búsqueda, mantén el índice existente al crear y probar el nuevo.
Eliminar el índice existente. Se eliminan inmediatamente todas las consultas dirigidas a ese índice. Recuerde que la eliminación de un índice es una acción irreversible, ya que se destruye el almacenamiento físico para la colección de campos y otras construcciones.
Publique un índice revisado, en el que el cuerpo de la solicitud incluya definiciones y configuraciones de campos modificadas o cambiadas.
Cargue documentos en el índice desde un origen de datos externo. Los documentos se indexan mediante las definiciones y configuraciones de campos del nuevo esquema.

Cuando se crea el índice, se asigna almacenamiento físico para cada campo del esquema de índice; se crea además un índice invertido para cada campo de búsqueda y un índice vectorial para cada campo vectorial. Los campos que no pueden buscarse se pueden usar en filtros o expresiones, pero no cuentan con índices invertidos y no están habilitados para búsquedas de texto completo o aproximadas. En una recompilación de índices, estos índices invertidos se eliminan y vuelven a crear en función del esquema de índice proporcionado.

Equilibrio de cargas de trabajo

La indexación no se ejecuta en segundo plano, pero el servicio de búsqueda equilibrará los trabajos de indexación con las consultas en curso. Durante la indexación, puede supervisar las solicitudes de consulta en el portal para asegurarse de que las consultas se completen puntualmente.

Si las cargas de trabajo de indexación presentan unos niveles inaceptables de latencia de consulta, realice un análisis de rendimiento y revise estas sugerencias de rendimiento para una posible mitigación.

Buscar actualizaciones

Puede empezar a consultar un índice en cuanto se carga el primer documento. Si conoce el identificador de un documento, la API REST para buscar documentos devuelve el documento específico. Para realizar pruebas más amplias, debe esperar hasta que el índice se haya cargado completamente y, a continuación, usar consultas para comprobar el contexto que espera ver.

Puede usar el explorador de búsqueda o un cliente REST para comprobar el contenido actualizado.

Si ha agregado un campo o le ha cambiado el nombre, use $select para devolver ese campo: search=*&$select=document-id,my-new-field,some-old-field&$count=true

Azure Portal proporciona el tamaño del índice y el tamaño del índice vectorial. Puede comprobar estos valores después de actualizar un índice, pero recuerde que cabe esperar un pequeño retraso a medida que el servicio procesa el cambio y que debe tener en cuenta las velocidades de actualización del portal, que puede ser de unos minutos.

Eliminación de documentos huérfanos

Azure AI Search admite operaciones de nivel de documento para que pueda buscar, actualizar y eliminar un documento concreto de forma aislada. En el ejemplo siguiente se muestra cómo eliminar un documento.

La eliminación de un documento no libera inmediatamente espacio en el índice. Cada pocos minutos, un proceso en segundo plano realiza la eliminación física. Tanto si usa el portal como una API para devolver las estadísticas del índice, cabe esperar un pequeño retraso antes de que la eliminación se refleje en las métricas del portal y de la API.

Identifique qué campo es la clave del documento. En el portal, puede ver los campos de cada índice. Las claves del documento son campos de cadena y se indican con un icono de una llave, con el fin de que sean más fáciles de detectar.
Compruebe los valores del campo de clave del documento: search=*&$select=HotelId. Una cadena simple es sencilla, pero si el índice usa un campo codificado en base 64 o si se generaron documentos de búsqueda a partir de una configuración parsingMode, es posible que esté trabajando con valores con los que no está familiarizado.
Consulte el documento para comprobar el valor del identificador del documento y examinar su contenido antes de eliminarlo. Especifique la clave o el identificador de documento en la solicitud. En los ejemplos siguientes se muestra una cadena sencilla del índice de ejemplo Hotels y una cadena codificada en base 64 para la clave metadata_storage_path del índice cog-search-demo.
```
GET https://[service name].search.windows.net/indexes/hotel-sample-index/docs/1111?api-version=2024-07-01
```
```
GET https://[service name].search.windows.net/indexes/cog-search-demo/docs/aHR0cHM6Ly9oZWlkaWJsb2JzdG9yYWdlMi5ibG9iLmNvcmUud2luZG93cy5uZXQvY29nLXNlYXJjaC1kZW1vL2d1dGhyaWUuanBn0?api-version=2024-07-01
```

Elimine el documento mediante una eliminación @search.action para quitarlo del índice de búsqueda.

POST https://[service name].search.windows.net/indexes/hotels-sample-index/docs/index?api-version=2024-07-01
Content-Type: application/json   
api-key: [admin key] 
{  
  "value": [  
    {  
      "@search.action": "delete",  
      "id": "1111"  
    }  
  ]  
}

Consulte también

Información general del indexador
Indexación de grandes conjuntos de datos a escala
Indexing in the portal (Indexación en el portal)
Azure SQL Database indexer (Indexador de Azure SQL Database)
Indizador de Azure Cosmos DB for NoSQL
Indizador de blobs de Azure
Indizador de tablas de Azure
Seguridad en Azure AI Search

Compartir vía