Aller au contenu principal
Dernière mise à jour le

Collectez les retours et les attentes en étiquetant les traces existantes

L'un des moyens les plus efficaces d'améliorer votre application GenAI est de faire examiner et étiqueter les traces existantes par des experts du domaine. L’application Review de MLflow fournit un processus structuré pour recueillir ces retours d’experts sur les interactions réelles avec votre application.

Examiner l'image hero de la prévisualisation de l'application.

Quand étiqueter les traces existantes​

Demandez aux experts d'examiner les interactions existantes avec votre application pour fournir des commentaires et des attentes.

Utilisez l’application de révision pour :

  • Comprendre à quoi ressemblent les réponses correctes et de haute qualité pour des requêtes spécifiques
  • Recueillir les contributions pour aligner les juges LLM sur vos exigences commerciales
  • Créer des datasets d’évaluation à partir de traces de production

Identifier les traces pour l’examen par un expert​

Avant de créer une session d'étiquetage, identifiez les traces qui bénéficieraient d'un examen expert. Concentrez-vous sur les cas qui nécessitent un jugement humain :

  • Traces de qualité ambiguë ou discutable
  • Cas limites non couverts par les juges automatisés
  • Exemples où les métriques automatisées ne concordent pas avec la qualité attendue
  • Échantillons représentatifs de différents modèles d'interaction des utilisateurs

Vous pouvez filtrer les traces dans l'interface utilisateur MLflow par statut, par balises ou par plage horaire. Pour une sélection programmatique avec des filtres avancés, consultez les requêtes de traces via le SDK.

Prérequis​

  • Vous devez installer MLflow et ses packages requis. Les fonctionnalités décrites dans ce guide nécessitent MLflow version 3.1.0 ou au-dessus. Exécutez la commande suivante pour installer ou mettre à niveau le SDK MLflow, y compris les modules complémentaires nécessaires à l'intégration de Databricks :

    Bash
    pip install --upgrade "mlflow[databricks]>=3.1.0" openai "databricks-connect>=16.1"

  • Votre environnement de développement doit être connecté à l’ Expérimentation MLflow où sont enregistrées les traces de votre application GenAI.

  • Les experts du domaine doivent disposer des autorisations suivantes pour utiliser l'application de révision afin d'étiqueter les traces existantes :

    • Accès au compte : Doit être provisionné dans votre compte Databricks, mais ne nécessite pas d'accès à votre workspace.

      Pour les utilisateurs sans accès au workspace, les administrateurs de compte peuvent :

      • Utilisez le provisionnement SCIM au niveau du compte pour synchroniser les utilisateurs depuis votre fournisseur d'identité
      • Enregistrer manuellement les utilisateurs et les groupes dans Databricks.

      Consultez la gestion des utilisateurs et des groupes pour plus de détails.

    • **Accès CAN_EDIT à l'expérimentation** : autorisation pour l'expérimentation MLflow.

Étape 1 : Créez une application dotée d'un système de traçage​

Avant de pouvoir recueillir des commentaires, vous devez avoir des traces enregistrées à partir de votre application GenAI. Ces traces capturent les entrées, les sorties et les étapes intermédiaires de l'exécution de votre application, y compris tout appel d'outil ou action de récupérateur.

Voici un exemple de la manière dont vous pourriez enregistrer des traces. Cet exemple inclut un récupérateur factice afin que nous puissions illustrer comment les documents récupérés dans les traces sont affichés dans l'application d'examen. Consultez Rendu du contenu de l'application de révision pour plus d'informations sur la façon dont l'application de révision rend les traces.

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

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"

  1. Définissez votre application :

    Python
    from mlflow.entities import Document
    from typing import List, Dict


    # Spans of type RETRIEVER are rendered in the Review App as documents.
    @mlflow.trace(span_type="RETRIEVER")
    def retrieve_docs(query: str) -> List[Document]:
     normalized_query = query.lower()
     if "john doe" in normalized_query:
         return [
             Document(
                 id="conversation_123",
                 page_content="John Doe mentioned issues with login on July 10th. Expressed interest in feature X.",
                 metadata={"doc_uri": "http://domain.com/conversations/123"},
             ),
             Document(
                 id="conversation_124",
                 page_content="Follow-up call with John Doe on July 12th. Login issue resolved. Discussed pricing for feature X.",
                 metadata={"doc_uri": "http://domain.com/conversations/124"},
             ),
         ]
     else:
         return [
             Document(
                 id="ticket_987",
                 page_content="Acme Corp raised a critical P0 bug regarding their main dashboard on July 15th.",
                 metadata={"doc_uri": "http://domain.com/tickets/987"},
             )
         ]

    # Sample app to review traces from
    @mlflow.trace
    def my_app(messages: List[Dict[str, str]]):
     # 1. Retrieve conversations based on the last user message
     last_user_message_content = messages[-1]["content"]
     retrieved_documents = retrieve_docs(query=last_user_message_content)
     retrieved_docs_text = "\n".join([doc.page_content for doc in retrieved_documents])

     # 2. Prepare messages for the LLM
     messages_for_llm = [
         {"role": "system", "content": "You are a helpful assistant!"},
         {
             "role": "user",
             "content": f"Additional retrieved context:\n{retrieved_docs_text}\n\nNow, please provide the one-paragraph summary based on the user's request {last_user_message_content} and this retrieved context.",
         },
     ]

     # 3. Call LLM to generate the summary
     return client.chat.completions.create(
         model=model_name,  # This example uses :re[DB] hosted claude-sonnet-4-5. If you provide your own OpenAI credentials, replace with a valid OpenAI model e.g., gpt-4o, etc.
         messages=messages_for_llm,
     )

Étape 2 : définir les schémas d’étiquetage​

Les schémas d’étiquetage définissent les questions et les types d’entrée que les experts du domaine utiliseront pour fournir des commentaires sur vos traces. Vous pouvez utiliser les schémas intégrés de MLflow ou en créer des personnalisés adaptés à vos critères d'évaluation spécifiques.

Il existe deux types principaux de schémas d'étiquetage :

  • **Type d'attente ()**type="expectation" : Utilisé lorsque l'expert fournit une « vérité terrain » ou une réponse correcte. Par exemple, en fournissant le expected_facts pour la réponse d'un système RAG. Ces étiquettes peuvent souvent être directement utilisées dans les datasets d'évaluation.
  • Type de commentaires (type="feedback") : utilisé pour les évaluations subjectives, les notes ou les classifications. Par exemple, évaluer une réponse sur une échelle de 1 à 5 pour la politesse, ou classer si une réponse répond à certains critères.

Consultez Créer et gérer des schémas d’étiquetage pour comprendre les différentes méthodes de saisie pour vos schémas, telles que les choix catégoriels, les échelles numériques ou le texte libre.

Python

from mlflow.genai.label_schemas import create_label_schema, InputCategorical, InputText

# Collect feedback on the summary
summary_quality = create_label_schema(
    name="summary_quality",
    type="feedback",
    title="Is this summary concise and helpful?",
    input=InputCategorical(options=["Yes", "No"]),
    instruction="Please provide a rationale below.",
    enable_comment=True,
    overwrite=True,
)

# Collect a ground truth summary
expected_summary = create_label_schema(
    name="expected_summary",
    type="expectation",
    title="Please provide the correct summary for the user's request.",
    input=InputText(),
    overwrite=True,
)

Étape 3 : Créez une session d'étiquetage​

Une session d’étiquetage est un type spécial de MLflow Run qui organise un ensemble de traces à examiner par des experts spécifiques à l’aide de schémas d’étiquetage sélectionnés. Il agit comme une file d'attente pour le processus d’examen.

Consultez Créer et gérer des sessions d'étiquetage pour plus de détails.

Voici comment créer une session d'étiquetage :

Python
from mlflow.genai.labeling import create_labeling_session

# Create the labeling session with the schemas we created in the previous step
label_summaries = create_labeling_session(
    name="label_summaries",
    assigned_users=[],
    label_schemas=[summary_quality.name, expected_summary.name],
)

Étape 4 : Générer des traces et les ajouter à la session d'étiquetage​

Une fois votre session d'étiquetage créée, vous devez y ajouter des traces. Les traces sont copiées dans la session d'étiquetage, de sorte que toutes les étiquettes ou modifications apportées pendant le processus de révision n'affectent pas vos traces d'origine enregistrées.

Vous pouvez ajouter n'importe quelle trace dans votre Experimentation MLflow. Consultez Créer et gérer les sessions d'étiquetage pour plus de détails.

remarque

Une fois les traces générées, vous pouvez également les ajouter à la session d’étiquetage en sélectionnant les traces dans l’onglet Trace tab, en cliquant sur Exporter les traces , puis en sélectionnant la session d’étiquetage que vous avez créée précédemment.

Python
import mlflow

# Use version tracking to be able to easily query for the traces
tracked_model = mlflow.set_active_model(name="my_app")

# Run the app to generate traces
sample_messages_1 = [
    {"role": "user", "content": "what issues does john doe have?"},
]
summary1_output = my_app(sample_messages_1)

sample_messages_2 = [
    {"role": "user", "content": "what issues does acme corp have?"},
]
summary2_output = my_app(sample_messages_2)

# Query for the traces we just generated
traces = mlflow.search_traces(model_id=tracked_model.model_id)

# Add the traces to the session
label_summaries.add_traces(traces)

# Print the URL to share with your domain experts
print(f"Share this Review App with your team: {label_summaries.url}")

Étape 5 : Partager l'application de révision avec des experts​

Une fois votre session d'étiquetage remplie de traces, vous pouvez partager son URL avec vos experts du domaine. Ils peuvent utiliser cette URL pour accéder à la Review App, afficher les traces qui leur sont attribuées (ou sélectionner parmi celles non attribuées), et fournir des commentaires en utilisant les schémas d'étiquetage que vous avez configurés.

important

Vos experts du domaine doivent être provisionnés dans votre compte Databricks et disposer de l’autorisation CAN_EDIT sur l’expérimentation MLflow. Ils n’ont pas besoin d’accéder à votre workspace Databricks. Consultez la section Prérequis pour plus de détails sur la façon de configurer l’accès au niveau du compte.

Interface utilisateur de création de session d'étiquetage

Personnaliser l’interface utilisateur de l'application de révision (facultatif)​

Pour les cas d'utilisation qui nécessitent une visualisation personnalisée des traces, des interfaces d'étiquetage sur mesure ou des workflows spécifiques, déployez un Template d'application de révision personnalisable. Ce Template open source utilise les mêmes API backend MLflow et le même modèle de données (sessions d'étiquetage, schémas et évaluations) tout en vous donnant un contrôle total sur l'expérience frontend. Les options de personnalisation comprennent :

  • Rendus de trace spécialisés pour vos types d'agents
  • Layout d'interface et interactions d'étiquetage personnalisés
  • Visualisations spécifiques à un domaine
  • Contrôler les informations de trace affichées aux évaluateurs.

Le repository de Template inclut des outils de ligne de commande pour une configuration programmatique ou un assistant IA (Claude Code) pour une personnalisation interactive : GitHub - custom-mlflow-review-app. L'application de révision personnalisée se déploie en tant qu' application Databricks et s'intègre directement à vos expérimentations MLflow et sessions d'étiquetage existantes. Consultez la documentation du repository de Template pour des instructions complètes de personnalisation et de déploiement.

L'interface utilisateur default de l'application de révision personnalisée

remarque

Le Template personnalisable est idéal pour les équipes qui ont besoin d’une visualisation des traces personnalisée, de workflows d’évaluation ou d’exigences d’interface utilisateur spécifiques au-delà de l’interface standard de l’application de révision. Pour les workflows d'évaluation standard, l'application de révision intégrée fournit une solution prête à la production sans configuration supplémentaire.

Étape 6 : Afficher et utiliser les étiquettes collectées​

Une fois que vos experts du domaine ont terminé leurs révisions, les commentaires recueillis sont joints aux traces de la session d'étiquetage. Vous pouvez récupérer ces étiquettes par programmation pour les analyser ou les utiliser afin de créer des dataset d'évaluation.

Les étiquettes sont stockées en tant qu'Assessment objets sur chaque Trace au sein de la session d'étiquetage.

Utiliser l'interface utilisateur MLflow​

Pour consulter les résultats, accédez à l’Expérimentation MLflow.

Résultats de la collecte de feedback dans l'interface utilisateur MLflow

Utiliser le SDK MLflow​

Le code suivant récupère toutes les traces de l'exécution de la session d’étiquetage et extrait les évaluations (étiquettes) dans un DataFrame pandas pour une analyse plus facile.

Python
labeled_traces_df = mlflow.search_traces(run_id=label_summaries.mlflow_run_id)

Passez en revue le rendu du contenu de l'application​

Lors de l'étiquetage des traces existantes, l'application Review utilise les entrées et sorties des traces existantes et stocke les résultats dans MLflow Traces à l'intérieur d'une session d'étiquetage. Vous devez fournir un schéma d'étiquetage personnalisé pour définir les questions et les critères de votre cas d'utilisation.

L'application Review rend automatiquement différents types de contenu à partir de votre trace MLflow :

  • Documents récupérés : les documents d'une RETRIEVER étendue sont affichés.

  • Messages au format OpenAI : Les entrées et les sorties du suivi MLflow suite aux conversations de chat OpenAI sont affichés :

    • outputs qui contiennent un objet ChatCompletions au format OpenAI
    • inputs ou outputs dictionnaires qui contiennent une clé messages avec un tableau de messages de chat au format OpenAI
      • Si le tableau messages contient des appels d'outils au format OpenAI, les appels d'outils sont également rendus

  • Dictionnaires : les entrées et les sorties de la MLflow Trace qui sont des dictionnaires sont rendues sous forme de JSON jolis.

Sinon, le contenu des input et output de l'étendue racine de chaque trace est utilisé comme contenu principal pour la révision.

Exemple de Notebook​

Le Notebook suivant inclut l'ensemble du code sur cette page.

Notebook pour la collecte des commentaires d'experts du domaine

Ouvrir le notebook dans un nouvel ongletOuvrir dans Databricks

Étapes suivantes​

Conversion en datasets d'évaluation​

Les étiquettes de type « expectation » (telles que expected_summary de notre exemple) sont particulièrement utiles pour créer des jeux de données d’évaluation. Ces datasets peuvent ensuite être utilisés avec mlflow.genai.evaluate() pour tester systématiquement les nouvelles versions de votre application GenAI par rapport à la vérité terrain définie par des experts.

Sur cette page