yolo-inference

推論、Results API、トラッキング

最速ルート: Platform でのテストとデプロイ

すべての Platform モデルには Predict タブがあります。画像をアップロードするか、サンプルを選択するか、Web カメラのフレームをキャプチャすると、推論が自動的に実行され、タスクのオーバーレイ、サマリー、生の JSON、タイミングが表示されます。conf、iou、imgsz は、以下で使用されているのと同じ意味で調整できます。

本番環境では、Deploy を開き、近くのリージョンを選択して、専用エンドポイントが Ready になるまで待ちます。そのデプロイページには、ヘルス、メトリクス、ログ、Predict パネル、すぐに使える Python/JavaScript/cURL の例が用意されています。デプロイに紐付けられた API キーをベアラートークンとして /predict を呼び出します:

import requests

with open("image.jpg", "rb") as image_file:
    response = requests.post(
        "https://YOUR_DEPLOYMENT_URL.run.app/predict",
        headers={"Authorization": "Bearer YOUR_API_KEY"},
        files={"file": image_file},
        data={"conf": 0.25, "iou": 0.7, "imgsz": 640},
    )
response.raise_for_status()
print(response.json())

デフォルトサイズのエンドポイントはゼロにスケールするため、アイドル期間の後はコールドスタートが発生します。カスタムサイズはウォームインスタンスを維持し、稼働時間に対して課金されます。詳細は Platform Inference と Dedicated Endpoints を参照してください。

クイックスタート

from ultralytics import YOLO

model = YOLO("yolo26n.pt")  # or your runs/detect/train/weights/best.pt
results = model("image.jpg")  # list[Results], one per image
results[0].show()

yolo predict model=yolo26n.pt source="image.jpg" save=True

動画/ストリームに関する唯一のルール: stream=True。 デフォルトではすべての結果をリストとして RAM に保持するため、長い動画では OOM になります。stream=True はジェネレーターを返します:

for r in model("video.mp4", stream=True):
    ...

ソース

そのまま受け付けられるもの: 画像/動画のパス、ディレクトリ、glob、URL、Web カメラのインデックス (0)、RTSP/RTMP/HTTP ストリーム、YouTube URL (pytubefix が必要)、PIL 画像、numpy 配列 (BGR とみなされます)、torch テンソル、またはこれらのリスト。vid_stride=N は N フレームごとに処理します。

重要な引数

引数	デフォルト	備考
conf	0.25	低くすると再現率が上がり、誤検出も増えます
iou	0.7	NMS しきい値。NMS フリーのヘッド (nms=False) では無視されます
nms	None	デフォルト: one-to-many ヘッド + NMS。False: より高速な NMS フリーの YOLO26 ヘッド。True: エクスポート時に NMS を埋め込みます。エクスポートはその選択を保持します
imgsz	モデル	チェックポイントから継承されます。異なる形状にする場合は明示的に設定します (静的エクスポートは常にエクスポート時のサイズで実行されます)
classes	None	これらの id のみを保持します (例: classes=[0])
max_det	300	密集したシーンでは増やしてください
quantize	None	16 を指定すると PyTorch/TorchScript で FP16 の計算を選択します。それ以外の場合はアーティファクト/ランタイムの精度が適用されます。以下の注意点を参照してください
batch	1	stream=True と組み合わせると、フォルダ/動画で 1 より大きい値が処理を高速化します
retina_masks	False	フル解像度のマスク (低速ですが、より精細)
augment	False	検出のみのテスト時拡張 (精度が向上、約 3 倍遅くなります)。nms=False やエクスポートでは警告が表示され、通常の推論が実行されます
verbose	True	ループ内では False にしてフレームごとのログを抑制します

quantize=16 は OpenVINO の入力を FP16 に丸めます。これは非推奨の half 引数を置き換えるものです。

保存/描画: save、save_txt、save_conf、save_crop、show、line_width → runs/<task>/predict*/。

Results API

各 Results にはタスクのペイロード — .boxes、.masks、.keypoints、.probs（classify）、.obb、.semantic_mask、.depth — に加えて、.names（id→name）、.orig_img（BGR）、.speed、およびメソッド .plot()、.show()、.save()、.save_txt()、.save_crop()、.summary() があります。エクスポーターは to_df()、to_csv()、to_json() のみです。

r = results[0]
r.boxes.xyxy / .xywh / .xyxyn / .xywhn   # (N,4) boxes, pixel / normalized
r.boxes.conf, r.boxes.cls, r.boxes.id    # confidence, class ids, track ids (track mode)
r.masks.xy                                # list of (K,2) pixel polygons per instance
r.keypoints.xy, r.keypoints.conf          # (N,K,2), (N,K)
r.probs.top1, r.probs.top1conf            # classify; r.names[r.probs.top1] → label
r.obb.xyxyxyxy, r.obb.xywhr               # oriented boxes

from collections import Counter
counts = Counter(r.names[int(c)] for c in r.boxes.cls)   # count per class

model.embed("image.jpg") は特徴ベクトルを返します（類似検索、クラスタリング）。

トラッキング（フレームをまたぐ永続 ID）

for r in model.track("video.mp4", stream=True):
    ids = r.boxes.id  # tensor of track ids, or None

# Frame-by-frame loop with your own capture: persist=True is REQUIRED
r = model.track(frame, persist=True)[0]  # else the tracker resets every frame

• tracker= で選択する 6 つのトラッカー: tracktrack.yaml（デフォルト）、botsort.yaml、bytetrack.yaml、ocsort.yaml、deepocsort.yaml、fasttrack.yaml。ByteTrack が最も軽量です。BoT-SORT/TrackTrack/DeepOCSORT は ReID（with_reid: True）とカメラモーション補償（gmc_method）をサポートします。
• カスタム動作: ultralytics/cfg/trackers/ から YAML をコピーし、調整して（track_buffer = 失われたトラックが存続するフレーム数、track_high_thresh）、自分のパスを渡します。
• トラッキングはすべての predict 引数を受け付けますが、トラッカーが低信頼度のボックスを認識できるようにデフォルトは conf=0.1 です。常に r.boxes.id is not None をガードしてください。

注釈付き動画の書き出しパターン

import cv2

cap = cv2.VideoCapture("in.mp4")
w, h, fps = (int(cap.get(p)) for p in (cv2.CAP_PROP_FRAME_WIDTH, cv2.CAP_PROP_FRAME_HEIGHT, cv2.CAP_PROP_FPS))
out = cv2.VideoWriter("out.mp4", cv2.VideoWriter_fourcc(*"mp4v"), fps, (w, h))
for r in model.track("in.mp4", stream=True):
    out.write(r.plot())  # .plot() returns annotated BGR frame
cap.release()
out.release()

パフォーマンスチェックリスト

1. サポートされている GPU 上の PyTorch/TorchScript では、quantize=16 を FP32 とベンチマーク比較してください。
2. ターゲットネイティブのバックエンド（TensorRT/OpenVINO/CoreML）にエクスポートし、ベンチマークしてください（yolo-export を参照。エクスポートはそのまま YOLO() に読み込み直せます）。
3. より小さなモデルや imgsz、または NMS 不要の YOLO26 ヘッド（nms=False）を使用してください。
4. オフラインのフォルダーには batch>1 を設定してください。すべてのフレームが不要な場合は vid_stride を使用してください。
5. verbose=False を設定してください。座標のみが必要な場合は .plot() をスキップしてください。
6. スレッドごとに 1 つの YOLO() インスタンスを使用してください — スレッド間で共有しないでください。

トラブルシューティング

症状	原因 / 修正
見えているオブジェクトが検出されない	conf が高すぎる。重みが間違っている。imgsz がトレーニングサイズとかけ離れている
ボックスがずれる	手動で事前リサイズしている — 生の画像を渡してください。前処理は内部で行われます
PIL/matplotlib で赤と青が入れ替わる	Results の配列（orig_img、.plot()）は BGR です。cv2.cvtColor(..., cv2.COLOR_BGR2RGB) で変換してください
動画で RAM が増加し続ける	stream=True が指定されていない
boxes.id is None でクラッシュ	None をガードしてください。手動ループでは persist=True
ボックスが重複する	iou を下げてください。nms=False を外してください（その NMS 不要ヘッドは iou を無視します。そのような成果物は再エクスポートしてください）。クラスをまたぐ重複には agnostic_nms=True を追加してください
300 オブジェクトで頭打ちになる	max_det を上げてください
初回推論が遅い	ウォームアップ — 2 回目の呼び出しからベンチマークしてください

関連ページ

• solutions.md（このフォルダー）— 手作業でカウント、ヒートマップ、速度推定、ゾーンロジック、キュー、駐車、ワークアウトカウント、プライバシーブラーを実装する前に読んでください。既製の Solution がほぼ確実に存在します。

インストール済みのバージョンが引数を拒否する場合は、このファイルよりもエラーメッセージと yolo cfg を信頼してください。