Usar o aplicativo de revisão para revisões humanas de um aplicativo de inteligência artificial generativa (MLflow 2)

2025-06-11

Importante

Esta página descreve o uso da versão 0.22 de Avaliação do Agente com o MLflow 2. O Databricks recomenda o uso do MLflow 3, que é integrado à Avaliação do Agente >1.0. No MLflow 3, as APIs de Avaliação do Agente agora fazem parte do mlflow pacote.

Para obter informações sobre este tópico, consulte Examinar Aplicativo.

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

Dê aos seus stakeholders a capacidade de conversar com um aplicativo de IA de pré-produção e fazer comentários.
Crie um conjunto de dados de avaliação, apoiado por uma tabela Delta no Catálogo do Unity.
Aproveitar os SMEs para expandir e iterar nesse conjunto de dados de avaliação.
Aproveite os SMEs para rotular rastreamentos de produção para entender a qualidade do seu aplicativo de IA de geração.

Imagem de destaque da visualização do aplicativo de análise.

O que acontece em uma avaliação humana?

O aplicativo de revisão do Databricks prepara um ambiente em que os stakeholders podem interagir com ele - em outras palavras, ter uma conversa, fazer perguntas, fornecer comentários e assim por diante.

Há duas maneiras principais de usar o aplicativo de revisão:

Chat com o bot: coletar perguntas, respostas e comentários em uma tabela de inferência para que você possa analisar ainda mais o desempenho do aplicativo de IA de geração. Dessa forma, o aplicativo de avaliação ajuda a garantir a qualidade e a segurança das respostas que seu aplicativo fornece.
Respostas do rótulo em uma sessão: colete os comentários e as expectativas de SMEs em uma sessão de rotulagem, armazenada em uma execução MLFLow. Opcionalmente, você pode sincronizar esses rótulos com um conjunto de dados de avaliação.

Requisitos

Os desenvolvedores precisam instalar o SDK do databricks-agents para configurar permissões e configurar o aplicativo de resenha.

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

Para conversar com o bot:
- As tabelas de inferência precisam ser habilitadas no ponto de extremidade que está atendendo o agente.
- Cada revisor humano precisa ter acesso ao workspace do app de revisão ou ser sincronizado à sua conta do Azure Databricks via SCIM. Consulte a próxima seção, Configurar permissões para usar o aplicativo de revisão.
Quanto às sessões de rotulagem:
- Cada revisor humano deve ter acesso ao workspace do aplicativo de revisão.

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

Observação

Para conversar com o bot, um revisor humano não requer acesso ao workspace.
Para uma sessão de rotulagem, um revisor humano requer acesso ao workspace.

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

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

O exemplo de código a seguir mostra como conceder aos usuários permissão para o modelo que foi implantado por meio de agents.deploy. O users parâmetro 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)

Observação

Para conceder permissões para todos os usuários no workspace, defina users=["users"].

Configurar 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 a revisão abaixo.

Criar um aplicativo de revisão

Usar `agents.deploy()` automaticamente

Quando você implanta um aplicativo de IA generativa usando agents.deploy(), o aplicativo de revisão é habilitado e implantado automaticamente. 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.

Observação

O agente não aparece na interface do aplicativo de resenha até que o endpoint seja totalmente implantado.

Link para o app de resenha da saída do comando do notebook.

Se você perder o link para a interface do app de revisão, poderá 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".

Usar manualmente a API do Python

O snippet de código abaixo demonstra como criar um aplicativo temporário de revisão e associá-lo a um ponto de extremidade do Serviço de Modelo para conversar com o bot. Para criar sessões de rotulagem, confira

Criar uma sessão de rotulagem e enviar para revisão para rotular um conjunto de dados de avaliação.
Coletar feedback sobre rastreamentos para rotulagem de rastreamentos. 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 Conjunto de dados é uma coleção de exemplos usados para avaliar um aplicativo de IA generativa. Os registros de conjunto de dados contêm entradas para um aplicativo 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 do MLFlow e podem ser usados diretamente como entradas para mlflow.evaluate(). Os conjuntos de dados são apoiados por tabelas Delta no Catálogo do Unity, 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:

exemplo de conjunto de dados

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

Coluna	Tipo de Dados	Descrição
dataset_record_id	cadeia de caracteres	O identificador exclusivo do registro.
entradas	cadeia de caracteres	Entradas para a avaliação como json serializado `dict<str, Any>`.
Expectativas	cadeia de caracteres	Valores esperados como `dict<str, Any>` json serializado. `expectations` tem chaves reservadas que são usadas para juízes LLM, como `guidelines`, `expected_facts`, e `expected_response`.
create_time	carimbo de data/hora	A hora em que o registro foi criado.
created_by	cadeia de caracteres	O usuário que criou o registro.
hora_última_atualização	carimbo de data/hora	A hora em que o registro foi atualizado pela última vez.
last_updated_by	cadeia de caracteres	O usuário que atualizou o registro pela última vez.
fonte	struct	A origem do registro do conjunto de dados.
source.human	struct	Definido quando a origem é de um humano.
source.human.user_name	cadeia de caracteres	O nome do usuário associado ao registro.
source.document	cadeia de caracteres	Definido quando o registro foi sintetizado de um documento.
source.document.doc_uri	cadeia de caracteres	O URI do documento.
source.document.content	cadeia de caracteres	O conteúdo do documento.
source.trace	cadeia de caracteres	Definido quando o registro foi criado a partir de um rastreamento.
source.trace.trace_id	cadeia de caracteres	O identificador exclusivo do rastreamento.
Etiquetas	mapa	Marcas de chave-valor para o registro do conjunto de dados.

Sessões de rotulagem

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

Sessão de rotulagem

Avaliações e rótulos

Quando um SME rotula um rastreamento, as Avaliações são gravadas no rastreamento no campo Trace.info.assessments. Assessments podem ter dois tipos:

expectation: rótulos que indicam o que um rastreamento 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 novamente com um conjunto de dados de avaliação para que possam ser usados com mlflow.evaluate().
feedback: rótulos que representam comentários simples em um rastreamento, como "curtir" e "não curtir" ou comentários de forma livre. Assessments do tipo feedback não são usados com conjuntos de dados de avaliação, pois são uma avaliação humana de um Rastreamento do MLFLow específico. Essas 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 um SME.
Solicite uma sessão de rotulagem de um SME para coletar um conjunto de dados de avaliação melhor.

Criar um conjunto de dados

O exemplo a seguir cria um conjunto de dados e insere avaliações. Para propagar o conjunto de dados com avaliações sintéticas, consulte Sintetizar os 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 do Unity e ficam visíveis no Catalog Explorer.

Observação

Diretrizes nomeadas (usando um dicionário) atualmente não têm suporte em uma sessão de rotulagem.

Usando um conjunto de dados para avaliação

O exemplo a seguir lê o conjunto de dados do Unity Catalog e usa o conjunto de dados de avaliação para avaliar um agente simples de prompt 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 rotulagem 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 dos SMEs usando o campo ReviewApp.label_schemas. Você também pode criar esquemas de rótulo personalizados com ReviewApp.create_label_schema

Observação

Ao criar uma sessão de rotulagem, os usuários atribuídos são:
- Permissão WRITE dada ao experimento MLFlow.
- Permissão QUERY dada a qualquer modelo que esteja servindo pontos de extremidade associados ao aplicativo de revisão.
Ao adicionar um conjunto de dados a uma sessão de rotulagem, os usuários atribuídos recebem permissão SELECT às tabelas delta dos conjuntos de dados usados para alimentar a sessão de rotulagem.

Para conceder permissões para todos os usuários no workspace, defina assigned_users=["users"].

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 as URLs acima para seus SMEs.

Enquanto o SME estiver etiquetando, você pode verificar o status da etiquetagem com o seguinte código:

mlflow.search_traces(run_id=my_session.mlflow_run_id)

Sincronizar as expectativas da sessão de rotulagem com o conjunto de dados

Quando o SME concluir a rotulagem, você poderá sincronizar os rótulos expectation de volta ao conjunto de dados usando LabelingSession.sync_expectations. Exemplos de rótulos com o tipo expectation incluem GUIDELINES, EXPECTED_FACTSou seu próprio esquema de rótulo personalizado que tem 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"
)

Coletar comentários sobre rastreamentos

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

Um experimento ou execução do MLFlow.
Uma tabela de inferência.
Qualquer objeto de Rastreamento do MLFlow Python.

Coletar comentários de um experimento ou execução do MLFlow

Esses exemplos criam um conjunto de rastreamentos a serem rotulados por seus SMEs.

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 rótulos para o rastreamento e criar uma sessão de rotulagem com base neles. Este exemplo configura uma sessão de rotulagem com um único esquema de rótulo para coletar feedback sobre a formalidade da resposta do Agente. Os rótulos do SME são armazenados como uma Avaliação no Rastreamento do MLFlow.

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 o SME tiver concluído a rotulagem, os rastreamentos e avaliações resultantes se tornarão 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 da tabela de inferência (logs de conteúdo de solicitação) em uma 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)

Notebooks de exemplo

Os notebooks a seguir ilustram as diferentes maneiras de usar conjuntos de dados e sessões de rotulagem na Avaliação do Agente do Mosaic AI.

Examinar o caderno de exemplo do aplicativo

Obter caderno

Notebook de métricas personalizadas, diretrizes e rótulos de especialistas em domínio da Avaliação do Agente

Obter caderno

Compartilhar via

Usar o aplicativo de revisão para revisões humanas de um aplicativo de inteligência artificial generativa (MLflow 2)

O que acontece em uma avaliação humana?

Requisitos

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

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

Configurar permissões para sessões de rotulagem

Criar um aplicativo de revisão

Usar agents.deploy() automaticamente

Usar manualmente a API do Python

Conceitos

Conjuntos de dados

Sessões de rotulagem

Avaliações e rótulos

Conjuntos de dados

Criar um conjunto de dados

Usando um conjunto de dados para avaliação

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

Sincronizar as expectativas da sessão de rotulagem com o conjunto de dados

Coletar comentários sobre rastreamentos

Coletar comentários de um experimento ou execução do MLFlow

Coletar comentários de uma tabela de inferência

Notebooks de exemplo

Examinar o caderno de exemplo do aplicativo

Notebook de métricas personalizadas, diretrizes e rótulos de especialistas em domínio da Avaliação do Agente

Comentários

Recursos adicionais

Usar `agents.deploy()` automaticamente