Condividi tramite

Guida al debug per la gestione dei modelli

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 registri

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.

Annotazioni

Se il codice del modello restituisce MlflowException errori, si prevede che il codice di risposta venga mappato a una 4xx risposta. Databricks considera questi errori del codice del modello come errori causati dal cliente, perché possono essere risolti in base al messaggio di errore risultante. 5xx I codici di errore sono riservati per comunicare gli errori in cui Databricks si trova in errore.

Controlla i registri degli eventi per il modello nell'interfaccia utente dell'area di lavoro e per 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 Debugging dopo il fallimento della 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.

Modelli di log che richiedono flash-attn

Se si registra un modello che richiede flash-attn, Databricks consiglia di usare una versione wheel personalizzata di flash-attn. Altrimenti possono verificarsi errori di compilazione come ModuleNotFoundError: No module named 'torch'.

Per usare una versione personalizzata del pacchetto wheel di flash-attn, specificare tutti i requisiti pip come elenco e passarli come parametro nella funzione mlflow.transformers.log_model. È inoltre necessario specificare le versioni pytorch, torch e torchvision compatibili con la versione CUDA specificata nella rotellina flash attn .

Ad esempio, Databricks consiglia di usare le versioni e le ruote seguenti per CUDA 11.8:


logged_model=mlflow.transformers.log_model(
transformers_model=test_pipeline,
       artifact_path="artifact_path",
       pip_requirements=["--extra-index-url https://download.pytorch.org/whl/cu118", "mlflow==2.13.1", "setuptools<70.0.0", "torch==2.0.1+cu118", "accelerate==0.31.0", "astunparse==1.6.3", "bcrypt==3.2.0", "boto3==1.34.39", "configparser==5.2.0", "defusedxml==0.7.1", "dill==0.3.6", "google-cloud-storage==2.10.0", "ipython==8.15.0", "lz4==4.3.2", "nvidia-ml-py==12.555.43", "optree==0.12.1", "pandas==1.5.3", "pyopenssl==23.2.0", "pytesseract==0.3.10", "scikit-learn==1.3.0", "sentencepiece==0.1.99", "torchvision==0.15.2+cu118", "transformers==4.41.2", "https://github.com/Dao-AILab/flash-attention/releases/download/v2.5.8/flash_attn-2.5.8+cu118torch2.0cxx11abiFALSE-cp311-cp311-linux_x86_64.whl"],
       input_example=input_example,
       registered_model_name=registered_model_name)

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 costruzione del contenitore fallisce, controlla i log del servizio per notare se si ripetono cicli quando l'endpoint tenta di caricare il modello. Se viene visualizzato questo comportamento, seguire questa procedura:

  1. Aprire un notebook e collegarsi a un cluster all-purpose che usa una versione di Databricks Runtime, non Databricks Runtime per Machine Learning.
  2. 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 o si verifica il timeout quando le richieste vengono inviate all'endpoint

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

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

Analisi della causa radice delle richieste non riuscite

Se una richiesta a un endpoint ha esito negativo, è possibile eseguire l'analisi della causa radice usando le tabelle di inferenza. Le tabelle di inferenza registrano automaticamente tutte le richieste e le risposte al tuo endpoint in una tabella del Catalogo Unity, che puoi interrogare.

Per eseguire query sulle tabelle di inferenza:

  1. Nell'area di lavoro passare alla scheda Serve e selezionare il nome dell'endpoint.
  2. Nella sezione Tabelle di inferenza trovare il nome completo della tabella di inferenza. Ad esempio: my-catalog.my-schema.my-table.
  3. Eseguire quanto segue in un notebook di Databricks: 
    %sql
SELECT * FROM my-catalog.my-schema.my-table
  4. Visualizzare e filtrare in base a colonne come request, responserequest_time e status_code per comprendere le richieste e limitare i risultati. 
    %sql
SELECT * FROM my-catalog.my-schema.my-table
WHERE status_code != 200
  5. Se è stata abilitata la traccia dell'agente per gli agenti di intelligenza artificiale, vedere la colonna Risposta per visualizzare tracce dettagliate. Vedere Abilitare le tabelle di inferenza per gli agenti di intelligenza artificiale.

L'area di lavoro supera la concorrenza provisionata

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

È possibile aumentare la concorrenza a seconda della disponibilità dell'area. Contatta il team del tuo account Databricks e fornisci il tuo 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.

Problemi del Firewall di Azure nell'erogazione 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..

Contatta il team del tuo account Databricks per ricevere assistenza nella risoluzione del 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..

Contatta il team del tuo account Databricks per ricevere assistenza nella risoluzione del problema.