Aller au contenu principal
Dernière mise à jour le

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 :

  • Création d’une experimentation MLflow dans votre Databricks Workspace
  • Connexion de votre environnement de développement local à l'Experimentation
  • Exécution d’une application GenAI simple localement sur votre machine
  • Affichage des données de trace upload dans votre workspace Databricks

trace

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 Icône d'informations. en haut à gauche. Vous utilisez ces valeurs dans les étapes ultérieures.

créer une expérience

É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.

  1. Dans votre Expérimentation MLflow, cliquez sur l’icône du menu kebab 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>

Étape 3b (recommandée) : activer le stockage des traces du Unity Catalog​

Les étapes ci-dessus utilisent le backend d’expérimentation géré, qui est le chemin le plus rapide vers votre première trace, mais qui limite le nombre de traces à 100 000 par expérimentation. Pour un stockage évolutif et gouverné sans limite de traces, Databricks recommande de lier votre Experimentation à un emplacement de trace Unity Catalog.

Ajoutez ce qui suit à votre environnement de terminal (parallèlement aux variables de l'étape 3) :

Bash
export MLFLOW_TRACING_SQL_WAREHOUSE_ID=<warehouse-id>

Lorsque vous créez app.py à l’étape 4, ajoutez ce qui suit en haut, avant tout appel de traçage :

Python
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>",
    ),
)

Pour obtenir des détails complets sur la configuration, consultez Store OpenTelemetry traces in Unity Catalog.

Étape 4 : Créez et instrumentez votre application​

Créez votre application GenAI avec le traçage activé. Le code s’exécute entièrement sur votre machine locale et upload les traces vers votre Experimentation MLflow dans le Databricks Workspace.

  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.

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

# 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"

  1. 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-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)

  2. Exécutez l'application :

    Bash
    python app.py

    Ce code s’exécute localement : le fichier app.py se trouve sur votre machine et les variables d’environnement de l’étape 3 indiquent au client MLflow où upload les données de trace. Pour modifier le prompt ou la logique de l’agent, modifiez le fichier local et réexécutez-le.

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​

Lorsqu’une trace apparaît dans l’interface utilisateur Databricks, votre code a été exécuté sur votre ordinateur portable et la trace a été envoyée via HTTPS.

  1. Retournez à l’expérimentation MLflow que vous avez sélectionnée à l’étape 2.
  2. La trace générée apparaît dans l'onglet tab .
  3. Cliquez sur la trace pour afficher ses détails.

Détails de la trace

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 :

Sur cette page