スキーマのラベル付け

2025-06-11

ラベル付けスキーマでは、レビューアプリで既存のトレースにラベルを付ける際にドメインエキスパートが回答する特定の質問を定義します。フィードバック収集プロセスを構成し、GenAI アプリを評価するための一貫性のある関連情報を確保します。

注

スキーマのラベル付けは、レビューアプリを使用して既存のトレースにラベルを付ける場合にのみ適用され、レビューアプリを使用してチャット UI で新しいアプリバージョンをテストする場合は適用されません。

ラベル付けスキーマの仕組み

ラベル付けセッションを作成するときは、それを 1 つ以上のラベル付けスキーマに関連付けます。各スキーマは、FeedbackにアタッチされるExpectationまたはAssessmentを表します。

スキーマコントロール:

レビュー担当者に表示される質問
入力メソッド (ドロップダウン、テキストボックスなど)
検証規則と制約
オプションの手順とコメント

Von Bedeutung

ラベル付けスキーマ名は、各 MLflow 実験内で一意である必要があります。同じ実験で同じ名前を持つ 2 つのスキーマを持つことはできませんが、異なる実験間でスキーマ名を再利用できます。

一般的なユースケースのスキーマのラベリング

MLflow は、期待値を使用する定義済みのスコアラーに対して定義済みのスキーマ名を提供します。これらの名前を使用してカスタムスキーマを作成して、組み込みの評価機能との互換性を確保できます。

ガイドラインスコアラーと連携する
- GUIDELINES: 要求に対して GenAI アプリが従う必要がある理想的な指示を収集します
正確性スコアラーと連携する
- EXPECTED_FACTS: 正確性のために含める必要がある事実に関する記述を収集します
- EXPECTED_RESPONSE:完全な地上の真実の答えを収集します

一般的なユースケースのスキーマの作成

import mlflow.genai.label_schemas as schemas
from mlflow.genai.label_schemas import LabelSchemaType, InputTextList, InputText

# Schema for collecting expected facts
expected_facts_schema = schemas.create_label_schema(
    name=schemas.EXPECTED_FACTS,
    type=LabelSchemaType.EXPECTATION,
    title="Expected facts",
    input=InputTextList(max_length_each=1000),
    instruction="Please provide a list of facts that you expect to see in a correct response.",
    overwrite=True
)

# Schema for collecting guidelines
guidelines_schema = schemas.create_label_schema(
    name=schemas.GUIDELINES,
    type=LabelSchemaType.EXPECTATION,
    title="Guidelines",
    input=InputTextList(max_length_each=500),
    instruction="Please provide guidelines that the model's output is expected to adhere to.",
    overwrite=True
)

# Schema for collecting expected response
expected_response_schema = schemas.create_label_schema(
    name=schemas.EXPECTED_RESPONSE,
    type=LabelSchemaType.EXPECTATION,
    title="Expected response",
    input=InputText(),
    instruction="Please provide a correct agent response.",
    overwrite=True
)

カスタムラベル付けスキーマの作成

ドメインの特定のフィードバックを収集するカスタムスキーマを作成します。スキーマは、MLflow UI を使用するか、SDK を使用してプログラムで作成できます。

注

スキーマ名は、現在の MLflow 実験内で一意である必要があります。各スキーマの目的を明確に示すわかりやすい名前を選択します。

UI を使用したスキーマの作成

MLflow UI の [ ラベル付け ] タブに移動して、スキーマを視覚的に作成します。これにより、コードを記述せずに質問、入力型、および検証規則を定義するための直感的なインターフェイスが提供されます。

人間のフィードバック

プログラムによるスキーマの作成

すべてのスキーマには、名前、型、タイトル、および入力の仕様が必要です。

基本的なスキーマの作成

import mlflow.genai.label_schemas as schemas
from mlflow.genai.label_schemas import InputCategorical, InputText

# Create a feedback schema for rating response quality
quality_schema = schemas.create_label_schema(
    name="response_quality",
    type="feedback",
    title="How would you rate the overall quality of this response?",
    input=InputCategorical(options=["Poor", "Fair", "Good", "Excellent"]),
    instruction="Consider accuracy, relevance, and helpfulness when rating."
)

スキーマの種類

次の 2 つのスキーマの種類から選択します。

feedback: 評価、好み、意見などの主観的評価
expectation:正しい答えや期待される行動のような客観的な地上の真実

import mlflow.genai.label_schemas as schemas
from mlflow.genai.label_schemas import InputCategorical, InputTextList

# Feedback schema for subjective assessment
tone_schema = schemas.create_label_schema(
    name="response_tone",
    type="feedback",
    title="Is the response tone appropriate for the context?",
    input=InputCategorical(options=["Too formal", "Just right", "Too casual"]),
    enable_comment=True  # Allow additional comments
)

# Expectation schema for ground truth
facts_schema = schemas.create_label_schema(
    name="required_facts",
    type="expectation",
    title="What facts must be included in a correct response?",
    input=InputTextList(max_count=5, max_length_each=200),
    instruction="List key facts that any correct response must contain."
)

ラベル付けスキーマの管理

SDK 関数を使用して、スキーマをプログラムで管理します。

スキーマの取得

import mlflow.genai.label_schemas as schemas

# Get an existing schema
schema = schemas.get_label_schema("response_quality")
print(f"Schema: {schema.name}")
print(f"Type: {schema.type}")
print(f"Title: {schema.title}")

スキーマの更新

import mlflow.genai.label_schemas as schemas
from mlflow.genai.label_schemas import InputCategorical

# Update by recreating with overwrite=True
updated_schema = schemas.create_label_schema(
    name="response_quality",
    type="feedback",
    title="Rate the response quality (updated question)",
    input=InputCategorical(options=["Excellent", "Good", "Fair", "Poor", "Very Poor"]),
    instruction="Updated: Focus on factual accuracy above all else.",
    overwrite=True  # Replace existing schema
)

スキーマの削除

import mlflow.genai.label_schemas as schemas

# Remove a schema that's no longer needed
schemas.delete_label_schema("old_schema_name")

カスタムスキーマの入力型

MLflow では、さまざまな種類のフィードバックを収集するための 5 種類の入力がサポートされています。

Single-Select ドロップダウン (`InputCategorical`)

相互に排他的なオプションに使用します。

from mlflow.genai.label_schemas import InputCategorical

# Rating scale
rating_input = InputCategorical(
    options=["1 - Poor", "2 - Below Average", "3 - Average", "4 - Good", "5 - Excellent"]
)

# Binary choice
safety_input = InputCategorical(options=["Safe", "Unsafe"])

# Multiple categories
error_type_input = InputCategorical(
    options=["Factual Error", "Logical Error", "Formatting Error", "No Error"]
)

複数選択ドロップダウン (`InputCategoricalList`)

複数のオプションを選択できる場合に使用します。

from mlflow.genai.label_schemas import InputCategoricalList

# Multiple error types can be present
errors_input = InputCategoricalList(
    options=[
        "Factual inaccuracy",
        "Missing context",
        "Inappropriate tone",
        "Formatting issues",
        "Off-topic content"
    ]
)

# Multiple content types
content_input = InputCategoricalList(
    options=["Technical details", "Examples", "References", "Code samples"]
)

Free-Form テキスト (`InputText`)

オープンエンドの応答に使用します。

from mlflow.genai.label_schemas import InputText

# General feedback
feedback_input = InputText(max_length=500)

# Specific improvement suggestions
improvement_input = InputText(
    max_length=200  # Limit length for focused feedback
)

# Short answers
summary_input = InputText(max_length=100)

複数のテキストエントリ (`InputTextList`)

テキストアイテムのリストを収集するために使用します。

from mlflow.genai.label_schemas import InputTextList

# List of factual errors
errors_input = InputTextList(
    max_count=10,        # Maximum 10 errors
    max_length_each=150  # Each error description limited to 150 chars
)

# Missing information
missing_input = InputTextList(
    max_count=5,
    max_length_each=200
)

# Improvement suggestions
suggestions_input = InputTextList(max_count=3)  # No length limit per item

数値入力 (`InputNumeric`)

数値評価またはスコアに使用します。

from mlflow.genai.label_schemas import InputNumeric

# Confidence score
confidence_input = InputNumeric(
    min_value=0.0,
    max_value=1.0
)

# Rating scale
rating_input = InputNumeric(
    min_value=1,
    max_value=10
)

# Cost estimate
cost_input = InputNumeric(min_value=0)  # No maximum limit

完全な例

カスタマーサービスの評価

顧客サービスの応答を評価するための包括的な例を次に示します。

import mlflow.genai.label_schemas as schemas
from mlflow.genai.label_schemas import (
    InputCategorical,
    InputCategoricalList,
    InputText,
    InputTextList,
    InputNumeric
)

# Overall quality rating
quality_schema = schemas.create_label_schema(
    name="service_quality",
    type="feedback",
    title="Rate the overall quality of this customer service response",
    input=InputCategorical(options=["Excellent", "Good", "Average", "Poor", "Very Poor"]),
    instruction="Consider helpfulness, accuracy, and professionalism.",
    enable_comment=True
)

# Issues identification
issues_schema = schemas.create_label_schema(
    name="response_issues",
    type="feedback",
    title="What issues are present in this response? (Select all that apply)",
    input=InputCategoricalList(options=[
        "Factually incorrect information",
        "Unprofessional tone",
        "Doesn't address the question",
        "Too vague or generic",
        "Contains harmful content",
        "No issues identified"
    ]),
    instruction="Select all issues you identify. Choose 'No issues identified' if the response is problem-free."
)

# Expected resolution steps
resolution_schema = schemas.create_label_schema(
    name="expected_resolution",
    type="expectation",
    title="What steps should be included in the ideal resolution?",
    input=InputTextList(max_count=5, max_length_each=200),
    instruction="List the key steps a customer service rep should take to properly resolve this issue."
)

# Confidence in assessment
confidence_schema = schemas.create_label_schema(
    name="assessment_confidence",
    type="feedback",
    title="How confident are you in your assessment?",
    input=InputNumeric(min_value=1, max_value=10),
    instruction="Rate from 1 (not confident) to 10 (very confident)"
)

医療情報レビュー

医療情報の応答を評価する例:

import mlflow.genai.label_schemas as schemas
from mlflow.genai.label_schemas import InputCategorical, InputTextList, InputNumeric

# Safety assessment
safety_schema = schemas.create_label_schema(
    name="medical_safety",
    type="feedback",
    title="Is this medical information safe and appropriate?",
    input=InputCategorical(options=[
        "Safe - appropriate general information",
        "Concerning - may mislead patients",
        "Dangerous - could cause harm if followed"
    ]),
    instruction="Assess whether the information could be safely consumed by patients."
)

# Required disclaimers
disclaimers_schema = schemas.create_label_schema(
    name="required_disclaimers",
    type="expectation",
    title="What medical disclaimers should be included?",
    input=InputTextList(max_count=3, max_length_each=300),
    instruction="List disclaimers that should be present (e.g., 'consult your doctor', 'not professional medical advice')."
)

# Accuracy of medical facts
accuracy_schema = schemas.create_label_schema(
    name="medical_accuracy",
    type="feedback",
    title="Rate the factual accuracy of the medical information",
    input=InputNumeric(min_value=0, max_value=100),
    instruction="Score from 0 (completely inaccurate) to 100 (completely accurate)"
)

ラベル付けセッションとの統合

作成したら、ラベル付けセッションでスキーマを使用します。

import mlflow.genai.label_schemas as schemas

# Schemas are automatically available when creating labeling sessions
# The Review App will present questions based on your schema definitions

# Example: Using schemas in a session (conceptual - actual session creation
# happens through the Review App UI or other APIs)
session_schemas = [
    "service_quality",      # Your custom schema
    "response_issues",      # Your custom schema
    schemas.EXPECTED_FACTS  # Built-in schema
]

ベストプラクティス

スキーマの設計

明確なタイトル: 明確で具体的なプロンプトとして質問を記述する
役に立つ手順: レビュー担当者をガイドするためのコンテキストを提供する
適切な制約: テキストの長さとリストの数に適切な制限を設定する
論理オプション: カテゴリ入力の場合は、オプションが相互に排他的で包括的であることを確認します

スキーマ管理

一貫性のある名前付け: スキーマ全体でわかりやすい一貫性のある名前を使用する
バージョン管理: スキーマを更新する場合は、既存のセッションへの影響を考慮してください
クリーンアップ: 未使用のスキーマを削除してワークスペースを整理する

入力の種類の選択

標準化された評価または分類に InputCategorical を使用する
複数の問題や機能が存在する可能性がある場合に InputCategoricalList を使用する
InputTextを使用して詳細な説明やカスタムフィードバックを表示する
アイテムの構造化リストに InputTextList を使用する
正確なスコア付けまたは信頼度評価に InputNumeric を使用する

次のステップ

既存のトレースにラベルを付ける - スキーマを適用して構造化されたフィードバックを収集する
ラベル付けセッションを作成する - スキーマを使用してレビューワークフローを整理する
評価データセットの構築 - ラベル付きデータをテストデータセットに変換する

次の方法で共有