Concepts de Span

L’objet Span est un composant fondamental du modèle de données de trace. Chaque span capture une seule étape dans une trace, par exemple, un appel LLM, une exécution d'outil ou une opération de récupération.

Les spans sont organisés hiérarchiquement dans une trace pour représenter le flux d’exécution de votre application. Chaque span capture :

Données d'entrée et de sortie
Informations de synchronisation (heures de start et de fin)
Statut (succès ou échec)
Métadonnées et attributs concernant l'opération
Relation avec d'autres étendues (connexions parent-enfant)

Architecture de portée

Schéma d'objet Span

Le schéma MLflow Span est compatible avec la spécification OpenTelemetry. Le schéma comporte 11 propriétés principales :

Propriété	Type	Description
`span_id`	`str`	Identifiant unique pour cette étendue dans la trace
`trace_id`	`str`	Lie le span à sa trace parente.
`parent_id`	`Optional[str]`	Établit la relation parent-enfant. Définir à `None` pour les spans racines.
`name`	`str`	Nom d'étendue défini par l'utilisateur ou généré automatiquement
`start_time_ns`	`int`	Timestamp Unix (nanosecondes) au start de l’intervalle
`end_time_ns`	`int`	Timestamp Unix (en nanosecondes) de fin d'intervalle
`status`	`SpanStatus`	Statut de l'étendue : `OK`, `UNSET`, ou `ERROR` avec une description facultative.
`inputs`	`Optional[Any]`	Données d'entrée entrant dans cette opération
`outputs`	`Optional[Any]`	Données de sortie provenant de cette opération
`attributes`	`Dict[str, Any]`	Paires clé-valeur de métadonnées fournissant des insights comportementaux
`events`	`List[SpanEvent]`	Exceptions au niveau du système et information de la trace de la pile

Propriété	Type	Description
`span_id`	`str`	Identifiant unique pour cette étendue dans la trace
`trace_id`	`str`	Lie le span à sa trace parente.
`parent_id`	`Optional[str]`	Établit la relation parent-enfant. Définir à `None` pour les spans racines.
`name`	`str`	Nom d'étendue défini par l'utilisateur ou généré automatiquement
`start_time_ns`	`int`	Timestamp Unix (nanosecondes) au start de l’intervalle
`end_time_ns`	`int`	Timestamp Unix (en nanosecondes) de fin d'intervalle
`status`	`SpanStatus`	Statut de l'étendue : `OK`, `UNSET`, ou `ERROR` avec une description facultative.
`inputs`	`Optional[Any]`	Données d'entrée entrant dans cette opération
`outputs`	`Optional[Any]`	Données de sortie provenant de cette opération
`attributes`	`Dict[str, Any]`	Paires clé-valeur de métadonnées fournissant des insights comportementaux
`events`	`List[SpanEvent]`	Exceptions au niveau du système et information de la trace de la pile

Pour plus d'informations, consultez la référence de l'API MLflow.

Attributs de portée

Les attributs sont des paires clé-valeur qui fournissent des insight sur les modifications comportementales pour les appels de fonction et de méthode. Ils capturent des métadonnées sur la configuration des opérations et le contexte d’exécution.

Vous pouvez ajouter des attributs spécifiques à la plateforme pour enrichir l'observabilité. Par exemple, vous pouvez ajouter les objets Unity Catalog que la portée a touchés, l'endpoint de mise en service du modèle ou la ressource de compute.

Par exemple, définissez les attributs sur une étendue qui encapsule un appel LLM :

Python
span.set_attributes({
    "ai.model.name": "claude-3-5-sonnet-20250122",
    "ai.model.version": "2025-01-22",
    "ai.model.provider": "anthropic",
    "ai.model.temperature": 0.7,
    "ai.model.max_tokens": 1000,
})

Types d'étendues

MLflow fournit des valeurs prédéfinies SpanType pour les opérations courantes. Pour les cas spécialisés, transmettez une valeur de chaîne personnalisée comme type d'étendue.

Type	Description
`CHAT_MODEL`	Requête vers un modèle de chat (interaction LLM spécialisée)
`CHAIN`	Chaîne d'opérations
`AGENT`	Opération d'agent autonome
`TOOL`	Exécution d'outils (généralement par des agents), comme les query de recherche
`EMBEDDING`	opération d'Intégration de texte
`RETRIEVER`	Opération de récupération de contexte telle que les requêtes de base de données vectorielles
`PARSER`	Opération d'analyse transformant le texte en format structuré
`RERANKER`	Opération de reclassement qui classe les contextes par pertinence
`MEMORY`	Opération de mémoire persistant le contexte dans le stockage à long terme
`UNKNOWN`	Type default utilisé lorsqu'aucun autre type n'est spécifié

Type	Description
`CHAT_MODEL`	Requête vers un modèle de chat (interaction LLM spécialisée)
`CHAIN`	Chaîne d'opérations
`AGENT`	Opération d'agent autonome
`TOOL`	Exécution d'outils (généralement par des agents), comme les query de recherche
`EMBEDDING`	opération d'Intégration de texte
`RETRIEVER`	Opération de récupération de contexte telle que les requêtes de base de données vectorielles
`PARSER`	Opération d'analyse transformant le texte en format structuré
`RERANKER`	Opération de reclassement qui classe les contextes par pertinence
`MEMORY`	Opération de mémoire persistant le contexte dans le stockage à long terme
`UNKNOWN`	Type default utilisé lorsqu'aucun autre type n'est spécifié

Définition des types d'étendue

Pour définir l'SpanType pour une portée, transmettez span_type au décorateur ou au gestionnaire de contexte :

Python
import mlflow
from mlflow.entities import SpanType

# Using a built-in span type
@mlflow.trace(span_type=SpanType.RETRIEVER)
def retrieve_documents(query: str):
    ...

# Using a custom span type
@mlflow.trace(span_type="ROUTER")
def route_request(request):
    ...

# With context manager
with mlflow.start_span(name="process", span_type=SpanType.TOOL) as span:
    span.set_inputs({"data": data})
    result = process_data(data)
    span.set_outputs({"result": result})

Recherche d'étendues par type

Interrogez programmatiquement des étendues à l'aide de MLflow search_spans():

Python
import mlflow
from mlflow.entities import SpanType

trace = mlflow.get_trace("<trace_id>")
retriever_spans = trace.search_spans(span_type=SpanType.RETRIEVER)

Vous pouvez également filtrer par type d'étendue dans l'interface utilisateur MLflow lors de l'affichage des traces.

Spans actifs ou terminés

Une portée active, représentée par LiveSpan, est une portée que MLflow est en train d'écrire. Les spans actifs sont produits par une fonction décorée avec @mlflow.trace ou par un gestionnaire de contexte de span. Une fois la fonction décorée terminée ou le gestionnaire de contexte fermé, la portée est terminée et devient un Span immuable.

Pour modifier l'étendue active, récupérez-la avec mlflow.get_current_active_span().

`RETRIEVER` schéma span

Le type d'étendue RETRIEVER représente les opérations qui récupèrent des données d'un magasin de données, par exemple, l'interrogation de documents à partir d'un magasin vectoriel. Les étendues RETRIEVER utilisent un schéma de sortie fixe, ce qui débloque des fonctionnalités de rendu d'interface utilisateur et d'évaluation plus riches dans MLflow. La sortie doit être une liste de documents, où chaque document est un dictionnaire avec :

page_content (str) : Contenu textuel du fragment de document récupéré
metadata (Optional[Dict[str, Any]]) : Métadonnées supplémentaires, y compris :
- doc_uri (str) : L'URI de la source du document. Lorsque vous utilisez AI Search sur Databricks, vous pouvez enregistrer les chemins de volume Unity Catalog dans doc_uri pour un suivi complet de la lignée.
- chunk_id (str) : Indiquez si le document fait partie d'un document fragmenté plus large.
id (Optional[str]) : Identifiant unique pour le fragment de document.

Utilisez l'entité MLflow Document pour construire cette structure de sortie.

Exemple d'implémentation :

Python
import mlflow
from mlflow.entities import SpanType, Document

def search_store(query: str) -> list[tuple[str, str]]:
    # Simulate retrieving documents (content, doc_uri pairs) from a vector database.
    return [
        ("MLflow Tracing helps debug GenAI applications...", "docs/mlflow/tracing_intro.md"),
        ("Key components of a trace include spans...", "docs/mlflow/tracing_datamodel.md"),
        ("MLflow provides automatic instrumentation...", "docs/mlflow/auto_trace.md"),
    ]

@mlflow.trace(span_type=SpanType.RETRIEVER)
def retrieve_relevant_documents(query: str):
    docs = search_store(query)
    span = mlflow.get_current_active_span()

    # Set outputs in the expected format
    outputs = [
        Document(page_content=doc, metadata={&quot;doc_uri&quot;: uri})
        for doc, uri in docs
    ]
    span.set_outputs(outputs)

    # Return the raw tuples for the caller; the trace records the structured Document objects.
    return docs

# Usage
user_query = "MLflow Tracing benefits"
retrieved_docs = retrieve_relevant_documents(user_query)

Ressources supplémentaires

Concepts de traçage – Comprendre les concepts et la structure au niveau de la trace.
Commencer : MLflow Tracing pour GenAI (Databricks Notebook) - Obtenez une expérience pratique avec le traçage dans un Notebook.

Schéma d'objet Span​

Attributs de portée​

Types d'étendues​

Définition des types d'étendue​

Recherche d'étendues par type​

Spans actifs ou terminés​

RETRIEVER schéma span​

Ressources supplémentaires​