Uso de la aplicación de revisión para evaluaciones humanas de una aplicación de inteligencia artificial (MLflow 2)

En este artículo se describe cómo usar la aplicación de revisión para recopilar comentarios de expertos en la materia (PYME). Puede usar la aplicación de revisión para hacer lo siguiente:

• Ofrezca a las partes interesadas la capacidad de chatear con una aplicación de inteligencia artificial generativa de preproducción y proporcionar comentarios.
• Cree un conjunto de datos de evaluación, respaldado por una tabla Delta en el catálogo de Unity.
• Aprovechar a los expertos en la materia para expandir e iterar en ese conjunto de datos de evaluación.
• Aprovechar a los expertos en la materia para etiquetar los seguimientos de producción para comprender la calidad de la aplicación de inteligencia artificial generativa.

¿Qué ocurre en las evaluaciones humanas?

La aplicación de revisión de Databricks crea fases de un entorno en el que las partes interesadas pueden interactuar con ella; es decir, tener una conversación, formular preguntas, proporcionar comentarios, etc.

Hay dos maneras principales de usar la aplicación de revisión:

1. Chatear con el bot: recopile preguntas, respuestas y comentarios en una tabla de inferencia para poder analizar aún más el rendimiento de la aplicación de inteligencia artificial de generación. De este modo, la aplicación de revisión ayuda a garantizar la calidad y seguridad de las respuestas que proporciona la aplicación.
2. Etiquetar respuestas en una sesión: recopile comentarios y expectativas de los expertos en la materia en una sesión de etiquetado, almacenada en una ejecución de MLFLow. Opcionalmente, puede sincronizar estas etiquetas con un conjunto de datos de evaluación.

Requisitos

• Los desarrolladores deben instalar el SDK de databricks-agents para configurar los permisos y la aplicación de revisión.

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

• Para chatear con el bot:
  • Las tablas de inferencia deben estar habilitadas en el punto de conexión que sirve al agente.
  • Cada revisor humano debe tener acceso al área de trabajo de revisión de la aplicación o sincronizarse con la cuenta de Azure Databricks con SCIM. Consulte la sección siguiente Configuración de permisos para usar la aplicación de revisión.
• Para las sesiones de etiquetado:
  • Cada revisor humano debe tener acceso al área de trabajo de la aplicación de revisión.

Configuración de permisos para usar la aplicación de revisión

Permisos de configuración para "Chat with the bot" (Chatear con el bot)

• Para los usuarios que no tienen acceso al área de trabajo, un administrador de cuentas usa el aprovisionamiento SCIM de nivel de cuenta para sincronizar usuarios y grupos automáticamente desde el proveedor de identidades a su cuenta de Azure Databricks. También puede registrar manualmente estos usuarios y grupos para concederles acceso al configurar identidades en Databricks. Consulte Sincronizar usuarios y grupos de Microsoft Entra ID mediante SCIM.
• Para los usuarios que ya tienen acceso al área de trabajo que contiene la aplicación de revisión, no se requiere ninguna configuración adicional.

En el ejemplo de código siguiente se muestra cómo conceder a los usuarios permiso para el modelo que se implementó a través agents.deployde . El users parámetro toma una lista de direcciones de correo electrónico.

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)

Configurar permisos para las sesiones de etiquetado

A los usuarios se les conceden automáticamente los permisos adecuados (acceso de escritura a un experimento y acceso de lectura a un conjunto de datos) al crear una sesión de etiquetado y proporcionar el assigned_users argumento . Para obtener más información, consulte Creación de una sesión de etiquetado y envío para su revisión a continuación.

Creación de una aplicación de revisión

Uso automático de agents.deploy()

Cuando se implementa una aplicación de IA generativa mediante agents.deploy(), la aplicación de revisión se habilita y se implementa automáticamente. La salida del comando muestra la dirección URL de la aplicación de revisión. Para obtener información sobre la implementación de una aplicación de inteligencia artificial de generación (también denominada "agente", consulte Implementación de un agente para aplicaciones de IA generativas).

Si pierde el vínculo a la interfaz de usuario de la aplicación de revisión, puede encontrarlo mediante 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".

Uso manual de la API de Python

El fragmento de código siguiente muestra cómo crear una aplicación de revisión y asociarla con un punto de conexión de servicio de modelo para chatear con el bot. Para la creación de sesiones de etiquetado, consulte

• Cree una sesión de etiquetado y envíe para su revisión para etiquetar un conjunto de datos de evaluación.
• Recopilar comentarios sobre seguimientos para etiquetar rastros. Tenga en cuenta que no se requiere un agente activo para esto.

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

Conceptos

Conjuntos de datos

Un Conjunto de datos es una colección de ejemplos que se usan para evaluar una aplicación de inteligencia artificial de generación. Los registros de conjunto de datos contienen entradas para una aplicación de inteligencia artificial de generación y, opcionalmente, expectativas (etiquetas de verdad básica, como expected_facts o guidelines). Los conjuntos de datos están vinculados a un experimento de MLFlow y se pueden usar directamente como entradas para mlflow.evaluate(). Los conjuntos de datos están respaldados por tablas delta en el catálogo de Unity, heredando los permisos definidos por la tabla Delta. Para crear un conjunto de datos, consulte Creación de un conjunto de datos.

Conjunto de datos de evaluación de ejemplo, que muestra solo las entradas y las columnas de expectativas:

Los conjuntos de datos de evaluación tienen el esquema siguiente:

Sesiones de etiquetado

Una LabelingSession es un conjunto finito de seguimientos o registros de conjuntos de datos para etiquetarse mediante un experto en la materia en la interfaz de usuario de la aplicación de revisión. Los rastros pueden provenir de tablas de inferencia para una aplicación en producción o un seguimiento sin conexión en experimentos de MLflow. Los resultados se almacenan como una ejecución de MLFlow. Las etiquetas se almacenan como Assessment en seguimientos de MLFlow. Las etiquetas con "expectativas" se pueden volver a sincronizar con un conjunto de datos de evaluación.

Evaluaciones y etiquetas

Cuando un experto en la materia etiqueta un seguimiento, las evaluaciones se escriben en el seguimiento en el campo Trace.info.assessments. Assessments pueden ser de dos tipos:

• expectation: Etiquetas que representan lo que debe tener una traza correcta. Por ejemplo: expected_facts se puede usar como una etiqueta expectation, que representa los hechos que deben estar presentes en una respuesta ideal. Estas etiquetas expectation se pueden sincronizar con un conjunto de datos de evaluación para que se puedan usar con mlflow.evaluate().
• feedback: etiquetas que representan comentarios simples sobre un seguimiento, como "pulgares hacia arriba" y "pulgares hacia abajo" o comentarios de forma libre. Las Assessment de tipo feedback no se usan con conjuntos de datos de evaluación, ya que son una evaluación humana de un seguimiento de MlFLow determinado. Estas evaluaciones se pueden leer con mlflow.search_traces().

Conjuntos de datos

En esta sección se explica cómo hacer lo siguiente:

• Cree un conjunto de datos y úselo para la evaluación, sin un SME.
• Solicite una sesión de etiquetado de un experto en la materia para mantener un mejor conjunto de datos de evaluación.

Creación de un conjunto de datos

En el ejemplo siguiente se crea un conjunto de datos e inserta evaluaciones. Para inicializar el conjunto de datos con evaluaciones sintéticas, consulte Sintetizar conjuntos de evaluación.

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)

Los datos de este conjunto de datos están respaldados por una tabla Delta en el catálogo de Unity y están visibles en el Explorador de catálogos.

Uso de un conjunto de datos para la evaluación

En el ejemplo siguiente se lee el conjunto de datos de Unity Catalog mediante el conjunto de datos de evaluación para evaluar un agente de solicitud del sistema 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"
)

Creación de una sesión de etiquetado y envío para su revisión

En el ejemplo siguiente se crea un LabelingSession a partir del conjunto de datos anterior mediante ReviewApp.create_labeling_session, configurando la sesión para recopilar guidelines y expected_facts de las SME mediante el campo ReviewApp.label_schemas. También puede crear esquemas de etiqueta personalizados con 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)

En este momento, puede enviar las direcciones URL anteriores a sus PYME.

Mientras su SME realiza el etiquetado, puede ver el estado del etiquetado con el código siguiente:

mlflow.search_traces(run_id=my_session.mlflow_run_id)

Sincronización de las expectativas de sesión de etiquetado al conjunto de datos

Una vez que el SME haya completado el etiquetado, puede sincronizar las etiquetasexpectation con el conjunto de datos usando LabelingSession.sync_expectations. Algunos ejemplos de etiquetas con el tipo expectation incluyen GUIDELINES, EXPECTED_FACTSo su propio esquema de etiqueta personalizado que tiene un tipo expectation.

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

Ahora puede usar este conjunto de datos de evaluación:

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

Recopilar comentarios sobre seguimientos

En esta sección se describe cómo recopilar etiquetas en objetos de seguimiento de MLFlow que pueden provenir de cualquiera de las siguientes opciones:

• Un experimento o ejecución de MLFlow.
• Una tabla de inferencia.
• Cualquier objeto de seguimiento de Python de MLFlow.

Recopilar comentarios de un experimento o ejecución de MLFlow

Este ejemplo crea un conjunto de seguimientos que sus SME podrán etiquetar.

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"}])

Puede obtener etiquetas para el seguimiento y crear una sesión de etiquetado a partir de ellas. En este ejemplo se configura una sesión de etiquetado con un único esquema de etiquetas para recopilar comentarios sobre el nivel de formalidad en la respuesta del agente. Las etiquetas del SME se almacenan como una evaluación en el seguimiento de MLFlow.

Para obtener más tipos de entradas de esquema, consulte SDK de 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)

Una vez que el SME haya terminado de etiquetar, los seguimientos y las evaluaciones resultantes forman parte de la ejecución asociada a la sesión de etiquetado.

mlflow.search_traces(run_id=my_session.mlflow_run_id)

Ahora puede usar estas evaluaciones para mejorar el modelo o actualizar el conjunto de datos de evaluación.

Recopilación de comentarios de una tabla de inferencia

En este ejemplo se muestra cómo agregar trazas directamente desde la tabla de inferencia (registros de la carga útil de solicitudes) a una sesión de etiquetado.

# 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)

Cuadernos de ejemplo

Los siguientes cuadernos ilustran las distintas formas de usar conjuntos de datos y sesiones de etiquetado en la evaluación de agentes de IA de Mosaic.

Revisión del cuaderno de ejemplo de la aplicación

Obtener el cuaderno

Cuaderno de métricas personalizadas, directrices y etiquetas de expertos de dominio para la evaluación de agentes

Obtener el cuaderno