Guida al debug per la gestione dei modelli

Articolo
01/21/2025

Questo articolo illustra i passaggi di debug per i problemi comuni che gli utenti potrebbero riscontrare durante l'uso degli endpoint di gestione del modello. I problemi comuni possono includere errori riscontrati dagli utenti quando l'endpoint non riesce a inizializzare o avviare, errori di compilazione correlati al contenitore o problemi durante l'operazione o l'esecuzione del modello nell'endpoint.

Accedere ed esaminare i log

Databricks consiglia di esaminare i log di compilazione per il debug e la risoluzione degli errori nel modello che gestisce i carichi di lavoro. Vedere Monitorare la qualità del modello e l'integrità degli endpoint per informazioni sui log e su come visualizzarli.

Controllare i registri eventi per il modello nell'interfaccia utente dell'area di lavoro e verificare la presenza di un messaggio di compilazione del contenitore riuscito. Se non viene visualizzato un messaggio di compilazione dopo un'ora, contattare il supporto di Databricks per assistenza.

Se la compilazione ha esito positivo, ma si verificano altri errori, vedere Debug dopo l'esito positivo della compilazione del contenitore. Se la compilazione non riesce, vedere Debug dopo l'errore di compilazione del contenitore.

Versioni dei pacchetti di libreria installate

Nei log di compilazione è possibile confermare le versioni del pacchetto installate.

Per le versioni di MLflow, se non è specificata una versione, Model Serving usa la versione più recente.
Per la gestione della GPU personalizzata, Model Serving installa le versioni consigliate di cuda e cuDNN in base alla documentazione pubblica di PyTorch e Tensorflow.

Prima dei controlli di convalida della distribuzione del modello

Databricks consiglia di applicare le linee guida in questa sezione prima di gestire il modello. I parametri seguenti possono intercettare i problemi prima di attendere l'endpoint. Vedere Convalidare l'input del modello prima della distribuzione per convalidare l'input del modello prima di distribuire il modello.

Testare le stime prima della distribuzione

Prima di distribuire il modello all'endpoint di servizio, testa le predizioni offline in un ambiente virtuale utilizzando mlflow.models.predict ed esempi di input. Per indicazioni più dettagliate, vedere la documentazione di MLflow per testare le previsioni.


input_example = {
                  "messages":
                  [
                    {"content": "How many categories of products do we have? Name them.", "role": "user"}
                  ]
                }

mlflow.models.predict(
   model_uri = logged_chain_info.model_uri,
   input_data = input_example,
)

Convalidare l'input del modello prima della distribuzione

I modelli che servono gli endpoint prevedono un formato speciale di input json per verificare che l'input del modello funzioni su un endpoint di servizio prima della distribuzione. È possibile usare validate_serving_input in MLflow per eseguire tale convalida.

Di seguito è riportato un esempio del codice generato automaticamente nella scheda artefatti dell'esecuzione se il modello viene registrato con un esempio di input valido.

from mlflow.models import validate_serving_input

model_uri = 'runs:/<run_id>/<artifact_path>'

serving_payload = """{
 "messages": [
   {
     "content": "How many product categories are there?",
     "role": "user"
   }
 ]
}
"""

# Validate the serving payload works on the model
validate_serving_input(model_uri, serving_payload)

È anche possibile testare qualsiasi esempio di input rispetto al modello registrato usando convert_input_example_to_serving_input API per generare un input json di gestione valido.

from mlflow.models import validate_serving_input
from mlflow.models import convert_input_example_to_serving_input

model_uri = 'runs:/<run_id>/<artifact_path>'

# Define INPUT_EXAMPLE with your own input example to the model
# A valid input example is a data instance suitable for pyfunc prediction

serving_payload = convert_input_example_to_serving_input(INPUT_EXAMPLE)

# Validate the serving payload works on the model
validate_serving_input(model_uri, serving_payload)

Debug dopo l'esito positivo della compilazione del contenitore

Anche se il contenitore viene compilato correttamente, potrebbero verificarsi problemi durante l'esecuzione del modello o durante il funzionamento dell'endpoint stesso. Le sottosezioni seguenti illustrano in dettaglio i problemi comuni e come risolvere i problemi e il debug

Dipendenza mancante

È possibile che venga visualizzato un errore simile a An error occurred while loading the model. No module named <module-name>.. Questo errore potrebbe indicare che manca una dipendenza dal contenitore. Verificare di aver indicato correttamente tutte le dipendenze che devono essere incluse nella compilazione del contenitore. Prestare particolare attenzione alle librerie personalizzate e assicurarsi che i .whl file siano inclusi come artefatti.

Ciclo dei log del servizio

Se la compilazione del contenitore non riesce, controllare i log del servizio per verificare se vengono visualizzati cicli quando l'endpoint tenta di caricare il modello. Se viene visualizzato questo comportamento, seguire questa procedura:

Aprire un notebook e collegarsi a un cluster all-purpose che usa una versione di Databricks Runtime, non Databricks Runtime per Machine Learning.
Caricare il modello usando MLflow e provare a eseguire il debug da questa posizione.

È anche possibile caricare il modello in locale nel PC ed eseguire il debug da questa posizione. Caricare il modello in locale usando quanto segue:

import os
import mlflow

os.environ["MLFLOW_TRACKING_URI"] = "databricks://PROFILE"

ARTIFACT_URI = "model_uri"
if '.' in ARTIFACT_URI:
    mlflow.set_registry_uri('databricks-uc')
local_path = mlflow.artifacts.download_artifacts(ARTIFACT_URI)
print(local_path)

conda env create -f local_path/artifact_path/conda.yaml
conda activate mlflow-env

mlflow.pyfunc.load_model(local_path/artifact_path)

Il modello ha esito negativo quando le richieste vengono inviate all'endpoint

È possibile che venga visualizzato un errore simile Encountered an unexpected error while evaluating the model. Verify that the input is compatible with the model for inference. a quando predict() viene chiamato sul modello.

Si è verificato un problema di codice nella predict() funzione. Databricks consiglia di caricare il modello da MLflow in un notebook e chiamarlo. In questo modo si evidenziano i problemi nella predict() funzione e si può vedere dove si verifica l'errore all'interno del metodo .

L'area di lavoro supera la concorrenza con provisioning

È possibile che venga visualizzato un Workspace exceeded provisioned concurrency quota errore.

È possibile aumentare la concorrenza a seconda della disponibilità dell'area. Contattare il team dell'account Databricks e fornire l'ID dell'area di lavoro per richiedere un aumento della concorrenza.

Debug dopo un errore di compilazione del contenitore

Questa sezione descrive in dettaglio i problemi che possono verificarsi quando la compilazione non riesce.

`OSError: [Errno 28] No space left on device`

L'errore No space left può essere dovuto a troppi artefatti di grandi dimensioni registrati insieme al modello inutilmente. Controllare in MLflow che gli artefatti estranei non vengono registrati insieme al modello e provare a ridistribuire il pacchetto ridotto.

Firewall di Azure problemi relativi alla gestione dei modelli dal catalogo unity

È possibile che venga visualizzato l'errore: Build could not start due to an internal error. If you are serving a model from UC and Azure Firewall is enabled, this is not supported by default..

Contattare il team dell'account Databricks per risolvere il problema.

Errore di compilazione a causa della mancanza di disponibilità della GPU

È possibile che venga visualizzato un errore: Build could not start due to an internal error - please contact your Databricks representative..