Condividi tramite

Risolvere i problemi relativi agli endpoint batch

  • Articolo

SI APPLICA A:Estensione ML dell'interfaccia della riga di comando di Azure v2 (corrente)Python SDK azure-ai-ml v2 (corrente)

Questo articolo fornisce indicazioni per la risoluzione degli errori comuni quando si usano gli endpoint batch per l'assegnazione del punteggio batch in Azure Machine Learning. Le sezioni seguenti descrivono come analizzare i log di assegnazione del punteggio batch per identificare possibili problemi e scenari non supportati. È anche possibile esaminare le soluzioni consigliate per risolvere gli errori comuni.

Ottenere i log per i processi di assegnazione del punteggio batch

Dopo aver richiamato un endpoint batch usando l'API REST o l'interfaccia della riga di comando di Azure, il processo di assegnazione del punteggio batch viene eseguito in modo asincrono. Sono disponibili due opzioni per ottenere i log per un processo di assegnazione del punteggio in batch:

  • Opzione 1: Trasmettere i log dei processi a una console locale. Vengono trasmessi solo i log nella cartella azureml-logs.

    Eseguire il comando seguente per trasmettere i log generati dal sistema alla console. Sostituire il parametro <job_name> con il nome del processo di assegnazione del punteggio batch:

    az ml job stream --name <job_name>

  • Opzione 2: Visualizzare i log dei processi in Azure Machine Learning Studio.

    Eseguire il comando seguente per ottenere il collegamento di processo da usare in Studio. Sostituire il parametro <job_name> con il nome del processo di assegnazione del punteggio batch:

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

    1. Aprire il collegamento al processo in Studio.

    2. Nel grafico del processo, selezionare il passaggio batchscoring.

    3. Nella scheda Output + log, selezionare uno o più log da esaminare.

Esaminare i file di log

Azure Machine Learning offre diversi tipi di file di log e altri file di dati che è possibile usare per risolvere i problemi del processo di assegnazione del punteggio batch.

Le due cartelle di primo livello per i log di assegnazione del punteggio batch sono azureml-logs e logs. Le informazioni del controller che avviano lo script di assegnazione del punteggio vengono archiviate nel ~/azureml-logs/70_driver_log.txt.

Esaminare le informazioni di alto livello

La natura distribuita dei processi di assegnazione del punteggio batch comporta log provenienti da origini diverse, ma due file combinati forniscono informazioni di alto livello:

File Descrizione
~/logs/job_progress_overview.txt Fornisce informazioni generali sul numero corrente di mini batch (noti anche come attività) creati e sul numero corrente di mini batch elaborati. Man mano che l'elaborazione per mini batch termina, il log registra i risultati del processo. Se il processo non riesce, verrà visualizzato il messaggio di errore e il punto in cui avviare la risoluzione dei problemi.
~/logs/sys/master_role.txt Fornisce la visualizzazione del nodo principale (chiamato anche agente di orchestrazione) del processo in esecuzione. Questo log include informazioni sulla creazione dell'attività, il monitoraggio dello stato e il risultato del processo.

Esaminare i dati di analisi dello stack per individuare gli errori

Altri file forniscono informazioni sui possibili errori nello script:

File Descrizione
~/logs/user/error.txt Fornisce un riepilogo degli errori nello script.
~/logs/user/error/* Fornisce tracce complete dello stack delle eccezioni generate durante il caricamento e l'esecuzione dello script di immissione.

Esaminare i log di processo per nodo

Per una conoscenza completa del modo in cui ogni nodo esegue lo script di punteggio, esaminare i singoli log di processo per ogni nodo. I log dei processi vengono archiviati nella cartella ~/logs/sys/node e raggruppati in base ai nodi di lavoro.

La cartella contiene una sottocartella <ip_address>/ che contiene un file <process_name>.txt con informazioni dettagliate su ogni mini batch. Il contenuto della cartella viene aggiornato quando un lavoratore seleziona o completa il mini batch. Per ogni mini batch, il file di log include:

  • Indirizzo IP e ID processo (PID) del processo di lavoro.
  • Numero totale di elementi, numero di elementi elaborati correttamente e numero di elementi non riusciti.
  • L'ora di inizio, la durata, il tempo di elaborazione e l'ora del metodo run.

Esaminare i controlli periodici per nodo

È anche possibile visualizzare i risultati dei controlli periodici dell'utilizzo delle risorse per ogni nodo. I file di log e i file di installazione vengono archiviati nella cartella ~/logs/perf.

Usare il parametro --resource_monitor_interval per modificare l'intervallo di controllo in secondi:

  • Usa valore predefinito: l'intervallo predefinito è 600 secondi (circa 10 minuti).
  • Arresta controlli: impostare il valore su 0 per interrompere l'esecuzione dei controlli nel nodo.

La cartella contiene una sottocartella <ip_address>/ relativa a ogni mini batch. Il contenuto della cartella viene aggiornato quando un lavoratore seleziona o completa il mini batch. Per ogni mini batch, la cartella include gli elementi seguenti:

File o cartella Descrizione
os/ Archivia informazioni su tutti i processi in esecuzione nel nodo. Un controllo esegue un comando del sistema operativo e salva il risultato in un file. In Linux, usare il comando: ps. La cartella contiene gli elementi seguenti:
- %Y%m%d%H: Sottocartella contenente uno o più file di controllo del processo. Il nome della sottocartella è la data e l'ora di creazione del controllo (Anno, Mese, Giorno, Ora).
processes_%M: File all'interno della sottocartella. Il file mostra i dettagli sul controllo del processo. Il nome del file termina con l'ora di controllo (minuto) rispetto all'ora di creazione del controllo.
node_disk_usage.csv Mostra l'utilizzo dettagliato del disco del nodo.
node_resource_usage.csv Fornisce la panoramica sull'utilizzo delle risorse del nodo.
processes_resource_usage.csv Fornisce una panoramica dell'utilizzo delle risorse di ogni processo.

Aggiungere la registrazione allo script di assegnazione del punteggio

È possibile usare la registrazione Python nello script di assegnazione dei punteggi. Questi log vengono archiviati nel file logs/user/stdout/<node_id>/process<number>.stdout.txt.

Il codice seguente illustra come aggiungere la registrazione nello 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")

Risolvere gli errori comuni

Le sezioni seguenti descrivono gli errori comuni che possono verificarsi durante lo sviluppo e l'utilizzo di endpoint batch e i passaggi per la risoluzione.

Nessun modulo denominato azureml

La distribuzione batch di Azure Machine Learning richiede il pacchetto azureml-core nell'installazione.

Messaggio registrato: "Nessun modulo denominato azureml".

Motivo: Il pacchetto azureml-core sembra non essere presente nell'installazione.

Soluzione: Aggiungere il pacchetto azureml-core al file delle dipendenze conda.

Nessun output nel file di previsione

La distribuzione batch prevede che una cartella vuota archivi il file predictions.csv. Quando la distribuzione rileva un file esistente nella cartella specificata, il processo non sostituisce il contenuto del file con il nuovo output o crea un nuovo file con i risultati.

Messaggio registrato: Nessun messaggio registrato specifico.

Motivo: La distribuzione batch non può sovrascrivere un file predictions.csv esistente.

Soluzione: Se il processo specifica un percorso della cartella di output per le previsioni, assicurarsi che la cartella non contenga un file predictions.csvesistente.

Timeout del processo batch

La distribuzione batch usa un valore timeout per determinare per quanto tempo la distribuzione deve attendere il completamento di ogni processo batch. Quando l'esecuzione di un batch supera il timeout specificato, la distribuzione batch interrompe il processo.

I processi interrotti vengono ritentati fino al numero massimo di tentativi specificati nel valore max_retries. Se si verifica l'errore di timeout in ogni tentativo di ripetizione, il processo di distribuzione ha esito negativo.

È possibile configurare le proprietà timeout e max_retries per ogni distribuzione con il parametro retry_settings.

Messaggio registrato: "Nessun aggiornamento dello stato in [numero] secondi. Nessun aggiornamento dello stato in questo controllo. Attendere [numero] secondi dall'ultimo aggiornamento."

Motivo: L'esecuzione batch supera il timeout e il numero massimo di tentativi specificati. Questa azione corrisponde all'errore della funzione run() nello script di immissione.

Soluzione: Aumentare il valore timeout per la distribuzione. Per impostazione predefinita, il valore timeout è 30 e il valore max_retries è 3. Per determinare un valore timeout appropriato per la distribuzione, prendere in considerazione il numero di file da elaborare in ogni batch e le dimensioni dei file. È possibile ridurre il numero di file da elaborare e generare mini batch di dimensioni inferiori. Questo approccio comporta un'esecuzione più rapida.

Eccezione in ScriptExecution.StreamAccess.Authentication

Affinché la distribuzione batch abbia esito positivo, l'identità gestita per il cluster di calcolo deve disporre dell'autorizzazione per montare l'archiviazione degli asset di dati. Quando l'identità gestita non dispone di autorizzazioni sufficienti, lo script genera un'eccezione. Questo errore può anche causare il mancato montaggio dell'archiviazione degli asset di dati.

Messaggio registrato: "ScriptExecutionException è stato causato da StreamAccessException. StreamAccessException è stato causato da AuthenticationException."

Motivo: il cluster di calcolo in cui è in esecuzione la distribuzione non può montare l'archiviazione in cui si trova l'asset di dati. L'identità gestita dell'ambiente di calcolo non dispone delle autorizzazioni per eseguire il montaggio.

Soluzioni: Verificare che l'identità gestita associata al cluster di calcolo in cui la distribuzione è in esecuzione abbia almeno accesso di Lettore di dati BLOB di archiviazione all'account di archiviazione. Solo i proprietari dell'account di archiviazione di Azure possono modificare il livello di accesso nel portale di Azure.

L'inizializzazione del set di dati non è riuscita; impossibile montare il set di dati

Il processo di distribuzione batch richiede l'archiviazione montata per l'asset di dati. Quando l'archiviazione non viene montata, il set di dati non può essere inizializzato.

Messaggio registrato: "Inizializzazione del set di dati non riuscita: UserErrorException: Messaggio: impossibile montare il set di dati(ID='xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx', name='None', version=None). L'origine del set di dati non è accessibile o non contiene dati."

Motivo: il cluster di calcolo in cui è in esecuzione la distribuzione non può montare l'archiviazione in cui si trova l'asset di dati. L'identità gestita dell'ambiente di calcolo non dispone delle autorizzazioni per eseguire il montaggio.

Soluzioni: Verificare che l'identità gestita associata al cluster di calcolo in cui la distribuzione è in esecuzione abbia almeno accesso di Lettore di dati BLOB di archiviazione all'account di archiviazione. Solo i proprietari dell'account di archiviazione di Azure possono modificare il livello di accesso nel portale di Azure.

dataset_param non ha un valore specificato o un valore predefinito

Durante la distribuzione batch, il nodo del set di dati fa riferimento al parametro dataset_param. Affinché la distribuzione proceda, il parametro deve avere un valore assegnato o un valore predefinito specificato.

Messaggio registrato: "Il nodo del set di dati [codice] fa riferimento al parametro dataset_param che non ha un valore specificato o un valore predefinito."

Motivo: l'asset di dati di input fornito all'endpoint batch non è supportato.

Soluzione: Assicurarsi che lo script di distribuzione fornisca un input di dati supportato per gli endpoint batch.

Errore del programma utente; esecuzione non riuscita

Durante l'esecuzione dello script per la distribuzione batch, se la funzione init() o run() rileva un errore, il programma utente o l'esecuzione può non riuscire. È possibile esaminare i dettagli dell'errore in un file di log generato.

Messaggio registrato: Errore del programma utente con eccezione: esecuzione non riuscita. Controllare i log per informazioni dettagliate. È possibile controllare log/readme.txt per il layout dei log."

Motivo: La funzione init() o run() genera un errore durante l'esecuzione dello script di assegnazione del punteggio.

Soluzione: Seguire questa procedura per individuare i dettagli sugli errori della funzione:

  1. In studio di Azure Machine Learning, andare all'esecuzione del processo di distribuzione batch non riuscita e selezionare la scheda Output + log.

  2. Aprire il file logs>user>error><node_identifier>>process<number>.txt.

  3. Individuare il messaggio di errore generato dalla funzione init() o run().

ValueError: nessun oggetto da concatenare

Affinché la distribuzione batch abbia esito positivo, ogni file in un mini-batch deve essere valido e implementare un tipo di file supportato. Tenere presente che i modelli MLflow supportano solo un subset di tipi di file. Per altre informazioni, vedere Considerazioni per la distribuzione nell'inferenza batch.

Messaggio registrato: "ValueError: nessun oggetto da concatenare."

Motivo: Tutti i file nel mini-batch generato sono danneggiati o sono tipi di file non supportati.

Soluzione: Seguire questa procedura per individuare i dettagli sui file non riusciti:

  1. In studio di Azure Machine Learning, andare all'esecuzione del processo di distribuzione batch non riuscita e selezionare la scheda Output + log.

  2. Aprire il file logs>user>stdout><node_identifier>>process<number>.txt.

  3. Cercare le voci che descrivono l'errore di input del file, ad esempio "ERROR:azureml:Error processing input file."

Se il tipo di file non è supportato, esaminare l'elenco dei file supportati. Potrebbe essere necessario modificare il tipo di file dei dati di input o personalizzare la distribuzione fornendo uno script di assegnazione del punteggio. Per altre informazioni, vedere Uso di modelli MLflow con uno script di punteggio.

Nessun mini batch riuscito

Il processo di distribuzione batch richiede che gli endpoint batch forniscano i dati nel formato previsto dalla funzione run(). Se i file di input sono file danneggiati o incompatibili con la firma del modello, la funzione run() non restituisce un mini batch riuscito.

Messaggio registrato: "Non è presente alcun elemento batch con esito positivo restituito da run(). Controllare 'response: run()' in https://aka.ms/batch-inference-documentation."

Motivo: L'endpoint batch non è riuscito a fornire dati nel formato previsto alla funzione run(). Il problema può essere dovuto alla lettura o all'incompatibilità dei file di input con la firma del modello (MLflow).

Soluzione: Seguire questa procedura per individuare i dettagli relativi al mini batch non riuscito:

  1. In studio di Azure Machine Learning, andare all'esecuzione del processo di distribuzione batch non riuscita e selezionare la scheda Output + log.

  2. Aprire il file logs>user>stdout><node_identifier>>process<number>.txt.

  3. Cercare le voci che descrivono l'errore del file di input per il mini batch, ad esempio "Errore durante l'elaborazione del file di input." I dettagli devono descrivere il motivo per cui il file di input non può essere letto correttamente.

Destinatari o servizio non consentito

I token di Microsoft Entra vengono emessi per azioni specifiche che identificano gli utenti consentiti (destinatari), il servizio e le risorse. Il token di autenticazione per l'API REST dell'endpoint batch deve impostare il parametro resource su https://ml.azure.com.

Messaggio registrato: Nessun messaggio registrato specifico.

Motivo: Si tenta di richiamare l'API REST per l'endpoint batch e la distribuzione con un token rilasciato per destinatari o un servizio diverso.

Soluzione: Seguire questa procedura per risolvere il problema di autenticazione:

  1. Quando si genera un token di autenticazione per l'API REST dell'endpoint batch, impostare il parametro resource su https://ml.azure.com.

    Si noti che questa risorsa è diversa dalla risorsa usata per gestire l'endpoint dall'API REST. Tutte le risorse di Azure (inclusi gli endpoint batch) usano la risorsa https://management.azure.com per la gestione.

  2. Quando si richiama l'API REST per un endpoint e una distribuzione batch, prestare attenzione all'uso del token rilasciato per l'API REST dell'endpoint batch e non di un token rilasciato per destinatari o un servizio diverso. In ogni caso, verificare di usare l'URI della risorsa corretto.

Se si vuole usare l'API di gestione e l'API di chiamata al processo contemporaneamente, sono necessari due token. Per altre informazioni, vedere Autenticazione negli endpoint batch (REST).

Nessuna distribuzione valida su cui eseguire il routing

Affinché la distribuzione batch abbia esito positivo, l'endpoint batch deve avere almeno una route di distribuzione valida. Il metodo standard consiste nel definire la distribuzione batch predefinita usando il parametro defaults.deployment_name.

Messaggio registrato: "Nessuna distribuzione valida su cui eseguire il routing. Verificare che l'endpoint abbia almeno una distribuzione con valori di peso positivi o usare un'intestazione specifica della distribuzione per il routing."

Motivo: La distribuzione batch predefinita non è impostata correttamente.

Soluzione: Usare uno dei metodi seguenti per risolvere il problema di routing:

  • Verificare che il parametro defaults.deployment_name definisca la distribuzione batch predefinita corretta. Per altre informazioni, vedere Aggiornare la distribuzione batch predefinita.

  • Definire la route con un'intestazione specifica della distribuzione.

Limitazioni e scenari non supportati

Quando si progettano soluzioni di distribuzione di Machine Learning che si basano su endpoint batch, tenere presente che alcune configurazioni e scenari non sono supportati. Le sezioni seguenti identificano le aree di lavoro e le risorse di calcolo non supportate e i tipi non validi per i file di input.

Configurazioni dell'area di lavoro non supportate

Le configurazioni dell'area di lavoro seguenti non sono supportate per la distribuzione batch:

  • Aree di lavoro configurate con registri di Azure Container con la funzionalità di quarantena abilitata
  • Aree di lavoro con chiavi gestite dal cliente

Configurazioni di calcolo non supportate

Le configurazioni di calcolo seguenti non sono supportate per la distribuzione batch:

  • Cluster Kubernetes di Azure ARC
  • Richiesta di risorse granulare (memoria, vCPU, GPU) per i cluster Azure Kubernetes (è possibile richiedere solo il numero di istanze)

Tipi di file di input non supportati

I tipi di file di input seguenti non sono supportati per la distribuzione batch:

  • Set di dati tabulari (V1)
  • Cartelle e set di dati di file (V1)
  • MLtable (V2)

Contenuto correlato