Use o aplicativo de revisão para avaliações humanas de um aplicativo de IA de geração (MLflow 2)

Este artigo descreve como usar o aplicativo de revisão para coletar feedback de especialistas no assunto (PMEs). Você pode usar o aplicativo de revisão para fazer o seguinte:

• Dê às partes interessadas a capacidade de conversar com um aplicativo de IA generativa de pré-produção e dar feedback.
• Crie um conjunto de dados de avaliação, apoiado por uma tabela Delta no Unity Catalog.
• Aproveite as PMEs para expandir e iterar esse conjunto de dados de avaliação.
• Aproveite as PMEs para rotular traços de produção para entender a qualidade do seu aplicativo de IA de geração.

O que acontece numa avaliação humana?

O aplicativo de revisão Databricks cria um ambiente onde as partes interessadas podem interagir com ele - em outras palavras, ter uma conversa, fazer perguntas, fornecer feedback e assim por diante.

Há duas maneiras principais de usar o aplicativo de avaliação:

1. Bate-papo com o bot: Colete perguntas, respostas e comentários em uma tabela de inferência para que você possa analisar melhor o desempenho do aplicativo de IA de geração. Dessa forma, o aplicativo de revisão ajuda a garantir a qualidade e a segurança das respostas que seu aplicativo fornece.
2. Rotular respostas em uma sessão: Colete feedback e expectativas de PMEs em uma sessão de rotulagem, armazenada sob uma execução MLFLow. Opcionalmente, você pode sincronizar esses rótulos com um conjunto de dados de avaliação.

Requerimentos

• Os desenvolvedores devem instalar o SDK do databricks-agents para configurar permissões e o aplicativo de revisão.

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

• Para conversar com o bot:
  • Tabelas de inferência devem ser ativadas no endpoint que serve o agente.
  • Cada revisor humano deve ter acesso ao espaço de trabalho do aplicativo de revisão ou ser sincronizado com sua conta do Azure Databricks com o SCIM. Consulte a próxima seção, Configurar permissões para usar o aplicativo de revisão.
• Para sessões de rotulagem:
  • Cada revisor humano deve ter acesso ao espaço de trabalho do aplicativo de revisão.

Configurar permissões para usar o aplicativo de revisão

Permissões de configuração para "Conversar com o bot"

• Para usuários que não têm acesso ao espaço de trabalho, um administrador de conta usa o provisionamento SCIM no nível da conta para sincronizar usuários e grupos automaticamente do seu provedor de identidade para sua conta do Azure Databricks. Você também pode registrar manualmente esses usuários e grupos para dar-lhes acesso ao configurar identidades no Databricks. Veja Sincronizar utilizadores e grupos do Microsoft Entra ID usando SCIM.
• Para os usuários que já têm acesso ao espaço de trabalho que contém o aplicativo de revisão, nenhuma configuração adicional é necessária.

O exemplo de código a seguir mostra como dar permissão aos usuários para o modelo que foi implantado via agents.deploy. O parâmetro users usa uma lista de endereços de 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)

Configuração de permissões para sessões de rotulagem

Os usuários recebem automaticamente as permissões apropriadas (acesso de gravação a um experimento e acesso de leitura a um conjunto de dados) quando você cria uma sessão de rotulagem e fornece o argumento assigned_users. Para obter mais informações, consulte Criar uma sessão de rotulagem e enviar para revisão abaixo.

Criar um aplicativo de avaliação

Usando automaticamente agents.deploy()

Quando se implanta uma aplicação de IA generativa usando agents.deploy(), a aplicação de revisão é automaticamente ativada e implantada. A saída do comando mostra a URL do aplicativo de revisão. Para obter informações sobre como implantar o aplicativo de IA de geração (também chamado de "agente", consulte Implantar um agente para aplicativos de IA generativos.

Se perderes o link para a interface de utilizador da aplicação de revisão, podes encontrá-lo usando 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".

Usando manualmente a API Python

O trecho de código abaixo demonstra como criar uma aplicação de revisão e associá-la a um ponto de extremidade de serviço do modelo para interação com o bot. Para criar sessões de rotulagem, consulte

• Crie uma sessão de rotulagem e envie para revisão para rotular um conjunto de dados de avaliação.
• Colete feedback sobre traços para rotular traços. Observe que um agente ativo não é necessário para isso.

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

Conceitos

Conjuntos de dados

Um Dataset é uma coleção de exemplos usados para avaliar uma aplicação de IA generativa. Os registros do conjunto de dados contêm entradas de dados para uma aplicação de IA generativa e, opcionalmente, expectativas (rótulos de verdade fundamental, como expected_facts ou guidelines). Os conjuntos de dados são vinculados a um experimento MLFlow e podem ser usados diretamente como entradas para mlflow.evaluate(). Os conjuntos de dados são apoiados por tabelas Delta no Unity Catalog, herdando as permissões definidas pela tabela Delta. Para criar um conjunto de dados, consulte Criar um conjunto de dados.

Exemplo de conjunto de dados de avaliação, mostrando apenas entradas e colunas de expectativas:

Os conjuntos de dados de avaliação têm o seguinte esquema:

Sessões de rotulagem

Um LabelingSession é um conjunto finito de rastreamentos ou registros de conjunto de dados para ser rotulado por uma PME na interface do usuário do aplicativo de revisão. Os rastreamentos podem vir de tabelas de inferência para um aplicativo em produção ou de um rastreamento offline em experimentos MLFlow. Os resultados são armazenados como uma operação de execução no MLFlow. Os rótulos são armazenados como Assessments no MLFlow Traces. Os rótulos com "expectativas" podem ser sincronizados com um conjunto de dados de avaliação.

Avaliações e rótulos

Quando uma PME rotula um traço, de Avaliação são escritos no traço sob o campo Trace.info.assessments. Assessments podem ter dois tipos:

• expectation: Etiquetas que indicam o que um traço correto deve ter. Por exemplo: expected_facts pode ser usado como um rótulo expectation, representando os fatos que devem estar presentes em uma resposta ideal. Esses rótulos expectation podem ser sincronizados com um conjunto de dados de avaliação para que possam ser usados com mlflow.evaluate().
• feedback: Etiquetas que representam feedback simples sobre um rasto, como "gosto" e "não gosto", ou comentários em formato livre. Assessments do tipo feedback não são usados com conjuntos de dados de avaliação, uma vez que representam uma avaliação humana de um determinado Trace do MLFLow. Estas avaliações podem ser lidas com mlflow.search_traces().

Conjuntos de dados

Esta seção explica como fazer o seguinte:

• Crie um conjunto de dados e use-o para avaliação, sem uma PME.
• Solicite uma sessão de rotulagem a uma PME para organizar um melhor conjunto de dados de avaliação.

Criar um conjunto de dados

O exemplo a seguir cria um Dataset e insere avaliações. Para semear o conjunto de dados com avaliações sintéticas, consulte Sintetizar conjuntos de avaliação.

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)

Os dados desse conjunto de dados são apoiados por uma tabela Delta no Catálogo Unity e ficam visíveis no Gerenciador de Catálogos.

Usando um conjunto de dados para avaliação

O exemplo a seguir lê o conjunto de dados do Unity Catalog, utilizando o conjunto de dados de avaliação para analisar um agente simples de prompts do sistema.

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

Criar uma sessão de etiquetagem e enviar para revisão

O exemplo a seguir cria uma LabelingSession do conjunto de dados acima usando ReviewApp.create_labeling_session, configurando a sessão para coletar guidelines e expected_facts de PMEs usando o campo ReviewApp.label_schemas. Você também pode criar esquemas de rótulos personalizados com 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)

Neste ponto, você pode enviar os URLs acima para suas PMEs.

Enquanto a sua PME está a rotular, pode ver o estado da etiquetagem com o seguinte código:

mlflow.search_traces(run_id=my_session.mlflow_run_id)

Sincronize as expectativas da sessão de etiquetagem com o conjunto de dados

Depois que a PME concluir a rotulagem, pode sincronizar os rótulos expectation de volta ao conjunto de dados com LabelingSession.sync_expectations. Exemplos de rótulos com o tipo expectation incluem GUIDELINES, EXPECTED_FACTSou seu próprio esquema de rótulo personalizado que tenha um tipo expectation.

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

Agora você pode usar este conjunto de dados de avaliação:

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

Recolher opiniões sobre traços

Esta seção descreve como coletar rótulos em objetos de rastreamento MLFlow que podem vir de qualquer um dos seguintes:

• Um experimento ou uma corrida do MLFlow.
• Uma tabela de inferência.
• Qualquer objeto MLFlow Python trace.

Recolher feedback de uma experiência ou execução do MLFlow

Este exemplo cria um conjunto de vestígios a serem rotulados pelas suas PMEs.

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

Você pode obter etiquetas para o traço e criar uma sessão de etiquetagem a partir delas. Este exemplo configura uma sessão de rotulagem com um único esquema de rótulo para obter feedback sobre "formalidade" na resposta do Agente. Os rótulos das Pequenas e Médias Empresas são armazenados como uma Avaliação no MLFlow Trace.

Para obter mais tipos de entradas de esquema, consulte databricks-agents SDK.

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

Depois que a PME terminar a rotulagem, os rastreamentos e avaliações resultantes se tornam parte da execução associada à sessão de rotulagem.

mlflow.search_traces(run_id=my_session.mlflow_run_id)

Agora você pode usar essas avaliações para melhorar seu modelo ou atualizar o conjunto de dados de avaliação.

Coletar comentários de uma tabela de inferência

Este exemplo mostra como adicionar rastreamentos diretamente a partir da tabela de inferência (registos de carga útil do pedido) numa sessão de rotulagem.

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

Exemplos de notebooks

Os cadernos seguintes ilustram as variadas formas de utilização dos conjuntos de dados e das sessões de rotulagem no Mosaic AI Agent Evaluation.

Rever o bloco de notas de exemplo da aplicação

Obter caderno

Caderno de métricas personalizadas, diretrizes e rótulos de especialistas de domínio para Avaliação de Agentes

Obter caderno