Utiliser l'application d'examen pour les révisions humaines d'une application d'IA générative (MLflow 2)

important

Databricks recommande d’utiliser MLflow 3 pour l’évaluation et le monitoring des applications GenAI. Cette page décrit MLflow 2 Agent Evaluation.

• Pour une introduction à l'évaluation et au monitoring sur MLflow 3, consultez Évaluer et surveiller les agents d'IA.
• Pour en savoir plus sur la migration vers MLflow 3, consultez Migration vers MLflow 3 depuis Agent Evaluation.
• Pour plus d'informations sur MLflow 3 à ce sujet, consultez les retours d'experts du domaine.

Cet article décrit comment utiliser l'application d'évaluation pour recueillir les commentaires des experts en la matière (SME). Vous pouvez utiliser l'application d'évaluation pour effectuer les opérations suivantes :

• Donnez à vos parties prenantes la possibilité de discuter avec une application d’IA générative de pré-production et de fournir des commentaires.
• Créer un dataset d'évaluation, basé sur une table Delta dans Unity Catalog.
• Mettez à contribution les PME pour étendre et itérer sur ce dataset d'évaluation.
• Tirez parti des PME pour étiqueter les traces de production afin de comprendre la qualité de votre application d'IA générative.

Que se passe-t-il lors d'une évaluation humaine ?

L'application de révision Databricks met en place un environnement où 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 les questions, les réponses et les commentaires dans une table d'inférence afin de pouvoir analyser davantage les performances de l'application d'IA générative. De cette manière, l'application de révision aide à garantir la qualité et la sécurité des réponses que votre application fournit.
2. Étiqueter les réponses dans une session : Recueillez les commentaires et les attentes d'experts en la matière lors d'une session d'étiquetage, stockés sous une exécution MLflow. Vous pouvez facultativement synchroniser ces étiquettes vers un dataset d'évaluation.

Exigences

• Les développeurs doivent installer le SDK databricks-agents pour configurer les autorisations et l'application de révision.

Python

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

• Pour discuter avec le bot :

  • Les tables d'inférence doivent être activées sur l'endpoint qui sert l'agent.
  • Chaque évaluateur humain doit avoir accès au workspace de l'application d'évaluation ou être synchronisé avec votre compte Databricks via SCIM. Consultez la section suivante, Configurez les autorisations pour utiliser l'application d'examen.

• Pour les sessions d’étiquetage :

  • Chaque examinateur humain doit avoir accès au Workspace d'application d'examen.

Configurez les autorisations pour utiliser l'application de révision

remarque

• Pour discuter avec le bot, un examinateur humain ne nécessite pas d’accéder au Workspace.
• Pour une session d'étiquetage, un réviseur humain nécessite bien un accès au Workspace.

Configurer les autorisations pour « Discuter avec le bot »

• 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. Consultez Synchroniser les utilisateurs et les groupes de votre fournisseur d’identité à l’aide de SCIM.
• Pour les utilisateurs qui ont déjà accès au Workspace qui contient l’application d’examen, aucune configuration supplémentaire n’est requise.

L'exemple de code suivant montre comment donner aux utilisateurs la permission d'accéder au modèle qui a été déployé via agents.deploy. Le paramètre users prend une liste d'adresses e-mail.

Python

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)

remarque

Pour accorder des autorisations à tous les utilisateurs du Workspace, définissez users=["users"].

Configurer les autorisations pour les sessions d'étiquetage

Les utilisateurs se voient automatiquement accorder les autorisations appropriées (accès en écriture à une expérimentation et accès en lecture à un dataset) 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 l'envoyer pour examen ci-dessous.

Créer une application de révision

Utilisation automatique agents.deploy()

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

remarque

L'agent n'apparaît pas dans l'interface utilisateur de l'application de révision tant que l'endpoint n'est pas entièrement déployé.

Si vous perdez le Link vers l'interface utilisateur de l'application d'examen, vous pouvez le trouver à l'aide de get_review_app().

Python

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 Endpoint de service de modèle pour discuter avec le bot. Pour la création de sessions d'étiquetage, voir

• Créez une session d'étiquetage et envoyez-la pour révision pour l'étiquetage d'un dataset d'évaluation.
• Recueillez des commentaires sur les traces pour l'étiquetage des traces. Veuillez noter qu'un agent en direct n'est pas requis pour cela.

Python

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".

Concepts

dataset

Un Dataset est une collection d'exemples utilisés pour évaluer une application d'IA générative. Les enregistrements guidelines de dataset contiennent des entrées pour expected_facts une application d'IA générative et éventuellement des attentes (étiquettes de vérité terrain, comme ou">). Les jeux de données sont liés à une Expérimentation MLflow et peuvent être directement utilisés comme entrées pour mlflow.evaluate(). Les jeux de données sont basés sur des tables Delta dans Unity Catalog, héritant des autorisations définies par la table Delta. Pour créer un dataset, consultez Créer un dataset.

Exemple de dataset d'évaluation, montrant uniquement les colonnes d'entrées et d'attentes :

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

Colonne	Type de données	Description
dataset_record_id	chaîne	L'identifiant unique de l'enregistrement.
entrées	chaîne	Entrées pour l'évaluation sous forme de dict<str, Any> sérialisé JSON.
Attentes	chaîne	Valeurs attendues au format JSON sérialisé dict<str, Any>. expectations possède des clés réservées qui sont utilisées pour les juges LLM, telles que guidelines, expected_facts et expected_response.
heure de création	Horodatage	Date de création de l'enregistrement.
Créé par	chaîne	L'utilisateur qui a créé l'enregistrement.
last_update_time	Horodatage	Le moment où l'enregistrement a été mis à jour pour la dernière fois.
dernière_mise_à_jour_par	chaîne	L'utilisateur qui a effectué la dernière mise à jour du dossier.
Source	structure	La source de l'enregistrement de dataset.
source.human	structure	Défini lorsque la source provient d'un humain.
source.human.user_name	chaîne	Le nom de l'utilisateur associé à l'enregistrement.
source.document	chaîne	Défini lorsque l'enregistrement a été synthétisé à partir d'un document.
source.document.doc_uri	chaîne	L'URI du document.
source.document.content	chaîne	Le contenu du document.
source.trace	chaîne	Défini lorsque l'enregistrement a été créé à partir d'une trace.
source.trace.trace_id	chaîne	L'identifiant unique de la trace.
Tags	Carte	Balises clé-valeur pour l’enregistrement du dataset.

Colonne	Type de données	Description
dataset_record_id	chaîne	L'identifiant unique de l'enregistrement.
entrées	chaîne	Entrées pour l'évaluation sous forme de dict<str, Any> sérialisé JSON.
Attentes	chaîne	Valeurs attendues au format JSON sérialisé dict<str, Any>. expectations possède des clés réservées qui sont utilisées pour les juges LLM, telles que guidelines, expected_facts et expected_response.
heure de création	Horodatage	Date de création de l'enregistrement.
Créé par	chaîne	L'utilisateur qui a créé l'enregistrement.
last_update_time	Horodatage	Le moment où l'enregistrement a été mis à jour pour la dernière fois.
dernière_mise_à_jour_par	chaîne	L'utilisateur qui a effectué la dernière mise à jour du dossier.
Source	structure	La source de l'enregistrement de dataset.
source.human	structure	Défini lorsque la source provient d'un humain.
source.human.user_name	chaîne	Le nom de l'utilisateur associé à l'enregistrement.
source.document	chaîne	Défini lorsque l'enregistrement a été synthétisé à partir d'un document.
source.document.doc_uri	chaîne	L'URI du document.
source.document.content	chaîne	Le contenu du document.
source.trace	chaîne	Défini lorsque l'enregistrement a été créé à partir d'une trace.
source.trace.trace_id	chaîne	L'identifiant unique de la trace.
Tags	Carte	Balises clé-valeur pour l’enregistrement du dataset.

Sessions d’étiquetage

Un LabelingSession est un ensemble fini de traces ou d'enregistrements de dataset à étiqueter par un 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 ligne dans les expérimentations MLFlow. Les résultats sont stockés sous la forme d'une exécution MLFlow. Les étiquettes sont stockées en tant que Assessments sur les traces MLFlow. Les étiquettes avec « attentes » peuvent être resynchronisées avec un dataset d'évaluation.

Évaluations et étiquettes

Lorsqu'un SME étiquette une trace, des évaluationssont écrites dans la trace sous le champ Trace.info.assessments. Les Assessmentpeuvent avoir deux types :

• expectation: Libellés qui représentent ce qu'une trace correcte devrait contenir. Par exemple : expected_facts peut être utilisé comme libellé expectation, représentant les faits qui devraient être présents dans une réponse idéale. Ces libellés expectation peuvent être resynchronisés vers un dataset d'évaluation afin qu'ils puissent être utilisés avec mlflow.evaluate().
• feedback: Libellés qui représentent des commentaires simples sur une trace, comme « pouce vers le haut » et « pouce vers le bas », ou des commentaires libres. Les Assessmentde type feedback ne sont pas utilisées avec les datasets d'évaluation, car elles sont une évaluation humaine d'une trace MLflow particulière. Ces évaluations peuvent être lues avec mlflow.search_traces().

dataset

Cette section explique comment effectuer les opérations suivantes :

• Créer un dataset et l'utiliser pour l'évaluation, sans SME.
• Demandez une session d'étiquetage à un SME pour organiser un meilleur dataset d'évaluation.

Créer un dataset

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

Python

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 dataset sont adossées à une table Delta dans Unity Catalog et sont visibles dans l'Explorateur de catalogues.

remarque

Les directives nommées (utilisant un dictionnaire) ne sont actuellement pas prises en charge dans une session d’étiquetage.

Utilisation d'un dataset pour l'évaluation

L'exemple suivant lit le dataset d'Unity Catalog, en utilisant le dataset d'évaluation pour évaluer un agent d'invite système simple.

Python

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éez une session d'étiquetage et envoyez-la pour révision

L'exemple suivant crée une LabelingSession à partir du dataset ci-dessus à l'aide de ReviewApp.create_labeling_session, configuration de la session pour collecter guidelines et expected_facts auprès des experts à l'aide de la ReviewApp.label_schemas champ. Vous pouvez également créer des schémas d'étiquettes personnalisés à l'aide de ReviewApp.create_label_schema.

remarque

• Lors de la création d'une session d'étiquetage, les utilisateurs assignés sont :

  • Étant donné l'autorisation d'ÉCRITURE à l'expérimentation MLFlow.
  • Autorisation QUERY accordée à tous les Endpoints de service de modèle associés à l'application de révision.

• Lorsque vous ajoutez un dataset à une session d'étiquetage, les utilisateurs affectés reçoivent l'autorisation SELECT pour les tables Delta des datasets utilisés pour initialiser la session d'étiquetage.

Pour accorder des autorisations à tous les utilisateurs du Workspace, définissez assigned_users=["users"].

Python

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 que votre SME procède à l'étiquetage, vous pouvez consulter l'état de l'étiquetage avec le code suivant :

Python

mlflow.search_traces(run_id=my_session.mlflow_run_id)

Synchroniser les attentes de la session d'étiquetage vers le dataset

Une fois que l'ESM a terminé l'étiquetage, vous pouvez synchroniser les étiquettes expectation avec le dataset à l'aide de LabelingSession.sync_expectations. Des exemples d'étiquettes de type expectation incluent GUIDELINES, EXPECTED_FACTS ou votre propre schéma d'étiquettes personnalisé de type expectation.

Python

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 dataset d'évaluation :

Python

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

Recueillir les commentaires sur les traces

Cette section décrit comment collecter des étiquettes sur les objets de trace MLflow qui peuvent provenir de l'un des éléments suivants :

• Une expérimentation ou une exécution MLflow.
• Un tableau d'inférence.
• Tout objet MLFlow Python Trace.

Recueillez les commentaires d'une expérimentation MLflow ou d'une exécution

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

Python

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 traces et créer une session d'étiquetage à partir d'elles. Cet exemple configure une session d'étiquetage avec un schéma d'étiquette unique pour recueillir des commentaires sur la « formalité » de la réponse de l'agent. Les étiquettes du SME sont stockées sous forme d'une évaluation sur la trace MLFlow.

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

Python

# 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 en la matière a terminé l'étiquetage, les traces et évaluations qui en résultent font partie de l'exécution associée à la session d'étiquetage.

Python

mlflow.search_traces(run_id=my_session.mlflow_run_id)

Vous pouvez désormais utiliser ces évaluations pour améliorer votre modèle ou mettre à jour le dataset d'évaluation.

Trouvez les réponses de feedback dans la table d’inférence

Si votre endpoint dispose de tables d'inférence activées, Databricks écrit également les réponses de feedback vers la vue des logs d'évaluation à l'adresse suivante :

{catalog_name}.{schema_name}.{model_name}_payload_assessment_logs_view

Cette vue remplace la table _payload_assessment_logs obsolète. Pour le schéma complet et l’état de dépréciation, consultez Tables d’inférence d’agent : requêtes et évaluation Logs (obsolète).

Recueillir les commentaires d'une table d'inférence

Cet exemple montre comment ajouter des traces directement depuis la table d'inférence (logs de charge utile de la requête) dans une session d'étiquetage.

Python

# 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 notebooks suivants illustrent les différentes manières d'utiliser les datasets et les sessions d'étiquetage dans Agent Evaluation.

Examiner l'exemple de notebook de l'application

Ouvrir le notebook dans un nouvel ongletOuvrir dans Databricks

Agent Evaluation : métriques personnalisées, directives et notebook de labels d'experts du domaine

Ouvrir le notebook dans un nouvel ongletOuvrir dans Databricks