ラベリングセッション

ラベリングセッションは、生成AIアプリケーションの動作に関するドメインエキスパートからのフィードバックを収集するための構造化された方法を提供します。ラベル付けセッションは、MLflow レビューアプリを使用してドメインの専門家にレビューしてもらう特定のトレースセットを含む特殊な種類の MLflow 実行です。

ラベル付けセッションの目標は、既存のMLflowトレースに対して人間が作成したAssessments (ラベル) を収集することです。Feedback または Expectationsをキャプチャし、体系的な評価を通じて生成AI アプリを改善するために使用できます。

注記

ラベリングセッションは MLflow の実行であるため、収集されたデータ (トレースとそれに関連する Assessments) は、MLflow SDK ( mlflow.search_runs()など) を使用してプログラムでアクセスし、MLflow UI 内で視覚化できます (各ラベリングセッションは [評価] タブに表示されます)。

ラベリングセッションの仕組み

ラベリングセッションを作成するときは、次の項目を定義します。

名前 : セッションのわかりやすい識別子
割り当てられたユーザー : ラベルを提供するドメインの専門家
エージェント : (オプション) 必要に応じて応答を生成する生成AI アプリ
ラベルスキーマ :フィードバック収集の質問と形式
マルチターンチャット : 会話スタイルのラベル付けをサポートするかどうか

このセッションは、トレースとそれに関連するラベルのコンテナとして機能し、評価と改善のワークフローを推進できる体系的なフィードバック収集を可能にします。

ラベリングセッションの作成

mlflow.genai.labeling.create_labeling_session() を使用して、特定の構成で新しいセッションを作成します。

UI を使用したセッションの作成

MLflow UI の ラベリング タブに移動して、セッションを視覚的に作成します。これにより、セッションパラメーターの定義、ユーザーの割り当て、ラベルスキーマの選択を、コードを記述せずに直感的なインターフェイスが提供されます。

ラベルセッション

UIによるセッションの表示

MLflow UI の ラベリング タブに移動して、セッションを視覚的に表示します。

ラベルセッション

プログラムによるセッションの作成

MLflow SDK を使用して、すべての構成オプションをプログラムで完全に制御するセッションを作成します。

基本的なセッション作成

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

警告

ラベル付けセッション名は一意であるとは限りません。複数のセッションに同じ名前を付けることができます。信頼性の高いプログラムによるアクセスを実現するには、名前ではなく MLflow 実行 ID (session.mlflow_run_id) でセッションを保存および参照します。

注記

ラベルスキーマは、ラベル付けセッションを作成するときに必要です。組み込みスキーマ (EXPECTED_FACTS、 EXPECTED_RESPONSE、 GUIDELINES) を使用するか、カスタムスキーマを作成できます。スキーマの作成と使用に関する詳細な情報については、ラベル付けスキーマガイドを参照してください。

カスタムラベルスキーマを使用したセッション

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

# Create custom schemas first (see Labeling Schemas guide)
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],
)

ラベリングセッションの管理

警告

セッション名のラベル付けは一意ではないため、名前でセッションを検索すると、複数の一致または予期しない結果が返される可能性があります。本番運用ワークフローの場合、セッションを MLflow 実行 ID で保存および参照することをお勧めします。

セッションの取得

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

特定のセッションを取得する

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

注記

ラベル付けセッション名は一意であるとは限らないため、プログラムで特定のセッションを取得する必要がある場合は、MLflow 実行 ID でセッションを格納および参照することをお勧めします。

セッションの削除

Python
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() メソッドを使用して専門家によるレビューのためにセッションにトレースを入力します。

注記

レビューアプリUI でトレースをレンダリングしてラベラーに表示する方法、さまざまなデータ型 (ディクショナリ、OpenAI メッセージ、ツール呼び出し) の表示方法などの詳細については、レビューアプリガイドを参照してください。

UI を使用したトレースの追加

また、MLflow UI を使用して トレース タブに移動し、含めるトレースを選択し、エクスポート機能を使用してラベル付けセッションに追加することで、トレースを直接追加することもできます。

検索結果からのトレースの追加

Python
import mlflow
import mlflow.genai.labeling as labeling
from openai import OpenAI

# First, let's create some sample traces with a simple app
# Connect to a Databricks LLM via OpenAI using the same credentials as MLflow
# Alternatively, you can use your own OpenAI credentials here
mlflow_creds = mlflow.utils.databricks_utils.get_databricks_host_creds()
client = OpenAI(
    api_key=mlflow_creds.token,
    base_url=f"{mlflow_creds.host}/serving-endpoints"
)

@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="databricks-claude-3-7-sonnet",  # 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")

個々のトレースオブジェクトの追加

Python
import mlflow
import mlflow.genai.labeling as labeling
from openai import OpenAI

# Set up the app to generate traces
# Connect to a Databricks LLM via OpenAI using the same credentials as MLflow
# Alternatively, you can use your own OpenAI credentials here
mlflow_creds = mlflow.utils.databricks_utils.get_databricks_host_creds()
client = OpenAI(
    api_key=mlflow_creds.token,
    base_url=f"{mlflow_creds.host}/serving-endpoints"
)

@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="databricks-claude-3-7-sonnet",  # 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=["nikhil.thorat@databricks.com"],
    label_schemas=["response_quality", schemas.EXPECTED_FACTS],
)

# Add individual traces
session.add_traces([trace1, trace2, trace3])

割り当てられたユーザーの管理

ユーザーアクセス要件

Databricks アカウント内のすべてのユーザーは、ワークスペースへのアクセス権があるかどうかに関係なく、ラベル付けセッションに割り当てることができます。ただし、ラベル付けセッションに対するアクセス許可をユーザーに付与すると、ラベル付けセッションの MLflow エクスペリメントにアクセスできるようになります。

ユーザーの権限の設定

ワークスペースにアクセスできないユーザーの場合、アカウント管理者はアカウントレベルの SCIM プロビジョニングを使用して、ユーザーとグループを ID プロバイダーから Databricks アカウントに自動的に同期します。また、これらのユーザーとグループを手動で登録して、 Databricksで ID を設定するときにアクセス権を付与することもできます。ユーザーとグループの管理を参照してください。
レビューアプリを含むワークスペースへのアクセス権を既に持っているユーザーの場合、追加の構成は必要ありません。

important

ラベリングセッションにユーザーを割り当てると、ラベリングセッションを含むMLflowエクスペリメントに必要な WRITE 権限が自動的に付与されます。これにより、割り当てられたユーザーは、エクスペリメントデータを表示および操作するためのアクセス権が付与されます。

既存のセッションへのユーザーの追加

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

割り当てられたユーザーの置き換え

Python
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() メソッドは、インテリジェントなアップサート操作を実行します。

一意のキー : 各トレースの入力は、データセット内のレコードを識別するための一意のキーとして機能します
期待値の更新 : 入力が一致するトレースの場合、ラベリングセッションからの期待値によってデータセット内の既存の期待値が上書きされます (期待値の名前が同じ場合)
新しいレコード : データセットに存在しないラベリングセッションのトレース (入力マッチングに基づく) は、新しいレコードとして追加されます
保持 : 異なる入力を持つ既存のデータセットレコードは変更されません

このアプローチにより、新しい例を追加し、既存の例のグラウンドトゥルースを更新することで、以前の作業を失うことなく、評価データセットを繰り返し改善できます。

データセットの同期

Python
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(dataset_name="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 を保存してください。プログラムによるアクセスには、セッション名に頼るのではなく、実行 ID を使用します。

Python
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 Workspace へのアクセスが必要であることを忘れないでください

概要

MLflow ラベル付けセッションは、生成AI アプリケーションに関する専門家のフィードバックを収集するための構造化されたフレームワークを提供します。ラベルスキーマとレビューアプリとセッションを組み合わせることで、評価と改善のワークフローを推進する高品質の人間による評価を体系的に収集できます。

主な機能は次のとおりです。

カスタム構成による 柔軟なセッション作成
ユーザー割り当てと権限管理
評価ワークフローのための データセットの同期

ラベリングセッションを使用して、アドホックなフィードバック収集を体系的で反復可能なプロセスに変換し、生成AIアプリケーションを継続的に改善します。

次のステップ

既存のトレースのラベル付け - ラベル付けセッションを使用したステップバイステップガイド
カスタムラベリングスキーマの作成 - 構造化されたフィードバックの質問を定義します
評価データセットの構築 - ラベル付けされたセッションをテストデータセットに変換します

ラベリングセッションの仕組み​

ラベリングセッションの作成​

UI を使用したセッションの作成​

UIによるセッションの表示​

プログラムによるセッションの作成​

基本的なセッション作成​

カスタムラベルスキーマを使用したセッション​

ラベリングセッションの管理​

セッションの取得​

特定のセッションを取得する​

セッションの削除​

セッションへのトレースの追加​

UI を使用したトレースの追加​

検索結果からのトレースの追加​

個々のトレースオブジェクトの追加​

割り当てられたユーザーの管理​

ユーザーアクセス要件​

ユーザーの権限の設定​

既存のセッションへのユーザーの追加​

割り当てられたユーザーの置き換え​

評価データセットへの同期​

データセットの同期のしくみ​

データセットの同期​

ベストプラクティス​

セッションの構成​

ユーザー管理​

概要​

次のステップ​