Используйте приложение для проверки человеком ИИ-приложения (MLflow 2)

В этой статье описывается, как использовать приложение проверки для получения отзывов от экспертов по темам (SMEs). Для выполнения следующих действий можно использовать приложение проверки:

• Предоставьте заинтересованным сторонам возможность общаться с предрелизным ИИ-приложением и давать обратную связь.
• Создайте набор данных оценки, поддерживаемый таблицей Delta в каталоге Unity.
• Используйте SMEs для расширения и итерации этого набора данных оценки.
• Использование SMEs для маркировки рабочих трассировок для понимания качества приложения ИИ.

Что происходит в оценке человека?

Приложение для обзора Databricks создаёт среду, где заинтересованные стороны могут взаимодействовать с ним, иначе говоря, общаться, задавать вопросы, оставлять отзывы и т. д.

Существует два основных способа использования приложения проверки:

1. Чат с ботом: сбор вопросов, ответов и отзывов в таблице вывода, чтобы можно было дополнительно проанализировать производительность приложения ИИ. Таким образом, приложение проверки помогает обеспечить качество и безопасность ответов, которые предоставляет ваше приложение.
2. Ответы на метки в сеансе: сбор отзывов и ожиданий от экспертов в области, участвуемых в сеансе разметки, хранящихся в выполнении MLFLow. При необходимости эти метки можно синхронизировать с набором данных оценки.

Requirements

• Разработчики должны установить пакет SDK databricks-agents, чтобы настроить разрешения и настроить приложение проверки.

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

• Для чата с ботом:
  • Инференсные таблицы должны быть включены на конечной точке, которая обслуживает агента.
  • Каждый рецензент должен иметь доступ к рабочему пространству приложения для проверки или быть синхронизированным с вашей учетной записью Azure Databricks с помощью SCIM. См. следующий раздел : настройка разрешений для использования рецензирующего приложения.
• Для сеансов маркировки:
  • Каждый рецензент должен иметь доступ к рабочей области приложения для рецензирования.

настройка разрешений для использования приложения для отзывов

Разрешения на настройку для "Чат с ботом"

• Для пользователей, у которых нет доступа к рабочей области, администратор учетной записи использует внедрение SCIM на уровне учетной записи для автоматической синхронизации пользователей и групп от вашего поставщика удостоверений в вашу учетную запись Azure Databricks. Вы также можете вручную зарегистрировать этих пользователей и группы, чтобы дать им доступ при настройке идентификаций в Databricks. См. раздел Синхронизация пользователей и групп из идентификатора Microsoft Entra с помощью SCIM.
• Для пользователей, у которых уже есть доступ к рабочей области, содержащей приложение проверки, дополнительная конфигурация не требуется.

В следующем примере кода показано, как предоставить пользователям разрешение на развертывание модели с помощью agents.deploy. Параметр users принимает список адресов электронной почты.

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)

Настройка разрешений для сеансов маркировки

Пользователям автоматически предоставляются соответствующие права (права на запись к эксперименту и права на чтение к набору данных) при создании сеанса маркировки и предоставлении аргумента assigned_users. Дополнительные сведения см. в статье Создание сеанса маркировки и отправка для проверки ниже.

Создание приложения проверки

Автоматическое использование agents.deploy()

При развертывании ИИ-приложения с помощью agents.deploy() приложение для проверки автоматически включается и разворачивается. Выходные данные команды показывают URL-адрес для приложения проверки. Сведения о развертывании приложения ИИ (также называемого агентом) см. в статье "Развертывание агента для приложений ИИ (обслуживание моделей)".

Если вы потеряете ссылку на интерфейс приложения для обзора, вы можете найти его с помощью 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".

Использование API 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

Наборы данных

Набор данных — это коллекция примеров, используемых для оценки приложения ИИ. Записи набора данных содержат входные данные для ИИ-приложения и необязательно ожидаемые результаты (эталонные метки, например expected_facts или guidelines). Наборы данных связаны с экспериментом MLFlow и могут использоваться непосредственно в качестве входных данных для mlflow.evaluate(). Наборы данных поддерживаются таблицами Delta в каталоге Unity, наследуя разрешения, определенные таблицей Delta. Сведения о создании набора данных см. в статье Создание набора данных.

Пример набора данных оценки, показывающий только входные и ожидаемые столбцы:

Наборы данных оценки имеют следующую схему:

Сеансы маркировки

LabelingSession — это конечный набор записей трассировок или данных, которые должны быть помечены SME в пользовательском интерфейсе приложения проверки. Трассировки могут поступать из таблиц вывода данных для приложения в промышленной среде или из офлайн-трассировки в экспериментах MLFlow. Результаты хранятся в виде сеанса MLFlow. Метки хранятся в виде Assessment в трассировках MLFlow. Метки с "ожиданиями" можно синхронизировать обратно с оценочным набором данных.

Оценки и метки

Когда SME помечает трассировку, оценки записываются в трассировку в поле Trace.info.assessments. Assessments может иметь два типа:

• expectation: метки, обозначающие то, что должно быть в правильной трассировке. Например, expected_facts можно использовать как метку expectation, представляющую факты, которые должны присутствовать в идеальном ответе. Эти expectation метки можно синхронизировать обратно в оценочный набор данных, чтобы их можно было использовать с mlflow.evaluate().
• feedback: Метки, представляющие простую обратную связь по следу, например, "лайк" и "дизлайк", или комментарии в свободной форме. Assessmentтипа feedback не используются с оценочными наборами данных, поскольку они представляют собой оценку, выполненную человеком для определенной трассировки MLFLow. Эти оценки можно считывать с помощью mlflow.search_traces().

Наборы данных

В этом разделе объясняется, как выполнить следующие действия.

• Создайте набор данных и используйте его для оценки без SME.
• Запросите проведение сеанса аннотации данных у эксперта в своей области для улучшения набора данных оценки.

Создание набора данных

В следующем примере создается набор данных и вставляются оценки. Чтобы заполнить набор данных искусственными оценками, см. Синтезировать наборы оценок.

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)

Данные из этого набора данных поддерживаются таблицей Delta в каталоге Unity и отображаются в обозревателе каталогов.

Использование набора данных для оценки

В следующем примере считывается набор данных из каталога Unity, при этом используется оценочный набор данных для оценки простого агента для системных запросов.

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

Создание сеанса маркировки и отправка для проверки

В следующем примере создается labelingSession из приведенного выше набора данных с помощью ReviewApp.create_labeling_session, при настройке сеанса для сбора guidelines и expected_facts из SMEs с помощью поля ReviewApp.label_schemas. Можно также создавать настраиваемые схемы меток с помощью 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)

На этом этапе вы можете отправить URL-адреса, указанные выше, в ваши SMEs.

Когда ваш SME выполняет маркировку, вы можете просмотреть состояние процесса маркировки с помощью следующего кода:

mlflow.search_traces(run_id=my_session.mlflow_run_id)

Синхронизируйте ожидания от сеанса маркировки с набором данных.

После того как SME завершит маркировку, вы можете синхронизировать метки expectation обратно с набором данных, используя LabelingSession.sync_expectations. Примеры меток с типом expectation включают GUIDELINES, EXPECTED_FACTSили собственную настраиваемую схему меток с типом expectation.

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

Теперь этот набор данных оценки можно использовать:

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

Сбор обратной связи по трассировкам

В этом разделе описывается, как собирать метки на объектах трассировки MLFlow, которые могут поступать из любого из следующих:

• Эксперимент MLFlow или запуск.
• Таблица вывода.
• Любой Python-объект трассировки MLFlow.

Собрать отзывы из эксперимента или запуска в MLFlow

В этом примере создается набор трассировок, помеченных вашими 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"}])

Вы можете получать метки для отслеживания и на их основе создать сессию маркировки. В этом примере настраивается сеанс маркировки с одной схемой меток для сбора отзывов о "формальности" ответа агента. Метки из SME хранятся как Assessment на трассе MLFlow.

Дополнительные типы входных данных схемы см. в пакете SDK 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)

После завершения маркировки экспертом полученные трассировки и оценки становятся частью процедуры, связанной с сеансом маркировки.

mlflow.search_traces(run_id=my_session.mlflow_run_id)

Теперь эти оценки можно использовать для улучшения модели или обновления набора данных оценки.

Найдите ответы на обратную связь в таблице инференса

Если для вашего эндпоинта включены таблицы инференса, Databricks также записывает ответы с обратной связью в представление assessment-logs по адресу:

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

Это представление заменяет устаревшую таблицу _payload_assessment_logs. Полную схему и статус устаревания см. в разделе Таблицы вывода агента: журналы запросов и оценок (устарело).

Сбор отзывов из таблицы вывода

В этом примере показано, как добавлять трассы непосредственно из таблицы вывода (журналы полезной нагрузки запроса) в сессию маркировки.

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

примеры записных книжек

В следующих блокнотах показаны различные способы использования наборов данных и сессий разметки в оценке агентов.

Пример записной книжки для приложения обзоров

Получите ноутбук

Блокнот для оценки агентов с пользовательскими метриками, рекомендациями и метками экспертов по домену

Получите ноутбук