開発者としてトレースにラベルを付ける

エージェントの構築に伴い、 MLflow Tracing を使用して、フィードバックや期待値をトレースに直接追加できます。品質の問題を記録したり、成功した例をマークしたり、後で参照するためのメモを追加したりできます。これにより、正式な評価を設定する前に、開発中の品質を追跡できるようになります。

前提 条件

• アプリケーションがMLflow Tracingで計測可能になっている
• アプリケーションを実行してトレースを生成している

評価ラベルを追加する

評価では、MLflow での品質評価と改善のために、構造化されたフィードバック、スコア、またはグラウンド トゥルースをトレースとスパンに添付します。

Databricks UI

MLflowのユーザーインターフェースを通して、トレースに直接注釈（ラベル）を追加できます。

注記

Databricksノートブックを使用している場合は、ノートブックにインラインでレンダリングされる Trace UI からこれらのステップを実行することもできます。

1. MLflowエクスペリメント UI の [トレース] タブに移動します。

2. 個別のトレースを開きます。

3. トレースUI内で、ラベルを付けたい特定の範囲をクリックします。

   • ルートスパンを選択すると、フィードバックがトレース全体に適用されます。

4. 右端にある「評価」タブを展開してください。

5. ご意見・ご感想は、こちらのフォームにご記入ください。

   • 評価タイプ

     • フィードバック : 品質の主観的な評価 (評価、コメント)
     • 期待値 : 期待される出力または値 (生成されるはずだったもの)

   • 評価名

     • フィードバックの内容を表す一意の名前

   • データ型

     • Number
     • Boolean
     • String

   • Value

     • あなたの評価

   • 根拠

     • 値に関するオプションの注意事項

6. 「作成」 をクリックしてラベルを保存します。

7. 「トレース」タブに戻ると、ラベルが新しい列として表示されます。

MLflow SDK

MLflow の SDK を使用して、プログラムでトレースにラベルを追加できます。これは、アプリケーションロジックに基づく自動ラベリングや、トレースのバッチ処理に役立ちます。

MLflow 2 つのAPIsを提供します。

• mlflow.log_feedback() - アプリの実際の出力または中間ステップを評価するフィードバックを記録します (例: 「応答は良好でしたか?」、評価、コメント)。
• mlflow.log_expectation() - アプリが生成するはずだった望ましい結果または正しい結果 (真実) を定義する期待値をログに記録します。

Python

import mlflow
from mlflow.entities.assessment import (
    AssessmentSource,
    AssessmentSourceType,
    AssessmentError,
)


@mlflow.trace
def my_app(input: str) -> str:
    return input + "_output"


# Create a sample trace to demonstrate assessment logging
my_app(input="hello")

trace_id = mlflow.get_last_active_trace_id()

# Handle case where trace_id might be None
if trace_id is None:
    raise ValueError("No active trace found. Make sure to run a traced function first.")

print(f"Using trace_id: {trace_id}")


# =============================================================================
# LOG_FEEDBACK - Evaluating actual outputs and performance
# =============================================================================

# Example 1: Human rating (integer scale)
# Use case: Domain experts rating response quality on a 1-5 scale
mlflow.log_feedback(
    trace_id=trace_id,
    name="human_rating",
    value=4,  # int - rating scale feedback
    rationale="Human evaluator rating",
    source=AssessmentSource(
        source_type=AssessmentSourceType.HUMAN,
        source_id="evaluator@company.com",
    ),
)

# Example 2: LLM judge score (float for precise scoring)
# Use case: Automated quality assessment using LLM-as-a-judge
mlflow.log_feedback(
    trace_id=trace_id,
    name="llm_judge_score",
    value=0.85,  # float - precise scoring from 0.0 to 1.0
    rationale="LLM judge evaluation",
    source=AssessmentSource(
        source_type=AssessmentSourceType.LLM_JUDGE,
        source_id="gpt-4o-mini",
    ),
    metadata={"temperature": "0.1", "model_version": "2024-01"},
)

# Example 3: Binary feedback (boolean for yes/no assessments)
# Use case: Simple thumbs up/down or correct/incorrect evaluations
mlflow.log_feedback(
    trace_id=trace_id,
    name="is_helpful",
    value=True,  # bool - binary assessment
    rationale="Boolean assessment of helpfulness",
    source=AssessmentSource(
        source_type=AssessmentSourceType.HUMAN,
        source_id="reviewer@company.com",
    ),
)

# Example 4: Multi-category feedback (list for multiple classifications)
# Use case: Automated categorization or multi-label classification
mlflow.log_feedback(
    trace_id=trace_id,
    name="automated_categories",
    value=["helpful", "accurate", "concise"],  # list - multiple categories
    rationale="Automated categorization",
    source=AssessmentSource(
        source_type=AssessmentSourceType.CODE,
        source_id="classifier_v1.2",
    ),
)

# Example 5: Complex analysis with metadata (when you need structured context)
# Use case: Detailed automated analysis with multiple dimensions stored in metadata
mlflow.log_feedback(
    trace_id=trace_id,
    name="response_analysis_score",
    value=4.2,  # single score instead of dict - keeps value simple
    rationale="Analysis: 150 words, positive sentiment, includes examples, confidence 0.92",
    source=AssessmentSource(
        source_type=AssessmentSourceType.CODE,
        source_id="analyzer_v2.1",
    ),
    metadata={  # Use metadata for structured details
        "word_count": "150",
        "sentiment": "positive",
        "has_examples": "true",
        "confidence": "0.92",
    },
)

# Example 6: Error handling when evaluation fails
# Use case: Logging when automated evaluators fail due to API limits, timeouts, etc.
mlflow.log_feedback(
    trace_id=trace_id,
    name="failed_evaluation",
    source=AssessmentSource(
        source_type=AssessmentSourceType.LLM_JUDGE,
        source_id="gpt-4o",
    ),
    error=AssessmentError(  # Use error field when evaluation fails
        error_code="RATE_LIMIT_EXCEEDED",
        error_message="API rate limit exceeded during evaluation",
    ),
    metadata={"retry_count": "3", "error_timestamp": "2024-01-15T10:30:00Z"},
)

# =============================================================================
# LOG_EXPECTATION - Defining ground truth and desired outcomes
# =============================================================================

# Example 1: Simple text expectation (most common pattern)
# Use case: Defining the ideal response for factual questions
mlflow.log_expectation(
    trace_id=trace_id,
    name="expected_response",
    value="The capital of France is Paris.",  # Simple string - the "correct" answer
    source=AssessmentSource(
        source_type=AssessmentSourceType.HUMAN,
        source_id="content_curator@example.com",
    ),
)

# Example 2: Complex structured expectation (advanced pattern)
# Use case: Defining detailed requirements for response structure and content
mlflow.log_expectation(
    trace_id=trace_id,
    name="expected_response_structure",
    value={  # Complex dict - detailed specification of ideal response
        "entities": {
            "people": ["Marie Curie", "Pierre Curie"],
            "locations": ["Paris", "France"],
            "dates": ["1867", "1934"],
        },
        "key_facts": [
            "First woman to win Nobel Prize",
            "Won Nobel Prizes in Physics and Chemistry",
            "Discovered radium and polonium",
        ],
        "response_requirements": {
            "tone": "informative",
            "length_range": {"min": 100, "max": 300},
            "include_examples": True,
            "citations_required": False,
        },
    },
    source=AssessmentSource(
        source_type=AssessmentSourceType.HUMAN,
        source_id="content_strategist@example.com",
    ),
    metadata={
        "content_type": "biographical_summary",
        "target_audience": "general_public",
        "fact_check_date": "2024-01-15",
    },
)

# Example 3: Multiple acceptable answers (list pattern)
# Use case: When there are several valid ways to express the same fact
mlflow.log_expectation(
    trace_id=trace_id,
    name="expected_facts",
    value=[  # List of acceptable variations of the correct answer
        "Paris is the capital of France",
        "The capital city of France is Paris",
        "France's capital is Paris",
    ],
    source=AssessmentSource(
        source_type=AssessmentSourceType.HUMAN,
        source_id="qa_team@example.com",
    ),
)

Databricks REST API

Databricks REST API を使用して評価を作成し、あらゆる環境からのトレースのフィードバックと評価をプログラムで記録します。

Databricks REST API ドキュメントを参照してください。

REST APIエンドポイント

POST https://<workspace-host>.databricks.com/api/3.0/mlflow/traces/{trace_id}/assessments

リクエストの例：

Bash

curl -X POST \
  "https://<workspace-host>.databricks.com/api/3.0/mlflow/traces/<trace-id>/assessments" \
  -H "Authorization: Bearer <databricks-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "assessment": {
      "assessment_name": "string",
      "create_time": "2019-08-24T14:15:22Z",
      "expectation": {
        "serialized_value": {
          "serialization_format": "string",
          "value": "string"
        },
        "value": {}
      },
      "feedback": {
        "error": {
          "error_code": "string",
          "error_message": "string",
          "stack_trace": "string"
        },
        "value": {}
      },
      "last_update_time": "2019-08-24T14:15:22Z",
      "metadata": {
        "property1": "string",
        "property2": "string"
      },
      "overrides": "string",
      "rationale": "string",
      "source": {
        "source_id": "string",
        "source_type": "HUMAN"
      },
      "span_id": "string",
      "valid": true
    }
  }'

応答例：

JSON

{
  "assessment": {
    "assessment_id": "string",
    "assessment_name": "string",
    "create_time": "2019-08-24T14:15:22Z",
    "expectation": {
      "serialized_value": {
        "serialization_format": "string",
        "value": "string"
      },
      "value": {}
    },
    "feedback": {
      "error": {
        "error_code": "string",
        "error_message": "string",
        "stack_trace": "string"
      },
      "value": {}
    },
    "last_update_time": "2019-08-24T14:15:22Z",
    "metadata": {
      "property1": "string",
      "property2": "string"
    },
    "overrides": "string",
    "rationale": "string",
    "source": {
      "source_id": "string",
      "source_type": "HUMAN"
    },
    "span_id": "string",
    "trace_id": "string",
    "valid": true
  }
}

その他のリソース

• ドメインの専門家からのフィードバックを収集する - 構造化されたラベル付けセッションを設定する
• 評価データセットの構築 - ラベル付けされたトレースを使用して、テストデータセットを作成します
• エンドユーザーのフィードバックを収集する - デプロイされたアプリケーションからフィードバックをキャプチャする

リファレンスガイド

このガイドで説明されている概念と機能の詳細なドキュメントをご覧ください。

• ラベル付けスキーマ - 構造化されたフィードバック収集について学習します

次のステップ: 専門家やコラボレーターがトレースにラベルを付けられるようにする