Guida introduttiva di AI Runtime

Databricks consiglia di iniziare con la CLI Databricks per eseguire il tuo primo workload AI Runtime. La CLI Databricks ti permette di inviare, monitorare e gestire carichi di lavoro della GPU serverless dal terminale. Se preferisci i notebook, consulta AI Runtime Notebook quickstart.

Requirements

  • Un'area di lavoro di Azure Databricks con AI Runtime abilitato. Vedi requisiti.
  • Databricks CLI versione 1.24.0 o superiore. Le versioni precedenti mancano dei databricks air comandi, del code_source formato o dell'elenco dei tipi di acceleratore che questo quickstart utilizza.
  • Git deve essere installato e disponibile sul tuo PATH per eseguire l'esempio Python. La CLI utilizza Git per impacchettare codice locale.

Esegui il tuo primo workload

  1. Installa o aggiorna la CLI di Databricks e autenticala con il tuo workspace. Vedere Installare o aggiornare l'interfaccia della riga di comando di Databricks e l'autenticazione per l'interfaccia della riga di comando di Databricks.

    Tip

    Per selezionare uno spazio di lavoro per la procedura guidata senza ripetere --profile, elenca i tuoi profili e imposta un valore predefinito:

    databricks auth profiles
    databricks auth switch --profile <profile>
    databricks auth describe
    

    Controlla che Host nell'output sia lo spazio di lavoro dove vuoi eseguire il carico di lavoro. Per una sessione di shell predefinita, usa export DATABRICKS_CONFIG_PROFILE=<profile> invece. Questa variabile di ambiente ha la precedenza sull'impostazione predefinita impostata da auth switch.

    Per sovrascrivere uno dei valori predefiniti per un comando, aggiungi --profile <other-profile>. Usa lo stesso profilo per l'invio, lo stato e i log: gli ID Job Run appartengono allo spazio di lavoro dove hai inviato il carico di lavoro. Consulta i profili di configurazione per Databricks CLI.

    Conferma che la versione CLI sia 1.24.0 o superiore e che i air comandi siano disponibili:

    databricks --version
    databricks air --help
    

    Se databricks air --help restituisce, unknown command "air" for "databricks"la tua versione CLI è troppo vecchia. Aggiorna la CLI e riprova.

  2. Crea un file di carico di lavoro minimo. Il seguente workload.yaml richiede una GPU A10 ed esegue nvidia-smi per stampare il nome della GPU:

    experiment_name: air-quickstart
    compute:
      num_accelerators: 1
      accelerator_type: GPU_1xA10
    command: nvidia-smi --query-gpu=name --format=csv,noheader
    

    accelerator_type i valori hanno la forma GPU_<GPUs per node>x<GPU model>, come GPU_1xA10, GPU_1xH100, o GPU_8xH100. Per tutti i valori, vedi Tipi di acceleratore. Per elencare i tipi di acceleratori disponibili nel tuo spazio di lavoro, esegui databricks air run -h config.compute.accelerator_type.

  3. Invia il workload e trasmetti i suoi log con databricks air run:

    databricks air run --file workload.yaml --watch
    

    La CLI restituisce l'ID esecuzione del job e un link all'esecuzione nel tuo workspace. --watch Tiene il terminale collegato e trasmette i log in streaming fino al termine del workload.

    Submitting experiment: air-quickstart
    Submitted workload with Job Run ID: 783940125630184
    View job run at: https://example.cloud.databricks.com/jobs/runs/783940125630184?o=1234567890123456
    
    Monitoring run and streaming logs...
    ...
    Environment setup completed at Thu Oct 1 14:23:45 UTC 2026
    NVIDIA A10
    

Tip

Per ottenere aiuto nello scrivere la configurazione del workload e gestire le esecuzioni, installa l'abilità databricks-ai-runtime per il tuo agente AI. Consulta Usare le abilità dell'agente con AI Runtime.

Esegui il tuo codice Python

Per caricare ed eseguire codice Python locale, crea una air-quickstart directory con i seguenti file:

air-quickstart/
├── workload.yaml
└── src/
    └── main.py

Tip

Per partire da un progetto eseguibile invece di creare questi file manualmente, clona il repository cookbook di AI Runtime e passa alla directory CLI getting-started:

git clone https://github.com/databricks-solutions/ai-runtime-cookbook.git
cd ai-runtime-cookbook/getting-started/air-cli

Il progetto del libro di cucina rimane main.py nella stessa directory di workload.yaml e utilizza root_path: ., quindi il suo layout differisce da quello mostrato qui.

Usa il seguente codice Python minimale per verificare che AI Runtime esegue il codice caricato sulla GPU:

import torch

print("Hello from Python on AI Runtime")
print(f"GPU: {torch.cuda.get_device_name(0)}")

Per estendere questo esempio, puoi sostituire src/main.py con il tuo addestramento, batch per inferenza o un'altra applicazione di IA.

Usa la seguente configurazione per workload.yaml:

experiment_name: python-quickstart
environment:
  version: databricks_ai_v6
compute:
  num_accelerators: 1
  accelerator_type: GPU_1xA10
code_source:
  root_path: ./src
command: python "$CODE_SOURCE_PATH/main.py"

Questa configurazione utilizza le seguenti impostazioni ed esegue src/main.py su una GPU A10:

  • environment.version seleziona l'ambiente Databricks AI versione 6, che include PyTorch. Questa chiave è facoltativa. Se lo ometti, la CLI usa il suo impostazione predefinita, un ambiente Standard che non include PyTorch. Per vedere la versione predefinita, esegui databricks air run -h config.environment.version.
  • root_path: ./src carica la src directory nella stessa directory di workload.yaml. Durante l'esecuzione, $CODE_SOURCE_PATH punta alla directory caricata.

Con la posizione di output predefinita, databricks air convert-to-dabs richiede che il codice sia in una sottodirectory, come in questo layout, quando converti il workload in un bundle.

Note

La CLI non carica i file che Git ignora, inclusi quelli ignorati da un repository padre. Se il carico di lavoro non riesce a trovare main.py, esegui git check-ignore -v src per verificare se la src directory è stata ignorata. Vedi code_source nel riferimento YAML del carico di lavoro.

Nei tuoi carichi di lavoro, imposta environment.version per bloccare i pacchetti preinstallati da cui dipende il tuo codice. Per i valori accettati da questa chiave, vedi environment. Per i pacchetti in ogni ambiente, vedi Configura il tuo ambiente di esecuzione AI.

Per portare il tuo stack di dipendenze, sostituisci il environment blocco con Standard environment versione 6 e dipendenze esplicite:

environment:
  version: 6
  dependencies:
    - torch==2.11.0

I carichi di lavoro CLI installano queste dipendenze ad ogni esecuzione. Questa opzione aggiunge tempo di download dei wheel PyTorch e CUDA.

Invia il workload dalla directory che contiene workload.yaml:

databricks air run --file workload.yaml --watch

I log trasmessi in streaming includono:

...
Hello from Python on AI Runtime
GPU: NVIDIA A10G

Ispeziona e gestisci la tua esecuzione

Ogni run ha un ID Job Run, che databricks air run stampa quando invii il carico di lavoro.

Per inviare in background, ometti --watch:

databricks air run --file workload.yaml

Il comando ritorna dopo l'invio mentre il carico di lavoro continua a essere eseguito. Usa il Job Run ID restituito e lo stesso profilo di workspace per i seguenti comandi.

Per verificare lo stato dell'esecuzione, la configurazione e i tempi, esegui:

databricks air get <job-run-id>

L'output contiene un collegamento all'esecuzione del Job e, se disponibile, un collegamento all'esecuzione di MLflow.

Per visualizzare i log di run, esegui:

databricks air logs <job-run-id>

databricks air logs stampa l'output del carico di lavoro esistente e continua a trasmettere mentre la run è attiva.

Usa il link Job run per ispezionare lo stato dell'esecuzione, il calcolo, i tentativi e l'output del driver. Usa il link di esecuzione di MLflow per visualizzare i log persistenti e eventuali parametri, metriche e artefatti registrati dal carico di lavoro.

Per i carichi di lavoro più lunghi, utilizza la scheda System metrics di MLflow per esaminare l'utilizzo della GPU e la memoria raccolti automaticamente. Per registrare metriche e artefatti personalizzati o confrontare le esecuzioni, vedi Tracciamento e osservabilità degli esperimenti.

Per elencare le run, incluse quelle completate, esegui:

databricks air list --all-status

Per annullare una run attiva, esegui:

databricks air cancel <job-run-id>

Se un'esecuzione fallisce, utilizza il suo stato, i log e i collegamenti Job o MLflow disponibili per identificare l'errore azionabile. Correggi il carico di lavoro o la configurazione, poi invia di nuovo.

Continua a esplorare la CLI Databricks

Questo quickstart utilizza una configurazione minima del carico di lavoro. Vedi Workload YAML reference per configurare ambienti, sorgenti di codice, calcolo, segreti, tentativi e altre impostazioni.

Se l'ambiente standard non soddisfa i requisiti delle tue dipendenze, usa un'immagine Docker personalizzata.

Per esplorare l'addestramento completo, la messa a punto, l'inferenza batch, l'addestramento distribuito e i carichi di lavoro Ray, clona il AI Runtime Cookbook ed esegui una ricetta.

Risorse aggiuntive