Accès programmatique aux traces
Recherchez, lisez et analysez des traces par programmation. Utilisez mlflow.search_traces() pour query les traces stockées dans les tables Unity Catalog, sur le serveur de suivi MLflow ou dans les tables d'inférence, et, pour les traces dans Unity Catalog, query directement les tables Delta à l'aide de SQL. Une fois que vous disposez d'une trace, lisez son modèle d'objet (métadonnées, portées, évaluations et consommation de tokens) pour inspecter ce qui s'est produit. 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 de l'étendue, type, statut et nom du service (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. |
Interroger les tables de traces avec SQL
Lorsque les traces sont stockées dans Unity Catalog, vous pouvez les query avec Databricks SQL en plus du SDK. Le service MLflow stocke les données de segment dans des tables conformes à OpenTelemetry et crée automatiquement des vues Databricks SQL qui transforment ces données au format MLflow. Pour configurer le stockage des traces Unity Catalog, consultez Store OpenTelemetry traces in Unity Catalog.
Databricks recommends querying the views (or using the SDK) rather than the underlying OpenTelemetry tables, whose schemas can change over time. For large trace volumes, view performance can degrade: create a materialized view over the views and update it incrementally, or use the SDK for best performance on recent data.
{table_prefix}_trace_unified
Une vue unifiée de toutes les données de trace, groupées par identifiant de trace. Chaque ligne contient les données brutes de portée ainsi que les métadonnées de trace (tags MLflow, métadonnées et évaluations). Colonnes de niveau supérieur :
trace_id: STRING
client_request_id: STRING
request_time: TIMESTAMP
state: STRING
execution_duration_ms: DOUBLE
request: STRING
response: STRING
trace_metadata: VARIANT
tags: MAP<STRING, STRING>
spans: LIST<STRUCT> # per-span records: name, kind, timing, attributes, status, events, links
assessments: LIST<STRUCT> # feedback and expectation records with source, value, rationale, metadata
La colonne trace_metadata et les champs de la portée attributes sont VARIANT. Lisez-les avec une syntaxe de chemin à deux points et effectuez un cast vers le type dont vous avez besoin, plutôt qu'avec une recherche par clé de map :
SELECT spans[0].attributes:`mlflow.spanInputs`::STRING FROM my_catalog.my_schema.my_prefix_trace_unified
{table_prefix}_trace_metadata
Contient uniquement les tags, métadonnées et évaluations MLflow regroupés par ID de trace. Il est plus performant que la vue unifiée lorsque vous avez besoin des données d’annotation MLflow, mais pas des données de span. Colonnes : trace_id, client_request_id, tags, trace_metadata et assessments (même structure que dans la vue unifiée).
Formats de données d'annotation
Les entités d’annotation MLflow (métadonnées, tags, évaluations et liens d’exécution) sont également stockées dans la table {table_prefix}_otel_annotations, à raison d’une ligne par entité avec un objet annotation_type typé (METADATA, TAG, FEEDBACK, EXPECTATION ou RUN_LINK). La table est en ajout seul (append-only) avec des suppressions logiques (soft deletes) ; par conséquent, dédupliquez lors de la récupération : prenez la dernière ligne par annotation_id (trier par updated_at de manière décroissante) et supprimez les lignes où deleted_at est défini. Les colonnes value et metadata sont au format VARIANT (JSON). Pour les évaluations, les métadonnées fournies par l’utilisateur côtoient les clés MLflow internes (préfixées par mlflow.) ; ignorez les clés internes lors de la lecture des métadonnées utilisateur.
Analysez les performances de la query
Pour diagnostiquer les requêtes lentes, inspectez les profils de requêtes dans le query history du SQL Warehouse : ouvrez la page SQL warehouses , sélectionnez votre warehouse, puis cliquez sur Query history . Recherchez les requêtes ayant MLflow comme source, puis ouvrez une requête pour afficher son profil et vérifier :
- Scheduling time : un temps de scheduling élevé signifie que les queries sont mises en file d'attente en raison d'une charge importante sur le warehouse. Passez à un autre warehouse dans l'interface utilisateur de MLflow ou configurez un autre warehouse dans votre client.
- Performances globales des querys : pour les querys constamment lentes, utilisez un SQL Warehouse plus grand, réduisez les limites sur
trace.timestamp_mset supprimez d'autres prédicats de filtre si possible.
Lire les données de trace
Un Trace MLflow possède deux composants :
Pour consulter le modèle d'objet de trace complet et le schéma, voir Référence du modèle de données de trace.
Propriétés de métadonnées de base
# Primary identifiers
print(f"Trace ID: {trace.info.trace_id}")
print(f"Client Request ID: {trace.info.client_request_id}")
# Status information
print(f"State: {trace.info.state}") # OK, ERROR, IN_PROGRESS
# Request/response previews (truncated)
print(f"Request preview: {trace.info.request_preview}")
print(f"Response preview: {trace.info.response_preview}")
Emplacement de stockage et Experimentation
location = trace.info.trace_location
print(f"Location type: {location.type}")
# Stored in Unity Catalog (recommended)
if location.uc_table_prefix:
print(f"UC location: {location.uc_table_prefix.full_table_prefix}")
# Stored in an MLflow experiment
if location.mlflow_experiment:
print(f"Experiment ID: {trace.info.experiment_id}")
# Stored in a Databricks inference table
if location.inference_table:
print(f"Table: {location.inference_table.full_table_name}")
L'expérimentation constitue le point d'entrée de l'interface utilisateur, quel que soit le backend. Utilisez trace.info.experiment_id pour ouvrir la trace dans l’interface utilisateur de MLflow, même lorsqu’elle est stockée dans Unity Catalog.
Aperçus des requêtes et des réponses
Les propriétés request_preview et response_preview fournissent des résumés tronqués des données de requête et de réponse complètes, ce qui vous permet de comprendre ce qui s'est passé sans charger les charges utiles complètes.
request_preview = trace.info.request_preview
response_preview = trace.info.response_preview
# Full request/response data (see below)
full_request = trace.data.request
full_response = trace.data.response
Propriétés liées au temps
# Timestamps (milliseconds since epoch)
print(f"Start time (ms): {trace.info.request_time}")
print(f"Timestamp (ms): {trace.info.timestamp_ms}") # Alias for request_time
# Duration
print(f"Execution duration (ms): {trace.info.execution_duration}")
# Convert to human-readable format
import datetime
start_time = datetime.datetime.fromtimestamp(trace.info.request_time / 1000)
print(f"Started at: {start_time}")
Tags et métadonnées
# Tags (mutable, can be updated after creation)
for key, value in trace.info.tags.items():
print(f" {key}: {value}")
print(f"Environment: {trace.info.tags.get('environment')}")
# Trace metadata (immutable, set at creation)
for key, value in trace.info.trace_metadata.items():
print(f" {key}: {value}")
Informations sur l'utilisation des jetons
MLflow Tracing peut suivre l’utilisation de jetons des appels de LLM à l’aide des décomptes de jetons renvoyés par les APIs des fournisseurs de LLM.
# Get aggregated token usage (if available)
token_usage = trace.info.token_usage
if token_usage:
print(f"Input tokens: {token_usage.get('input_tokens')}")
print(f"Output tokens: {token_usage.get('output_tokens')}")
print(f"Total tokens: {token_usage.get('total_tokens')}")
La façon dont vous suivez l'utilisation des jetons dépend du fournisseur de LLM :
Scénario | Comment suivre l’utilisation des jetons |
|---|---|
Utilisez le client OpenAI pour vérifier que MLflow Tracing suit automatiquement l'utilisation des jetons. | |
Fournisseurs de LLM dotés d'une prise en charge native de MLflow Tracing | Consultez la page d'intégration du fournisseur sous Intégrations MLflow Tracing pour déterminer si le suivi natif des jetons est pris en charge. |
Fournisseurs sans prise en charge native de MLflow Tracing | Consignez manuellement l'utilisation des jetons à l'aide de |
Surveillez plusieurs Endpoint sur votre plateforme d’IA. | Use AI Gateway usage tracking for logging token usage to system tables across serving endpoints. |
Évaluations
Rechercher des évaluations avec search_assessments():
# Get all assessments
all_assessments = trace.search_assessments()
# Search by name
helpfulness = trace.search_assessments(name="helpfulness")
if helpfulness:
assessment = helpfulness[0]
print(f"Helpfulness: {assessment.value}")
print(f"Source: {assessment.source.source_type} - {assessment.source.source_id}")
print(f"Rationale: {assessment.rationale}")
# Search by type
feedback_only = trace.search_assessments(type="feedback")
expectations_only = trace.search_assessments(type="expectation")
# Search by span ID
span_assessments = trace.search_assessments(span_id=retriever_span.span_id)
# Include overridden assessments
all_including_invalid = trace.search_assessments(all=True)
Accédez aux détails de l’évaluation :
for assessment in trace.info.assessments:
print(f"Assessment: {assessment.name}")
print(f" Type: {type(assessment).__name__}")
print(f" Value: {assessment.value}")
print(f" Source: {assessment.source.source_type.value}")
if assessment.rationale:
print(f" Rationale: {assessment.rationale}")
if assessment.metadata:
print(f" Metadata: {assessment.metadata}")
if assessment.error:
print(f" Error: {assessment.error}")
Travailler avec des spans
Les spans sont les éléments de base des traces, représentant des opérations individuelles ou des unités de travail. La classe Span représente les spans immuables et terminés récupérés à partir des traces.
Accéder aux propriétés de portée
# Access all spans from a trace
spans = trace.data.spans
print(f"Total spans: {len(spans)}")
span = spans[0]
# Basic properties
print(f"Span ID: {span.span_id}")
print(f"Name: {span.name}")
print(f"Type: {span.span_type}")
print(f"Parent ID: {span.parent_id}") # None for root spans
# Timing (nanoseconds)
duration_ms = (span.end_time_ns - span.start_time_ns) / 1_000_000
print(f"Duration: {duration_ms:.2f}ms")
# Status
print(f"Status code: {span.status.status_code}")
# Inputs and outputs
print(f"Inputs: {span.inputs}")
print(f"Outputs: {span.outputs}")
Find specific spans
Utilisez search_spans() pour rechercher des spans correspondant à des critères spécifiques :
import re
from mlflow.entities import SpanType
# Search by exact name
retriever_spans = trace.search_spans(name="retrieve_documents")
# Search by regex pattern
tool_spans = trace.search_spans(name=re.compile(r".*_tool$"))
# Search by span type
chat_spans = trace.search_spans(span_type=SpanType.CHAT_MODEL)
llm_spans = trace.search_spans(span_type="CHAT_MODEL") # String also works
# Search by span ID
specific_span = trace.search_spans(span_id=retriever_spans[0].span_id)
# Combine criteria
tool_fact_check = trace.search_spans(
name="fact_check_tool",
span_type=SpanType.TOOL,
)
Attributs d'étendue
from mlflow.tracing.constant import SpanAttributeKey
chat_span = trace.search_spans(span_type=SpanType.CHAT_MODEL)[0]
# Get all attributes
for key, value in chat_span.attributes.items():
print(f" {key}: {value}")
# Get a specific attribute
specific_attr = chat_span.get_attribute("custom_attribute")
# Access chat-specific attributes using SpanAttributeKey
messages = chat_span.get_attribute(SpanAttributeKey.CHAT_MESSAGES)
tools = chat_span.get_attribute(SpanAttributeKey.CHAT_TOOLS)
# Access per-span token usage
input_tokens = chat_span.get_attribute("llm.token_usage.input_tokens")
output_tokens = chat_span.get_attribute("llm.token_usage.output_tokens")
Données de demande et de réponse
import json
# Get root span request/response
request_json = trace.data.request
response_json = trace.data.response
# Parse JSON strings
if request_json:
request_data = json.loads(request_json)
if response_json:
response_data = json.loads(response_json)
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
Un Databricks SQL warehouse est requis pour lire les traces stockées dans les expérimentations Unity Catalog. Définissez MLFLOW_TRACING_SQL_WAREHOUSE_ID avant d'appeler mlflow.search_traces() ou mlflow.get_trace() sur une expérimentation prise en charge par Unity Catalog. Sans cette variable d'environnement définie, la lecture échoue avec SQL warehouse ID is required for accessing traces in UC tables.. Consultez Store traces in Unity Catalog pour la configuration.
Pour les grands datasets non-Unity Catalog tels que les tables d'inférence, un SQL Warehouse est facultatif et améliore les performances des query.
import os
os.environ['MLFLOW_TRACING_SQL_WAREHOUSE_ID'] = 'fa92bea7022e81fb'
# Required for UC-backed experiments. Improves performance for large non-UC datasets.
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
- Rechercher des problèmes dans les traces – Laissez MLflow détecter les problèmes dans vos traces.
- Référence du modèle de données de trace – Le modèle d’objet de trace complet : spans, types de span et cycle de vie.
- Enrichir les traces : tags, contexte et feedback – Enrichir les traces avec des tags, des métadonnées et du contexte pour une recherche plus riche.
- Créer des jeux de données d’évaluation — Convertissez les traces interrogées en jeux de données de test.
Étape suivante : recueillir les commentaires et créer des datasets