Use o aplicativo de avaliação para avaliações humanas de um aplicativo do gênero AI

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

• Dê às partes interessadas a possibilidade de conversar com um aplicativo gerador de pré-produção AI e dar feedback.
• Crie uma avaliação dataset, apoiada por uma tabela Delta em Unity Catalog.
• Aproveite as PMEs para expandir e iterar essa avaliação dataset.
• Utilize as PMEs para rastrear a produção de rótulos para entender a qualidade de seu aplicativo gen AI.

O que acontece em uma avaliação humana?

O aplicativo de revisão da Databricks prepara um ambiente em que as partes interessadas podem interagir com ele - em outras palavras, conversar, fazer perguntas, fornecer feedback e assim por diante.

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

1. Converse com o bot : Colete perguntas, respostas e feedback em uma tabela de inferência para que o senhor possa analisar melhor o desempenho do aplicativo gen AI. Dessa forma, o aplicativo de avaliação ajuda a garantir a qualidade e a segurança das respostas que seu aplicativo fornece.
2. respostas do rótulo em uma sessão : Colete feedback e expectativas das PMEs em uma sessão de rótulo, armazenada em uma execução do MLFLow. Opcionalmente, o senhor pode sincronizar esses rótulos com uma avaliação dataset.

Requisitos

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

Python

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

• Para conversar com o bot:

  • As tabelas de inferência devem estar ativadas no endpoint que está servindo o agente.
  • Cada avaliador humano deve ter acesso ao aplicativo de avaliação workspace ou estar sincronizado com o seu Databricks account com SCIM. Consulte a próxima seção, Configurar permissões para usar o aplicativo de avaliação.

• Para sessões de rótulo:

  • Cada revisor humano deve ter acesso ao aplicativo de revisão workspace.

Configurar permissões para usar o aplicativo de avaliação

nota

• Para conversar com o bot, um revisor humano não precisa ter acesso ao site workspace.
• Para uma sessão de rótulo, um revisor humano precisa ter acesso ao site workspace.

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

• Para usuários que não têm acesso workspace ao, um administrador do account usa accounto SCIM provisionamento de nível para sincronizar usuários e grupos automaticamente do provedor de identidade para o Databricks account. O senhor também pode registrar manualmente esses usuários e grupos para dar-lhes acesso quando configurar identidades em Databricks. Consulte Sincronizar usuários e grupos do seu provedor de identidade usando o SCIM.
• Para os usuários que já têm acesso ao site workspace que contém o aplicativo de revisão, não é necessária nenhuma configuração adicional.

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 recebe uma lista de endereços email.

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)

nota

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

Configurar permissões para sessões de rótulo

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

Crie um aplicativo de avaliação

Usando automaticamente agents.deploy()

Quando o senhor implanta um aplicativo gen AI usando agents.deploy(), o aplicativo de revisão é automaticamente ativado e implantado. A saída do comando mostra o URL do aplicativo de revisão. Para obter informações sobre o aplicativo gen AI implantado (também chamado de agente "" , consulte implantado um agente para aplicativos generativos AI.

nota

O agente não aparece na interface do usuário do aplicativo de revisão até que o endpoint seja totalmente implantado.

Se você perder o link para a interface do usuário do aplicativo de avaliação, poderá encontrá-lo usando 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".

Usando manualmente a API do Python

O trecho de código abaixo demonstra como criar um aplicativo de revisão e associá-lo a um modelo de serviço endpoint para conversar com o bot. Para criar sessões de rótulo, consulte

• Crie uma sessão de rótulo e envie para revisão de rótulo uma avaliação dataset.
• Coletar feedback sobre traços para rótulo traços. Observe que não é necessário um agente ativo para isso.

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

Conceitos

conjunto de dados

Um conjunto de dados é uma coleção de exemplos usados para avaliar um AI aplicativo do site. Os registros do conjunto de dados contêm entradas para um aplicativo gen AI e, opcionalmente, expectativas (rótulo da verdade básica, como expected_facts ou guidelines). estão vinculados a um experimento MLFlow e podem ser usados diretamente como entradas para mlflow.evaluate(). são apoiados pelas tabelas Delta em Unity Catalog, herdando as permissões definidas pela tabela Delta. Para criar um dataset, consulte Criar um conjunto de dados.

Exemplo de avaliação dataset, mostrando apenas as colunas de entradas e expectativas:

O conjunto de dados de avaliação tem o seguinte esquema:

Coluna	Tipo de dados	Descrição
conjunto de dados	string	O identificador exclusivo do registro.
entradas	string	Entradas para avaliação como JSON serializadas dict<str, Any>
Expectativas	string	Valores esperados como JSON serializado dict<str, Any>
create_time	carimbo de data/hora	A hora em que o registro foi criado.
criado_por	string	O usuário que criou o registro.
hora da última atualização	carimbo de data/hora	A hora em que o registro foi atualizado pela última vez.
último atualizado_por	string	O usuário que atualizou o registro pela última vez.
Origem	struct	A fonte do registro dataset
fonte.human	struct	Definido quando a fonte é de um humano
fonte.human.nome_do_usuário	string	O nome do usuário associado ao registro.
fonte.documento	string	Definido quando o registro foi sintetizado a partir de um documento
fonte.document.doc_uri	string	O URI do documento.
fonte.documento.conteúdo	string	O conteúdo do documento.
fonte.trace	string	Definido quando o registro foi criado a partir de um rastreamento
fonte.trace.trace_id	string	O identificador exclusivo do rastreamento.
tags	map	Tags de valor-chave para o registro dataset

rótulo Sessões

Um LabelingSession é um conjunto finito de traços ou dataset registros para serem rótulo por um SME na UI do aplicativo de revisão. Os rastreamentos podem vir de tabelas de inferência para uma aplicação em produção ou de um rastreamento offline em experimentos de MLflow. Os resultados são armazenados como uma execução do MLFlow. rótulo são armazenados como Assessments em MLFlow Traces. rótulo com "expectativas" pode ser sincronizado de volta a um conjunto de dados de avaliação.

Avaliações e rótulo

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

• expectationRótulo que representa 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 com uma avaliação dataset para que possam ser usados com mlflow.evaluate().
• feedbackO senhor pode usar o rótulo que representa um feedback simples sobre um rastreamento, como "thumbs up" e "thumbs down", ou comentários de forma livre. Assessments do tipo feedback não são usados com o conjunto de dados de avaliação, pois são uma avaliação humana de um determinado traço do MLFLow. Essas avaliações podem ser lidas com mlflow.search_traces().

conjunto de dados

Esta seção explica como fazer o seguinte:

• Crie um dataset e use-o para avaliação, sem um SME.
• Solicite uma sessão de rótulo de uma PME para selecionar uma avaliação melhor dataset.

Criar um conjunto de dados

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

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.
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 site dataset são apoiados por uma tabela Delta em Unity Catalog e são visíveis no Catalog Explorer.

nota

No momento, não há suporte para diretrizes nomeadas (usando um dicionário) em uma sessão de rótulo.

Usando o site dataset para avaliação

O exemplo a seguir lê o dataset de Unity Catalog, usando a avaliação dataset para avaliar um agente simples de prompt do sistema.

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

Criar uma sessão de rótulo e enviar para revisão

O exemplo a seguir cria uma LabelingSession a partir do site dataset acima usando ReviewApp.create_labeling_session, Configurar a sessão para coletar guidelines e expected_facts das PMEs usando o ReviewApp.rótulo campo. O senhor também pode criar esquemas de rótulos personalizados com ReviewApp.create_label_schema

nota

• Ao criar uma sessão de rótulo, os usuários atribuídos são:

  • Recebeu permissão WRITE para o experimento MLflow.
  • Permissão QUERY dada a qualquer endpoint de modelo de serviço associado ao aplicativo de revisão.

• Ao adicionar um dataset a uma sessão de rótulo, os usuários designados recebem permissão SELECT para as tabelas delta do conjunto de dados usado para semear a sessão de rótulo.

Para conceder permissões a todos os usuários no site workspace, defina 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)

Nesse ponto, o senhor pode enviar os URLs acima para as PMEs.

Enquanto seu SME estiver em rótulo, o senhor pode view o status do rótulo com o seguinte código:

Python

mlflow.search_traces(run_id=my_session.mlflow_run_id)

Sincronizar as expectativas da sessão de rótulos de volta ao dataset

Depois que o SME tiver concluído o rótulo, o senhor poderá sincronizar o rótulo expectation de volta para o site dataset com LabelingSession.sync_expectations. Exemplos de rótulo com o tipo expectation incluem GUIDELINES, EXPECTED_FACTS ou seu próprio esquema de rótulo personalizado que tenha um tipo expectation.

Python

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

Agora o senhor pode usar essa avaliação dataset:

Python

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

Colete feedback sobre rastreamentos

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

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

Coletar feedback de um experimento ou execução do MLFlow

Esses exemplos criam um conjunto de traços a serem rotulados por seus SMEs.

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

O senhor pode obter o rótulo para o rastreamento e criar uma sessão de rótulo a partir dele. Este exemplo configura uma sessão de rótulo com um único esquema de rótulo para coletar "formality" feedback sobre a resposta do Agente. O rótulo do SME é armazenado como uma avaliação no MLFlow Trace.

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

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)

Depois que o SME terminar o rótulo, os rastros e as avaliações resultantes se tornarão parte da execução associada à sessão de rótulo.

Python

mlflow.search_traces(run_id=my_session.mlflow_run_id)

Agora o senhor pode usar essas avaliações para aprimorar seu modelo ou atualizar a avaliação dataset.

Colete feedback de uma tabela de inferência

Este exemplo mostra como adicionar traços diretamente da tabela de inferência (carga útil da solicitação logs) em uma sessão de rótulo.

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)

Exemplo de notebook

O Notebook a seguir ilustra as diferentes maneiras de usar sessões de conjunto de dados e rótulo em Mosaic AI Agent Evaluation.

Exemplo de aplicativo de revisão Notebook

Open notebook in new tab

Avaliação do agente métricas personalizadas, diretrizes e rótulo de especialista em domínio Notebook

Open notebook in new tab