Solución de problemas de errores y advertencias comunes del indexador en Azure AI Search

En este artículo se proporciona información y soluciones a errores y advertencias comunes que puede encontrar durante la indexación y el enriquecimiento con IA en Azure AI Search.

La indexación se detiene cuando el recuento de errores supera "maxFailedItems".

Si desea que los indexadores pasen por alto estos errores (y omitan "documentos fallidos"), considere actualizar maxFailedItems y maxFailedItemsPerBatch como se describe aquí.

La información de error de este artículo puede ayudarle a resolver errores, lo que permite que la indexación continúe.

Las advertencias no detienen la indexación, pero indican condiciones que podrían dar lugar a resultados inesperados. Si decides actuar o no, depende de los datos y de tu situación.

¿Dónde puede encontrar errores específicos del indexador?

Para comprobar un estado del indexador e identificar errores en Azure Portal, siga estos pasos:

1. Inicie sesión en Azure Portal y encuentre su servicio de búsqueda.

2. A la izquierda, expanda Administración de Búsqueda>Indexadores y seleccione un indexador.

3. En Historial de ejecución, seleccione el estado. Todos los estados, incluido Correcto, tienen detalles sobre la ejecución.

4. Si se produce un error, mantenga el puntero sobre el mensaje de error. Aparece un panel en el lado derecho de la pantalla que muestra información detallada sobre el error.

Errores transitorios

Por varias razones, como interrupciones transitorias de la comunicación de red, tiempos de espera de procesos de ejecución prolongada o matices específicos del documento, es habitual encontrar errores transitorios o advertencias durante las ejecuciones del indexador. Sin embargo, estos errores son temporales y deben resolverse en ejecuciones posteriores del indexador.

Para administrar estos errores de forma eficaz, se recomienda colocar el indexador en una programación, por ejemplo, para ejecutarse cada cinco minutos, donde la siguiente ejecución comienza cinco minutos después de completar la primera ejecución, cumpliendo con el límite máximo de tiempo de ejecución en el servicio. Las ejecuciones programadas periódicamente ayudan a corregir errores transitorios o advertencias.

Si un error persiste en varias ejecuciones del indexador, es probable que no sea un problema transitorio. En tales casos, consulte la lista siguiente para ver posibles soluciones.

Propiedades de error

Error: Could not read document

Indizador no pudo leer el documento del origen de datos. Estos pueden ser los motivos:

Error: Could not extract content or metadata from your document

El indexador con un origen de datos blob no pudo extraer el contenido o los metadatos del documento (por ejemplo, un archivo PDF). Estos pueden ser los motivos:

Error: Could not parse document

Indexador leyó el documento del origen de datos, pero hubo un problema al convertir el contenido del documento en el esquema de asignación de campos especificado. Estos pueden ser los motivos:

Error: Could not map output field 'xyz' to search index due to deserialization problem while applying mapping function 'abc'

Es posible que se haya producido un error en la asignación de salida porque los datos de salida tienen un formato incorrecto para la función de asignación que está usando. Por ejemplo, aplicar Base64Encode la función de asignación en datos binarios generaría este error. Para resolver el problema, vuelva a ejecutar el indexador sin especificar la función de asignación o asegúrese de que la función de asignación sea compatible con el tipo de datos del campo de salida. Consulte Asignación de campos de salida para obtener más información.

Error: Could not execute skill

El indexador no pudo ejecutar una aptitud del conjunto de aptitudes.

Error: Could not execute skill because the Web API request failed

Falló la ejecución de la habilidad porque se produjo un error en la llamada a la API web. Normalmente, esta clase de error se produce cuando se usan habilidades personalizadas, en cuyo caso debemos depurar el código personalizado para resolver el problema. Si, en su lugar, el error procede de una aptitud integrada, consulte el mensaje de error para obtener ayuda para corregir el problema.

Durante la depuración de este problema, asegúrese de prestar atención a las advertencias de entrada de aptitudes de esta aptitud. Es posible que se produzca un error en el punto de conexión de la API web porque el indexador le está proporcionando una entrada inesperada.

Error: Could not execute skill because Web API skill response is invalid

Error en la ejecución de la habilidad debido a que la llamada a la API web devolvió una respuesta no válida. Normalmente, esta clase de error se produce cuando se usan habilidades personalizadas, en cuyo caso debemos depurar el código personalizado para resolver el problema. Si el error, en cambio, procede de una habilidad integrada, envíe un ticket de soporte para obtener ayuda.

Error: Type of value has a mismatch with column type. Couldn't store in 'xyz' column. Expected type is 'abc'

Si el origen de datos tiene un campo con un tipo de datos diferente al campo que intenta asignar en el índice, podría producirse este error. Compruebe los tipos de datos del campo de origen de datos y asegúrese de que están asignados correctamente a los tipos de datos de índice.

Error: Skill did not execute within the time limit

Hay dos casos en los que podría encontrar este mensaje de error, cada uno de los cuales debe tratarse de forma diferente. Siga las instrucciones que se indican a continuación según la aptitud que devuelva este error en su caso.

Aptitudes integradas de las herramientas de Foundry

Muchas de las aptitudes cognitivas integradas, como la detección de idioma, el reconocimiento de entidades o OCR, están respaldadas por un punto de conexión de la API de Foundry Tools. En ocasiones, hay problemas transitorios con estos puntos de conexión y se agota el tiempo de espera de la solicitud. En estos casos, la única solución es esperar y volver a intentarlo. Como mitigación, considere la posibilidad de establecer el indexador para que se ejecute según una programación. La indexación programada continúa desde donde se quedó. Suponiendo que se resuelvan los problemas transitorios, la indexación y el procesamiento de aptitudes cognitivas deben poder continuar en la siguiente ejecución programada.

Si sigue viendo este error en el mismo documento para una aptitud cognitiva integrada, registre una incidencia de soporte técnico para obtener ayuda, ya que no se espera.

Aptitudes personalizadas

Si se produce un error de tiempo de espera con una aptitud personalizada, puede probar un par de cosas. En primer lugar, revise la habilidad personalizada y asegúrese de que no se bloquea en un bucle infinito y de que devuelve un resultado consistentemente. Una vez que haya confirmado que se devuelve un resultado, compruebe la duración del proceso de ejecución. Si no estableció explícitamente un timeout valor en la definición de aptitud personalizada, el valor predeterminado timeout es de 30 segundos. Si 30 segundos no son suficientes para que se ejecute la habilidad, puede especificar un valor mayor timeout en la definición de su habilidad personalizada. Este es un ejemplo de una definición de aptitud personalizada en la que el tiempo de espera se establece en 90 segundos:

  {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "uri": "<your custom skill uri>",
        "batchSize": 1,
        "timeout": "PT90S",
        "context": "/document",
        "inputs": [
          {
            "name": "input",
            "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "output",
            "targetName": "output"
          }
        ]
      }

El valor máximo que puede establecer para el timeout parámetro es de 230 segundos. Si su habilidad personalizada no se puede ejecutar de forma coherente en un plazo de 230 segundos, puede considerar la posibilidad de reducir el batchSize de su habilidad personalizada para que tenga menos documentos que procesar dentro de una sola ejecución. Si ya ha establecido su batchSize en 1, debe reescribir la habilidad para que pueda ejecutarse en menos de 230 segundos, o bien dividirla en varias habilidades personalizadas de modo que el tiempo de ejecución de cualquiera de ellas sea como máximo de 230 segundos. Revise la documentación de aptitudes personalizadas para obtener más información.

Error: Could not 'MergeOrUpload' | 'Delete' document to the search index

El documento se leyó y procesó, pero el indexador no pudo agregarlo al índice de búsqueda. Estos pueden ser los motivos:

Error: Could not index document because some of the document's data was not valid

El indexador leyó y procesó el documento, pero debido a una falta de coincidencia en la configuración de los campos de índice y los datos extraídos y procesados por el indexador, no se pudo agregar al índice de búsqueda. Estos pueden ser los motivos:

En todos estos casos, consulte Tipos de datos admitidos y asignación de tipos de datos para indexadores para asegurarse de compilar el esquema de índice correctamente y de haber configurado las asignaciones de campos del indexador adecuadas. El mensaje de error incluye detalles que pueden ayudar a realizar un seguimiento del origen de la falta de coincidencia.

Error: Integrated change tracking policy cannot be used because table has a composite primary key

Esto se aplica a las tablas SQL y suele ocurrir cuando la clave se define como una clave compuesta o, cuando la tabla ha definido un índice clúster único (como en un índice SQL, no como un índice de Azure Search). La razón principal es que el atributo de clave se modifica para que sea una clave principal compuesta en un índice clúster único. En ese caso, asegúrese de que la tabla SQL no tenga un índice clúster único o que asigne el campo de clave a un campo garantizado que no tenga valores duplicados.

Error: Could not process document within indexer max run time

Este error se produce cuando el indexador no puede terminar de procesar un único documento desde el origen de datos dentro del tiempo de ejecución permitido. El tiempo máximo de ejecución es más corto cuando se usan conjuntos de aptitudes. Cuando se produce este error, si tiene maxFailedItems establecido en un valor distinto de 0, el indexador omite el documento en ejecuciones futuras para que la indexación pueda avanzar. Si no puede permitirse omitir ningún documento o si ve este error de forma coherente, considere la posibilidad de dividir documentos en documentos más pequeños para que se pueda realizar un progreso parcial dentro de una sola ejecución del indexador.

Error: Could not project document

Este error se produce cuando el indexador intenta proyectar datos en un almacén de conocimiento y se produjo un error en el intento. Este error puede ser constante y necesitar corrección, o puede ser un error transitorio del receptor de salida de la proyección. En este último caso, puede que tenga que esperar y volver a intentarlo para que se resuelva. Este es un conjunto de estados de error conocidos y posibles resoluciones.

Error: The cognitive service for skill '<skill-name>' has been throttled

La ejecución de la habilidad falló porque la llamada a Foundry Tools se vio limitada. Normalmente, esta clase de error se produce cuando se ejecutan demasiadas aptitudes en paralelo. Si usa la biblioteca cliente Microsoft.Search.Documents para ejecutar el indexador, puede usar SearchIndexingBufferedSender para obtener el reintento automático en los pasos con errores. De lo contrario, puede restablecer y volver a ejecutar el indexador.

Error: Expected IndexAction metadata

Un error de "Metadatos de IndexAction esperados" significa que cuando el indexador intentó leer el documento para identificar qué acción se debe realizar, no encontró ningún metadato correspondiente en el documento. Normalmente, este error se produce cuando el indexador tiene una caché de anotaciones agregada o quitada sin restablecer el indexador. Para solucionar esto, debería restablecer y reejecutar el indexador.

Warning: Skill input was invalid

Falta una entrada de datos para la habilidad, tiene el tipo incorrecto o es inválida. Es posible que vea la siguiente información:

• Could not execute skill

• Skill executed but may have unexpected results

Las aptitudes cognitivas tienen entradas necesarias y entradas opcionales. Por ejemplo, la aptitud de extracción de frases clave tiene dos entradas textnecesarias , languageCodey ninguna entrada opcional. Todas las entradas de aptitud personalizadas se consideran entradas opcionales.

Si faltan entradas necesarias o si la entrada no es del tipo correcto, se omite la aptitud y se genera una advertencia. Las aptitudes omitidas no generan salidas. Si las habilidades posteriores consumen los resultados de la habilidad omitida, pueden generar otras advertencias.

Si falta una entrada opcional, la aptitud todavía se ejecuta, pero podría producir una salida inesperada debido a la entrada que falta.

En ambos casos, esta advertencia se debe a la forma de sus datos. Por ejemplo, si tiene un documento que contiene información sobre las personas con los campos firstName, middleNamey lastName, es posible que tenga algunos documentos que no tengan una entrada para middleName. Si va a pasar middleName como una entrada a una aptitud de la canalización, se espera que falte algo de tiempo en esta entrada de aptitud. Debe evaluar los datos y el escenario para determinar si se requiere o no alguna acción como resultado de esta advertencia.

Si desea proporcionar un valor predeterminado para una entrada que falta, puede usar la aptitud condicional para generar un valor predeterminado y, a continuación, usar la salida de la aptitud condicional como entrada de aptitud.

{
    "@odata.type": "#Microsoft.Skills.Util.ConditionalSkill",
    "context": "/document",
    "inputs": [
        { "name": "condition", "source": "= $(/document/language) == null" },
        { "name": "whenTrue", "source": "= 'en'" },
        { "name": "whenFalse", "source": "= $(/document/language)" }
    ],
    "outputs": [ { "name": "output", "targetName": "languageWithDefault" } ]
}

Warning: Skill input 'languageCode' has the following language codes 'X,Y,Z', at least one of which is invalid.

Uno o varios de los valores que pasan a la entrada languageCode opcional de una aptitud de nivel inferior no se admiten. Esto puede ocurrir si va a pasar la salida de LanguageDetectionSkill a aptitudes posteriores y la salida consta de más idiomas de los que se admiten en esas aptitudes de nivel inferior.

Tenga en cuenta que también puede obtener una advertencia similar a esta si se pasa una entrada no válida countryHint a LanguageDetectionSkill. Si esto sucede, valide que el campo que usa del origen de datos para esa entrada contenga códigos de país alfa-2 válidos según la norma ISO 3166-1. Si algunos son válidos y e inválidos, continúe con las instrucciones siguientes, pero reemplace languageCode con countryHint y defaultLanguageCode con defaultCountryHint para que coincidan con su caso de uso.

Si sabe que el conjunto de datos solo tiene un idioma, debe quitar el elemento LanguageDetectionSkill y la entrada de aptitud languageCode y usar en cambio el parámetro de aptitud defaultLanguageCode para esa aptitud, suponiendo que el idioma sea compatible con ella.

Si sabe que el conjunto de datos contiene varios idiomas y, por tanto, necesita el elemento LanguageDetectionSkill y la entrada languageCode, considere agregar un elemento ConditionalSkill para filtrar el texto con los idiomas que no se admiten antes de pasar el texto a la aptitud de nivel inferior. Este es un ejemplo de lo que podría tener este aspecto para EntityRecognitionSkill:

{
    "@odata.type": "#Microsoft.Skills.Util.ConditionalSkill",
    "context": "/document",
    "inputs": [
        { "name": "condition", "source": "= $(/document/language) == 'de' || $(/document/language) == 'en' || $(/document/language) == 'es' || $(/document/language) == 'fr' || $(/document/language) == 'it'" },
        { "name": "whenTrue", "source": "/document/content" },
        { "name": "whenFalse", "source": "= null" }
    ],
    "outputs": [ { "name": "output", "targetName": "supportedByEntityRecognitionSkill" } ]
}

Estas son algunas referencias para los idiomas admitidos actualmente para cada una de las aptitudes que pueden generar este mensaje de error:

• Idiomas admitidos en EntityRecognitionSkill
• Idiomas compatibles con EntityLinkingSkill
• Idiomas compatibles con KeyPhraseExtractionSkill
• Idiomas admitidos en LanguageDetectionSkill
• Idiomas compatibles con PIIDetectionSkill
• Idiomas admitidos por SentimentSkill
• Idiomas admitidos por Translator
• Idiomas admitidos por Text SplitSkill:da, de, en, es, fi, fr, it, ko, pt

Warning: Skill input was truncated

Las aptitudes cognitivas limitan la longitud del texto que se puede analizar al mismo tiempo. Si la entrada de texto supera el límite, el texto se trunca antes de ser enriquecido. La aptitud se ejecuta, pero no sobre todos los datos.

En el ejemplo LanguageDetectionSkill siguiente, el 'text' campo de entrada podría desencadenar esta advertencia si la entrada supera el límite de caracteres. Los límites de entrada se pueden encontrar en la documentación de referencia de aptitudes.

 {
    "@odata.type": "#Microsoft.Skills.Text.LanguageDetectionSkill",
    "inputs": [
      {
        "name": "text",
        "source": "/document/text"
      }
    ],
    "outputs": [...]
  }

Si desea asegurarse de que se analiza todo el texto, considere la posibilidad de usar la aptitud Dividir.

Warning: Web API skill response contains warnings

El indexador ha ejecutado la aptitud del conjunto de aptitudes, pero la respuesta de la solicitud de API web indica que hay advertencias. Revise las advertencias para comprender cómo se ven afectados los datos y si es necesario realizar más acciones.

Warning: The current indexer configuration does not support incremental progress

Esta advertencia solo se produce para orígenes de datos de Azure Cosmos DB.

El progreso incremental durante la indexación garantiza que si la ejecución del indexador se interrumpe por errores transitorios o límite de tiempo de ejecución, el indexador puede recoger dónde se dejó la próxima vez que se ejecute, en lugar de tener que volver a indexar toda la colección desde cero. Esto es especialmente importante al indexar colecciones grandes.

La capacidad de reanudar un trabajo de indexación sin terminar se basa en tener documentos ordenados por la _ts columna. El indexador usa la marca de tiempo para determinar qué documento se va a seleccionar a continuación. Si falta la _ts columna o si el indexador no puede determinar si una consulta personalizada está ordenada por ella, el indexador comienza al principio y verá esta advertencia.

Es posible invalidar este comportamiento, lo que permite el progreso incremental y suprime esta advertencia mediante la assumeOrderByHighWaterMarkColumn propiedad de configuración.

Para obtener más información, consulte Progreso incremental y consultas personalizadas.

Warning: Some data was lost during projection. Row 'X' in table 'Y' has string property 'Z' which was too long.

El servicio Table Storage tiene límites en el tamaño que pueden tener las propiedades de entidad. Las cadenas pueden tener 32 000 caracteres o menos. Si se proyecta una fila con una propiedad de cadena de más de 32 000 caracteres, solo se conservan los primeros 32 000 caracteres. Para solucionar este problema, evite proyectar filas con propiedades de cadena de más de 32 000 caracteres.

Warning: Truncated extracted text to X characters

Los indexadores limitan la cantidad de texto que se puede extraer de cualquier documento. Este límite depende del plan de tarifa: 32 000 caracteres para el nivel Gratis, 64 000 para Básico, 4 millones para Standard, 8 millones para Standard S2 y 16 millones para Standard S3. El texto truncado no se indexará. Para evitar esta advertencia, intente dividir documentos con grandes cantidades de texto en varios documentos más pequeños.

Para obtener más información, consulte Límites del indexador.

Warning: Could not map output field 'X' to search index

Las asignaciones de campos de salida que hacen referencia a datos no existentes o null producirán advertencias para cada documento y darán como resultado un campo de índice vacío. Para solucionar este problema, compruebe las rutas de acceso de origen de la asignación de campos de salida en busca de posibles errores tipográficos o establezca un valor predeterminado mediante la aptitud condicional. Consulte Asignación de campos de salida para obtener más información.

Warning: The data change detection policy is configured to use key column 'X'

Las directivas de detección de cambios de datos tienen requisitos específicos para las columnas que usan para detectar cambios. Uno de estos requisitos es que esta columna se actualiza cada vez que se cambia el elemento de origen. Otro requisito es que el nuevo valor de esta columna sea mayor que el valor anterior. Las columnas de clave no cumplen este requisito porque no cambian en todas las actualizaciones. Para solucionar este problema, seleccione una columna diferente para la directiva de detección de cambios.

Warning: Document text appears to be UTF-16 encoded, but is missing a byte order mark

Los modos de análisis del indexador deben saber cómo se codifica el texto antes de analizarlo. Las dos formas más comunes de codificar texto son UTF-16 y UTF-8. UTF-8 es una codificación de longitud variable donde cada carácter está comprendido entre 1 byte y 4 bytes de longitud. UTF-16 es una codificación de longitud fija donde cada carácter tiene 2 bytes de longitud. UTF-16 tiene dos variantes diferentes, big endian y little endian. La codificación de texto se determina por byte order mark, una serie de bytes antes del texto.

Si no hay ninguna marca de orden de bytes presente, se supone que el texto se codifica como UTF-8.

Para solucionar esta advertencia, determine cuál es la codificación de texto para este blob y agregue la marca de orden de bytes adecuada.

Warning: Azure Cosmos DB collection 'X' has a Lazy indexing policy. Some data may be lost

Las colecciones con directivas de indexación Lazy no se pueden consultar de forma coherente, lo que resulta en que el indexador pierda datos. Para solucionar esta advertencia, cambie la directiva de indexación a Coherente.

Warning: The document contains very long words (longer than 64 characters). These words may result in truncated and/or unreliable model predictions.

Esta advertencia se envía desde el servicio de idiomas de Foundry Tools. En algunos casos, es seguro omitir esta advertencia, por ejemplo, si la cadena larga es solo una dirección URL larga. Tenga en cuenta que cuando una palabra tiene más de 64 caracteres, se trunca a 64 caracteres que pueden afectar a las predicciones del modelo.

Error: Cannot write more bytes to the buffer than the configured maximum buffer size

Los indexadores tienen límites de tamaño de documento. Asegúrese de que los documentos del origen de datos sean más pequeños que el límite de tamaño admitido, tal como se documenta para el nivel de servicio.

Error: Failed to compare value 'X' of type M to value 'Y' of type N.

Este error suele producirse en los indexadores de Azure SQL cuando el tipo de columna de origen usado para dataChangeDetectionPolicy no coincide con lo que espera el indexador, especialmente si convertHighWaterMarkToRowVersion está activado.

Por ejemplo, si la columna usada para la detección de cambios es de tipo datetime, pero el indexador espera un tipo rowversion porque convertHighWaterMarkToRowVersion está habilitado, la falta de coincidencia provocará un error.

Compruebe el tipo de datos de la columna "Umbral máximo" en el origen y actualice la configuración del indexador según sea necesario. Una vez comprobado y actualizado, restablezca y vuelva a ejecutar el indexador para procesar los valores de columna.

Error: Access denied to Virtual Network/Firewall rules.

Este error suele producirse debido a una de las siguientes acciones:

• Restricciones de firewall en los recursos de Azure requeridos por el indexador, en función de la configuración. Estos recursos pueden incluir: el origen de datos, la cuenta de Azure Storage (que se usa para las sesiones de depuración, el enriquecimiento incremental o el almacén de conocimiento), la función de Azure (que se usa para las aptitudes personalizadas de api web) o las implementaciones de Microsoft Foundry que se usan durante el enriquecimiento con IA.
• Configuraciones de punto de conexión privado que bloquean el acceso desde el indexador a esos recursos.

Asegúrese de que el indexador tiene acceso a los componentes de configuración revisando las configuraciones de recursos para confirmar que permiten el tráfico a todos los servicios necesarios:

• Configuración de restricciones de IP y firewall
• Configuración de enlace privado compartido

Error: Credentials provided in the connection string are invalid or have expired.

Este error se produce cuando el indexador de Azure AI Search no se puede autenticar mediante la cadena de conexión proporcionada o tiene problemas para acceder a la cuenta de almacenamiento para comprobar las credenciales.