Suivre les agents déployés en dehors de Databricks

MLflow Tracing offre une observabilité complète pour les agents GenAI de production déployés en dehors de Databricks, en capturant les détails d'exécution et en les envoyant à votre workspace Databricks, où vous pouvez les consulter dans l'interface utilisateur de MLflow.

Cette page traite du déploiement d'agents en dehors de Databricks avec le traçage activé. Si votre agent est déployé à l'aide de Databricks Model Serving, consultez Déployer avec des agents personnalisés (recommandé).

Pour les charges de travail de production, Databricks recommande de lier l'Expérimentation qui reçoit ces traces à un emplacement de traces Unity Catalog afin que les traces soient stockées dans des tables Delta avec une rétention illimitée, une gouvernance Unity Catalog et une interrogeabilité SQL. Créez l'expérimentation basée sur Unity Catalog à partir d'un Notebook Databricks, puis référencez-la par nom ou par ID dans les variables d'environnement ci-dessous. Consultez Stocker les traces OpenTelemetry dans Unity Catalog.

Prérequis

Installez les packages requis. Le tableau suivant décrit vos options :

Package	Cas d'usage recommandé	Avantages
mlflow-tracing SDK Python ou SDK TypeScript	Déploiements en production	Dépendances minimales pour des déploiements légers et rapides Performances optimisées pour le traçage à haut volume Axé sur le traçage côté client pour le monitoring de la production
mlflow[databricks]	Développement et expérimentation	Ensemble complet de fonctionnalités d'expérimentation MLflow (IU, LLM-as-a-judge, outils de développement et plus encore) Inclut tous les outils et utilitaires de développement.

Package	Cas d'usage recommandé	Avantages
mlflow-tracing SDK Python ou SDK TypeScript	Déploiements en production	Dépendances minimales pour des déploiements légers et rapides Performances optimisées pour le traçage à haut volume Axé sur le traçage côté client pour le monitoring de la production
mlflow[databricks]	Développement et expérimentation	Ensemble complet de fonctionnalités d'expérimentation MLflow (IU, LLM-as-a-judge, outils de développement et plus encore) Inclut tous les outils et utilitaires de développement.

Python

## Install mlflow-tracing for production deployment tracing
%pip install --upgrade "mlflow-tracing==3.1.0"

## Install mlflow for experimentation and development
%pip install --upgrade "mlflow[databricks]==3.1.0"

Configuration de base du traçage

Configurez le déploiement de votre application pour qu'il se connecte à votre workspace Databricks afin que Databricks puisse collecter les traces.

Configurez les variables d'environnement suivantes :

Bash

# Required: Set the Databricks workspace host and authentication token
export DATABRICKS_HOST="https://your-workspace.cloud.databricks.com"
export DATABRICKS_TOKEN="your-databricks-token"

# Required: Set MLflow Tracking URI to "databricks" to log to Databricks
export MLFLOW_TRACKING_URI=databricks

# Required: Configure the experiment name for organizing traces (must be a workspace path)
export MLFLOW_EXPERIMENT_NAME="/Shared/production-genai-app"

Exemples de déploiement

Une fois les variables d'environnement définies, transmettez-les à votre application. Cliquez sur les onglets pour voir comment transmettre les détails de connexion à différents frameworks.

Docker

Pour les déploiements Docker, transmettez les variables d'environnement via la configuration du conteneur :

Dockerfile

# Dockerfile
FROM python:3.11-slim

# Install dependencies
COPY requirements.txt .
RUN pip install -r requirements.txt

# Copy application code
COPY . /app
WORKDIR /app

# Set default environment variables (can be overridden at runtime)
ENV DATABRICKS_HOST=""
ENV DATABRICKS_TOKEN=""
ENV MLFLOW_TRACKING_URI=databricks
ENV MLFLOW_EXPERIMENT_NAME="/Shared/production-genai-app"

CMD ["python", "app.py"]

Exécutez le conteneur avec des variables d'environnement :

Bash

docker run -d \
  -e DATABRICKS_HOST="https://your-workspace.cloud.databricks.com" \
  -e DATABRICKS_TOKEN="your-databricks-token" \
  -e MLFLOW_TRACKING_URI=databricks \
  -e MLFLOW_EXPERIMENT_NAME="/Shared/production-genai-app" \
  -e APP_VERSION="1.0.0" \
  your-app:latest

Kubernetes

Pour les déploiements Kubernetes, transmettez les variables d'environnement à l'aide de ConfigMaps et de Secrets :

YAML

# configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: databricks-config
data:
  DATABRICKS_HOST: 'https://your-workspace.cloud.databricks.com'
  MLFLOW_TRACKING_URI: databricks
  MLFLOW_EXPERIMENT_NAME: '/Shared/production-genai-app'

---
# secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: databricks-secrets
type: Opaque
stringData:
  DATABRICKS_TOKEN: 'your-databricks-token'

---
# deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: genai-app
spec:
  template:
    spec:
      containers:
        - name: app
          image: your-app:latest
          envFrom:
            - configMapRef:
                name: databricks-config
            - secretRef:
                name: databricks-secrets
          env:
            - name: APP_VERSION
              value: '1.0.0'

Vérifiez la collecte de traces.

Après le déploiement de votre application, vérifiez que les traces sont correctement collectées :

Python

import mlflow
from mlflow.client import MlflowClient
import os

# Ensure MLflow is configured for Databricks
mlflow.set_tracking_uri("databricks")

# Check connection to MLflow server
client = MlflowClient()
try:
    # List recent experiments to verify connectivity
    experiments = client.search_experiments()
    print(f"Connected to MLflow. Found {len(experiments)} experiments.")

    # Check if traces are being logged
    traces = mlflow.search_traces(
        experiment_names=[os.getenv("MLFLOW_EXPERIMENT_NAME", "/Shared/production-genai-app")],
        max_results=5
    )
    print(f"Found {len(traces)} recent traces.")
except Exception as e:
    print(f"Error connecting to MLflow: {e}")
    print(f"Check your authentication and connectivity")

Stocker les traces à long terme avec le monitoring de production

Une fois les Logs enregistrés dans votre expérimentation MLflow, vous pouvez les stocker à long terme dans des tables Delta à l'aide du monitoring de production (en version bêta).

Avantages du Monitoring de production pour le stockage des traces :

• Stockage durable : stocke les traces dans les tables Delta pour une rétention à long terme au-delà du cycle de vie des artefacts d’expérimentation MLflow.
• Aucune limite de taille de trace : Contrairement aux autres méthodes de stockage, Production Monitoring gère les traces de toute taille.
• **Évaluation automatisée de la qualité** : Exécutez les scorers MLflow sur les traces de production pour surveiller en continu la qualité de l'application.
• **Synchronisation rapide** : les traces se synchronisent aux tables Delta environ toutes les 15 minutes.

remarque

Vous pouvez également utiliser des tables d’inférence activées pour AI Gateway pour stocker les traces. Cependant, soyez conscient des limites sur les tailles de traces et les délais de synchronisation.

Ressources supplémentaires

• Afficher les traces dans l'interface utilisateur Databricks MLflow - Affichez les traces dans l'interface utilisateur MLflow.
• Production monitoring – Stockez les traces dans les tables Delta pour une rétention à long terme et évaluez-les automatiquement avec des évaluateurs.
• Ajouter du contexte aux traces – Joignez les identifiants d'utilisateur ou de session, les tags personnalisés ou le feedback utilisateur pour améliorer le debugging et les insights.