Compartir a través de

Solución de problemas de puntos de conexión por lotes

  • Artículo

SE APLICA A:Extensión ML de la CLI de Azure v2 (actual)SDK de Python azure-ai-ml v2 (actual)

En este artículo se proporcionan instrucciones para solucionar errores comunes al usar puntos de conexión por lotes para la puntuación por lotes en Azure Machine Learning. En las siguientes secciones se describe cómo analizar los registros de puntuación por lotes para identificar posibles problemas y escenarios no admitidos. También puede revisar las soluciones recomendadas para resolver errores comunes.

Obtención de registros para trabajos de puntuación por lotes

Después de invocar un punto de conexión por lotes mediante la CLI de Azure o la API de REST, el trabajo de puntuación por lotes se ejecuta de forma asincrónica. Existen dos opciones para obtener los registros para un trabajo de puntuación por lotes:

  • Opción 1: transmisión de registros de trabajo a una consola local. Solo se transmitirán los registros de la carpeta azureml-logs.

    Ejecute el siguiente comando para transmitir los registros generados por el sistema a la consola. Reemplace el parámetro <job_name> por el nombre del trabajo de puntuación por lotes:

    az ml job stream --name <job_name>

  • Opción 2: visualización de los registros de trabajos en Estudio de Azure Machine Learning.

    Ejecute el siguiente comando para obtener el vínculo del trabajo que se va a usar en Studio. Reemplace el parámetro <job_name> por el nombre del trabajo de puntuación por lotes:

    az ml job show --name <job_name> --query services.Studio.endpoint -o tsv

    1. Abra el vínculo del trabajo en Studio.

    2. En el grafo del trabajo, seleccione el paso batchscoring.

    3. En la pestaña Salidas y registros, seleccione uno o varios registros para revisarlos.

Revisión de los archivos de registro

Azure Machine Learning proporciona varios tipos de archivos de registro y otros archivos de datos que puede usar para ayudar a solucionar problemas del trabajo de puntuación por lotes.

Las dos carpetas de nivel superior para los registros de puntuaciones por lotes son azureml-logs y logs. La información del controlador que inicia el script de puntuación se almacena en el archivo ~/azureml-logs/70_driver_log.txt.

Examen de la información de alto nivel

La naturaleza distribuida de los trabajos de puntuación por lotes da como resultado registros de orígenes diferentes, pero dos archivos combinados proporcionan información de alto nivel:

Archivo Descripción
~/logs/job_progress_overview.txt Proporciona información de alto nivel sobre el número actual de minilotes (también conocidos como tareas) creados y el número actual de minilotes procesados. A medida que el procesamiento de minilotes finaliza, el registro registra los resultados del trabajo. Si se produce un error en el trabajo, el registro muestra el mensaje de error y dónde iniciar la solución de problemas.
~/logs/sys/master_role.txt Proporciona la vista del nodo principal (también conocido como orquestador ) del trabajo en ejecución. Este registro incluye información sobre la creación de tareas, la supervisión del progreso y el resultado del trabajo.

Examen de los datos de seguimiento de la pila para detectar errores

Otros archivos proporcionan información sobre posibles errores en el script:

Archivo Descripción
~/logs/user/error.txt Proporciona un resumen de los errores en el script.
~/logs/user/error/* Proporciona los seguimientos de pila completos de las excepciones producidas al cargar y ejecutar el script de entrada.

Examen de registros de procesos por nodo

Para obtener una comprensión completa de cómo cada nodo ejecuta el script de puntuación, examine los registros de procesos individuales de cada nodo. Los registros de proceso se almacenan en la carpeta ~/logs/sys/node y se agrupan por nodos de trabajo.

La carpeta contiene una subcarpeta <ip_address>/ que contiene un archivo <process_name>.txt con información detallada sobre cada minilote. El contenido de la carpeta se actualiza cuando un trabajo selecciona o completa el minilote. Para cada minilote, el archivo de registro incluye:

  • La dirección IP y el identificador de proceso (PID) del proceso de trabajo.
  • El número total de elementos, el número de elementos procesados correctamente y el número de elementos con errores.
  • Hora de inicio, duración, tiempo de proceso y tiempo del método de ejecución.

Examen de comprobaciones periódicas por nodo

También puede ver los resultados de las comprobaciones periódicas del uso de recursos de cada nodo. Los archivos de registro y los archivos de instalación se almacenan en la carpeta ~/logs/perf.

Use el parámetro --resource_monitor_interval para cambiar el intervalo de comprobación en segundos:

  • Use el predeterminado: el intervalo predeterminado es de 600 segundos (aproximadamente 10 minutos).
  • Detenga las comprobaciones: establezca el valor en 0 para detener la ejecución de comprobaciones en el nodo.

La carpeta contiene una subcarpeta <ip_address>/ sobre cada minilote. El contenido de la carpeta se actualiza cuando un trabajo selecciona o completa el minilote. Para cada minilote, la carpeta incluye los siguientes elementos:

Archivo o carpeta Descripción
os/ Almacena información sobre todos los procesos en ejecución en el nodo. Una comprobación ejecuta un comando del sistema operativo y guarda el resultado en un archivo. En Linux, el comando es ps. La carpeta contiene los siguientes elementos:
- %Y%m%d%H: subcarpeta que contiene uno o varios archivos de comprobación de procesos. El nombre de la subcarpeta es la fecha y hora de creación de la comprobación (Año, Mes, Día, Hora).
processes_%M: archivo dentro de la subcarpeta. El archivo muestra detalles sobre la comprobación del proceso. El nombre del archivo termina con la hora de comprobación (Minuto) relativa a la hora de creación del control.
node_disk_usage.csv Muestra el uso detallado del disco del nodo.
node_resource_usage.csv Proporciona información general sobre el uso de recursos del nodo.
processes_resource_usage.csv Proporciona información general sobre el uso de recursos de cada proceso.

Adición del registro al script de puntuación

Puede usar el registro de Python en el script de puntuación. Estos registros se almacenan en el archivo logs/user/stdout/<node_id>/process<number>.stdout.txt.

En el siguiente código se muestra cómo agregar el registro en el script:

import argparse
import logging

# Get logging_level
arg_parser = argparse.ArgumentParser(description="Argument parser.")
arg_parser.add_argument("--logging_level", type=str, help="logging level")
args, unknown_args = arg_parser.parse_known_args()
print(args.logging_level)

# Initialize Python logger
logger = logging.getLogger(__name__)
logger.setLevel(args.logging_level.upper())
logger.info("Info log statement")
logger.debug("Debug log statement")

Resolución de problemas comunes

En las siguientes secciones se describen los errores comunes que pueden producirse durante el desarrollo y el consumo de puntos de conexión por lotes, y los pasos para la resolución.

No hay ningún módulo denominado azureml

La implementación por lotes de Azure Machine Learning requiere el paquete azureml-core en la instalación.

Mensaje registrado: "No hay ningún módulo denominado azureml".

Motivo: parece que falta el paquete azureml-core en la instalación.

Solución: agregue el paquete azureml-core al archivo de dependencias de Conda.

No hay ninguna salida en el archivo de predicciones

La implementación por lotes espera una carpeta vacía para almacenar el archivo predictions.csv. Cuando la implementación encuentra un archivo existente en la carpeta especificada, el proceso no reemplaza el contenido del archivo por la nueva salida ni crea un nuevo archivo con los resultados.

Mensaje registrado: no hay ningún mensaje registrado específico.

Motivo: la implementación por lotes no puede sobrescribir un archivo predictions.csv existente.

Solución: si el proceso especifica una ubicación de carpeta de salida para las predicciones, asegúrese de que la carpeta no contiene un archivo predictions.csv existente.

Se agota el tiempo de espera del proceso por lotes

La implementación de Batch usa un valor de timeout para determinar cuánto tiempo debe esperar la implementación para que se complete cada proceso por lotes. Cuando la ejecución de un lote supera el tiempo de espera especificado, la implementación por lotes anula el proceso.

Los procesos anulados se reintentan hasta el número máximo de intentos especificados en el valor de max_retries. Si el error de tiempo de espera se produce en cada reintento, se produce un error en el trabajo de implementación.

Puede configurar las propiedades timeout y max_retries para cada implementación con el parámetro retry_settings.

Mensaje registrado: "No hay ninguna actualización de progreso en [número] segundos. No hay ninguna actualización de progreso en esta comprobación. Espere [número] segundos desde la última actualización".

Motivo: la ejecución por lotes supera el tiempo de espera especificado y el número máximo de reintentos. Esta acción corresponde a un error de la función run() en el script de entrada.

Solución: aumente el valor de timeout de la implementación. De forma predeterminada, el valor de timeout es 30 y el valor de max_retries es 3. Para determinar un valor de timeout adecuado para la implementación, tenga en cuenta el número de archivos que se van a procesar en cada lote y los tamaños de archivo. Puede reducir el número de archivos que se van a procesar y generar minilotes de menor tamaño. Este enfoque da como resultado una ejecución más rápida.

Excepción en ScriptExecution.StreamAccess.Authentication

Para que la implementación por lotes se realice correctamente, la identidad administrada del clúster de proceso debe tener permiso para montar el almacenamiento de recursos de datos. Cuando la identidad administrada no tiene permisos suficientes, el script produce una excepción. Este error también puede hacer que el almacenamiento de recursos de datos no monte.

Mensaje registrado: "ScriptExecutionException fue causado por StreamAccessException. StreamAccessException fue causado por AuthenticationException".

Motivo: el clúster de proceso donde se ejecuta la implementación no puede montar el almacenamiento donde se encuentra el recurso de datos. La identidad administrada del proceso no tiene permisos para realizar el montaje.

Solución: asegúrese de que la identidad administrada asociada al clúster de proceso donde se ejecuta la implementación tiene al menos acceso de Lector de datos de Storage Blob a la cuenta de almacenamiento. Solo los propietarios de cuentas de Azure Storage pueden cambiar el nivel de acceso en Azure Portal.

Error de inicialización del conjunto de datos, no se puede montar el conjunto de datos

El proceso de implementación por lotes requiere almacenamiento montado para el recurso de datos. Cuando el almacenamiento no se monta, no se puede inicializar el conjunto de datos.

Mensaje registrado: "Error de inicialización del conjunto de datos: UserErrorException: Mensaje: No se puede montar Dataset(ID='xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', name='None', version=None). El origen del conjunto de datos no es accesible o no contiene datos".

Motivo: el clúster de proceso donde se ejecuta la implementación no puede montar el almacenamiento donde se encuentra el recurso de datos. La identidad administrada del proceso no tiene permisos para realizar el montaje.

Solución: asegúrese de que la identidad administrada asociada al clúster de proceso donde se ejecuta la implementación tiene al menos acceso de Lector de datos de Storage Blob a la cuenta de almacenamiento. Solo los propietarios de cuentas de Azure Storage pueden cambiar el nivel de acceso en Azure Portal.

dataset_param no tiene el valor especificado ni el valor predeterminado

Durante la implementación por lotes, el nodo del conjunto de datos hace referencia al parámetro dataset_param. Para que la implementación continúe, el parámetro debe tener un valor asignado o un valor predeterminado especificado.

Mensaje registrado: "El [código] del nodo del conjunto de datos hace referencia al parámetro dataset_param, que no tiene un valor especificado o predeterminado".

Motivo: no se admite el recurso de datos de entrada proporcionado al punto de conexión por lotes.

Solución: asegúrese de que el script de implementación proporciona una entrada de datos compatible con los puntos de conexión por lotes.

Se produce un error en el programa de usuario, se produce un error en la ejecución

Durante la ejecución del script para la implementación por lotes, si la función init() o run() encuentra un error, el programa de usuario o la ejecución pueden producir un error. Puede revisar los detalles del error en un archivo de registro generado.

Mensaje registrado: "Error del programa de usuario con excepción: error en la ejecución. Compruebe los registros para obtener más información. Puede comprobar los registros o el archivo readme.txt para ver el diseño de los registros".

Motivo: la función init() o run() genera un error durante la ejecución del script de puntuación.

Solución: siga estos pasos para buscar detalles sobre los errores de función:

  1. En Estudio de Azure Machine Learning, vaya a la ejecución del trabajo de implementación por lotes con errores y seleccione la pestaña Salidas y registros.

  2. Abra el archivo logs>user>error><node_identifier>>process<number>.txt.

  3. Busque el mensaje de error generado por la función init() o run().

ValueError: sin objetos para concatenar

Para que la implementación por lotes se realice correctamente, cada archivo de un minilotes debe ser válido e implementar un tipo de archivo compatible. Tenga en cuenta que los modelos de MLflow solo admiten un subconjunto de tipos de archivo. Para obtener más información, consulte Consideraciones para la implementación con fines de inferencia por lotes.

Mensaje registrado: "ValueError: sin objetos para concatenar".

Motivo: todos los archivos del minilote generado están dañados o no son compatibles.

Solución: siga estos pasos para buscar detalles sobre los archivos con errores:

  1. En Estudio de Azure Machine Learning, vaya a la ejecución del trabajo de implementación por lotes con errores y seleccione la pestaña Salidas y registros.

  2. Abra el archivo logs>user>stdout><node_identifier>>process<number>.txt.

  3. Busque entradas que describan el error de entrada del archivo, como "ERROR:azureml:Error processing input file".

Si no se admite el tipo de archivo, revise la lista de archivos admitidos. Posiblemente tenga que cambiar el tipo de archivo de los datos de entrada o personalizar la implementación proporcionando un script de puntuación. Para más información, consulte Uso de modelos de MLflow con un script de puntuación.

No se realizó correctamente el minilote

El proceso de implementación por lotes requiere puntos de conexión por lotes para proporcionar datos en el formato esperado por la función run(). Si los archivos de entrada están dañados o no son compatibles con la firma del modelo, la función run() no puede devolver un minilote correcto.

Mensaje registrado: "No se ha devuelto ningún elemento de mini lotes correcto de run(). Compruebe "respuesta: run()" en https://aka.ms/batch-inference-documentation".

Motivo: el punto de conexión por lotes no ha podido proporcionar datos en el formato esperado a la función run(). Este problema puede deberse a que se leen los archivos dañados o a incompatibilidad de los datos de entrada con la firma del modelo (MLflow).

Solución: siga estos pasos para buscar detalles sobre los minilotes con errores:

  1. En Estudio de Azure Machine Learning, vaya a la ejecución del trabajo de implementación por lotes con errores y seleccione la pestaña Salidas y registros.

  2. Abra el archivo logs>user>stdout><node_identifier>>process<number>.txt.

  3. Busque entradas que describan el error del archivo de entrada para el minilote, como "Archivo de entrada de procesamiento de errores". Los detalles deben describir por qué el archivo de entrada no se puede leer correctamente.

Audiencia o servicio no permitido

Los tokens de Microsoft Entra se emiten para acciones específicas que identifican los usuarios permitidos (audiencia), servicio y recursos. El token de autenticación de la API de REST de punto de conexión del lote debe establecer el parámetro resource en https://ml.azure.com.

Mensaje registrado: no hay ningún mensaje registrado específico.

Motivo: intenta invocar la API de REST para el punto de conexión por lotes y la implementación con un token emitido para una audiencia o servicio diferente.

Solución: siga estos pasos para resolver este problema de autenticación:

  1. Al generar un token de autenticación para la API de REST de punto de conexión de lotes, establezca el parámetro resource en https://ml.azure.com.

    Tenga en cuenta que este recurso es diferente del recurso que se usa para administrar el punto de conexión desde la API de REST. Todos los recursos de Azure (incluidos los puntos de conexión por lotes) usan el recurso https://management.azure.com para la administración.

  2. Al invocar la API de REST para un punto de conexión por lotes y una implementación, tenga cuidado de usar el token emitido para la API de REST de punto de conexión de lotes y no un token emitido para una audiencia o un servicio diferente. En cada caso, confirme que usa el URI de recurso correcto.

Si quiere usar la API de administración y la API de invocación de trabajos al mismo tiempo, necesita dos tokens. Para obtener más información, consulte Autenticación en puntos de conexión por lotes (REST).

No hay implementaciones válidas para enrutar

Para que la implementación por lotes se realice correctamente, el punto de conexión por lotes debe tener al menos una ruta de implementación válida. El método estándar consiste en definir la implementación por lotes predeterminada mediante el parámetro defaults.deployment_name.

Message logged: "No hay implementaciones válidas a las que enrutar. Compruebe que el punto de conexión tiene al menos una implementación con valores de peso positivos o use un encabezado específico de implementación para enrutar".

Motivo: la implementación por lotes predeterminada no se ha ajustado correctamente.

Solución: use uno de los siguientes métodos para resolver el problema de enrutamiento:

  • Confirme que el parámetro defaults.deployment_name define la implementación por lotes predeterminada correcta. Para obtener más información, consulte Actualizar la implementación por lotes predeterminada.

  • Defina la ruta con un encabezado específico de la implementación.

Limitaciones y escenarios no admitidos

Al diseñar soluciones de implementación de aprendizaje automático que dependen de puntos de conexión por lotes, tenga en cuenta que no se admiten algunas configuraciones y escenarios. En las siguientes secciones se identifican áreas de trabajo no admitidas y recursos de proceso y tipos no válidos para los archivos de entrada.

Configuraciones de área de trabajo no admitidas

No se admiten las siguientes configuraciones de área de trabajo para la implementación por lotes:

  • Áreas de trabajo configuradas con una característica de Azure Container Registries con la característica Cuarentena habilitada
  • Áreas de trabajo con claves administradas por el cliente

Configuraciones de proceso no admitidas

No se admiten las siguientes configuraciones de proceso para la implementación por lotes:

  • Clústeres de Kubernetes de Azure ARC
  • Solicitud de recursos pormenorizada (memoria, vCPU, GPU) para los clústeres de Azure Kubernetes (solo se puede solicitar el recuento de instancias)

Tipos de archivo de entrada no admitidos

No se admiten los siguientes tipos de archivo de entrada para la implementación por lotes:

  • Conjuntos de datos tabulares (V1)
  • Carpetas y conjuntos de datos de archivos (V1)
  • MLtable (V2)

Contenido relacionado