Créer et gérer des sessions d’étiquetage

Les sessions d’étiquetage offrent un moyen structuré de recueillir les retours d’experts du domaine sur le comportement de vos applications GenAI. Une session d’étiquetage est un type spécial d’exécution MLflow qui contient un ensemble spécifique de traces que vous souhaitez que les experts du domaine examinent à l’aide de l’application d’examen MLflow.

L’objectif d’une session d’étiquetage est de recueillir des évaluations (étiquettes) générées par l’homme sur les traces MLflow existantes. Vous pouvez capturer soit les données Feedback soit les données Expectation, qui peuvent ensuite être utilisées pour améliorer votre application GenAI grâce à une évaluation systématique. Pour plus d’information sur la collecte des évaluations pendant le développement d’applications, consultez Étiqueter pendant le développement.

Les sessions d'étiquetage apparaissent dans la tab Évaluations de l'interface utilisateur MLflow. Puisque les sessions d'étiquetage sont enregistrées en tant qu'exécutions MLflow, vous pouvez également accéder aux traces et aux évaluations associées à l'aide de l'API MLflow mlflow.search_runs().

Fonctionnement des sessions d'étiquetage

Une session d’étiquetage agit comme un conteneur pour les traces et leurs étiquettes associées, permettant une collecte systématique de commentaires qui peut orienter les flux de travail d'évaluation et d'amélioration. Lorsque vous créez une session d’étiquetage, vous définissez :

Nom : Un identifiant descriptif pour la session.
Utilisateurs attribués : experts du domaine qui fourniront des étiquettes.
Agent : (Facultatif) L'application GenAI pour générer des réponses si nécessaire.
Schémas d'étiquetage : Les questions et le format pour la collecte des retours. Vous pouvez utiliser des schémas intégrés (EXPECTED_FACTS, EXPECTED_RESPONSE, GUIDELINES) ou en créer des personnalisés. Consultez Créer et gérer les schémas d'étiquetage pour des informations détaillées sur la création et l'utilisation des schémas.
Chat multi-tours : Prise en charge de l'étiquetage de type conversationnel.

remarque

Le champ optionnel Agent connecte une session d'étiquetage à l'interface utilisateur de Chat de l'application de révision pour des tests interactifs. L'interface utilisateur de discussion nécessite qu'un agent soit déployé sur un Endpoint Model Serving et ne prend pas actuellement en charge les agents déployés sur Databricks Apps. L’examen et l’étiquetage des traces existantes fonctionnent, quelle que soit la manière dont votre agent est déployé.

Pour plus de détails sur l’API LabelingSession, consultez mlflow.genai.LabelingSession.

Créer des sessions d'étiquetage

Vous pouvez créer des sessions d'étiquetage à l'aide de l'interface utilisateur ou de l'API.

important

Les noms de session peuvent ne pas être uniques. Utilisez l'ID d'exécution MLflow (session.mlflow_run_id) pour stocker et référencer les sessions.

Créer des sessions à l'aide de l'interface utilisateur

Pour créer une session d'étiquetage dans l'interface utilisateur MLflow :

Dans le Workspace Databricks, dans la barre latérale gauche, cliquez sur Expériences .
Cliquez sur le nom de votre Experimentation pour l'ouvrir.
Cliquez sur Sessions d’étiquetage dans la barre latérale.
Cliquez sur Créer une session . La boîte de dialogue Créer une session d'étiquetage apparaît.
Saisissez un nom pour la session.

Vous pouvez également spécifier facultativement un dataset d'évaluation ou sélectionner des schémas d'étiquetage.

La section Aperçu des étiquettes vous permet de voir comment les questions apparaissent pour les relecteurs.
Lorsque vous êtes prêt, cliquez sur Créer une session . La nouvelle session apparaît dans la liste sur le côté gauche de la page.
Pour partager la session avec les relecteurs, cliquez sur le nom de la session dans la liste, puis cliquez sur **Partager** en haut à droite.
Saisissez une adresse e-mail pour chaque réviseur et cliquez sur Enregistrer . Les réviseurs sont informés et ont accès à l'application de révision.

Afficher les sessions à l'aide de l'interface utilisateur

Pour afficher les commentaires de l'examinateur pour une session, cliquez sur le nom de la session dans la liste, puis cliquez sur la demande.

Affichez les commentaires du réviseur.

Une notification apparaît affichant les évaluations de trace et de réviseur. Pour afficher les contributions des relecteurs, cliquez sur Évaluations en haut à droite.

Afficher les évaluations des évaluateurs.

Créez des sessions à l'aide de l'API

Pour créer des sessions avec un contrôle programmatique complet sur toutes les options de configuration, utilisez l’API MLflow mlflow.genai.labeling.create_labeling_session().

Créer une session de base

Python
import mlflow.genai.labeling as labeling
import mlflow.genai.label_schemas as schemas

# Create a simple labeling session with built-in schemas
session = labeling.create_labeling_session(
    name="customer_service_review_jan_2024",
    assigned_users=["alice@company.com", "bob@company.com"],
    label_schemas=[schemas.EXPECTED_FACTS]  # Required: at least one schema needed
)

print(f"Created session: {session.name}")
print(f"Session ID: {session.labeling_session_id}")

Créez une session à l'aide de schémas d'étiquetage personnalisés

Python
import mlflow.genai.labeling as labeling
import mlflow.genai.label_schemas as schemas

# Create custom schemas first
quality_schema = schemas.create_label_schema(
    name="response_quality",
    type="feedback",
    title="Rate the response quality",
    input=schemas.InputCategorical(options=["Poor", "Fair", "Good", "Excellent"]),
    overwrite=True,
)

# Create session using the schemas
session = labeling.create_labeling_session(
    name="quality_assessment_session",
    assigned_users=["expert@company.com"],
    label_schemas=["response_quality", schemas.EXPECTED_FACTS],
)

Gérer les sessions d'étiquetage

Pour les détails de l'API, consultez mlflow.genai.get_labeling_sessions et mlflow.genai.delete_labeling_sessions.

Récupérer les sessions

Python
import mlflow.genai.labeling as labeling

# Get all labeling sessions
all_sessions = labeling.get_labeling_sessions()
print(f"Found {len(all_sessions)} sessions")

for session in all_sessions:
    print(f"- {session.name} (ID: {session.labeling_session_id})")
    print(f"  Assigned users: {session.assigned_users}")

Obtenir une session spécifique

Python
import mlflow
import mlflow.genai.labeling as labeling
import pandas as pd

# Get all labeling sessions first
all_sessions = labeling.get_labeling_sessions()

# Find session by name (note: names may not be unique)
target_session = None
for session in all_sessions:
    if session.name == "customer_service_review_jan_2024":
        target_session = session
        break

if target_session:
    print(f"Session name: {target_session.name}")
    print(f"Experiment ID: {target_session.experiment_id}")
    print(f"MLflow Run ID: {target_session.mlflow_run_id}")
    print(f"Label schemas: {target_session.label_schemas}")
else:
    print("Session not found")

# Alternative: Get session by MLflow Run ID (if you know it)
run_id = "your_labeling_session_run_id"
run = mlflow.search_runs(
    experiment_ids=["your_experiment_id"],
    filter_string=f"tags.mlflow.runName LIKE '%labeling_session%' AND attribute.run_id = '{run_id}'"
).iloc[0]

print(f"Found labeling session run: {run['run_id']}")
print(f"Session name: {run['tags.mlflow.runName']}")

Supprimer les sessions

Python
import mlflow.genai.labeling as labeling

# Find the session to delete by name
all_sessions = labeling.get_labeling_sessions()
session_to_delete = None
for session in all_sessions:
    if session.name == "customer_service_review_jan_2024":
        session_to_delete = session
        break

if session_to_delete:
    # Delete the session (removes from Review App)
    review_app = labeling.delete_labeling_session(session_to_delete)
    print(f"Deleted session: {session_to_delete.name}")
else:
    print("Session not found")

Ajouter des traces aux sessions

Après avoir créé une session, vous devez y ajouter des traces pour un examen par des experts. Vous pouvez le faire en utilisant l'interface utilisateur ou l'API add_traces(). Pour les détails de l'API, consultez mlflow.genai.LabelingSession.add_traces.

remarque

Pour plus de détails sur la manière dont les traces sont rendues et affichées aux étiqueteurs dans l’interface utilisateur de l’application de révision, y compris la façon dont les différents types de données (dictionnaires, messages OpenAI, appels d’outils) sont présentés, consultez Rendu du contenu de l’application de révision.

Ajouter des traces à l'aide de l'interface utilisateur

Pour ajouter des traces à une session d'étiquetage :

Dans le Workspace Databricks, dans la barre latérale gauche, cliquez sur Expériences .
Cliquez sur le nom de votre Experimentation pour l'ouvrir.
Cliquez sur Traces dans la barre latérale.
Sélectionnez les traces que vous souhaitez ajouter en cochant la case à gauche de l'identifiant de trace.
Dans le menu déroulant **Actions**, sélectionnez **Ajouter à la session d’étiquetage**.

Une boîte de dialogue apparaît, affichant les sessions d'étiquetage existantes pour l'Experimentation.
Dans la boîte de dialogue, cliquez sur Exporter à côté de la session d'étiquetage à laquelle vous souhaitez ajouter les traces, puis cliquez sur Terminé .

Ajouter des traces à partir des résultats de recherche

Initialisez un client OpenAI pour vous connecter soit à des LLM hébergés par Databricks, soit à des LLM hébergés par OpenAI.

Databricks-hosted LLMs
OpenAI-hosted LLMs

Utilisez databricks-openai pour obtenir un client OpenAI qui se connecte aux LLM hébergés par Databricks. Sélectionnez un modèle parmi les modèles de fondation disponibles.

Python
import mlflow
from databricks_openai import DatabricksOpenAI

# Enable MLflow's autologging to instrument your application with Tracing
mlflow.openai.autolog()

# Set up MLflow tracking to Databricks
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment("/Shared/docs-demo")

# Create an OpenAI client that is connected to Databricks-hosted LLMs
client = DatabricksOpenAI()

# Select an LLM
model_name = "databricks-claude-sonnet-4"

Utilisez le SDK natif OpenAI pour vous connecter aux modèles hébergés par OpenAI. Sélectionnez un modèle parmi les modèles OpenAI disponibles.

Python
import mlflow
import os
import openai

# Ensure your OPENAI_API_KEY is set in your environment
# os.environ["OPENAI_API_KEY"] = "<YOUR_API_KEY>" # Uncomment and set if not globally configured

# Enable auto-tracing for OpenAI
mlflow.openai.autolog()

# Set up MLflow tracking to Databricks
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment("/Shared/docs-demo")

# Create an OpenAI client connected to OpenAI SDKs
client = openai.OpenAI()

# Select an LLM
model_name = "gpt-4o-mini"

Créez des exemples de traces et ajoutez-les à une session d’étiquetage :

Python
import mlflow.genai.labeling as labeling


# First, create some sample traces with a simple app
@mlflow.trace
def support_app(question: str):
 """Simple support app that generates responses"""
 mlflow.update_current_trace(tags={&quot;test_tag&quot;: &quot;C001&quot;})
 response = client.chat.completions.create(
     model=model_name,  # This example uses Databricks hosted Claude 3.5 Sonnet. If you provide your own OpenAI credentials, replace with a valid OpenAI model e.g., gpt-4o, etc.
     messages=[
         {"role": "system", "content": "You are a helpful customer support agent."},
         {"role": "user", "content": question},
     ],
 )
 return {"response": response.choices[0].message.content}

# Generate some sample traces
with mlflow.start_run():
 # Create traces with negative feedback for demonstration
 support_app("My order is delayed")

 support_app("I can't log into my account")

# Now search for traces to label
traces_df = mlflow.search_traces(
 filter_string="tags.test_tag = 'C001'", max_results=50
)

# Create session and add traces
session = labeling.create_labeling_session(
 name="negative_feedback_review",
 assigned_users=["quality_expert@company.com"],
 label_schemas=["response_quality", "expected_facts"]
)

# Add traces from search results
session.add_traces(traces_df)
print(f"Added {len(traces_df)} traces to session")

Ajouter des objets de trace individuels

Initialisez un client OpenAI pour vous connecter soit à des LLM hébergés par Databricks, soit à des LLM hébergés par OpenAI.

Databricks-hosted LLMs
OpenAI-hosted LLMs

Utilisez databricks-openai pour obtenir un client OpenAI qui se connecte aux LLM hébergés par Databricks. Sélectionnez un modèle parmi les modèles de fondation disponibles.

Python
import mlflow
from databricks_openai import DatabricksOpenAI

# Enable MLflow's autologging to instrument your application with Tracing
mlflow.openai.autolog()

# Set up MLflow tracking to Databricks
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment("/Shared/docs-demo")

# Create an OpenAI client that is connected to Databricks-hosted LLMs
client = DatabricksOpenAI()

# Select an LLM
model_name = "databricks-claude-sonnet-4"

Utilisez le SDK natif OpenAI pour vous connecter aux modèles hébergés par OpenAI. Sélectionnez un modèle parmi les modèles OpenAI disponibles.

Python
import mlflow
import os
import openai

# Ensure your OPENAI_API_KEY is set in your environment
# os.environ["OPENAI_API_KEY"] = "<YOUR_API_KEY>" # Uncomment and set if not globally configured

# Enable auto-tracing for OpenAI
mlflow.openai.autolog()

# Set up MLflow tracking to Databricks
mlflow.set_tracking_uri("databricks")
mlflow.set_experiment("/Shared/docs-demo")

# Create an OpenAI client connected to OpenAI SDKs
client = openai.OpenAI()

# Select an LLM
model_name = "gpt-4o-mini"

Créer et ajouter des objets de trace individuels à une session d'étiquetage :

Python
import mlflow.genai.labeling as labeling


# Set up the app to generate traces
@mlflow.trace
def support_app(question: str):
 """Simple support app that generates responses"""
 mlflow.update_current_trace(tags={&quot;test_tag&quot;: &quot;C001&quot;})
 response = client.chat.completions.create(
     model=model_name,  # This example uses Databricks hosted Claude 3.5 Sonnet. If you provide your own OpenAI credentials, replace with a valid OpenAI model e.g., gpt-4o, etc.
     messages=[
         {"role": "system", "content": "You are a helpful customer support agent."},
         {"role": "user", "content": question},
     ],
 )
 return {"response": response.choices[0].message.content}

# Generate specific traces for edge cases
with mlflow.start_run() as run:
 # Create traces for specific scenarios
 support_app("What's your refund policy?")
 trace_id_1 = mlflow.get_last_active_trace_id()

 support_app("How do I cancel my subscription?")
 trace_id_2 = mlflow.get_last_active_trace_id()

 support_app("The website is down")
 trace_id_3 = mlflow.get_last_active_trace_id()

# Get the trace objects
trace1 = mlflow.get_trace(trace_id_1)
trace2 = mlflow.get_trace(trace_id_2)
trace3 = mlflow.get_trace(trace_id_3)

# Create session and add traces
session = labeling.create_labeling_session(
 name="negative_feedback_review",
 assigned_users=["name@databricks.com"],
 label_schemas=["response_quality", schemas.EXPECTED_FACTS],
)

# Add individual traces
session.add_traces([trace1, trace2, trace3])

Récupérer les réponses de feedback

Une fois que les réviseurs ont terminé une session d'étiquetage, MLflow stocke leurs réponses en tant que Assessments sur les traces de la session. Vous pouvez les récupérer dans l'interface utilisateur ou avec l'API MLflow.

Ouvrez l'interface utilisateur Expérimentation , cliquez sur la session d'étiquetage, puis cliquez sur la requête. Cliquez sur Évaluations en haut à droite pour afficher les réponses de chaque évaluateur. Pour les captures d'écran, consultez Afficher les sessions à l'aide de l'interface utilisateur.

Utilisez mlflow.search_traces() avec le mlflow_run_id de la session. Le DataFrame retourné inclut une colonne assessments contenant les étiquettes de chaque réviseur.

Python
import mlflow

traces = mlflow.search_traces(run_id=session.mlflow_run_id)
print(traces[["trace_id", "assessments"]])

Pour les détails de l'API, consultez mlflow.search_traces.

Gérer les utilisateurs attribués

Exigences d'accès des utilisateurs

Tout utilisateur du compte Databricks peut être attribué à une session d'étiquetage, qu'il ait ou non accès au Workspace. Cependant, accorder une autorisation à un utilisateur pour une session d'étiquetage lui donnera accès à l'Experimentation MLflow de la session d'étiquetage.

Configurer les autorisations pour les utilisateurs

Pour les utilisateurs qui n'ont pas accès au Workspace, un administrateur de compte utilise le provisionnement SCIM au niveau du compte pour synchroniser automatiquement les utilisateurs et les groupes de votre fournisseur d'identité vers votre compte Databricks. Vous pouvez également enregistrer manuellement ces utilisateurs et groupes pour leur donner accès lorsque vous configurez des identités dans Databricks. Consulter la Gestion des utilisateurs et des groupes.
Pour les utilisateurs qui ont déjà accès au Workspace qui contient l’application d’examen, aucune configuration supplémentaire n’est requise.

important

Lorsque vous attribuez des utilisateurs à une session d'étiquetage, le système accorde automatiquement les autorisations WRITE nécessaires sur l'Expérimentation MLflow contenant la session d'étiquetage. Cela donne aux utilisateurs assignés accès pour consulter et interagir avec les données d'expérimentation.

Ajouter des utilisateurs aux sessions existantes

Pour ajouter des utilisateurs aux sessions existantes, utilisez set_assigned_users. Pour les détails de l’API, veuillez consulter mlflow.genai.LabelingSession.set_assigned_users.

Python
import mlflow.genai.labeling as labeling

# Find existing session by name
all_sessions = labeling.get_labeling_sessions()
session = None
for s in all_sessions:
    if s.name == "customer_review_session":
        session = s
        break

if session:
    # Add more users to the session
    new_users = ["expert2@company.com", "expert3@company.com"]
    session.set_assigned_users(session.assigned_users + new_users)
    print(f"Session now has users: {session.assigned_users}")
else:
    print("Session not found")

Remplacer les utilisateurs attribués

Python
import mlflow.genai.labeling as labeling

# Find session by name
all_sessions = labeling.get_labeling_sessions()
session = None
for s in all_sessions:
    if s.name == "session_name":
        session = s
        break

if session:
    # Replace all assigned users
    session.set_assigned_users(["new_expert@company.com", "lead_reviewer@company.com"])
    print("Updated assigned users list")
else:
    print("Session not found")

Synchroniser avec les dataset d'évaluation

Vous pouvez synchroniser les Expectations collectés vers les dataset d'évaluation.

Fonctionnement de la synchronisation des dataset

La méthode sync() effectue une opération d'upsert intelligente. Pour les détails de l’API, veuillez consulter mlflow.genai.LabelingSession.sync.

Les entrées de chaque trace servent de clé unique pour identifier les enregistrements dans le dataset.
Pour les traces avec des entrées correspondantes, les attentes de la session d'étiquetage écrasent les attentes existantes dans le dataset lorsque les noms d'attente sont identiques.
Les traces de la session d’étiquetage qui ne correspondent pas aux entrées de trace existantes dans le dataset sont ajoutées en tant que nouveaux enregistrements.
Les enregistrements de dataset existants avec des entrées différentes restent inchangés.

Cette approche vous permet d’améliorer de manière itérative votre dataset d’évaluation en ajoutant de nouveaux exemples et en mettant à jour la vérité terrain pour les exemples existants.

Synchronisation des datasets

Python
import mlflow.genai.labeling as labeling

# Find session with completed labels by name
all_sessions = labeling.get_labeling_sessions()
session = None
for s in all_sessions:
    if s.name == "completed_review_session":
        session = s
        break

if session:
    # Sync expectations to dataset
    session.sync(to_dataset="customer_service_eval_dataset")
    print("Synced expectations to evaluation dataset")
else:
    print("Session not found")

Bonnes pratiques

Organisation de la session

Utilisez des noms clairs, descriptifs et horodatés, tels que customer_service_review_march_2024.
Gardez les sessions centrées sur des objectifs d'évaluation ou des périodes spécifiques.
Visez 25 à 100 traces par session pour éviter la fatigue des réviseurs.

Stockez toujours le session.mlflow_run_id lorsque vous créez une session. Utilisez l'ID d'exécution pour l'accès programmatique au lieu de vous fier aux noms de session, car le nom de session pourrait ne pas être unique.

Python
import mlflow.genai.labeling as labeling

# Good: Store run ID for later reference
session = labeling.create_labeling_session(name="my_session", ...)
session_run_id = session.mlflow_run_id  # Store this!

# Later: Use run ID to find session via mlflow.search_runs()
# rather than searching by name through all sessions

Gestion des utilisateurs

Attribuez les utilisateurs en fonction de l'expertise du domaine et de la disponibilité.
Répartissez le travail d'étiquetage uniformément entre plusieurs experts.
N'oubliez pas que les utilisateurs doivent avoir accès au Workspace Databricks.

Ressources supplémentaires

Étiqueter les traces existantes - Guide étape par étape utilisant des sessions d'étiquetage
Créez des schémas d'étiquetage personnalisés – Définissez des questions de feedback structurées.
Créer des jeux de données d’évaluation – Convertissez les sessions étiquetées en jeux de données de test.

Fonctionnement des sessions d'étiquetage​

Créer des sessions d'étiquetage​

Créer des sessions à l'aide de l'interface utilisateur​

Afficher les sessions à l'aide de l'interface utilisateur​

Créez des sessions à l'aide de l'API​

Créer une session de base​

Créez une session à l'aide de schémas d'étiquetage personnalisés​

Gérer les sessions d'étiquetage​

Récupérer les sessions​

Obtenir une session spécifique​

Supprimer les sessions​

Ajouter des traces aux sessions​

Ajouter des traces à l'aide de l'interface utilisateur​

Ajouter des traces à partir des résultats de recherche​

Ajouter des objets de trace individuels​

Récupérer les réponses de feedback​

Gérer les utilisateurs attribués​

Exigences d'accès des utilisateurs​

Configurer les autorisations pour les utilisateurs​

Ajouter des utilisateurs aux sessions existantes​

Remplacer les utilisateurs attribués​

Synchroniser avec les dataset d'évaluation​

Fonctionnement de la synchronisation des dataset​

Synchronisation des datasets​

Bonnes pratiques​

Organisation de la session​

Gestion des utilisateurs​

Ressources supplémentaires​