Data Curation

このガイドでは、MLdebuggerを使用したデータキュレーションの概念と戦略を説明します。

概要

AIプロダクトのライフサイクルにおいて、継続的にデータ収集する際には、以下の項目が重要です。

AIモデルの成長に寄与しないデータは収集しない（特異度の最大化）
AIモデルが改善するべき致命的なエラーを有するデータは見逃さない（感度の最大化）
アプリケーションが対象とするデータ範囲内で多様性のある収集をする
データ分布自体の変化に対応するため未知のデータを見逃さない（Out-of-Distribution Detection）

MLdebuggerのClassificationDataFilter、ObjectDetectionDataFilter、ObjectDetection3DDataFilterは、内部特徴量とエラー確率の分析に基づいて、効果的なデータ選択を実現します。

Issue Categoryに基づくデータ分類

MLdebuggerは、エラーコードと内部特徴量の関係性を分析することで、推論時のモデルの内部特徴量に基づいてデータを分類します。

閾値設定について

現在のバージョンでは、固定の閾値でカテゴリーを決定しています。そのため、モデルの成熟度が低い段階ではStable（Coverage）領域にもエラーが含まれる可能性があります。また、マルチクラスの場合はクラスごとにHeatmap上の分布に偏りが生じるため、GUI上での評価結果の確認も重要です。

モデルの成熟度やHeatmapに基づいて閾値を調整することで、より詳細なデータ収集設定が可能です。将来的にはMLdebuggerが評価するモデルの成熟度に基づく動的な閾値設定機能も導入予定です。

Coverage領域（収集不要）

カテゴリ	特徴	データ収集
`stable_coverage` (Highly Stable)	高品質な出力が可能で内部特徴量が安定	不要
`operational_coverage` (Stable)	運用上許容可能で内部特徴量が安定	低優先度

効果: 収集データ中の有効データの割合（特異度）を向上

Hotspot領域（収集推奨）

カテゴリ	特徴	データ収集
`hotspot` (Unstable)	内部特徴量が不安定で予測が揺らぎやすい	推奨
`recessive_hotspot` (Under-Confidence)	モデルの確信度が低くエラーを予測しやすい	推奨

効果: モデルが十分に特徴量表現を学べていないデータを収集でき、よりロバストなモデルを構築可能

Critical/Aleatoric領域（優先収集）

カテゴリ	特徴	データ収集
`critical_hotspot` (Over-Confidence)	エラー確率が高いが高確信度で予測	最優先
`aleatoric_hotspot` (Outlier)	特徴量が不十分でモデルが学習困難	要レビュー

効果: 重要度の高いエラーの見逃しを防止（感度の最大化）

Critical Hotspotの重要性

Critical Hotspotは、モデルが自信を持って間違えるため運用時に検出困難です。優先的に収集してモデル改善に活用してください。

ClassificationDataFilterの使用

初期化

評価結果（result_name）を指定してDataFilterを初期化します。

from ml_debugger.data_filter import ClassificationDataFilter

data_filter = ClassificationDataFilter(
    model,
    model_name="my_model",
    version_name="v1",
    result_name="my_model_v1_classification_v1_20251219",
)

クエリ戦略

query()メソッドのstrategyパラメータには、文字列または辞書を指定できます。

ソート戦略

データを指定の指標で並び替え、上位N件を取得します。

戦略	説明	用途
`"high_error_proba"`	エラー確率が高いデータを優先選択	Hard Example Mining
`"low_error_proba"`	エラー確率が低いデータを優先選択	信頼性の高いデータ収集

フィルタ戦略

条件にマッチするデータを最大N件取得します。辞書形式でIssue Categoryや閾値条件を指定します。

# Hotspotゾーンのデータを選択
queried_ids = data_filter.query(
    n_data=100,
    strategy={"target_zones": ["hotspot", "critical_hotspot"]},
)

# 閾値条件でカスタム選択
queried_ids = data_filter.query(
    n_data=100,
    strategy={"conditions": [{"error_proba": ">=0.8"}]},
)

フィルタ戦略の利点

Issue Categoryに基づく選択は、エラー確率だけでなくモデルの内部状態（確信度、特徴量の安定性）も考慮するため、より効果的なデータ選択が可能です。

リアルタイムフィルタリング

バッチ後処理方式に加えて、filter_configを使用したリアルタイムフィルタリングが可能です。推論時にデータがどのIssue Categoryに属するかを即座に判定できます。

target_zonesとIssue Categoryの対応

target_zone	Issue Category	説明
`stable_coverage`	Highly Stable	高品質な出力が可能で内部特徴量が安定
`operational_coverage`	Stable	運用上許容可能で内部特徴量が安定
`hotspot`	Unstable	内部特徴量が不安定で予測が揺らぎやすい
`recessive_hotspot`	Under-Confidence	モデルの確信度が低くエラーを予測しやすい
`critical_hotspot`	Over-Confidence	エラー確率が高いが高確信度で予測
`aleatoric_hotspot`	Outlier	特徴量が不十分でモデルが学習困難

使用例: Critical Hotspotのリアルタイム検出

運用環境でCritical Hotspot（モデルが自信を持って間違えるデータ）をリアルタイムで検出し、即座にデータ収集パイプラインに送る例です。

from ml_debugger.data_filter import ClassificationDataFilter

# Critical Hotspotを対象としたフィルタ設定
data_filter = ClassificationDataFilter(
    model,
    model_name="my_model",
    version_name="v1",
    result_name="my_model_v1_classification_v1_20251219",
    filter_config={"target_zones": ["critical_hotspot"]},
)

# 推論時にリアルタイムでフィルタリング
for image, _, idx in inference_dataloader:
    model_output, filter_flags = data_filter(
        image.to(device),
        input_ids=[idx],
    )

    if filter_flags[0] is True:
        # Critical Hotspot検出 → 優先的にラベル付けを依頼
        send_to_labeling_queue(idx, priority="high")

使用例: 学習寄与度が低いデータの間引き

Coverage領域のデータ（モデルが既に十分学習済み）を除外し、ストレージコストを削減する例です。

# Coverageゾーンを対象（=除外対象を特定）
data_filter = ClassificationDataFilter(
    model,
    model_name="my_model",
    version_name="v1",
    result_name=result.result_name,
    filter_config={"target_zones": ["stable_coverage", "operational_coverage"]},
)

for image, _, idx in inference_dataloader:
    model_output, filter_flags = data_filter(
        image.to(device),
        input_ids=[idx],
    )

    if filter_flags[0] is True:
        # Coverageゾーン → 保存しない（学習に寄与しない）
        pass
    else:
        # Hotspot/Criticalゾーン → 保存する（学習に有用）
        save_to_storage(image, idx)

Object Detectionでのリアルタイムフィルタリング

Object Detectionでは、filter_configにBBoxStrategy辞書を渡して、BBox単位のエラー確率を画像単位に集約した結果に基づくフィルタリングが可能です。

from ml_debugger.data_filter import ObjectDetectionDataFilter

# 画像レベルのエラー確率が0.5以上の場合にフラグを立てる
data_filter = ObjectDetectionDataFilter(
    model,
    model_name="yolov5",
    version_name="v1",
    result_name=result.result_name,
    filter_config={
        "img_error_threshold": 0.5,
        "aggregation": "mean",
        "target_column": "error_proba",
    },
)

for image, _, idx in inference_dataloader:
    model_output, filter_flags = data_filter(
        image.to(device),
        input_ids=[idx],
    )

    if filter_flags[0] is True:
        # 画像レベルのエラー確率が閾値以上 → 収集
        save_to_storage(image, idx)

BBoxStrategyとfilter_configの詳細

BBoxStrategy の詳細（target_column, top_n, aggregation 等）および filter_config の使用方法は Getting Started - DataFiltering を参照してください。

ユースケース

Active Learning

ラベルなしデータプールから最も有益なデータを選択的にラベル付けすることで、少ないラベル付けコストでモデルの性能を向上させます。

詳細な実装方法は Active Learning を参照してください。

データセット品質向上

既存データセットの中から問題のあるデータを特定し、アノテーションの見直しを行います。

活用シーン:

アノテーションミスの発見と修正
曖昧なデータの特定と除外
ラベルノイズの軽減

運用時のデータ収集最適化

本番環境で推論するデータの中から、モデル改善に有用なデータのみを収集します。

効果:

ストレージコストの削減
ラベル付けコストの最適化
継続的なモデル改善

コストと効果のトレードオフ

データ収集時に戦略の重み付けを調整することで、コストに直結するデータ収集量とその質をコントロール可能です。

戦略	データ量	ラベル付けコスト	モデル改善効果
全データ収集	大	高	中
High Error Proba	小	低	高
Random	中	中	中

次のステップ

Getting Started - DataFiltering - DataFilterの基本操作
Evaluation と Result - Issue Categoryの詳細