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

Сеансы маркировки предоставляют структурированный способ получения отзывов от экспертов домена о поведении приложений GenAI. Сеанс маркировки — это особый тип запуска MLflow, который содержит определенный набор трассировок, которые необходимо проверить экспертами домена с помощью приложения проверки MLflow.

Цель сеанса маркировки — собрать созданные человеком оценки (метки) для существующих трассировок MLflow. Вы можете записывать данные Feedback или Expectation, которые затем можно использовать для улучшения интеллектуального приложения GenAI с помощью систематической оценки и анализа. Дополнительные сведения о сборе оценок во время разработки приложений см. в разделе Label во время разработки.

Сеансы маркировки отображаются на вкладке "Оценки " пользовательского интерфейса MLflow. Так как сеансы разметки регистрируются как запуски MLflow, вы также можете получить доступ к трассировкам и связанным оценкам с помощью API MLflowmlflow.search_runs().

Как работают сеансы маркировки

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

• Имя: описательный идентификатор для сеанса.
• Назначенные пользователи: эксперты домена, которые будут предоставлять метки.
• Агент: (необязательно) Приложение GenAI для создания ответов при необходимости.
• Схемы маркировки: вопросы и формат сбора отзывов. Можно использовать встроенные схемы (EXPECTED_FACTS,, EXPECTED_RESPONSE, GUIDELINES) или создавать пользовательские. Дополнительные сведения о создании и использовании схем см. в статье "Создание схем и управление ими ".
• Многоэтапный чат: следует ли поддерживать маркировку в стиле беседы.

Дополнительные сведения об API LabelingSession см. в разделе mlflow.genai.LabelingSession.

Создайте сеансы маркировки

Сеансы маркировки можно создавать с помощью пользовательского интерфейса или API.

Создание сеансов с помощью пользовательского интерфейса

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

1. В рабочей области Databricks в левой боковой панели щелкните "Эксперименты".

2. Щелкните имя эксперимента, чтобы открыть его.

3. Нажмите сеансы лейблинга на боковой панели.

4. Нажмите кнопку "Создать сеанс". Откроется диалоговое окно создания сеанса маркировки .

   

5. Введите имя сеанса.

   Кроме того, можно также указать набор данных оценки или выбрать схемы маркировки.

   В разделе "Предварительный просмотр меток" можно просмотреть, как отображаются вопросы для рецензентов.

6. Когда вы будете готовы, нажмите кнопку "Создать сеанс". Новый сеанс появится в списке слева от страницы.

7. Чтобы предоставить общий доступ к сеансу рецензентам, щелкните имя сеанса в списке и нажмите кнопку "Поделиться " в правом верхнем углу.

   

8. Введите адрес электронной почты для каждого рецензента и нажмите кнопку "Сохранить". Рецензенты уведомляются и получают доступ к приложению проверки.

Просмотр сеансов с помощью пользовательского интерфейса

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

Появляется уведомление с данными трассировки и оценками проверяющего. Чтобы отобразить входные данные рецензентов, нажмите кнопку "Оценки " в правом верхнем углу.

Создание сеансов с помощью API

Чтобы создать сеансы с полным программным контролем над всеми параметрами конфигурации, используйте API mlflow.genai.labeling.create_labeling_session()MLflow.

Создание базового сеанса

import mlflow.genai.labeling as labeling
import mlflow.genai.label_schemas as schemas

# Create a simple labeling session with built-in schemas
session = labeling.create_labeling_session(
    name="customer_service_review_jan_2024",
    assigned_users=["alice@company.com", "bob@company.com"],
    label_schemas=[schemas.EXPECTED_FACTS]  # Required: at least one schema needed
)

print(f"Created session: {session.name}")
print(f"Session ID: {session.labeling_session_id}")

Создайте сеанс с использованием пользовательских схем меток

import mlflow.genai.labeling as labeling
import mlflow.genai.label_schemas as schemas

# Create custom schemas first
quality_schema = schemas.create_label_schema(
    name="response_quality",
    type="feedback",
    title="Rate the response quality",
    input=schemas.InputCategorical(options=["Poor", "Fair", "Good", "Excellent"]),
    overwrite=True,
)

# Create session using the schemas
session = labeling.create_labeling_session(
    name="quality_assessment_session",
    assigned_users=["expert@company.com"],
    label_schemas=["response_quality", schemas.EXPECTED_FACTS],
)

Управление сеансами маркировки

Дополнительные сведения об API см. в разделе mlflow.genai.get_labeling_sessions и mlflow.genai.delete_labeling_sessions.

Восстановление сеансов

import mlflow.genai.labeling as labeling

# Get all labeling sessions
all_sessions = labeling.get_labeling_sessions()
print(f"Found {len(all_sessions)} sessions")

for session in all_sessions:
    print(f"- {session.name} (ID: {session.labeling_session_id})")
    print(f"  Assigned users: {session.assigned_users}")

Получите конкретный сеанс

import mlflow
import mlflow.genai.labeling as labeling
import pandas as pd

# Get all labeling sessions first
all_sessions = labeling.get_labeling_sessions()

# Find session by name (note: names may not be unique)
target_session = None
for session in all_sessions:
    if session.name == "customer_service_review_jan_2024":
        target_session = session
        break

if target_session:
    print(f"Session name: {target_session.name}")
    print(f"Experiment ID: {target_session.experiment_id}")
    print(f"MLflow Run ID: {target_session.mlflow_run_id}")
    print(f"Label schemas: {target_session.label_schemas}")
else:
    print("Session not found")

# Alternative: Get session by MLflow Run ID (if you know it)
run_id = "your_labeling_session_run_id"
run = mlflow.search_runs(
    experiment_ids=["your_experiment_id"],
    filter_string=f"tags.mlflow.runName LIKE '%labeling_session%' AND attribute.run_id = '{run_id}'"
).iloc[0]

print(f"Found labeling session run: {run['run_id']}")
print(f"Session name: {run['tags.mlflow.runName']}")

Удаление сеансов

import mlflow.genai.labeling as labeling

# Find the session to delete by name
all_sessions = labeling.get_labeling_sessions()
session_to_delete = None
for session in all_sessions:
    if session.name == "customer_service_review_jan_2024":
        session_to_delete = session
        break

if session_to_delete:
    # Delete the session (removes from Review App)
    review_app = labeling.delete_labeling_session(session_to_delete)
    print(f"Deleted session: {session_to_delete.name}")
else:
    print("Session not found")

Добавьте трассировки в сеансы

После создания сеанса необходимо добавить в него трассировки для экспертной проверки. Это можно сделать с помощью пользовательского add_traces() интерфейса или API. Дополнительные сведения об API см. в статье mlflow.genai.LabelingSession.add_traces.

Добавление трассировок с помощью пользовательского интерфейса

Чтобы добавить трассировки в сеанс маркировки, выполните приведенные действия.

1. В рабочей области Databricks в левой боковой панели щелкните "Эксперименты".

2. Щелкните имя эксперимента, чтобы открыть его.

3. Щелкните «Трассы» на боковой панели.

4. Выберите трассировки, которые нужно добавить, установив флажок слева от идентификатора трассировки.

   

5. В раскрывающемся меню "Действия" выберите "Добавить в сеанс маркировки".

   

   Откроется диалоговое окно с существующими сеансами маркировки для эксперимента.

   

6. В диалоговом окне нажмите кнопку "Экспорт" рядом с сеансом маркировки, в который нужно добавить трассировки, а затем нажмите кнопку "Готово".

Добавление трассировок из результатов поиска

1. Инициализируйте клиент OpenAI для подключения к LLM, размещенным в Databricks или OpenAI.

   Размещенные в Databricks LLM

   Используется databricks-openai для получения клиента OpenAI, который подключается к размещенным в Databricks LLM. Выберите модель из доступных базовых моделей.

   import mlflow
   from databricks_openai import DatabricksOpenAI
   
   # Enable MLflow's autologging to instrument your application with Tracing
   mlflow.openai.autolog()
   
   # Set up MLflow tracking to Databricks
   mlflow.set_tracking_uri("databricks")
   mlflow.set_experiment("/Shared/docs-demo")
   
   # Create an OpenAI client that is connected to Databricks-hosted LLMs
   client = DatabricksOpenAI()
   
   # Select an LLM
   model_name = "databricks-claude-sonnet-4"
   

   Хостируемые OpenAI LLMs

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

   import mlflow
   import os
   import openai
   
   # Ensure your OPENAI_API_KEY is set in your environment
   # os.environ["OPENAI_API_KEY"] = "<YOUR_API_KEY>" # Uncomment and set if not globally configured
   
   # Enable auto-tracing for OpenAI
   mlflow.openai.autolog()
   
   # Set up MLflow tracking to Databricks
   mlflow.set_tracking_uri("databricks")
   mlflow.set_experiment("/Shared/docs-demo")
   
   # Create an OpenAI client connected to OpenAI SDKs
   client = openai.OpenAI()
   
   # Select an LLM
   model_name = "gpt-4o-mini"
   

2. Создайте примеры трассировок и добавьте их в сеанс маркировки:

   import mlflow.genai.labeling as labeling
   
   
   # First, create some sample traces with a simple app
   @mlflow.trace
   def support_app(question: str):
    """Simple support app that generates responses"""
    mlflow.update_current_trace(tags={"test_tag": "C001"})
    response = client.chat.completions.create(
        model=model_name,  # This example uses Databricks hosted Claude 3.5 Sonnet. If you provide your own OpenAI credentials, replace with a valid OpenAI model e.g., gpt-4o, etc.
        messages=[
            {"role": "system", "content": "You are a helpful customer support agent."},
            {"role": "user", "content": question},
        ],
    )
    return {"response": response.choices[0].message.content}
   
   # Generate some sample traces
   with mlflow.start_run():
    # Create traces with negative feedback for demonstration
    support_app("My order is delayed")
   
    support_app("I can't log into my account")
   
   # Now search for traces to label
   traces_df = mlflow.search_traces(
    filter_string="tags.test_tag = 'C001'", max_results=50
   )
   
   # Create session and add traces
   session = labeling.create_labeling_session(
    name="negative_feedback_review",
    assigned_users=["quality_expert@company.com"],
    label_schemas=["response_quality", "expected_facts"]
   )
   
   # Add traces from search results
   session.add_traces(traces_df)
   print(f"Added {len(traces_df)} traces to session")
   

Добавление отдельных объектов трассировки

1. Инициализируйте клиент OpenAI для подключения к LLM, размещенным в Databricks или OpenAI.

   Размещенные в Databricks LLM

   Используется databricks-openai для получения клиента OpenAI, который подключается к размещенным в Databricks LLM. Выберите модель из доступных базовых моделей.

   import mlflow
   from databricks_openai import DatabricksOpenAI
   
   # Enable MLflow's autologging to instrument your application with Tracing
   mlflow.openai.autolog()
   
   # Set up MLflow tracking to Databricks
   mlflow.set_tracking_uri("databricks")
   mlflow.set_experiment("/Shared/docs-demo")
   
   # Create an OpenAI client that is connected to Databricks-hosted LLMs
   client = DatabricksOpenAI()
   
   # Select an LLM
   model_name = "databricks-claude-sonnet-4"
   

   Хостируемые OpenAI LLMs

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

   import mlflow
   import os
   import openai
   
   # Ensure your OPENAI_API_KEY is set in your environment
   # os.environ["OPENAI_API_KEY"] = "<YOUR_API_KEY>" # Uncomment and set if not globally configured
   
   # Enable auto-tracing for OpenAI
   mlflow.openai.autolog()
   
   # Set up MLflow tracking to Databricks
   mlflow.set_tracking_uri("databricks")
   mlflow.set_experiment("/Shared/docs-demo")
   
   # Create an OpenAI client connected to OpenAI SDKs
   client = openai.OpenAI()
   
   # Select an LLM
   model_name = "gpt-4o-mini"
   

2. Создайте и добавьте отдельные объекты трассировки в сеанс маркировки:

   import mlflow.genai.labeling as labeling
   
   
   # Set up the app to generate traces
   @mlflow.trace
   def support_app(question: str):
    """Simple support app that generates responses"""
    mlflow.update_current_trace(tags={"test_tag": "C001"})
    response = client.chat.completions.create(
        model=model_name,  # This example uses Databricks hosted Claude 3.5 Sonnet. If you provide your own OpenAI credentials, replace with a valid OpenAI model e.g., gpt-4o, etc.
        messages=[
            {"role": "system", "content": "You are a helpful customer support agent."},
            {"role": "user", "content": question},
        ],
    )
    return {"response": response.choices[0].message.content}
   
   # Generate specific traces for edge cases
   with mlflow.start_run() as run:
    # Create traces for specific scenarios
    support_app("What's your refund policy?")
    trace_id_1 = mlflow.get_last_active_trace_id()
   
    support_app("How do I cancel my subscription?")
    trace_id_2 = mlflow.get_last_active_trace_id()
   
    support_app("The website is down")
    trace_id_3 = mlflow.get_last_active_trace_id()
   
   # Get the trace objects
   trace1 = mlflow.get_trace(trace_id_1)
   trace2 = mlflow.get_trace(trace_id_2)
   trace3 = mlflow.get_trace(trace_id_3)
   
   # Create session and add traces
   session = labeling.create_labeling_session(
    name="negative_feedback_review",
    assigned_users=["name@databricks.com"],
    label_schemas=["response_quality", schemas.EXPECTED_FACTS],
   )
   
   # Add individual traces
   session.add_traces([trace1, trace2, trace3])
   

Получить ответы на отзывы

После завершения сеанса разметки рецензентами MLflow сохраняет их ответы как Assessments в трассах этого сеанса. Их можно получить в пользовательском интерфейсе или с помощью API MLflow.

Пользовательский интерфейс

Откройте пользовательский интерфейс "Эксперименты" , щелкните сеанс маркировки, а затем щелкните запрос. Щелкните оценки в правом верхнем углу, чтобы просмотреть ответы каждого рецензента. Снимок экрана: просмотр сеансов с помощью пользовательского интерфейса.

API

Используйте mlflow.search_traces() с mlflow_run_id сеанса. Возвращаемый кадр данных содержит assessments столбец, содержащий метки каждого рецензента.

import mlflow

traces = mlflow.search_traces(run_id=session.mlflow_run_id)
print(traces[["trace_id", "assessments"]])

Дополнительные сведения об API см. в статье mlflow.search_traces.

Управление назначенными пользователями

Требования к доступу пользователей

Любой пользователь в учетной записи Databricks может быть назначен сеансу маркировки независимо от того, есть ли у них доступ к рабочей области. Однако предоставление пользователю разрешения на сеанс маркировки предоставит доступ к сеансу маркировки и его эксперименту MLflow.

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

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

Добавление пользователей в существующие сеансы

Чтобы добавить пользователей в существующие сеансы, используйте set_assigned_users. Дополнительные сведения об API см. в статье mlflow.genai.LabelingSession.set_assigned_users.

import mlflow.genai.labeling as labeling

# Find existing session by name
all_sessions = labeling.get_labeling_sessions()
session = None
for s in all_sessions:
    if s.name == "customer_review_session":
        session = s
        break

if session:
    # Add more users to the session
    new_users = ["expert2@company.com", "expert3@company.com"]
    session.set_assigned_users(session.assigned_users + new_users)
    print(f"Session now has users: {session.assigned_users}")
else:
    print("Session not found")

Замена назначенных пользователей

import mlflow.genai.labeling as labeling

# Find session by name
all_sessions = labeling.get_labeling_sessions()
session = None
for s in all_sessions:
    if s.name == "session_name":
        session = s
        break

if session:
    # Replace all assigned users
    session.set_assigned_users(["new_expert@company.com", "lead_reviewer@company.com"])
    print("Updated assigned users list")
else:
    print("Session not found")

Синхронизация с наборами данных для оценки

Вы можете синхронизировать собранные данные Expectations с набором для оценки.

Как работает синхронизация наборов данных

Метод sync() выполняет интеллектуальную операцию upsert. Дополнительные сведения об API см. в статье mlflow.genai.LabelingSession.sync.

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

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

Синхронизация наборов данных

import mlflow.genai.labeling as labeling

# Find session with completed labels by name
all_sessions = labeling.get_labeling_sessions()
session = None
for s in all_sessions:
    if s.name == "completed_review_session":
        session = s
        break

if session:
    # Sync expectations to dataset
    session.sync(to_dataset="customer_service_eval_dataset")
    print("Synced expectations to evaluation dataset")
else:
    print("Session not found")

Лучшие практики

Организация сеансов

• Используйте четкие, описательные названия с датами, например customer_service_review_march_2024.

• Сохраняйте сеансы, ориентированные на определенные цели оценки или периоды времени.

• Стремитесь к 25-100 трассировок на сеанс, чтобы избежать усталости рецензента.

• Всегда сохраняйте session.mlflow_run_id при создании сеанса. Используйте идентификатор выполнения для программного доступа вместо того, чтобы полагаться на имена сеансов, так как имя сеанса может не быть уникальным.

  import mlflow.genai.labeling as labeling
  
  # Good: Store run ID for later reference
  session = labeling.create_labeling_session(name="my_session", ...)
  session_run_id = session.mlflow_run_id  # Store this!
  
  # Later: Use run ID to find session via mlflow.search_runs()
  # rather than searching by name through all sessions
  

Управление пользователями

• Назначьте пользователей на основе их профессиональной области и доступности.
• Равномерно распределяйте работу по маркировке между несколькими экспертами.
• Помните, что у пользователей должен быть доступ к рабочей области Databricks.

Дальнейшие шаги

• Отметьте существующие трассировки - Пошаговое руководство по использованию сеансов маркировки.
• Создание пользовательских схем маркировки — определение структурированных вопросов обратной связи
• Создание наборов данных оценки . Преобразование помеченных сеансов в тестовые наборы данных