Utiliser l'application d'évaluation pour les évaluations humaines d'une application d'IA générative (MLflow 2)

Cet article explique comment utiliser l’application de révision pour recueillir les commentaires d’experts techniques (SME). Vous pouvez utiliser l’application de révision pour effectuer les opérations suivantes :

• Donnez à vos parties prenantes la possibilité de discuter avec une application IA générative en préproduction et de fournir des commentaires.
• Créez un jeu de données d’évaluation, soutenu par une table Delta dans le catalogue Unity.
• Tirez parti des PME pour développer et itérer sur ce jeu de données d’évaluation.
• Tirez profit des experts techniques (SME) pour étiqueter les traces de production afin de comprendre la qualité de votre application d’IA générative.

En quoi consiste une évaluation humaine ?

L’application de révision Databricks met en scène un environnement dans lequel les parties prenantes peuvent interagir avec elle , en d’autres termes, avoir une conversation, poser des questions, fournir des commentaires, et ainsi de suite.

Il existe deux façons principales d’utiliser l’application de révision :

1. Discutez avec le bot : collectez des questions, des réponses et des commentaires dans une table d’inférence pour vous permettre d’analyser plus en détail les performances de l’application IA gen. De cette façon, l’application de révision permet de garantir la qualité et la sécurité des réponses fournies par votre application.
2. Réponses d’étiquette dans une session : collectez les commentaires et attentes des experts techniques (SME) dans une session d’étiquetage, stockée sous une exécution MLFLow. Vous pouvez éventuellement synchroniser ces étiquettes avec un jeu de données d’évaluation.

Spécifications

• Les développeurs doivent installer le kit de développement logiciel (SDK) databricks-agents pour configurer les autorisations et configurer l’application de révision.

  %pip install databricks-agents
  dbutils.library.restartPython()

• Pour discuter avec le bot :
  • Les tables d'inférence doivent être activées sur le point de terminaison qui sert l’agent.
  • Chaque réviseur humain doit avoir accès à l’espace de travail de l’application de révision ou être synchronisé avec votre compte Azure Databricks avec SCIM. Consultez la section suivante, configurer les autorisations pour utiliser l’application de révision.
• Pour les sessions d’étiquetage :
  • Chaque réviseur humain doit avoir accès à l’espace de travail de l’application de révision.

Configurer des autorisations pour utiliser l’application de révision

Autorisations d’installation pour « Discuter avec le bot »

• Pour les utilisateurs qui n’ont pas accès à l’espace de travail, 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 Azure Databricks. Vous pouvez également inscrire manuellement ces utilisateurs et groupes pour leur donner accès lorsque vous configurez des identités dans Databricks. Consultez Synchroniser des utilisateurs et des groupes à partir de Microsoft Entra ID à l’aide de SCIM.
• Pour les utilisateurs qui ont déjà accès à l’espace de travail qui contient l’application de révision, aucune configuration supplémentaire n’est requise.

L’exemple de code suivant montre comment accorder aux utilisateurs l’autorisation du modèle déployé via agents.deploy. Le users paramètre prend une liste d’adresses e-mail.

from databricks import agents

# Note that <user_list> can specify individual users or groups.
agents.set_permissions(model_name=<model_name>, users=[<user_list>], permission_level=agents.PermissionLevel.CAN_QUERY)

Configurer les autorisations pour les sessions d’étiquetage

Les utilisateurs reçoivent automatiquement les autorisations appropriées (accès en écriture à une expérience et accès en lecture à un jeu de données) lorsque vous créez une session d’étiquetage et fournissez l’argument assigned_users . Pour plus d’informations, consultez Créer une session d’étiquetage et envoyer pour révision ci-dessous.

Créer une application de révision

Utilisation automatique de agents.deploy()

Lorsque vous déployez une application IA de génération à l’aide agents.deploy(), l’application de révision est automatiquement activée et déployée. La sortie de la commande montre l’URL de l’application de révision. Pour plus d’informations sur le déploiement d’une application IA de génération (également appelée « agent », consultez Déployer un agent pour les applications IA génératives.

Si vous perdez le lien vers l’interface utilisateur de l’application de révision, vous pouvez le trouver à l’aide get_review_app().

import mlflow
from databricks.agents import review_app

# The review app is tied to the current MLFlow experiment.
mlflow.set_experiment("same_exp_used_to_deploy_the_agent")
my_app = review_app.get_review_app()
print(my_app.url)
print(my_app.url + "/chat") # For "Chat with the bot".

Utilisation manuelle de l’API Python

L’extrait de code ci-dessous montre comment créer une application de révision et l’associer à un point de terminaison de mise en service pour discuter avec le bot. Pour créer des sessions d’étiquetage, consultez

• Créez une session d’étiquetage et envoyez pour révision l’étiquetage d’un jeu de données d’évaluation.
• Collecter des commentaires sur les traces pour l’étiquetage des traces. Notez qu’un agent en direct n’est pas requis pour cela.

from databricks.agents import review_app

# The review app is tied to the current MLFlow experiment.
my_app = review_app.get_review_app()

# TODO: Replace with your own serving endpoint.
my_app.add_agent(
    agent_name="llama-70b",
    model_serving_endpoint="databricks-meta-llama-3-3-70b-instruct",
)
print(my_app.url + "/chat") # For "Chat with the bot".

Les concepts

Jeux de données

Un jeu de données est une collection d’exemples utilisés pour évaluer une application IA de génération. Les enregistrements de jeu de données contiennent les entrées d’une application d’IA générative et éventuellement les attentes (étiquettes de vérité d’ancrage, par exemple expected_facts ou guidelines). Les jeux de données sont liés à une expérience MLFlow et peuvent être utilisés directement comme entrées pour mlflow.evaluate(). Les jeux de données sont soutenus par des tables Delta dans le catalogue Unity, qui héritent des autorisations définies par la table Delta. Pour créer un jeu de données, consultez Créer un jeu de données.

Exemple de jeu de données d’évaluation, affichant uniquement les entrées et les colonnes des attentes :

Les jeux de données d’évaluation ont le schéma suivant :

Sessions d’étiquetage

Une LabelingSession est un ensemble fini de traces ou d’enregistrements de jeu de données qui doivent être étiquetés par un expert technique (SME) dans l’interface utilisateur de l’application de révision. Les traces peuvent provenir de tables d’inférence pour une application en production ou d’une trace hors connexion dans les expériences MLFlow. Les résultats sont stockés en tant qu’exécution de MLFlow. Les étiquettes sont stockées en tant que Assessment dans les traces MLFlow. Les étiquettes avec des « attentes » peuvent être synchronisées vers un jeu de données d’évaluation.

Évaluations et étiquettes

Quand un SME étiquette une trace, des évaluations sont écrites dans la trace sous le champ Trace.info.assessments. Les évaluations (Assessment) peuvent être de deux types :

• expectation: étiquettes qui représentent ce qu’une trace correcte doit avoir. Par exemple : expected_facts peut être utilisé comme étiquette de expectation, représentant les faits qui doivent être présents dans une réponse idéale. Ces étiquettes expectation peuvent être synchronisées avec un jeu de données d’évaluation afin qu’elles puissent être utilisées avec mlflow.evaluate().
• feedback : étiquettes qui représentent de simples commentaires sur une trace, par exemple « pouce vers le haut » et « pouce vers le bas », ou des commentaires libres. Les Assessment de type feedback ne sont pas utilisés avec les jeux de données d’évaluation, car il s’agit d’une évaluation humaine d’une trace MLflow particulière. Ces évaluations peuvent être lues avec mlflow.search_traces().

Jeux de données

Cette section explique comment effectuer les opérations suivantes :

• Créez un jeu de données et utilisez-le pour l’évaluation, sans PME.
• Demandez une session d’étiquetage d’un PME pour organiser un meilleur jeu de données d’évaluation.

Créer un jeu de données

L’exemple suivant crée un jeu de données et insère des évaluations. Pour amorcer le jeu de données avec des évaluations synthétiques, consultez Synthétiser les ensembles d'évaluation.

from databricks.agents import datasets
import mlflow

# The following call creates an empty dataset. To delete a dataset, use datasets.delete_dataset(uc_table_name).
dataset = datasets.create_dataset("cat.schema.my_managed_dataset")

# Optionally, insert evaluations.
# The `guidelines` specified here are saved to the `expectations` field in the dataset.
eval_set = [{
  "request": {"messages": [{"role": "user", "content": "What is the capital of France?"}]},
  "guidelines": ["The response must be in English", "The response must be clear, coherent, and concise"],
}]

dataset.insert(eval_set)

Les données de ce jeu de données sont sauvegardées par une table Delta dans le catalogue Unity et sont visibles dans l’Explorateur de catalogues.

Utilisation d’un jeu de données pour l’évaluation

L'exemple suivant consiste en la lecture du jeu de données depuis le catalogue Unity, en utilisant le jeu de données d'évaluation afin d'évaluer un agent de commandes système simple.

import mlflow
from mlflow.deployments import get_deploy_client

# Define a very simple system-prompt agent to test against our evaluation set.
@mlflow.trace(span_type="AGENT")
def llama3_agent(request):
  SYSTEM_PROMPT = """
    You are a chatbot that answers questions about Databricks.
    For requests unrelated to Databricks, reject the request.
  """
  return get_deploy_client("databricks").predict(
    endpoint="databricks-meta-llama-3-3-70b-instruct",
    inputs={
      "messages": [
        {"role": "system", "content": SYSTEM_PROMPT},
        *request["messages"]
      ]
    }
  )

evals = spark.read.table("cat.schema.my_managed_dataset")

mlflow.evaluate(
  data=evals,
  model=llama3_agent,
  model_type="databricks-agent"
)

Créer une session d’étiquetage et envoyer pour révision

L’exemple suivant crée une labelingSession à partir du jeu de données ci-dessus à l’aide de ReviewApp.create_labeling_session, en configurant la session pour collecter guidelines et expected_facts à partir de PME à l’aide du champ ReviewApp.label_schemas . Vous pouvez également créer des schémas d’étiquette personnalisés avec ReviewApp.create_label_schema

from databricks.agents import review_app
import mlflow

# The review app is tied to the current MLFlow experiment.
my_app = review_app.get_review_app()

# You can use the following code to remove any existing agents.
# for agent in list(my_app.agents):
#     my_app.remove_agent(agent.agent_name)

# Add the llama3 70b model serving endpoint for labeling. You should replace this with your own model serving endpoint for your
# own agent.
# NOTE: An agent is required when labeling an evaluation dataset.
my_app.add_agent(
    agent_name="llama-70b",
    model_serving_endpoint="databricks-meta-llama-3-3-70b-instruct",
)

# Create a labeling session and collect guidelines and/or expected-facts from SMEs.
# Note: Each assigned user is given QUERY access to the serving endpoint above and write access.
# to the MLFlow experiment.
my_session = my_app.create_labeling_session(
  name="my_session",
  agent="llama-70b",
  assigned_users = ["email1@company.com", "email2@company.com"],
  label_schemas = [review_app.label_schemas.GUIDELINES, review_app.label_schemas.EXPECTED_FACTS]
)

# Add the records from the dataset to the labeling session.
# Note: Each assigned user above is given SELECT access to the UC delta table.
my_session.add_dataset("cat.schema.my_managed_dataset")

# Share the following URL with your SMEs for them to bookmark. For the given review app linked to an experiment, this URL never changes.
print(my_app.url)

# You can also link them directly to the labeling session URL, however if you
# request new labeling sessions from SMEs there will be new URLs. Use the review app
# URL above to keep a permanent URL.
print(my_session.url)

À ce stade, vous pouvez envoyer les URL ci-dessus à vos PME.

Pendant l’étiquetage de votre PME, vous pouvez afficher l’état de l’étiquetage avec le code suivant :

mlflow.search_traces(run_id=my_session.mlflow_run_id)

Synchroniser à nouveau les attentes de la session d'étiquetage avec le jeu de données

Une fois que le SME a effectué l’étiquetage, vous pouvez resynchroniser les étiquettes expectation avec le jeu de données à l’aide de LabelingSession.sync_expectations. Parmi les exemples d’étiquettes avec le type expectation, citons GUIDELINES, EXPECTED_FACTS ou votre propre schéma d’étiquette personnalisé avec un type expectation.

my_session.sync_expectations(to_dataset="cat.schema.my_managed_dataset")
display(spark.read.table("cat.schema.my_managed_dataset"))

Vous pouvez maintenant utiliser ce jeu de données d’évaluation :

eval_results = mlflow.evaluate(
    model=llama3_agent,
    data=dataset.to_df(),
    model_type="databricks-agent"
)

Collecter des commentaires sur les traces

Cette section explique comment collecter des étiquettes sur des objets de trace MLFlow qui peuvent provenir de l’un des éléments suivants :

• Une expérience ou une exécution MLFlow.
• Table d’inférence.
• N’importe quel objet de trace Python MLFlow.

Collecter des commentaires à partir d’une expérience ou d’une exécution MLFlow

Cet exemple crée un ensemble de traces à étiqueter par vos PME.

import mlflow
from mlflow.deployments import get_deploy_client

@mlflow.trace(span_type="AGENT")
def llama3_agent(messages):
  SYSTEM_PROMPT = """
    You are a chatbot that answers questions about Databricks.
    For requests unrelated to Databricks, reject the request.
  """
  return get_deploy_client("databricks").predict(
    endpoint="databricks-meta-llama-3-3-70b-instruct",
    inputs={"messages": [{"role": "system", "content": SYSTEM_PROMPT}, *messages]}
  )

# Create a trace to be labeled.
with mlflow.start_run(run_name="llama3") as run:
    run_id = run.info.run_id
    llama3_agent([{"content": "What is databricks?", "role": "user"}])
    llama3_agent([{"content": "How do I set up a SQL Warehouse?", "role": "user"}])

Vous pouvez obtenir des étiquettes pour la trace et créer une session d’étiquetage à partir d’elles. Cet exemple montre comment configurer une session d'étiquetage avec un schéma d'étiquettes unique pour collecter des commentaires sur le niveau de formalité de la réponse de l'agent. Les étiquettes du SME sont stockées sous forme d’Évaluation dans la trace MLFlow.

Pour plus de types d’entrées de schéma, consultez SDK databricks-agents.

# The review app is tied to the current MLFlow experiment.
my_app = review_app.get_review_app()

# Use the run_id from above.
traces = mlflow.search_traces(run_id=run_id)

formality_label_schema = my_app.create_label_schema(
  name="formal",
  # Type can be "expectation" or "feedback".
  type="feedback",
  title="Is the response formal?",
  input=review_app.label_schemas.InputCategorical(options=["Yes", "No"]),
  instruction="Please provide a rationale below.",
  enable_comment=True
)

my_session = my_app.create_labeling_session(
  name="my_session",
  # NOTE: An `agent` is not required. If you do provide an Agent, your SME can ask follow up questions in a converstion and create new questions in the labeling session.
  assigned_users=["email1@company.com", "email2@company.com"],
  # More than one label schema can be provided and the SME will be able to provide information for each one.
  # We use only the "formal" schema defined above for simplicity.
  label_schemas=["formal"]
)
# NOTE: This copies the traces into this labeling session so that labels do not modify the original traces.
my_session.add_traces(traces)

# Share the following URL with your SMEs for them to bookmark. For the given review app, linked to an experiment, this URL will never change.
print(my_app.url)

# You can also link them directly to the labeling session URL, however if you
# request new labeling sessions from SMEs there will be new URLs. Use the review app
# URL above to keep a permanent URL.
print(my_session.url)

Une fois que l’expert technique (SME) a terminé l’étiquetage, les traces et évaluations dérivées font partie de l’exécution associée à la session d’étiquetage.

mlflow.search_traces(run_id=my_session.mlflow_run_id)

Vous pouvez maintenant utiliser ces évaluations pour améliorer votre modèle ou mettre à jour le jeu de données d’évaluation.

Collecter des commentaires à partir d’une table d’inférence

Cet exemple montre comment ajouter des traces directement à partir de la table d’inférence (journaux de charge utile de requêtes) dans une session d’étiquetage.

# CHANGE TO YOUR PAYLOAD REQUEST LOGS TABLE
PAYLOAD_REQUEST_LOGS_TABLE = "catalog.schema.my_agent_payload_request_logs"
traces = spark.table(PAYLOAD_REQUEST_LOGS_TABLE).select("trace").limit(3).toPandas()

my_session = my_app.create_labeling_session(
  name="my_session",
  assigned_users = ["email1@company.com", "email2@company.com"],
  label_schemas=[review_app.label_schemas.EXPECTED_FACTS]
)

# NOTE: This copies the traces into this labeling session so that labels do not modify the original traces.
my_session.add_traces(traces)
print(my_session.url)

Exemples de notebooks

Les blocs-notes suivants illustrent les différentes façons d’utiliser des jeux de données et des sessions d’étiquetage dans l’évaluation de l’Agent d'IA Mosaic.

Exemple de bloc-notes d’application de révision

Obtenir un ordinateur portable

Carnet de notes sur l’évaluation de l’agent, les métriques personnalisées, les directives et les labels d’expert du domaine.

Obtenir un ordinateur portable