Introduzione al tracciamento MLflow per GenAI in un IDE locale

Questa guida introduttiva consente di integrare l'app GenAI con MLflow Tracing se si usa un ambiente di sviluppo locale, ad esempio un ambiente di sviluppo locale( VS Code, PyCharm, Cursor o altri) o un ambiente notebook ospitato localmente, ad esempio Jupyter. Se si usa un notebook di Databricks, vedere invece la guida introduttiva al notebook di Databricks .

Questa esercitazione illustra le procedure seguenti:

• Creare un esperimento MLflow nel tuo workspace Azure Databricks
• Collegare il tuo ambiente di sviluppo locale all'esperimento
• Eseguire una semplice applicazione GenAI localmente sulla tua macchina
• Visualizzazione dei dati di traccia caricati sul tuo workspace Azure Databricks

Prerequisiti

• Accesso a un'area di lavoro Azure Databricks.

Passaggio 1: Installare MLflow

Installare MLflow con la connettività di Databricks:

pip install --upgrade "mlflow[databricks]>=3.14.0" openai

Passaggio 2: Creare un nuovo esperimento MLflow

Un esperimento MLflow è il contenitore per l'applicazione GenAI. Per altre informazioni, vedere Esperimenti.

1. Aprire l'area di lavoro di Azure Databricks.
2. Nella barra laterale sinistra, in Intelligenza artificiale/Machine Learning, fare clic su Esperimenti.
3. Nella parte superiore della pagina Esperimenti fare clic su App e agenti GenAI.
4. Per ottenere l'ID e il percorso dell'esperimento, fare clic sull'icona delle informazioni nell'angolo in alto a sinistra. Questi valori verranno usati nei passaggi successivi.

Passaggio 3: Connettere l'ambiente a MLflow

I frammenti di codice seguenti illustrano come configurare l'autenticazione usando un token di accesso personale (PAT) Azure Databricks. MLflow funziona anche con gli altri metodi di autenticazione supportati da Databricks.

Utilizzare le variabili di ambiente

1. Nell'esperimento MLflow, fare clic sull'icona del menu kebab >Registra le tracce localmente>Genera chiave API.

2. Copiare ed eseguire il codice generato nel terminale.

   export DATABRICKS_TOKEN=<databricks-personal-access-token>
   export DATABRICKS_HOST=https://<workspace-name>.cloud.databricks.com
   export MLFLOW_TRACKING_URI=databricks
   export MLFLOW_REGISTRY_URI=databricks-uc
   export MLFLOW_EXPERIMENT_ID=<experiment-id>
   

Usare un file .env

1. Nell'esperimento MLflow, fare clic sull'icona del menu kebab >Registra le tracce localmente>Genera chiave API.

2. Copiare il codice generato in un .env file nella radice del progetto.

   DATABRICKS_TOKEN=<databricks-personal-access-token>
   DATABRICKS_HOST=https://<workspace-name>.cloud.databricks.com
   MLFLOW_TRACKING_URI=databricks
   MLFLOW_REGISTRY_URI=databricks-uc
   MLFLOW_EXPERIMENT_ID=<experiment-id>
   

3. Installare il pacchetto python-dotenv.

   pip install python-dotenv
   

4. Caricare le variabili di ambiente nel codice:

   # At the beginning of your Python script
   from dotenv import load_dotenv
   
   # Load environment variables from .env file
   load_dotenv()
   

Passo 3b (consigliato): abilita lo storage delle tracce del Catalogo Unity

I passaggi sopra utilizzano il backend dell'esperimento gestito, che è il percorso più veloce verso la tua prima traccia ma limita le tracce a 100.000 per esperimento. Per uno storage scalabile e governato senza limite di traccia, Azure Databricks consiglia di associare il tuo esperimento a una posizione di traccia del Catalogo Unity.

Quando crei app.py nel Passo 4, aggiungi quanto segue in cima prima di qualsiasi chiamata di tracciamento:

import mlflow
from mlflow.entities.trace_location import UnityCatalog

mlflow.set_experiment(
    experiment_id="<experiment-id>",  # the ID you copied in Step 2
    trace_location=UnityCatalog(
        catalog_name="<UC_CATALOG_NAME>",
        schema_name="<UC_SCHEMA_NAME>",
        table_prefix="<UC_TABLE_PREFIX>",
    ),
)

Per dettagli completi sulla configurazione, consulta Archivia le tracce OpenTelemetry nel Catalogo Unity.

Passaggio 4: Creare e instrumentare l'applicazione

Crea la tua app GenAI con la traccia attivata. Il codice gira interamente sulla tua macchina locale e carica tracce al tuo esperimento MLflow nello spazio di lavoro di Azure Databricks.

1. Creare un file Python denominato app.py nella directory del progetto.

2. Inizializza un client OpenAI per connettersi a LLM ospitati da Databricks o da OpenAI.

   Modelli di linguaggio di grandi dimensioni ospitati in Databricks

   Usare databricks-openai per ottenere un client OpenAI che si connette a LLM ospitati su Databricks. Selezionare un modello dai modelli di base disponibili.

   import mlflow
   from databricks_openai import DatabricksOpenAI
   
   # Enable MLflow's autologging to instrument your application with Tracing
   mlflow.openai.autolog()
   
   # Traces are written to the experiment set by MLFLOW_EXPERIMENT_ID and the
   # tracking server set by MLFLOW_TRACKING_URI, both configured in the previous step
   
   # Create an OpenAI client that is connected to Databricks-hosted LLMs
   client = DatabricksOpenAI()
   
   # Select an LLM
   model_name = "databricks-claude-sonnet-5"
   

   LLMs ospitati da OpenAI

   Usare OpenAI SDK nativo per connettersi ai modelli ospitati in OpenAI. Selezionare un modello dai modelli OpenAI disponibili.

   import mlflow
   import os
   import openai
   
   # Ensure your OPENAI_API_KEY is set in your environment
   # os.environ["OPENAI_API_KEY"] = "<YOUR_API_KEY>" # Uncomment and set if not globally configured
   
   # Enable auto-tracing for OpenAI
   mlflow.openai.autolog()
   
   # Traces are written to the experiment set by MLFLOW_EXPERIMENT_ID and the
   # tracking server set by MLFLOW_TRACKING_URI, both configured in the previous step
   
   # Create an OpenAI client connected to OpenAI SDKs
   client = openai.OpenAI()
   
   # Select an LLM
   model_name = "gpt-5"
   

3. Definire ed eseguire l'applicazione:

   Usare il @mlflow.trace decorator, che semplifica la tracciabilità di qualsiasi funzione Python, combinato con la strumentazione automatica di OpenAI per acquisire i dettagli delle chiamate all'SDK di OpenAI.

   # Use the trace decorator to capture the application's entry point
   @mlflow.trace
   def my_app(input: str):
       # This call is automatically instrumented by `mlflow.openai.autolog()`
       response = client.chat.completions.create(
           # Uses a Databricks-hosted LLM by default. To use an AI Gateway, Model Serving endpoint, or your own OpenAI credentials, replace `model_name` with a valid model such as `gpt-5`.
           model=model_name,
           messages=[
               {
                   "role": "system",
                   "content": "You are a helpful assistant.",
               },
               {
                   "role": "user",
                   "content": input,
               },
           ],
       )
       return response.choices[0].message.content
   
   result = my_app(input="What is MLflow?")
   print(result)
   

4. Eseguire l'applicazione:

   python app.py
   

   Questo codice viene eseguito localmente: il app.py file rimane sulla tua macchina, e le variabili di ambiente del Passo 3 indicano al client MLflow dove caricare i dati delle tracce. Per cambiare la logica del prompt o dell'agente, modifica il file locale e rieseguilo.

Per informazioni dettagliate sull'aggiunta della traccia alle app, vedere Aggiungere tracce alle applicazioni: traccia automatica e manuale e Integrazioni di traccia MLflow (oltre 20 integrazioni di librerie).

Passaggio 5: Visualizzare la traccia in MLflow

Quando appare una traccia nell'interfaccia di Azure Databricks, il tuo codice viene eseguito sul tuo portatile e la traccia viene inviata tramite HTTPS.

1. Torna all'esperimento MLflow che hai selezionato nello Step 2.
2. La traccia generata viene visualizzata nella scheda Tracce .
3. Fare clic sulla traccia per visualizzarne i dettagli.

Comprendere la traccia

La nuova traccia mostra:

• Intervallo radice: rappresenta gli input per la my_app(...) funzione
  • Intervallo figlio: rappresenta la richiesta di completamento della OpenAI
• Attributi: contiene metadati come il nome del modello, i conteggi dei token e le informazioni di intervallo
• Input: messaggi inviati al modello
• Output: risposta ricevuta dal modello

Anche questa traccia minima presenta informazioni utili sul comportamento dell'applicazione, tra cui:

• Cosa è stato chiesto
• Quale risposta è stata generata
• Quanto tempo ha impiegato la richiesta
• Quanti token sono stati usati (che influiscono sui costi)

Per applicazioni più complesse, ad esempio sistemi RAG o agenti in più passaggi, MLflow Tracing offre ancora più valore rivelando i lavori interni di ogni componente e passaggio.

Guide e riferimenti

Per informazioni dettagliate sui concetti e sulle funzionalità di questa guida, vedere:

• Traccia MLflow - Osservabilità GenAI : iniziare da qui per informazioni approfondite su MLflow Tracing.
• Integrazioni di traccia MLflow: più di 20 librerie con integrazioni automatiche di traccia.
• Concetti di traccia : comprendere i concetti fondamentali di MLflow Tracing.