Rechercher les traces par programmation
Recherchez et analysez les traces par programmation en utilisant mlflow.search_traces(). Cette fonction peut query les traces stockées dans les tables Unity Catalog, le serveur de suivi MLflow, ou les tables d'inférence. Utilisez l'argument locations pour spécifier où chercher ; experiment_ids est obsolète. Vous pouvez sélectionner des sous-ensembles de traces à analyser ou pour créer des datasets d'évaluation.
mlflow.search_traces() API
def mlflow.search_traces(
experiment_ids: list[str] | None = None,
filter_string: str | None = None,
max_results: int | None = None,
order_by: list[str] | None = None,
extract_fields: list[str] | None = None,
run_id: str | None = None,
return_type: Literal['pandas', 'list'] | None = None,
model_id: str | None = None,
sql_warehouse_id: str | None = None,
include_spans: bool = True,
locations: list[str] | None = None,
) -> pandas.DataFrame | list[Trace]
mlflow.search_traces() vous permet de filtrer et de sélectionner des données selon quelques dimensions :
- Filtrer par chaîne de query
- Filtrer par emplacements : Expérimentation, exécution, modèle ou schéma Unity Catalog
- Limiter les données : résultats max, inclure ou exclure des intervalles
- Ajuster le format de la valeur de retour : format des données, ordre des données.
search_traces() renvoie soit un DataFrame pandas, soit une liste d'objets Trace, qui peuvent ensuite être analysés plus en détail ou remodelés en datasets d'évaluation. Consultez les détails du schéma de ces types de retour.
Consultez la documentation de l'APImlflow.search_traces() pour plus de détails.
MLflow managé par Databricks et MLflow OSS (outil/solution/technologie/plateforme open source) partagent la plupart de la syntaxe de query de recherche, mais présentent quelques différences au niveau des champs. Consultez Différences avec MLflow open source pour plus de détails.
mlflow.search_traces() paramètres
Catégorie |
| Description | Exemple |
|---|---|---|---|
Filtrer par chaîne de requête |
| Consultez la syntaxe des requêtes de recherche pour connaître les filtres et comparateurs pris en charge. |
|
Filtrer par emplacements |
| Cet argument peut être une liste d'ID d'expérimentation ou des emplacements |
|
| ID d'exécution MLflow. |
| |
| ID du modèle MLflow |
| |
Limiter les données |
| Nombre maximal de traces (lignes) à renvoyer |
|
| Incluez ou excluez les portées des résultats. Les spans incluent les détails de la trace et peuvent rendre les tailles des résultats nettement plus grandes. |
| |
Format de la valeur de retour |
| Consultez la syntaxe et les clés prises en charge. |
|
| Cette fonction peut renvoyer un DataFrame pandas ou une liste d'objets |
| |
Obsolète |
| Utilisez | |
| Sélectionnez plutôt les champs du DataFrame ou des objets de trace renvoyés. | ||
| Utilisez plutôt la variable d’environnement |
Syntaxe de query de recherche
L’argument filter_string utilise un langage de query de type SQL pour filtrer les traces. Les valeurs de chaîne doivent être placées entre guillemets simples (par exemple, « trace.status = 'OK' »), et les valeurs numériques ne doivent pas être citées (par exemple, trace.execution_time_ms > 1000). Combiner les conditions avec AND. L'opérateur OR n'est pas pris en charge.
Filtres et comparateurs pris en charge
Les champs et comparateurs suivants sont pris en charge sur MLflow géré par Databricks.
Les filtres marqués (UC only) ne sont pris en charge que pour les traces MLflow stockées dans Unity Catalog. Consultez Stocker les traces OpenTelemetry dans Unity Catalog.
Type de champ | Champs | Comparateurs | Exemple |
|---|---|---|---|
Statut de la trace |
|
|
|
Tracer les horodatages |
|
|
|
ID de trace |
|
|
|
Champs de chaîne |
|
|
|
**Contenu des requêtes et des réponses** (UC uniquement) |
|
|
|
Nombre de jetons (UC uniquement) |
|
|
|
Invites liées |
|
|
|
**Nom, type et état de la portée** (UC uniquement) |
|
|
|
Attributs d'étendue OTel (UC uniquement) |
|
|
|
Tags |
|
Pour les traces MLflow stockées dans une expérimentation (pas dans Unity Catalog), seuls |
|
Métadonnées |
|
Pour les traces MLflow stockées dans une expérimentation (pas dans Unity Catalog), seuls |
|
Commentaires (UC uniquement) |
|
|
|
Attentes (UC uniquement) |
|
|
|
Différences par rapport à MLflow OSS
La syntaxe des query de recherche sur MLflow géré par Databricks suit de près MLflow OSS, avec les différences suivantes :
Champ | MLflow géré par Databricks | OSS MLflow | Notes |
|---|---|---|---|
| Pris en charge (UC uniquement) | Non pris en charge | Utilisez ces champs pour filtrer le contenu sérialisé des requêtes et des réponses. |
| Pris en charge (UC uniquement) | Non pris en charge | Filtrer les traces par nombre total de jetons. |
| Pris en charge (UC uniquement) | Non pris en charge | Filtrer les traces par les attributs d'étendue OpenTelemetry. |
| Non pris en charge | Pris en charge (uniquement un magasin SQLAlchemy) | OSS expose |
| Non pris en charge | Pris en charge (mappé au tag des prompts liés) | Sur Databricks, utilisez le champ |
| Non pris en charge | Pris en charge | Sur Databricks, utilisez |
| Non pris en charge | Pris en charge | Filtrer les traces liées à un ID de problème spécifique. |
Recherchez les spans OpenTelemetry tiers
Pour rechercher les traces ingérées à partir d'outils OpenTelemetry tiers tels que Langfuse, utilisez plutôt le préfixe span.attributes.*. Consultez Rechercher des traces par attributs d'étendue OTel.
Bonnes pratiques
Arguments par mot-clé
Utilisez toujours des arguments par mot-clé (nommés) avec mlflow.search_traces(). Il permet des arguments positionnels, mais les arguments de la fonction sont en évolution.
Bonnes pratiques : mlflow.search_traces(filter_string="trace.status = 'OK'")
Mauvaise pratique : mlflow.search_traces([], "trace.status = 'OK'")
filter_string pièges
Lorsque vous effectuez une recherche à l'aide de l'argument filter_string pour mlflow.search_traces(), n'oubliez pas de :
- Utilisez les préfixes :
trace.,tag., oumetadata. - Utilisez des guillemets obliques si les noms de balises ou d'attributs contiennent des points :
tag.`mlflow.traceName` - Utilisez uniquement des guillemets simples :
'value'pas"value" - Utilisez le timestamp Unix (millisecondes) pour l'heure :
1749006880539et non des dates - Utiliser UNIQUEMENT ET : pas de prise en charge du OU
Consultez la syntaxe de query de recherche pour la liste complète des champs et opérateurs pris en charge.
Intégration de SQL Warehouse
mlflow.search_traces() peut utiliser en option un SQL Warehouse Databricks pour améliorer les performances sur les grands datasets de trace dans les tables d'inférence ou les tables Unity Catalog. Spécifiez l'ID de votre SQL Warehouse à l'aide de la variable d'environnement MLFLOW_TRACING_SQL_WAREHOUSE_ID.
Exécutez des queries de trace à l'aide d'un warehouse Databricks SQL pour des performances améliorées sur les grands datasets de trace :
import os
os.environ['MLFLOW_TRACING_SQL_WAREHOUSE_ID'] = 'fa92bea7022e81fb'
# Use SQL warehouse for better performance
traces = mlflow.search_traces(
filter_string="trace.status = 'OK'",
locations=['my_catalog.my_schema'],
)
Pagination
mlflow.search_traces() renvoie les résultats en mémoire, ce qui fonctionne bien pour les ensembles de résultats plus petits. Pour gérer les résultats volumineux, utilisez MlflowClient.search_traces() car il prend en charge la pagination.
Ressources supplémentaires
- Didacticiel : Rechercher des traces par programme – Exécutez un ensemble d'exemples simples de
mlflow.search_traces() - Tutoriel : Tracer et analyser les utilisateurs et les environnements - Exécutez un exemple d'ajout de métadonnées de contexte aux traces et d'analyse des résultats
- Exemples : Analyse des traces - Voir une variété d'exemples d'analyse de traces
- Créer des datasets d'évaluation - Convertir les traces interrogées en datasets de test