Guía de solución de problemas del indexador para Azure AI Search

Artículo
12/10/2024

De vez en cuando, los indexadores se encuentran con problemas que no generan errores o que ocurren en otros servicios de Azure, como durante la autenticación o al conectarse. Este artículo se centra en cómo solucionar los problemas del indexador cuando no hay mensajes que sirvan de guía para hacerlo. También muestra soluciones a errores que proceden de recursos que no son de búsqueda usados durante la indexación.

Nota:

Si desea investigar un error de Búsqueda de Azure AI, consulte Solución de errores y advertencias comunes en el indexador en su lugar.

Solución de problemas de conexiones a recursos restringidos

En el caso de los orígenes de datos en la seguridad de red de Azure, los indexadores tienen limitaciones en cuanto a la realización de la conexión. Actualmente, los indizadores pueden acceder a orígenes de datos restringidos detrás de un firewall de IP, o bien en una red virtual a través de un punto de conexión privado mediante un vínculo privado compartido.

Reglas de firewall

Azure Storage, Azure Cosmos DB y Azure SQL proporcionan un firewall configurable. No aparece ningún mensaje de error específico cuando el firewall está habilitado. Por lo general, los errores de firewall son genéricos. Estos son algunos de los errores comunes:

The remote server returned an error: (403) Forbidden
This request is not authorized to perform this operation
Credentials provided in the connection string are invalid or have expired

Hay dos opciones para permitir que los indizadores accedan a estos recursos en estos casos:

Configure tanto una regla de entrada para la dirección IP del servicio de búsqueda como el intervalo de direcciones IP de la etiqueta de servicio AzureCognitiveSearch. Los detalles para configurar las restricciones del intervalo de direcciones IP para cada tipo de origen de datos se pueden encontrar en los vínculos siguientes:
Como último recurso o a modo de medida temporal, deshabilite el firewall, lo que permite el acceso desde todas las redes.

Limitación: las restricciones del intervalo de direcciones IP solo funcionan si el servicio de búsqueda y la cuenta de almacenamiento están en regiones diferentes.

Además de la recuperación de datos, los indizadores también envían solicitudes salientes mediante conjuntos de aptitudes y aptitudes personalizadas. En el caso de las aptitudes personalizadas basadas en una función de Azure, tenga en cuenta que las funciones de Azure también tienen restricciones de direcciones IP. La lista de direcciones IP que se van a permitir mediante la ejecución de aptitudes personalizadas incluye la dirección IP del servicio de búsqueda y el intervalo de direcciones IP de la etiqueta de servicio AzureCognitiveSearch.

Reglas de grupos de seguridad de red (NSG)

Cuando un indexador accede a los datos de una instancia administrada de SQL o cuando se usa una máquina virtual de Azure como identificador URI del servicio web para una aptitud personalizada, el grupo de seguridad de red determina si se permiten solicitudes.

En el caso de los recursos externos que residen en una red virtual, configure las reglas de NSG entrantes para la etiqueta de servicio AzureCognitiveSearch.

Para obtener más información sobre cómo conectarse a una máquina virtual, vea Configuración de una conexión a SQL Server en una máquina virtual de Azure.

Errores de red

Normalmente, los errores de red son genéricos. Estos son algunos de los errores comunes:

A network-related or instance-specific error occurred while establishing a connection to the server
The server was not found or was not accessible
Verify that the instance name is correct and that the source is configured to allow remote connections

Cuando reciba cualquiera de esos errores:

Asegúrese de que el origen sea accesible. Para ello, intente conectarse a él directamente, y no a través del servicio de búsqueda.
Compruebe en Azure Portal si hay errores o interrupciones en el recurso.
Compruebe si hay interrupciones de red en Estado de Azure.
Compruebe que usa un DNS público para la resolución de nombres, no DNS privado de Azure.

Indexación de Azure SQL Database sin servidor (código de error 40613)

Si la base de datos SQL está en un nivel de proceso sin servidor, asegúrese de que la base de datos se esté ejecutando (y no en pausa) cuando el indexador se conecta a ella.

Si la base de datos está en pausa, se espera que el primer inicio de sesión del servicio de búsqueda reanude automáticamente la base de datos, pero se devuelve un error que indica que la base de datos no está disponible y aparece el código de error 40613. Cuando se haya ejecutado la base de datos, vuelva a intentar el inicio de sesión para establecer la conectividad.

Directivas de acceso condicional a Microsoft Entra

Al crear un indexador de SharePoint Online, hay un paso que requiere que inicie sesión en la aplicación Microsoft Entra después de proporcionar un código de dispositivo. Si recibe el siguiente mensaje, "Your sign-in was successful but your admin requires the device requesting access to be managed", es probable que una directiva de acceso condicional haya bloqueado el indizador desde la biblioteca de documentos de SharePoint.

Para actualizar la directiva y permitir el acceso del indizador a la biblioteca de documentos:

Abra Azure Portal y busque Acceso condicional de Microsoft Entra.
En el menú izquierdo, seleccione Directivas. Si no tiene acceso para ver esta página, debe buscar a alguien que tenga acceso u obtener acceso.
Determine cuál es la directiva que bloquea el acceso del indexador de SharePoint Online a la biblioteca de documentos. La directiva que podría estar bloqueando el indexador incluye la cuenta de usuario que usó para autenticarse durante el paso de creación del indexador en la sección Usuarios y grupos. Es posible que la directiva también tenga condiciones que:
- Restrinjan las plataformas Windows.
- Restrinjan aplicaciones móviles y equipos cliente de escritorio.
- Configuren Estado de dispositivo como Sí.
Una vez que haya confirmado qué directiva bloquea el indizador, realice una exención para este. Para empezar, recupere la dirección IP del servicio de búsqueda.

En primer lugar, obtenga el nombre de dominio completo (FQDN) del servicio de búsqueda. El FQDN es similar a <your-search-service-name>.search.windows.net. Puede encontrarlo en Azure Portal.

Una vez que tenga el nombre, obtenga la dirección IP del servicio de búsqueda, para lo que debe realizar una operación nslookup (o ping) del nombre de dominio completo. En el siguiente ejemplo, agregaría "150.0.0.1" a una regla de entrada en el firewall de Azure Storage. La configuración del firewall puede tardar hasta 15 minutos en actualizarse para que el indexador del servicio de búsqueda pueda acceder a la cuenta de Azure Storage.
```
nslookup contoso.search.windows.net
Server:  server.example.org
Address:  10.50.10.50

Non-authoritative answer:
Name:    <name>
Address:  150.0.0.1
Aliases:  contoso.search.windows.net
```
Obtenga los intervalos de direcciones IP del entorno de ejecución del indexador de su región.

Se usan direcciones IP adicionales para las solicitudes que se originan en el entorno de ejecución multiinquilino del indizador. Puede obtener este intervalo de direcciones IP de la etiqueta de servicio .

Los intervalos de direcciones IP de la etiqueta de servicio AzureCognitiveSearch pueden obtenerse a través de la API de detección o el archivo JSON descargable.

Para este ejercicio, si el servicio de búsqueda es la nube pública de Azure, se debe descargar el archivo JSON público de Azure.

En el archivo JSON, si el servicio de búsqueda se encuentra en la región Centro-oeste de EE. UU., a continuación, se muestra la lista de direcciones IP del entorno de ejecución multiinquilino del indexador.
```
    {
      "name": "AzureCognitiveSearch.WestCentralUS",
      "id": "AzureCognitiveSearch.WestCentralUS",
      "properties": {
        "changeNumber": 1,
        "region": "westcentralus",
        "platform": "Azure",
        "systemService": "AzureCognitiveSearch",
        "addressPrefixes": [
          "52.150.139.0/26",
          "52.253.133.74/32"
        ]
      }
    }
```
Vuelva a la página Acceso condicional de Azure Portal, seleccione Ubicaciones con nombre en el menú de la izquierda y después + Ubicación de los intervalos de direcciones IP. Asigne un nombre a la nueva ubicación con nombre y agregue los intervalos de direcciones IP del servicio de búsqueda y los entornos de ejecución del indexador que recopiló en los dos últimos pasos. 1
- En el caso de la dirección IP del servicio de búsqueda, es posible que tenga que agregar "/32" al final de la dirección IP, ya que solo acepta intervalos IP válidos.
- Recuerde que en el caso de los intervalos IP del entorno de ejecución del indexador, solo tiene que agregar los intervalos IP de la región en la que se encuentra el servicio de búsqueda.
Excluya la nueva ubicación con nombre de la directiva:
1. En el menú izquierdo, seleccione Directivas.
2. Seleccione la directiva que bloquea al indexador.
3. Seleccione Condiciones.
4. Seleccione Ubicaciones.
5. Seleccione Excluir y agregue la nueva ubicación con nombre.
6. Guarde los cambios.
Espere unos minutos a que la directiva se actualice y aplique las nuevas reglas de directiva.
Intente volver a crear el indexador:
1. Envíe una solicitud de actualización del objeto de origen de datos que creó.
2. Vuelva a enviar la solicitud de creación del indexador. Use el nuevo código para iniciar sesión y, después, envíe otra solicitud de creación del indizador.

Indexación de tipos de documentos no admitidos

Si va a indexar contenido de Azure Blob Storage y el contenedor incluye blobs de un tipo de contenido no admitido, el indizador omite ese documento. En otros casos, es posible que surjan problemas con documentos individuales.

En ese caso, puede establecer opciones de configuración para que el procesamiento del indizador continúe, aunque haya problemas con documentos individuales.

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2024-07-01
Content-Type: application/json
api-key: [admin key]

{
  ... other parts of indexer definition
  "parameters" : { "configuration" : { "failOnUnsupportedContentType" : false, "failOnUnprocessableDocument" : false } }
}

Documentos faltantes

Los indizadores extraen documentos o filas de un origen de datos externo y crean documentos de búsqueda que, después, indexa el servicio de búsqueda. En ocasiones, un documento que existe en el origen de datos no aparece en un índice de búsqueda. Este resultado inesperado puede producirse por los motivos siguientes:

El documento se ha actualizado después de ejecutar el indizador. Si el indizador sigue una programación, a la larga se vuelve a ejecutar y recoge el documento.
El indizador ha agotado el tiempo de espera antes de que se pudiera ingerir el documento. Hay límites de tiempo de procesamiento máximos después de los cuales no se procesa ningún documento. Puede comprobar el estado del indexador en Azure Portal o llamando a Obtener estado del indexador (API de REST).
Las asignaciones de campos o el enriquecimiento con IA han cambiado el documento y su articulación en el índice de búsqueda es diferente de lo que espera.
Los valores de seguimiento de cambios son erróneos o faltan requisitos previos. Si el valor del límite máximo es una fecha establecida en un momento futuro, el indizador omite todos los documentos que tenga una fecha anterior a esta. Puede determinar el estado del seguimiento de cambios del indizador mediante los campos "initialTrackingState" y "finalTrackingState" del estado del indizador. Los indizadores de Azure SQL y MySQL deben tener un índice en la columna de límite máximo de la tabla de origen, o las consultas que usa el indizador hayan podrían agotar el tiempo de espera.

Sugerencia

Si faltan documentos, compruebe la consulta que usa para asegurarse de que no excluye el documento en cuestión. Para consultar un documento específico, use la API REST de búsqueda de documentos.

Falta de contenido de Blob Storage

El indizador de blobs busca y extrae texto de los blobs de un contenedor. Algunos problemas con la extracción de texto son los siguientes:

El documento solo contiene imágenes escaneadas. Los blobs de PDF que tienen contenido no textual, como imágenes escaneadas (JPG), no generan resultados en una canalización de indexación de blobs estándar. Si tiene contenido de imagen con elementos de texto, puede usar OCR o el análisis de imágenes para buscar y extraer el texto.
El indizador de blobs está configurado para indexar solo metadatos. Para extraer contenido, el indizador de blobs se debe configurar para extraer tanto contenido como metadatos:

PUT https://[service name].search.windows.net/indexers/[indexer name]?api-version=2024-07-01
Content-Type: application/json
api-key: [admin key]

{
  ... other parts of indexer definition
  "parameters" : { "configuration" : { "dataToExtract" : "contentAndMetadata" } }
}

Falta de contenido de Azure Cosmos DB

Azure AI Search tiene una dependencia implícita del indexado de Azure Cosmos DB. Si desactiva el indexado automático en Azure Cosmos DB, Azure AI Search devuelve un estado correcto, pero no puede indexar el contenido del contenedor. Para instrucciones sobre cómo establecer y activar el indexado, consulte Administración automática en Azure Cosmos DB.

Discrepancia en el número de documentos entre el origen de datos y el índice

Un indizador puede mostrar un número de documentos diferente al del origen de datos, al del propio índice o al del código. Estos son algunos de los motivos por los que se puede producir este comportamiento:

El índice puede retardar en mostrar el recuento real de documentos, especialmente en Azure Portal.
El indexador tiene una directiva de documento eliminados. El indizador cuenta los documentos que se han eliminado si se indexan antes de eliminarlos.
Si la columna id. del origen de datos no es única. Esto se aplica a los orígenes de datos que tienen el concepto de columna, como Azure Cosmos DB.
Si la definición del origen de datos tiene una consulta diferente a la que usa para calcular el número de registros. Por ejemplo, en la base de datos, va a consultar el número de registros de la base de datos, mientras que en la consulta de la definición del origen de datos podría seleccionar solo un subconjunto de registros para indexarlos.
Los recuentos se comprueban en intervalos diferentes para cada componente de la canalización: origen de datos, indizador e índice.
El origen de datos tiene un archivo que está asignado a muchos documentos. Esta condición puede producirse cuando se realiza la indexación de los blob y "parsingMode" se establece en jsonArray y jsonLines.

Documentos procesados varias veces

Los indexadores usan una estrategia de almacenamiento en búfer conservadora para asegurarse de que todos los documentos nuevos y modificados del origen de datos se recogen durante la indexación. En determinadas situaciones, estos búferes se pueden superponer, lo que hace que un indexador indexe un documento dos o más veces, lo que hace que el número de documentos procesados sea mayor que el número real de documentos del origen de datos. Este comportamiento no afecta a los datos almacenados en el índice, como la duplicación de documentos, pero este puede tardar más tiempo en alcanzar la coherencia final. Esto es especialmente frecuente si se cumple cualquiera de los siguientes criterios:

Las solicitudes del indexador a petición se emiten en una sucesión rápida
La topología del origen de datos incluye varias réplicas y particiones (un ejemplo de este tipo se describe aquí)
El origen de datos es una base de datos de Azure SQL y la columna elegida como "marca de agua alta" es de tipo datetime2

Los indizadores no están diseñados para que se invoquen varias veces en una sucesión rápida. Si necesita actualizaciones rápidamente, el enfoque admitido es insertar actualizaciones en el índice mientras actualiza simultáneamente el origen de datos. Para el procesamiento a petición, se recomienda seguir el ritmo de las solicitudes en intervalos de cinco minutos o más y ejecutar el indexador según una programación.

Ejemplo de procesamiento de documentos duplicados con búfer de 30 segundos

Las condiciones en las que se procesa un documento dos veces se explican en la siguiente escala de tiempo que anota cada acción y acción de contador. En la escala de tiempo siguiente se muestra el problema:

Escala de tiempo (hh:mm:ss)	Evento	Límite superior del indexador	Comentario
00:01:00	Escriba `doc1` en el origen de datos con coherencia final	`null`	La marca de tiempo del documento es 00:01:00.
00:01:05	Escriba `doc2` en el origen de datos con coherencia final	`null`	Document timestamp is 00:01:05.
00:01:10	Se inicia el indexador	`null`
00:01:11	El indexador consulta todos los cambios antes de las 00:01:10. La réplica que consulta el indexador solo detecta `doc2` y solo se recupera `doc2`.	`null`	El indexador solicita todos los cambios antes de iniciar la marca de tiempo, pero recibe realmente un subconjunto. Este comportamiento necesita el período de búfer de retroceso.
00:01:12	El indexador procesa `doc2` por primera vez	`null`
00:01:13	Finaliza el indexador	00:01:10	El límite superior se actualiza a la marca de tiempo inicial de la ejecución actual del indexador.
00:01:20	Se inicia el indexador	00:01:10
00:01:21	El indexador consulta todos los cambios entre las 00:00:40 y las 00:01:20. La réplica que consulta el indexador detecta `doc1` y `doc2`, y recupera `doc1` y `doc2`.	00:01:10	El indexador solicita todos los cambios entre la marca del límite superior actual menos el búfer de 30 segundos y la marca de tiempo inicial de la ejecución actual del indexador.
00:01:22	El indexador procesa `doc1` por primera vez	00:01:10
00:01:23	El indexador procesa `doc2` por segunda vez	00:01:10
00:01:24	Finaliza el indexador	00:01:20	El límite superior se actualiza a la marca de tiempo inicial de la ejecución actual del indexador.
00:01:32	Se inicia el indexador	00:01:20
00:01:33	El indexador consulta todos los cambios entre las 00:00:50 y las 00:01:32, y recupera `doc1` y `doc2`.	00:01:20	El indexador solicita todos los cambios entre la marca del límite superior actual menos el búfer de 30 segundos y la marca de tiempo inicial de la ejecución actual del indexador.
00:01:34	El indexador procesa `doc1` por segunda vez	00:01:20
00:01:35	El indexador procesa `doc2` por tercera vez	00:01:20
00:01:36	Finaliza el indexador	00:01:32	El límite superior se actualiza a la marca de tiempo inicial de la ejecución actual del indexador.
00:01:40	Se inicia el indexador	00:01:32
00:01:41	El indexador consulta todos los cambios entre las 00:01:02 y las 00:01:40, y recupera `doc2`.	00:01:32	El indexador solicita todos los cambios entre la marca del límite superior actual menos el búfer de 30 segundos y la marca de tiempo inicial de la ejecución actual del indexador.
00:01:42	El indexador procesa `doc2` por cuarta vez	00:01:32
00:01:43	Finaliza el indexador	00:01:40	Observe que esta ejecución del indexador se inició más de 30 segundos después de la última escritura en el origen de datos y también procesó `doc2`. Este es el comportamiento esperado porque si se eliminan todas las ejecuciones del indexador anteriores a las 00:01:35, se convierte en la primera y única ejecución para procesar `doc1` y `doc2`.

En la práctica, este escenario solo se produce cuando los indexadores a petición se invocan manualmente en cuestión de minutos entre sí, para determinados orígenes de datos. Puede dar lugar a números no coincidentes (como que el indexador procesó un total de 345 documentos según las estadísticas de ejecución del indexador, pero solo hay 340 documentos en el origen de datos y el índice) o una facturación potencialmente mayor si ejecuta las mismas aptitudes para el mismo documento varias veces. La recomendación preferida es ejecutar un indexador mediante una programación.

Indexación en paralelo

Cuando varios indexadores funcionan simultáneamente, es habitual que algunos escriban una cola, esperando a que los recursos disponibles comiencen a ejecutarse. El número de indizadores que se pueden ejecutar simultáneamente depende de varios factores. Si los indexadores no están vinculados con conjuntos de aptitudes, la capacidad de funcionar en paralelo depende del número de réplicas y particiones configuradas en el servicio de búsqueda de IA.

Por otra parte, si un indexador está asociado a un conjunto de competencias, opera dentro de los clústeres internos de la búsqueda de IA. La capacidad de ejecutarse simultáneamente en este caso viene determinada por la complejidad del conjunto de aptitudes y si otros conjuntos de aptitudes se ejecutan simultáneamente. Los indexadores integrados están diseñados para extraer datos de forma confiable del origen, por lo que no se pierde ningún dato si se ejecuta según una programación. Sin embargo, se espera que los procesos del indexador de paralelización y el escalado horizontal requieran algún tiempo.

Indexación de documentos con etiquetas de confidencialidad

Si tienen etiquetas de confidencialidad en los documentos, es posible que no se puedan indexar. Si recibe errores, quite las etiquetas antes de la indexación.

Compartir a través de