モデルAPI

構築

ファクトリーはファミリークラスのインスタンスを返します。そのクラスを直接構築する場合も 同じ引数を取りますが、sizeは必須です。

Family(model_path, size, nb_classes=80, device="auto", task=None, **kwargs)

device="auto"は、利用できる場合はCUDA、次にMPS、最後にCPUを選択します。整数または 数字の文字列はCUDAの序数として読み取られるため、device=0とdevice="0"はいずれも cuda:0を意味します。taskはファミリーのSUPPORTED_TASKSに照らして検証されます。 model_path=Noneを渡すとアーキテクチャを構築して学習モードのままにし、dictを渡すと そのstate dictを直接読み込みます。

predictと__call__

predictは__call__の別名です。

model(
    source=None,
    *,
    conf=0.25,
    iou=0.45,
    imgsz=None,
    device=None,
    classes=None,
    max_det=300,
    augment=False,
    save=False,
    batch=1,
    stream=False,
    stream_buffer=False,
    vid_stride=1,
    show=False,
    output_path=None,
    color_format="auto",
    tiling=False,
    overlap_ratio=0.2,
    output_file_format=None,
    cuda_graph=False,
    **kwargs,
)

単一の画像ソースは1つのResultsを返します。リスト、タプル、またはディレクトリは それらのリストを返し、stream=Trueはどの場合もジェネレーターを返します。

ライブストリームのソースには終端がなく、stream=Trueが必要です。tilingとaugmentは 同時に使用できません。テスト時データ拡張は、embed、point、edgeタスクでは例外を 発生させます。

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt") model.info()result = model(SAMPLE_IMAGE, conf=0.25, iou=0.45) print(result.boxes.xyxy)print(result.speed)

batch > 1では、SUPPORTS_BATCHED_PREDICTがtrueのファミリーはチャンクごとに スタックした順伝播を1回実行します。batch=1では画像ごとに順伝播を1回実行します。

from libreyolo import LibreYOLO, SAMPLE_IMAGE model = LibreYOLO("LibreYOLO9t.pt") # stream=Trueはジェネレーターを返し、フレームまたは画像ごとにResultsを1つ生成for result in model([SAMPLE_IMAGE, SAMPLE_IMAGE], stream=True):    print(len(result))

embed

model.embed(source=None, **kwargs) -> torch.Tensor

predictの便利なラッパーで、すべての埋め込みベクトルの行を1つの(N_total, D)テンソルに スタックします。モデルはtask="embed"で構築されている必要があり、それ以外の場合は NotImplementedErrorを発生させます。

track

model.track(
    source,
    *,
    track_conf=0.25,
    iou=0.45,
    imgsz=None,
    classes=None,
    max_det=300,
    save=False,
    show=False,
    vid_stride=1,
    output_path=None,
    tracker="bytetrack",
    tracker_config=None,
    augment=False,
    **tracker_kwargs,
) -> Generator[Results, None, None]

track_idを設定したResultsをフレームごとに1つ生成します。trackerには "bytetrack"、"botsort"、"ocsort"、または"deepocsort"を指定できます。 tracker_configを指定した場合は設定の型がトラッカーを選択するため、trackerは無視されます。 track_confは、ByteTrackとBoT-SORTではtrack_high_threshに、OC-SORTとDeep OC-SORTでは det_threshに対応します。output_pathのデフォルトはruns/track/<video_stem>.mp4です。

val

model.val(
    data=None,
    batch=16,
    imgsz=None,
    conf=0.001,
    iou=0.6,
    workers=4,
    allow_download_scripts=False,
    device=None,
    split="val",
    augment=False,
    save_json=False,
    verbose=True,
    *,
    plots=None,
    **kwargs,
) -> Dict

タスクに応じたキーを持つ指標辞書を返します。検出ではmetrics/precision、 metrics/recall、metrics/mAP50、metrics/mAP50-95を返します。imgszは正方形の整数値 または(height, width)タプルを受け取り、デフォルトではモデル固有の入力サイズを使います。 plotsはsave_plotsの別名です。allow_download_scriptsは、データセットYAMLのdownload フィールドに含まれる可能性がある埋め込みPythonの実行可否を制御します。

faster_coco_evalは**kwargsを通じて受け入れられ、デフォルトはTrueです。パッケージが インストールされていない場合はpycocotoolsへフォールバックします。実行されたバックエンドは model.last_eval_backendで報告されます。

拡張検証は、obbとposeタスクでは例外を発生させます。

train

trainはファミリーごとに定義されているため、引数が異なります。基底クラスが各ファミリーの trainをラップするため、2つの動作は共通です。

• cfg=は、キーが呼び出しへマージされるYAMLパスを受け取ります。明示的なキーワード引数がファイルより優先されます。
• カバレッジグループg0またはg1のファミリーでpretrained=Falseを指定すると、学習前にモデルを最初から再初期化します。resume=Trueとは併用できません。

ファミリーが実際にどのデータ拡張設定を尊重するかは、ファミリーごとに異なります。 データ拡張マトリックスを参照してください。

export

model.export(format="onnx", **kwargs) -> str

書き出された成果物のパスを返します。formatはエクスポーターレジストリによって解決されます。 ここではengineがtensorrtの別名、litertがtfliteの別名です。すべてのエクスポーターに 共通する引数は次のとおりです。

禁止された組み合わせは、トレース前の事前検査でNotImplementedErrorを発生させます。 カバレッジとその規則はエクスポートマトリックスのページに あります。有効なLoRAアダプターが存在する場合は密な重みに統合されます。この統合は、すべての 要求拒否を確認した後にのみ行われます。

save

model.save(path) -> str

スキーマv1.0のLibreYOLOチェックポイントを書き出します。これはstate dictと、 チェックポイントスキーマで説明されているメタデータです。 量子化モデルにはquantマニフェストも含まれるため、LibreYOLO(path)は量子化された構造と スケールを復元します。

quantize、quant_info、dequantize

model.quantize(
    recipe,
    calib="coco128.yaml",
    samples=128,
    batch=8,
    algorithm="auto",
    keep_high_precision=None,
    allow_download_scripts=False,
    verbose=True,
)

その場で量子化し、モデルを返します。recipeにはキャストのfp16とbf16、ConvとLinearの レシピint8とfp8、またはLinear専用のレシピw4a16、w4a8、nvfp4、mxfp4、int2の いずれかを指定します。後者はRF-DETRなどのTransformerファミリーでサポートされます。 int2にはQATが必要です。calibはdata.yamlのパスまたは組み込みデータセット名を受け取り、 順伝播専用で画像を読み込みます。ラベルは一切読みません。キャリブレーションを省略するには calib=Noneを渡します。algorithmは"minmax"、"percentile"、または"auto"です。

model.quant_info()は量子化状態の概要を返し、浮動小数点モデルではNoneを返します。 model.dequantize()は、量子化学習済みのマスター重みを維持しながら、その場で浮動小数点 モジュールを復元します。これはQATからexport(format="onnx", int8=True, data=...)への 橋渡しになります。

infoとlayers

model.info(detailed=False, verbose=True) -> Dict[str, Any]
model.get_available_layer_names() -> List[str]
model.get_distill_config() -> Dict

infoはJSON互換の辞書を返し、verboseがtrueの場合は人間が読める概要をログへ記録します。 get_available_layer_namesは、蒸留または特徴量抽出の設定で名前を指定できる層を一覧化します。

CUDAグラフ

SUPPORTS_CUDA_GRAPHクラス属性がtrueのファミリーで利用できます。リプレイはeager実行と ビット単位で同一です。

model.capture_graph(imgsz=None, batch=1, dtype=None) -> None
model.cuda_graph_scope(mode=True)          # コンテキストマネージャー
model.graph_info() -> Dict[str, Any]
model.release_graphs() -> None

キャプチャしたグラフは、キャプチャ時と完全に同じ形状でのみ有効です。そのため、batchと imgszは後続のpredict呼び出しと一致する必要があります。capture_graphはキャプチャの コストを最初の要求から切り離します。modeには、初回使用時にキャプチャするTrueまたは "on"、形状が繰り返されるまで待つ"auto"、何もしないFalseを指定できます。 ファミリーがオプトインしていない場合、capture_graphはNotImplementedErrorを発生させ、 キャプチャに失敗した場合はCudaGraphUnavailableを発生させます。

デバイスとdtype

Resultsオブジェクトには.to()、.cpu()、.cuda()、.numpy()があります。 Resultsの型を参照してください。モデル自体を移動するには、 predictまたは構築時にdevice=を渡します。