Compartir vía

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

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 durante la iteración del 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. Usa un alias de índice para cambiar al nuevo índice, de manera que puedas evitar 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 agregar, quitar o sobrescribir el contenido de un índice de búsqueda a través de la API REST, pero los SDK de Azure proporcionan una funcionalidad equivalente.

El cuerpo de la solicitud contiene uno o más documentos para indexar. Dentro de la solicitud, cada documento en el índice es:

  • Identificado por una clave única que distingue mayúsculas de minúsculas.
  • Asociado a una acción: "upload", "delete", "merge" o "mergeOrUpload".
  • Rellenado con un conjunto de pares nombre-valor para cada campo que va a agregar o actualizar.
{  
  "value": [  
    {  
      "@search.action": "upload (default) | merge | mergeOrUpload | delete",  
      "key_field_name": "unique_key_of_document", (key/value pair for key field from index schema)  
      "field_name": field_value (name/value pairs matching index schema)  
        ...  
    },  
    ...  
  ]  
}

  • En primer lugar, use las API para cargar documentos, como Documents - Index (REST) o una API equivalente en los SDK de Azure. Para obtener más información sobre las técnicas de indexación, consulte Carga de documentos.

  • Para una actualización grande, se recomienda el procesamiento por lotes (hasta 1000 documentos por lote, o aproximadamente 16 MB por lote, lo que ocurra primero) y mejora significativamente el rendimiento de la indexación.

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

    Acción Efecto
    eliminar 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 Azure Portal como una API para devolver estadísticas de índice, puede esperar un pequeño retraso antes de que la eliminación se refleje en Azure Portal y a través de 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"].

    El mismo comportamiento se aplica a colecciones complejas. Si el documento contiene un campo de colección complejo denominado Salas con un valor de [{ "Type": "Budget Room", "BaseRate": 75.0 }] y ejecuta una combinación con un valor de [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }], el valor final del campo Salas será [{ "Type": "Standard Room" }, { "Type": "Budget Room", "BaseRate": 60.5 }]. No anexará ni combinará valores nuevos y existentes.
    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.

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

Nota:

No hay garantías de ordenación para las que se ejecuta primero la acción en el cuerpo de la solicitud. No se recomienda tener varias acciones de "combinación" asociadas al mismo documento en un único cuerpo de solicitud. Si hay varias acciones de "combinación" necesarias para el mismo documento, realice la combinación del lado cliente antes de actualizar el documento en el índice de búsqueda.

Respuestas

El código de estado 200 se devuelve para una respuesta correcta, lo que significa que todos los elementos se han almacenado de forma duradera y empezarán a indexarse. La indexación se ejecuta en segundo plano y hace que los nuevos documentos estén disponibles (es decir, consultables y buscables) unos segundos después de que se complete la operación de indexación. El retraso específico depende de la carga del servicio.

La indexación correcta se indica mediante la propiedad status que se establece en true para todos los elementos, así como la propiedad statusCode que se establece en 201 (para documentos recién cargados) o 200 (para documentos combinados o eliminados):

{
  "value": [
    {
      "key": "unique_key_of_new_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 201
    },
    {
      "key": "unique_key_of_merged_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 200
    },
    {
      "key": "unique_key_of_deleted_document",
      "status": true,
      "errorMessage": null,
      "statusCode": 200
    }
  ]
}

El código de estado 207 se devuelve cuando al menos un elemento no se indizara correctamente. Los elementos que no se han indexado tienen el campo de estado establecido en false. Las propiedades errorMessage y statusCode indican el motivo del error de indexación:

{
  "value": [
    {
      "key": "unique_key_of_document_1",
      "status": false,
      "errorMessage": "The search service is too busy to process this document. Please try again later.",
      "statusCode": 503
    },
    {
      "key": "unique_key_of_document_2",
      "status": false,
      "errorMessage": "Document not found.",
      "statusCode": 404
    },
    {
      "key": "unique_key_of_document_3",
      "status": false,
      "errorMessage": "Index is temporarily unavailable because it was updated with the 'allowIndexDowntime' flag set to 'true'. Please try again later.",
      "statusCode": 422
    }
  ]
}

La propiedad errorMessage indica el motivo del error de indexación si es posible.

La tabla siguiente explica los distintos códigos de estado por documento que se pueden devolver en la respuesta. Algunos códigos de estado indican problemas con la propia solicitud, mientras que otros indican condiciones de error temporales. En este último caso debe volver a intentarlo después de un tiempo.

código de estado Significado Se puede volver a intentar Notas
200 El documento fue modificado o eliminado con éxito. N/D Las operaciones de eliminación son idempotentes. Es decir, aunque no exista una clave de documento en el índice, al intentar una operación de eliminación con esa clave se producirá un código de estado 200.
201 El documento se creó correctamente. N/D
400 Se produjo un error en el documento que ha impedido que se indexe. No El mensaje de error de la respuesta indica lo que está mal con el documento.
404 No se pudo combinar el documento porque la clave especificada no existe en el índice. No Este error no se produce para las cargas, ya que crean nuevos documentos y no se produce para las eliminaciones porque son idempotentes.
409 Se detectó un conflicto de versión al intentar indexar un documento. Sí Esto puede ocurrir si intenta indexar el mismo documento más de una vez al mismo tiempo.
422 El índice no está disponible temporalmente porque se ha actualizado con el indicador 'allowIndexDowntime' establecido en 'true'. Sí
429 Demasiadas solicitudes Sí Si obtiene este código de error durante la indexación, normalmente significa que tiene poco espacio de almacenamiento disponible. A medida que se acercan a los límites de almacenamiento, el servicio puede especificar un estado en el que no se puede agregar ni actualizar hasta que se eliminen algunos documentos. Para obtener más información, consulte Planear y administrar la capacidad si desea más almacenamiento o liberar espacio mediante la eliminación de documentos.
503 El servicio de búsqueda no está disponible temporalmente, posiblemente debido a una carga elevada. Sí En este caso, el código debe esperar antes de reintentar ya que, de lo contrario, se arriesga a prolongar la no disponibilidad del servicio.

Si el código de cliente encuentra con frecuencia una respuesta 207, una posible razón es que el sistema está bajo carga. Para confirmarlo, compruebe la propiedad de statusCode para 503. Si statusCode es 503, se recomienda limitar las solicitudes de indexación. De lo contrario, si el tráfico de indexación no se reduce, es posible que el sistema comience a rechazar todas las solicitudes con errores 503.

El código de estado 429 indica que ha superado la cuota en el número de documentos por índice. Debe actualizar para obtener límites de capacidad más altos o crear un nuevo índice.

Nota:

Al cargar valores de DateTimeOffset con información de zona horaria en el índice, Azure AI Search normaliza estos valores a UTC. Por ejemplo, 2024-01-13T14:03:00-08:00 se almacena como 2024-01-13T22:03:00Z. Si necesita almacenar información de zona horaria, agregue una columna adicional al índice para este punto de datos.

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 stored propiedad 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 falso es que los vectores se eliminan 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 LA API 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}}

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

Actualizaciones sin recompilación

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.

El orden de las operaciones es:

  1. Obtenga la definición del índice.

  2. Revisar el esquema con actualizaciones de la lista anterior.

  3. Actualice el esquema de índice en el servicio de búsqueda.

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

Actualizaciones que requieren una recompilación

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, tienes que reconstruir el índice. Cuando una recompilación inmediata no es práctica, puede modificar el código de aplicación para redirigir el acceso fuera de un campo obsoleto o usar searchFields y seleccionar parámetros de consulta 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 a un nombre de campo, un tipo de datos o atributos de índice específicos (que se pueden buscar, filtrar, ordenar, facetable) requieren 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 se aplica tanto a las propiedades analyzer como 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 Suggesters , vuelva a generar el índice.
Actualización del servicio o nivel Si necesita más capacidad, compruebe si puede actualizar el servicio o cambiar a un plan de tarifa superior. Si no es así, debe crear un nuevo servicio y recompilar los índices desde cero. Para ayudar a automatizar este proceso, puede usar un ejemplo de código que realiza una copia de seguridad del índice en una serie de archivos JSON. A continuación, puede volver a crear el índice en un servicio de búsqueda que especifique.

El orden de las operaciones es:

  1. Obtenga una definición de índice en caso de que la necesite para una referencia futura o para usarla como base para una nueva versión.

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

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

  4. Publique un índice revisado, donde el cuerpo de la solicitud incluye definiciones y configuraciones de campo cambiadas o modificadas.

  5. Cargue el índice con documentos de un origen 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 reconstrucción de índices, estos índices invertidos e índices vectoriales se eliminan y vuelven a crear en función del esquema de índice que proporcione.

Para minimizar la interrupción del código de la aplicación, considere la posibilidad de crear un alias de índice. El código de aplicación hace referencia al alias, pero puede actualizar el nombre del índice al que apunta el alias.

Adición de una descripción del índice (versión preliminar)

A partir de la versión 2025-05-01-preview de la API REST, ahora se admite un ddescription. Este texto legible es muy valioso cuando un sistema debe acceder a varios índices y tomar una decisión basada en la descripción. Considere un servidor de Protocolo de contexto de modelo (MCP) que debe elegir el índice correcto en tiempo de ejecución. La decisión puede basarse en la descripción en lugar de en el nombre del índice solo.

Una descripción de índice es una actualización de esquema y puede agregarla sin tener que recompilar todo el índice.

  • La longitud de cadena es de 4000 caracteres como máximo.
  • El contenido debe ser legible para personas, en Unicode. El caso de uso debe determinar qué idioma se va a usar.

La compatibilidad con una descripción de índice se proporciona en la API REST en versión preliminar, el Azure Portal o en un paquete de Azure SDK de versión preliminar que proporciona esta funcionalidad.

Azure Portal admite la API de versión preliminar más reciente.

  1. Inicie sesión en Azure Portal y busque el servicio de búsqueda.

  2. En Gestión de búsqueda>Índices, seleccione un índice.

  3. Seleccione Editar JSON.

  4. Inserte "description", seguido de la descripción. El valor debe tener menos de 4000 caracteres y en Unicode.

    Captura de pantalla de la definición JSON de un índice en Azure Portal.

  5. Guarde el índice.

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 Azure Portal para asegurarse de que las consultas se completan de forma oportuna.

Si las cargas de trabajo de indexación presentan niveles inaceptables de latencia de consulta, realice el análisis de rendimiento y revise estas sugerencias de rendimiento para la 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 buscar documento 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 si hay contenido actualizado.

Si ha agregado o cambiado el nombre de un campo, 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 Azure Portal como una API para devolver estadísticas de índice, puede esperar un pequeño retraso antes de que la eliminación se refleje en Azure Portal y las métricas de API.

  1. Identifique qué campo es la clave del documento. En Azure 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.

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

  3. Busque el documento para comprobar el valor del identificador del documento y revisar su contenido antes de eliminarlo. Especifique la clave o el identificador de documento en la solicitud. En los ejemplos siguientes se muestra una cadena simple para el í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

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