Suivi de version et `LoggedModel`

Le suivi de version MLflow vous permet de créer des représentations versionnées de vos applications GenAI. Le versionnage offre les avantages suivants :

Reproductibilité et auditabilité. Chaque application ou version de modèle renvoie à son code spécifique, tel que le hachage de commit Git, et à sa configuration.
Aide au debugging. Comparez le code, les configurations, les résultats d’évaluation et les traces entre les versions de modèle.
Évaluation systématique. Utilisez mlflow.genai.evaluate() pour comparer côte à côte des métriques telles que les scores de qualité, le coût et la latence.

Pour créer une version d'application ou de modèle, vous utilisez un LoggedModel. Dans MLflow, un LoggedModel représente une version spécifique de votre application GenAI. Chaque état distinct de votre application que vous souhaitez évaluer, déployer ou auquel vous souhaitez vous référer peut être capturé en tant que nouveau LoggedModel.

Cette page est une introduction au suivi de version MLflow. Pour un tutoriel étape par étape, consultez Suivre les versions d'applications basées sur Git avec MLflow.

Méthodes de suivi des versions

MLflow propose deux méthodes pour le suivi des versions :

mlflow.set_active_model(): Suivi de version simple. Crée automatiquement un LoggedModel si nécessaire et lie les traces ultérieures.
mlflow.create_external_model(): contrôle total sur la création de versions. Vous pouvez fournir des métadonnées, des paramètres et des tags étendus.

`set_active_model`

Lie les traces à une version LoggedModel spécifique. Si un modèle portant le nom indiqué n'existe pas, il en crée un automatiquement.

Python
def set_active_model(
    name: Optional[str] = None,
    model_id: Optional[str] = None
) -> ActiveModel:

parameter

parameter	Type	Obligatoire	Description
`name`	`str \| None`	Non*	Nom du modèle. Si le modèle n'existe pas, en crée un nouveau
`model_id`	`str \| None`	Non*	ID généré d’un LoggedModel existant, qui start avec `m-`

parameter	Type	Obligatoire	Description
`name`	`str \| None`	Non*	Nom du modèle. Si le modèle n'existe pas, en crée un nouveau
`model_id`	`str \| None`	Non*	ID généré d’un LoggedModel existant, qui start avec `m-`

*Vous devez fournir name ou model_id.

Valeur de retour

Renvoie un objet ActiveModel (sous-classe de LoggedModel) pouvant être utilisé comme gestionnaire de contexte.

Exemple d’utilisation

Python
import mlflow

# Simple usage - creates model if it doesn't exist
mlflow.set_active_model(name="my-agent-v1.0")

# Use as context manager
with mlflow.set_active_model(name="my-agent-v2.0") as model:
    print(f"Model ID: {model.model_id}")
    # Traces within this context are linked to this model

# Use with existing model ID
mlflow.set_active_model(model_id="m-9dcd3a2b8e764e5bb4e8a89b4e4c6f21")

`create_external_model`

Crée un nouveau LoggedModel pour les applications dont le code et les artefacts sont stockés en dehors de MLflow (par exemple, dans Git).

Python
def create_external_model(
    name: Optional[str] = None,
    source_run_id: Optional[str] = None,
    tags: Optional[dict[str, str]] = None,
    params: Optional[dict[str, str]] = None,
    model_type: Optional[str] = None,
    experiment_id: Optional[str] = None,
) -> LoggedModel:

parameter

parameter	Type	Obligatoire	Description
`name`	`str \| None`	Non	Nom du modèle. S'il n'est pas spécifié, un nom aléatoire est généré
`source_run_id`	`str \| None`	Non	ID de l'exécution associée. Utilise par défaut l'ID d'exécution actif si vous êtes dans un contexte d'exécution
`tags`	`dict[str, str] \| None`	Non	Paires clé-valeur pour l'organisation et le filtrage
`params`	`dict[str, str] \| None`	Non	Paramètres et configuration du modèle (doivent être des chaînes)
`model_type`	`str \| None`	Non	Type défini par l'utilisateur pour la catégorisation (p. ex. « agent », « rag-system »)
`experiment_id`	`str \| None`	Non	Expérimentation à associer. Utilise l'expérimentation active si non spécifié

parameter	Type	Obligatoire	Description
`name`	`str \| None`	Non	Nom du modèle. S'il n'est pas spécifié, un nom aléatoire est généré
`source_run_id`	`str \| None`	Non	ID de l'exécution associée. Utilise par défaut l'ID d'exécution actif si vous êtes dans un contexte d'exécution
`tags`	`dict[str, str] \| None`	Non	Paires clé-valeur pour l'organisation et le filtrage
`params`	`dict[str, str] \| None`	Non	Paramètres et configuration du modèle (doivent être des chaînes)
`model_type`	`str \| None`	Non	Type défini par l'utilisateur pour la catégorisation (p. ex. « agent », « rag-system »)
`experiment_id`	`str \| None`	Non	Expérimentation à associer. Utilise l'expérimentation active si non spécifié

Valeur de retour

Renvoie un objet LoggedModel avec :

model_id: identifiant unique pour le modèle
name: Le nom de modèle attribué
experiment_id: ID d’Experimentation associé
creation_timestamp: date de création du modèle
status: statut du modèle (toujours « READY » pour les modèles externes)
tags: dictionnaire de tags
params: Dictionnaire de parameters

Exemple d’utilisation

Python
import mlflow

# Basic usage
model = mlflow.create_external_model(
    name="customer-support-agent-v1.0"
)

# With full metadata
model = mlflow.create_external_model(
    name="recommendation-engine-v2.1",
    model_type="rag-agent",
    params={
        &quot;llm_model&quot;: &quot;gpt-4&quot;,
        &quot;temperature&quot;: &quot;0.7&quot;,
        &quot;max_tokens&quot;: &quot;1000&quot;,
        &quot;retrieval_k&quot;: &quot;5&quot;
    },
    tags={
        &quot;team&quot;: &quot;ml-platform&quot;,
        &quot;environment&quot;: &quot;staging&quot;,
        &quot;git_commit&quot;: &quot;abc123def&quot;
    }
)

# Within a run context
with mlflow.start_run() as run:
    model = mlflow.create_external_model(
        name="my-agent-v3.0",
        source_run_id=run.info.run_id
    )

Classe LoggedModel

La classe LoggedModel représente un modèle versionné dans MLflow.

Propriétés

Propriété	Type	Description
`model_id`	`str`	Identifiant unique pour le modèle
`name`	`str`	Nom du modèle
`experiment_id`	`str`	ID d'expérience associé
`creation_timestamp`	`int`	Heure de création (millisecondes depuis l’époque)
`last_updated_timestamp`	`int`	Heure de dernière mise à jour (millisecondes depuis l'époque)
`model_type`	`str \| None`	Type de modèle défini par l’utilisateur
`source_run_id`	`str \| None`	ID de l'exécution (run) qui a créé ce modèle
`status`	`LoggedModelStatus`	Statut du modèle (READY, FAILED_REGISTRATION, etc.)
`tags`	`dict[str, str]`	Dictionnaire de tags
`params`	`dict[str, str]`	Dictionnaire de parameters
`model_uri`	`str`	URI pour référencer le modèle (par exemple, « models:/model_id »)

Propriété	Type	Description
`model_id`	`str`	Identifiant unique pour le modèle
`name`	`str`	Nom du modèle
`experiment_id`	`str`	ID d'expérience associé
`creation_timestamp`	`int`	Heure de création (millisecondes depuis l’époque)
`last_updated_timestamp`	`int`	Heure de dernière mise à jour (millisecondes depuis l'époque)
`model_type`	`str \| None`	Type de modèle défini par l’utilisateur
`source_run_id`	`str \| None`	ID de l'exécution (run) qui a créé ce modèle
`status`	`LoggedModelStatus`	Statut du modèle (READY, FAILED_REGISTRATION, etc.)
`tags`	`dict[str, str]`	Dictionnaire de tags
`params`	`dict[str, str]`	Dictionnaire de parameters
`model_uri`	`str`	URI pour référencer le modèle (par exemple, « models:/model_id »)

Modèles courants

Suivi de version avec intégration Git

Python
import mlflow
import subprocess

# Get current git commit
git_commit = subprocess.check_output(["git", "rev-parse", "HEAD"]).decode().strip()[:8]

# Create versioned model name
model_name = f"my-app-git-{git_commit}"

# Track the version
model = mlflow.create_external_model(
    name=model_name,
    tags={&quot;git_commit&quot;: git_commit}
)

Lier les traces aux versions

Python
import mlflow

# Set active model - all subsequent traces will be linked
mlflow.set_active_model(name="my-agent-v1.0")

# Your application code with tracing
@mlflow.trace
def process_request(query: str):
    # This trace will be automatically linked to my-agent-v1.0
    return f"Processing: {query}"

# Run the application
result = process_request("Hello world")

Déploiement en production

En production, utilisez des variables d'environnement au lieu d'appeler set_active_model(). Contrairement à set_active_model(), cette variable n'accepte que l'ID LoggedModel généré, qui start par m-. Lisez-le à partir de model.model_id après avoir créé le LoggedModel, et conservez le nom du modèle uniquement pour l'affichage et la création :

Bash
# Set the generated LoggedModel ID that traces should be linked to
export MLFLOW_ACTIVE_MODEL_ID="m-9dcd3a2b8e764e5bb4e8a89b4e4c6f21"

Pour des exemples de déploiement et des requêtes de trace spécifiques à une version, consultez Link Production Traces to App Versions.

Bonnes pratiques

Utilisez le versionnage sémantique dans les noms de modèles (par exemple, « app-v1.2.3 »)
Inclure les commits git dans les tags pour la traçabilité
Les paramètres doivent être des chaînes - convertissez les nombres et les booléens
Utilisez model_type pour catégoriser des applications similaires
Définissez le modèle actif avant le traçage pour garantir une liaison correcte

Problèmes courants

Types de parameter non valides :

Python
# Error: Parameters must be strings
# Wrong:
params = {"temperature": 0.7, "max_tokens": 1000}

# Correct:
params = {"temperature": "0.7", "max_tokens": "1000"}

Ressources supplémentaires

Suivre les versions d’application - Guide étape par étape pour versionner votre application GenAI
Link production traces - Connectez les données de production aux versions de l’application
Package pour le déploiement - Déployez des applications versionnées vers Model Serving

Méthodes de suivi des versions​

set_active_model​

parameter​

Valeur de retour​

Exemple d’utilisation​

create_external_model​

parameter​

Valeur de retour​

Exemple d’utilisation​

Classe LoggedModel​

Propriétés​

Modèles courants​

Suivi de version avec intégration Git​

Lier les traces aux versions​

Déploiement en production​

Bonnes pratiques​

Problèmes courants​

Ressources supplémentaires​

Méthodes de suivi des versions

`set_active_model`

parameter

Valeur de retour

Exemple d’utilisation

`create_external_model`

parameter

Valeur de retour

Exemple d’utilisation

Classe LoggedModel

Propriétés

Modèles courants

Suivi de version avec intégration Git

Lier les traces aux versions

Déploiement en production

Bonnes pratiques

Problèmes courants

Ressources supplémentaires