Ajouter du contexte aux traces

L'ajout de contexte aux traces vous permet de suivre les détails d'exécution, d'analyser le comportement de l'utilisateur, de déboguer les problèmes dans différents environnements et de surveiller les performances de l'application. MLflow fournit des champs de métadonnées standardisés pour les types de contexte courants, ainsi que la flexibilité d'ajouter des métadonnées personnalisées spécifiques à votre application.

Exigences

Installez le package approprié pour le traçage en fonction de votre environnement :

Production

Pour les déploiements de production, installez le package mlflow-tracing :

Bash

pip install --upgrade mlflow-tracing

Le package mlflow-tracing est optimisé pour une utilisation en production avec des dépendances minimales et de meilleures caractéristiques de performance.

Development

Pour les environnements de développement, installez le package MLflow complet avec les extras Databricks :

Bash

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

Le package mlflow[databricks] complet inclut toutes les fonctionnalités nécessaires au développement local et à l'expérimentation sur Databricks.

remarque

MLflow 3 est requis pour le suivi du contexte. MLflow 2.x n'est pas pris en charge en raison de limitations de performances et de fonctionnalités manquantes essentielles pour une utilisation en production.

Mise en œuvre

Pour ajouter des métadonnées et des tags aux traces :

1. Tracez votre application. Le plus souvent, vous utiliserez le décorateur @mlflow.trace pour tracer automatiquement les fonctions.
2. Pendant l'exécution de votre application, appelez mlflow.update_current_trace() pour ajouter du contexte aux traces à l'aide de tags ou metadata. Une fois votre application terminée et qu'une Logs est journalisée, tags sont mutables, mais metadata sont immuables dans la trace journalisée.

Python

import mlflow
mlflow.update_current_trace(
    metadata={
        "mlflow.trace.user": user_id,
        "mlflow.trace.session": session_id,
    },
    tags={
        "query_category": "chat",  # Example of a custom tag
    },
)

Pour accéder aux métadonnées et aux tags dans les logs de trace, utilisez les champs metadata et tags du pandas DataFrame renvoyé par mlflow.search_traces(), ou utilisez les champs Trace.info.trace_metadata et Trace.info.tags des objets Trace.

Consultez le Tutoriel : Tracer et analyser les utilisateurs et les environnements pour un tutoriel complet.

Types de métadonnées contextuelles

Les applications de production doivent suivre simultanément plusieurs éléments de contexte. MLflow a des champs de métadonnées standardisés pour capturer des informations contextuelles importantes :

Type de contexte	Cas d’utilisation	Champ MLflow
ID de requête client	Link les traces à des requêtes client spécifiques ou des appels API pour un debugging de bout en bout	TraceInfo parameter client_request_id
ID de session utilisateur	Regroupez les traces des conversations à plusieurs tours, vous permettant d'analyser le flux conversationnel complet.	mlflow.trace.session Métadonnées
ID utilisateur	Associez les traces à des utilisateurs spécifiques pour la personnalisation, l'analyse des cohortes et le debugging spécifique aux utilisateurs	mlflow.trace.user Métadonnées
Données d'environnement	Suivez le contexte de déploiement (environnement, version, région) pour des insights opérationnels et le debugging sur différents déploiements.	métadonnées automatiques et métadonnées personnalisées
Métadonnées personnalisées	Ajoutez des métadonnées spécifiques à l'application pour l'organisation, la recherche et le filtrage des traces	(vos clés de métadonnées)

Type de contexte	Cas d’utilisation	Champ MLflow
ID de requête client	Link les traces à des requêtes client spécifiques ou des appels API pour un debugging de bout en bout	TraceInfo parameter client_request_id
ID de session utilisateur	Regroupez les traces des conversations à plusieurs tours, vous permettant d'analyser le flux conversationnel complet.	mlflow.trace.session Métadonnées
ID utilisateur	Associez les traces à des utilisateurs spécifiques pour la personnalisation, l'analyse des cohortes et le debugging spécifique aux utilisateurs	mlflow.trace.user Métadonnées
Données d'environnement	Suivez le contexte de déploiement (environnement, version, région) pour des insights opérationnels et le debugging sur différents déploiements.	métadonnées automatiques et métadonnées personnalisées
Métadonnées personnalisées	Ajoutez des métadonnées spécifiques à l'application pour l'organisation, la recherche et le filtrage des traces	(vos clés de métadonnées)

Suivre les utilisateurs et les sessions

Le suivi des utilisateurs et des sessions dans votre application GenAI fournit un contexte essentiel pour la compréhension du comportement des utilisateurs, l'analyse des flux de conversation et l'amélioration de la personnalisation.

Pourquoi suivre les utilisateurs et les sessions ?

Le suivi des utilisateurs et des sessions permet une analytique puissante et des améliorations :

1. Analyse du comportement des utilisateurs – Comprendre comment différents utilisateurs interagissent avec votre application
2. Suivi du flux de conversation : Analysez les conversations à plusieurs tours et la rétention de contexte
3. **Insights de personnalisation** - Identifiez des modèles pour améliorer les expériences spécifiques aux utilisateurs
4. Qualité par utilisateur - Suivre les métriques de performance à travers différents segments d'utilisateurs
5. Continuité de session – Maintenez le contexte sur plusieurs interactions

Champs de métadonnées standard pour les utilisateurs et les sessions

MLflow fournit deux champs de métadonnées standard pour le suivi des sessions et des utilisateurs :

• mlflow.trace.user - Associe les traces à des utilisateurs spécifiques
• mlflow.trace.session - Regroupe les traces appartenant aux conversations multi-tours

Lorsque vous utilisez ces champs de métadonnées standard, MLflow active automatiquement le filtrage et le regroupement dans l'interface utilisateur. Contrairement aux tags, les métadonnées ne peuvent pas être mises à jour une fois la trace journalisée, ce qui les rend idéales pour les identifiants immuables comme les identifiants utilisateur et de session.

Suivre les environnements et les versions

Le suivi de l'environnement d'exécution et de la version de votre application GenAI vous permet de déboguer les problèmes de performance et de qualité liés au code. Ces métadonnées permettent :

• **Analyse spécifique à l’environnement** à development travers, staging et production
• Suivi des performances/de la qualité et détection des régressions sur toutes les versions d'applications
• Analyse des causes profondes plus rapide en cas de problèmes.

Pour les métadonnées de déploiement telles que les environnements et les versions, votre application doit généralement extraire les métadonnées des variables d’environnement, plutôt que d’avoir les métadonnées codées en dur dans l’application. Les variables d'environnement simplifient le processus de déploiement. Par exemple :

Python

import mlflow
import os

# In your application logic
mlflow.update_current_trace(
    metadata={
        "mlflow.source.type": os.getenv("APP_ENVIRONMENT", "development"),  # Override default
    }
)

Métadonnées remplies automatiquement

MLflow définit automatiquement certains champs de métadonnées standard en fonction de votre environnement d'exécution.

Vous pouvez remplacer l'un des champs de métadonnées remplis automatiquement en utilisant mlflow.update_current_trace(). Ceci est utile lorsque la détection automatique ne répond pas à vos exigences. Par exemple, remplacez la valeur de l'environnement d'exécution à l'aide de mlflow.update_current_trace(metadata={"mlflow.source.name": "custom_name"}).

Catégorie	Champ de métadonnées	Description	Logique de réglage automatique
Environnement d'exécution	mlflow.source.name	Le point d'entrée ou le script qui a généré la trace.	Renseigné automatiquement avec le nom de fichier pour les scripts Python, le nom de notebook pour les notebooks Databricks/Jupyter.
	mlflow.source.git.commit	Hachage de commit Git.	Si exécuté depuis un repository Git, le hachage du commit est automatiquement détecté et renseigné.
	mlflow.source.git.branch	Git Branch.	S’il est exécuté à partir d’un repository Git, le nom de la Branch actuelle est automatiquement détecté et renseigné.
	mlflow.source.git.repoURL	URL du dépôt Git.	S'il est exécuté à partir d'un repository Git, l'URL du repository est automatiquement détectée et renseignée.
	mlflow.source.type	Capture l'environnement d'exécution.	Automatiquement défini sur NOTEBOOK si vous exécutez dans Jupyter ou un Notebook Databricks, LOCAL si vous exécutez un script Python local, sinon UNKNOWN (détecté automatiquement). Dans votre application déployée, nous vous suggérons de mettre à jour cette variable en fonction de l'environnement, par exemple, PRODUCTION, STAGING, etc.
	mlflow.sourceRun	L'ID de l'exécution source qui a généré la trace.	Défini automatiquement sur l'ID d'exécution de l'exécution source qui a généré la trace.
Version de l'application	metadata.mlflow.modelId	Identifiant du MLflow LoggedModel.	Automatiquement défini sur la valeur de l'ID de modèle dans la variable d'environnement MLFLOW_ACTIVE_MODEL_ID ou sur l'ID de modèle défini via la fonction mlflow.set_active_model().

Catégorie	Champ de métadonnées	Description	Logique de réglage automatique
Environnement d'exécution	mlflow.source.name	Le point d'entrée ou le script qui a généré la trace.	Renseigné automatiquement avec le nom de fichier pour les scripts Python, le nom de notebook pour les notebooks Databricks/Jupyter.
	mlflow.source.git.commit	Hachage de commit Git.	Si exécuté depuis un repository Git, le hachage du commit est automatiquement détecté et renseigné.
	mlflow.source.git.branch	Git Branch.	S’il est exécuté à partir d’un repository Git, le nom de la Branch actuelle est automatiquement détecté et renseigné.
	mlflow.source.git.repoURL	URL du dépôt Git.	S'il est exécuté à partir d'un repository Git, l'URL du repository est automatiquement détectée et renseignée.
	mlflow.source.type	Capture l'environnement d'exécution.	Automatiquement défini sur NOTEBOOK si vous exécutez dans Jupyter ou un Notebook Databricks, LOCAL si vous exécutez un script Python local, sinon UNKNOWN (détecté automatiquement). Dans votre application déployée, nous vous suggérons de mettre à jour cette variable en fonction de l'environnement, par exemple, PRODUCTION, STAGING, etc.
	mlflow.sourceRun	L'ID de l'exécution source qui a généré la trace.	Défini automatiquement sur l'ID d'exécution de l'exécution source qui a généré la trace.
Version de l'application	metadata.mlflow.modelId	Identifiant du MLflow LoggedModel.	Automatiquement défini sur la valeur de l'ID de modèle dans la variable d'environnement MLFLOW_ACTIVE_MODEL_ID ou sur l'ID de modèle défini via la fonction mlflow.set_active_model().

Ajouter des métadonnées personnalisées

Vous utilisez des clés metadata personnalisées pour capturer tout autre contexte spécifique à l'application. Par exemple, vous pourriez vouloir joindre des informations telles que :

• Version de l'application
• ID de déploiement
• Région de déploiement
• Indicateurs de fonctionnalité

Bonnes pratiques

1. Formats d’ID cohérents — Utilisez des formats standardisés pour les ID d’utilisateur et de session dans toute votre application.
2. Limites de session – Définissez des règles claires pour le start et la fin des sessions
3. **Variables d'environnement** – Remplissez les métadonnées à partir de variables d’environnement plutôt que de coder en dur les valeurs
4. **Combine context types** — Suivez le contexte utilisateur, de session et d'environnement ensemble pour une traçabilité complète.
5. Analyse régulière — Configurez des tableaux de bord pour superviser le comportement des utilisateurs, les modèles de session et les performances des versions.
6. Override default thoughtfully — Ne remplacez les métadonnées renseignées automatiquement qu’en cas de besoin

Ressources supplémentaires

• Tutoriel : Tracer et analyser les utilisateurs et les environnements – Voir un exemple complet d'ajout de métadonnées d'utilisateur, de session, d'environnement et de version d'application aux traces.
• Rechercher des traces par programme – En savoir plus sur l'utilisation de mlflow.search_traces().
• Exemples : analytique des traces – Voir des exemples d'analytique des traces.