Link to this sectionコールバック#

Ultralyticsフレームワークはコールバックをサポートしており、train、val、export、predictモード中の戦略的な段階でエントリーポイントとして機能します。各コールバックは、操作の種類に応じてTrainer、Validator、またはPredictorオブジェクトを受け取ります。これらのオブジェクトの全プロパティについては、ドキュメントのリファレンスセクションで詳しく解説されています。

Watch: How to use Ultralytics Callbacks | Predict, Train, Validate and Export Callbacks | Ultralytics YOLO🚀

Link to this section例#

Link to this section推論結果に付加情報を追加して返す#

この例では、各結果オブジェクトと一緒に元のフレームを返す方法を説明します。

from ultralytics import YOLO

def on_predict_batch_end(predictor):
    """Combine prediction results with corresponding frames."""
    _, image, _, _ = predictor.batch

    # Ensure that image is a list
    image = image if isinstance(image, list) else [image]

    # Combine the prediction results with the corresponding frames
    predictor.results = zip(predictor.results, image)

# Create a YOLO model instance
model = YOLO("yolo26n.pt")

# Add the custom callback to the model
model.add_callback("on_predict_batch_end", on_predict_batch_end)

# Iterate through the results and frames
for result, frame in model.predict():  # or model.track()
    pass

Link to this section`on_model_save`コールバックを使用してモデルのメトリクスにアクセスする#

この例では、on_model_saveコールバックを使用してチェックポイントが保存された後に、best_fitnessスコア、total_loss、その他のメトリクスなどの学習詳細を取得する方法を示します。

from ultralytics import YOLO

# Load a YOLO model
model = YOLO("yolo26n.pt")

def print_checkpoint_metrics(trainer):
    """Print trainer metrics and loss details after each checkpoint is saved."""
    print(
        f"Model details\n"
        f"Best fitness: {trainer.best_fitness}, "
        f"Loss names: {trainer.loss_names}, "  # List of loss names
        f"Metrics: {trainer.metrics}, "
        f"Total loss: {trainer.tloss}"  # Total loss value
    )

if __name__ == "__main__":
    # Add on_model_save callback.
    model.add_callback("on_model_save", print_checkpoint_metrics)

    # Run model training on custom dataset.
    results = model.train(data="coco8.yaml", epochs=3)

Link to this sectionすべてのコールバック#

以下にサポートされているすべてのコールバックを示します。詳細については、コールバックのソースコードを参照してください。

Link to this sectionトレーナー（Trainer）コールバック#

コールバック	説明
`on_pretrain_routine_start`	事前学習ルーチンの開始時、データ読み込みとモデル設定の前でトリガーされます。
`on_pretrain_routine_end`	事前学習ルーチンの終了時、データ読み込みとモデル設定の完了後にトリガーされます。
`on_train_start`	学習が開始される際、最初のエポックが始まる前にトリガーされます。
`on_train_epoch_start`	各学習エポックの開始時、バッチの反復処理が始まる前にトリガーされます。
`on_train_batch_start`	各学習バッチの開始時、順伝播（forward pass）の前にトリガーされます。
`optimizer_step`	オプティマイザのステップ中にトリガーされます。カスタム統合用に予約されており、デフォルトの学習ループからは呼び出されません。
`on_before_zero_grad`	勾配のゼロ化の前にトリガーされます。カスタム統合用に予約されており、デフォルトの学習ループからは呼び出されません。
`on_train_batch_end`	各学習バッチの終了時、逆伝播（backward pass）の後にトリガーされます。勾配累積のため、オプティマイザのステップが遅延される場合があります。
`on_train_epoch_end`	各学習エポックの終了時、全バッチの処理完了後で、検証（validation）の前にトリガーされます。検証メトリクスやフィットネススコアはまだ利用できない場合があります。
`on_model_save`	検証後、モデルのチェックポイントが保存されるときにトリガーされます。
`on_fit_epoch_end`	各フィットエポック（学習＋検証）の終了時、検証およびチェックポイント保存の後にトリガーされます。検証メトリクスは利用可能であり、エポックごとの学習呼び出し時にフィットネスも利用可能です。このコールバックは最終的なベストモデル評価中にも呼び出されますが、その際チェックポイント保存は行われず、フィットネスが存在しない可能性があります。
`on_train_end`	学習プロセスが終了する際、ベストモデルの最終評価後にトリガーされます。
`on_params_update`	モデルパラメータが更新されたときにトリガーされます。カスタム統合用に予約されており、デフォルトの学習ループからは呼び出されません。
`teardown`	学習プロセスがクリーンアップされる際にトリガーされます。

Link to this sectionバリデーター（Validator）コールバック#

コールバック	説明
`on_val_start`	検証が開始されるときにトリガーされます。
`on_val_batch_start`	各検証バッチの開始時にトリガーされます。
`on_val_batch_end`	各検証バッチの終了時にトリガーされます。
`on_val_end`	検証が終了するときにトリガーされます。

Link to this sectionプレディクター（Predictor）コールバック#

コールバック	説明
`on_predict_start`	推論プロセスが開始されるときにトリガーされます。
`on_predict_batch_start`	各推論バッチの開始時にトリガーされます。
`on_predict_postprocess_end`	推論の後処理が完了したときにトリガーされます。
`on_predict_batch_end`	各推論バッチの終了時にトリガーされます。
`on_predict_end`	推論プロセスが終了するときにトリガーされます。

Link to this sectionエクスポーター（Exporter）コールバック#

コールバック	説明
`on_export_start`	エクスポートプロセスが開始されるときにトリガーされます。
`on_export_end`	エクスポートプロセスが終了するときにトリガーされます。

Link to this sectionよくある質問 (FAQ)#

Link to this sectionUltralyticsコールバックとは何か、どのように使用できるか？#

Ultralyticsコールバックは、学習、検証、エクスポート、推論などのモデル操作の重要な段階でトリガーされる専門的なエントリーポイントです。これらのコールバックはプロセスの特定のポイントでカスタム機能を有効にし、ワークフローの強化や変更を可能にします。各コールバックは、操作の種類に応じてTrainer、Validator、またはPredictorオブジェクトを受け取ります。これらのオブジェクトの詳細なプロパティについては、リファレンスセクションを参照してください。

コールバックを使用するには、関数を定義し、model.add_callback()メソッドを使用してモデルに追加します。以下は推論中に付加情報を返す例です。

from ultralytics import YOLO

def on_predict_batch_end(predictor):
    """Handle prediction batch end by combining results with corresponding frames; modifies predictor results."""
    _, image, _, _ = predictor.batch
    image = image if isinstance(image, list) else [image]
    predictor.results = zip(predictor.results, image)

model = YOLO("yolo26n.pt")
model.add_callback("on_predict_batch_end", on_predict_batch_end)
for result, frame in model.predict():
    pass

Link to this sectionコールバックを使用してUltralyticsの学習ルーチンをカスタマイズするには？#

学習プロセスの特定の段階にロジックを注入することで、Ultralyticsの学習ルーチンをカスタマイズできます。Ultralytics YOLOは、on_train_start、on_train_end、on_train_batch_endなど、多様な学習コールバックを提供しており、独自のメトリクスや処理、ログ機能を追加できます。

コールバックを使用してレイヤーをフリーズする際にBatchNorm統計量を固定する方法は次のとおりです：

from ultralytics import YOLO

# Add a callback to put the frozen layers in eval mode to prevent BN values from changing
def put_in_eval_mode(trainer):
    n_layers = trainer.args.freeze
    if not isinstance(n_layers, int):
        return

    for i, (name, module) in enumerate(trainer.model.named_modules()):
        if name.endswith("bn") and int(name.split(".")[1]) < n_layers:
            module.eval()
            module.track_running_stats = False

model = YOLO("yolo26n.pt")
model.add_callback("on_train_epoch_start", put_in_eval_mode)
model.train(data="coco.yaml", epochs=10)

学習コールバックの効果的な使用方法に関する詳細については、学習ガイドを参照してください。

Link to this sectionUltralytics YOLOの検証中にコールバックを使用すべき理由は何か？#

Ultralytics YOLOの検証中にコールバックを使用すると、独自の処理やログ記録、メトリクス計算が可能になり、モデル評価が強化されます。on_val_start、on_val_batch_end、on_val_endなどのコールバックは、カスタムロジックを挿入するためのエントリーポイントを提供し、詳細かつ包括的な検証プロセスを保証します。

例えば、最初の3バッチだけでなく、すべての検証バッチをプロットするには：

import inspect

from ultralytics import YOLO

def plot_samples(validator):
    frame = inspect.currentframe().f_back.f_back
    v = frame.f_locals
    validator.plot_val_samples(v["batch"], v["batch_i"])
    validator.plot_predictions(v["batch"], v["preds"], v["batch_i"])

model = YOLO("yolo26n.pt")
model.add_callback("on_val_batch_end", plot_samples)
model.val(data="coco.yaml")

検証プロセスへのコールバックの組み込みに関する詳細な洞察については、検証ガイドを参照してください。

Link to this sectionUltralytics YOLOで推論モード用のカスタムコールバックをアタッチするには？#

Ultralytics YOLOで推論モード用のカスタムコールバックをアタッチするには、コールバック関数を定義し、それを推論プロセスに登録します。一般的な推論コールバックには、on_predict_start、on_predict_batch_end、on_predict_endがあります。これらを使用すると、推論結果の変更や、データログの記録、結果の変換などの追加機能を統合できます。

以下は、特定のクラスのオブジェクトが存在するかどうかに基づいて推論結果を保存するカスタムコールバックの例です：

from ultralytics import YOLO

model = YOLO("yolo26n.pt")

class_id = 2

def save_on_object(predictor):
    r = predictor.results[0]
    if class_id in r.boxes.cls:
        predictor.args.save = True
    else:
        predictor.args.save = False

model.add_callback("on_predict_postprocess_end", save_on_object)
results = model("pedestrians.mp4", stream=True, save=True)

for results in results:
    pass

より包括的な使用法については、詳細な手順と追加のカスタマイズオプションが含まれている推論ガイドを参照してください。

Link to this sectionUltralytics YOLOでのコールバック使用の具体的な例は？#

Ultralytics YOLOは、学習、検証、推論といったさまざまなフェーズを強化およびカスタマイズするために、多様なコールバックの実装をサポートしています。具体的な例には次のようなものがあります：

カスタムメトリクスのログ記録: 学習や検証のエポック終了時など、さまざまな段階で追加のメトリクスを記録します。
データ拡張: 推論バッチや学習バッチ中にカスタムのデータ変換や拡張を実装します。
中間結果の保存: 推論結果やフレームなどの中間結果を保存し、その後の分析や視覚化に役立てます。

例：on_predict_batch_endを使用して推論時にフレームと推論結果を結合する：

from ultralytics import YOLO

def on_predict_batch_end(predictor):
    """Combine prediction results with frames."""
    _, image, _, _ = predictor.batch
    image = image if isinstance(image, list) else [image]
    predictor.results = zip(predictor.results, image)

model = YOLO("yolo26n.pt")
model.add_callback("on_predict_batch_end", on_predict_batch_end)
for result, frame in model.predict():
    pass

その他のオプションや例については、コールバックのソースコードを確認してください。

貢献者

GLglenn-jocher¹⁴ RIRizwanMunawar³ RAraimbekovm² Y-Y-T-G¹

作成日時 2023年11月12日更新日時 6 日前