Démarrer : MLflow Tracing pour la GenAI dans un IDE local

Ce démarrage rapide vous aide à intégrer votre application GenAI à MLflow Tracing si vous utilisez un environnement de développement local tel qu'un IDE (VS Code, PyCharm, Cursor ou autres) ou un environnement de notebook hébergé localement, tel que Jupyter. Si vous utilisez un notebook Databricks, consultez plutôt le guide de démarrage rapide du notebook Databricks.

Ce didacticiel vous guidera à travers :

• Une Expérimentation MLflow pour votre application GenAI
• Votre environnement de développement local connecté à MLflow
• Une simple application GenAI instrumentée avec MLflow Tracing
• Une trace de cette application dans votre expérimentation MLflow

astuce

Ce guide de démarrage rapide utilise le backend d’Expérimentation géré pour le chemin le plus rapide vers votre première trace. Pour un stockage évolutif et régi sans limite de trace, Databricks recommande de stocker les traces dans Unity Catalog. Consultez Stocker les traces OpenTelemetry dans Unity Catalog.

Prérequis

• Accès à un Workspace Databricks.

Étape 1 : Installer MLflow

Installer MLflow avec la connectivité Databricks :

Bash

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

Étape 2 : Créez une nouvelle expérience MLflow

Une expérience MLflow est le conteneur de votre application GenAI. Pour plus d’informations, consultez Experimentations.

1. Ouvrez votre workspace Databricks.
2. Dans la barre latérale gauche, sous IA/ML , cliquez sur Experimentation .
3. En haut de la page Expérimentations, cliquez sur Applications et agents GenAI .
4. Pour obtenir l'ID et le chemin de l'Experimentation, cliquez sur l'icône d'information en haut à gauche. Vous utilisez ces valeurs dans les étapes ultérieures.

Étape 3 : Connecter votre environnement à MLflow.

Les extraits de code suivants montrent comment configurer l'authentification à l'aide d'un jeton d'accès personnel (PAT) Databricks. MLflow fonctionne également avec les autres méthodes d'authentification prises en charge par Databricks.

Use environment variables

1. Dans votre Expérimentation MLflow, cliquez sur l’icône du menu kebab > Enregistrer des traces localement > Générer une clé API .

2. Copiez et exécutez le code généré dans votre terminal.

   Bash

   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>

Use a .env file

1. Dans votre Expérimentation MLflow, cliquez sur l’icône du menu kebab > Enregistrer des traces localement > Générer une clé API .

2. Copiez le code généré dans un fichier .env dans la racine de votre projet.

   Bash

   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. Installez le package python-dotenv.

   Bash

   pip install python-dotenv

4. Chargez les variables d'environnement dans votre code :

   Python

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

Étape 4 : Créez et instrumentez votre application

Créez votre application GenAI avec le traçage activé.

1. Créez un fichier Python nommé app.py dans votre répertoire de projet.

2. Initialisez un client OpenAI pour vous connecter soit à des LLM hébergés par Databricks, soit à des LLM hébergés par OpenAI.

Databricks-hosted LLMs

Utilisez databricks-openai pour obtenir un client OpenAI qui se connecte aux LLM hébergés par Databricks. Sélectionnez un modèle parmi les modèles de fondation disponibles.

Python

import mlflow
from databricks_openai import DatabricksOpenAI

# Enable MLflow's autologging to instrument your application with Tracing
mlflow.openai.autolog()

# Set up MLflow tracking to Databricks
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment("/Shared/docs-demo")

# Create an OpenAI client that is connected to Databricks-hosted LLMs
client = DatabricksOpenAI()

# Select an LLM
model_name = "databricks-claude-sonnet-4"

OpenAI-hosted LLMs

Utilisez le SDK natif OpenAI pour vous connecter aux modèles hébergés par OpenAI. Sélectionnez un modèle parmi les modèles OpenAI disponibles.

Python

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()

# Set up MLflow tracking to Databricks
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment("/Shared/docs-demo")

# Create an OpenAI client connected to OpenAI SDKs
client = openai.OpenAI()

# Select an LLM
model_name = "gpt-4o-mini"

3. Définissez et exécutez votre application :

   Utilisez le décorateur@mlflow.trace, qui facilite le traçage de toute fonction Python, combiné à l'instrumentation automatique OpenAI pour capturer les détails de l'appel au SDK OpenAI.

   Python

   # 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-4o`.
           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. Exécutez l'application :

   Bash

   python app.py

Pour plus de détails sur l'ajout de traçage aux applications, consultez Ajouter des traces aux applications : traçage automatique et manuel et Intégrations MLflow Tracing (plus de 20 intégrations de bibliothèques).

Étape 5 : Visualiser la trace dans MLflow

1. Retournez à l'interface utilisateur de l'Experimentation MLflow.
2. La trace générée apparaît dans l'onglet tab .
3. Cliquez sur la trace pour afficher ses détails.

Comprendre la trace

La nouvelle trace montre :

• Portée racine : représente les entrées de la fonction my_app(...)

  • Child span : Représente la demande de complétion OpenAI.

• Attributs : Contient des métadonnées telles que le nom du modèle, le nombre de jetons et les informations de synchronisation

• Entrées : les messages envoyés au modèle

• Sorties : la réponse reçue du modèle

Même cette trace minimale fournit des informations utiles sur le comportement de votre application, notamment :

• Ce qui a été demandé
• Quelle réponse a été générée
• Combien de temps la requête a-t-elle pris
• Nombre de jetons utilisés (impactant le coût)

Pour les applications plus complexes comme les systèmes RAG ou les agents multi-étapes, MLflow Tracing offre encore plus de valeur en révélant le fonctionnement interne de chaque composant et étape.

Guides et références

Pour plus de détails sur les concepts et les fonctionnalités de ce guide, consultez :

• MLflow Tracing - GenAI observability — Start here for in-depth learning about MLflow Tracing.
• Intégrations MLflow Tracing — Plus de 20 bibliothèques avec des intégrations de traçage automatique.
• Concepts de traçage — Comprenez les principes fondamentaux du MLflow Tracing.