はじめる

Rust向けUltralytics Inference

Ultralytics Inference GitHub Ultralytics Inference Crates.io Ultralytics Inference docs.rs Ultralytics Inference Downloads Ultralytics Inference MSRV

Ultralytics Inferenceは、Rustで記述された高性能なYOLO推論ライブラリおよびコマンドラインツールです。ONNX Runtimeを介してエクスポート済みのONNXモデルを実行し、推論時にPythonランタイムを必要とせず、画像、動画、Webカメラ、ストリームに対して高速でメモリ安全な予測を実行します。

このプロジェクトはultralytics-inferenceという単一のクレートとして提供され、2通りの方法で使用できます。すばやい予測やバッチジョブ用のCLIとして使う方法と、Rustアプリケーションに直接組み込むライブラリとして使う方法です。すべてのUltralytics タスクと、統一されたデバイスインターフェースを介した幅広いハードウェアバックエンドに対応しています。ブラウザーでの推論向けに、同じリポジトリから@ultralytics/yolo npmパッケージも公開されています。セットアップガイドをご覧ください。

Rustで推論する理由#

  • ネイティブの速度と小さなフットプリント。インタープリター不要のネイティブバイナリにコンパイルされるため、サーバー、コンテナ、エッジデバイスに最適です。
  • メモリ安全性。Rustの所有権モデルにより、ガベージコレクターを使わずに、実行時エラーの多くの種類を防止できます。
  • すべてのYOLOタスクに対応。 1つのAPIで検出、セグメンテーション、セマンティックセグメンテーション、深度推定、分類、姿勢推定、OBBを実行でき、シーンテキストOCRや大きな画像向けのタイル推論にも対応します。
  • 幅広いハードウェアをサポート。 CPUに加え、CUDA、TensorRT、CoreML、OpenVINO、DirectML、ROCm、MIGraphX、XNNPACKの実行プロバイダーをビルド時に選択でき、ネイティブのOpenVINO IRモデルにも対応します。
  • GPU側の前処理。オプションの融合CUDAカーネルがGPU上でレターボックス処理、正規化、レイアウト変換を実行し、デバイスから離れることなく結果をモデルに渡します。
  • 自動ダウンロード。 既知のYOLOモデル名、OCRモデル、サンプルアセットは初回使用時に自動でダウンロードされます。
  • Pythonと同じ出力。 マスク、マスクの輪郭、描画結果はUltralytics Pythonパッケージに準拠するため、--saveはplot()と同じ画像を生成します。
Pythonパッケージをお探しですか?

このページではスタンドアロンのRustクレートを扱います。Pythonワークフロー(トレーニング、検証、エクスポート、予測)については、メインのクイックスタートとPredictモードをご覧ください。ONNX連携を使って任意のUltralyticsモデルをONNXにエクスポートし、ここで実行できます。

インストール#

Rust 1.92以降が必要です。動画機能を使用するには、システムにFFmpeg 6から9もインストールされている必要があります。

# Install the command-line tool from crates.io
cargo install ultralytics-inference

# Or with GPU support compiled in
cargo install ultralytics-inference --features cuda,tensorrt

バイナリは~/.cargo/bin/ultralytics-inference(LinuxおよびmacOS)またはWindows上の%USERPROFILE%\.cargo\bin\に配置されます。

CLIクイックスタート#

CLIにはpredictサブコマンドがあります。引数を指定しない場合、nano検出モデルとサンプル画像をダウンロードして推論を実行し、注釈付きの結果をruns/detect/predictに保存します。

# Detect on the built-in samples (downloads model and images)
ultralytics-inference predict

# Detect on your own image
ultralytics-inference predict --model yolo26n.onnx --source image.jpg

# Segmentation (auto-downloads yolo26n-seg.onnx)
ultralytics-inference predict --task segment --source image.jpg

# Pose on a video, shown live in a window
ultralytics-inference predict --task pose --source video.mp4 --show

# Depth estimation (auto-downloads yolo26n-depth.onnx)
ultralytics-inference predict --task depth --source image.jpg

# Tune thresholds and filter to specific classes
ultralytics-inference predict --source image.jpg --conf 0.5 --iou 0.45 --classes "0,1,2"

# Run a whole folder on the GPU in half precision
ultralytics-inference predict --source images/ --device cuda:0 --quantize 16

# Tile a large aerial image into overlapping 640 px windows to find small objects
ultralytics-inference predict --model yolo26n-obb.onnx --source aerial.jpg --tile 640

# Read scene text (auto-downloads yolo26n-text.onnx and the PaddleOCR models)
ultralytics-inference predict --ocr --source sign.jpg

# Thicker lines, no confidences in labels
ultralytics-inference predict --source image.jpg --line-width 4 --show-conf false

すべてのpredictフラグ:

フラグデフォルト説明
--model, -myolo26n.onnxONNXモデルまたはOpenVINOエクスポートへのパスです。既知のYOLO名を指定すると自動でダウンロードされます。
--taskdetectdetect、segment、semantic、depth、classify、pose、obbのいずれかです。--modelを省略すると、nanoモデルが選択されます。
--source, -sサンプル画像、ディレクトリ、glob、動画、Webカメラのインデックス、ストリーム、またはURLです。
--conf0.25信頼度のしきい値。
--iou0.5非極大値抑制のIoUしきい値。
--max-det300画像ごとの検出数の上限。
--imgszモデルのメタデータ推論時の画像サイズ。
--rect [<BOOL>]trueパディングを最小限に抑えた矩形推論。
--tile [<TILE>]オフ重なり合うウィンドウ推論のタイルサイズです。値を指定せずに--tileを指定すると、--imgszが使用されます。タイル推論をご覧ください。
--retina-masksfalse推論サイズではなく、元の画像サイズでセグメンテーションマスクを生成します。
--ocrfalsePaddleOCRで各ボックス、OBB、またはマスク内のテキストを読み取ります。--modelを指定しない場合は、yolo26n-text.onnxが実行されます。OCRをご覧ください。
--batch1推論のバッチサイズ。
--quantizeモデルの精度推論精度: 8、16、32、int8、fp16、fp32、w8a8、w16a16、w32a32、w8a16、またはw8a32です。
--save [<BOOL>]trueアノテーション済みの結果をruns/<task>/predictに保存します。
--save-framesfalse動画ファイルの代わりに、動画入力の個々のフレームを保存します。
--save-jsonfalseセマンティックセグメンテーションのクラスマップをPNGで保存します。
--showfalse結果をウィンドウに表示します。
--show-labels [<BOOL>]trueボックスラベルにクラス名を表示します。
--show-conf [<BOOL>]trueボックスラベルに信頼度を表示します。
--show-boxes [<BOOL>]trueボックスとそのラベルを描画します。
--line-width画像サイズからボックスの線幅(ピクセル単位)です。ラベルのサイズもこれに応じて変わります。
--deviceauto実行デバイスです。例: cpu、cuda:0、tensorrt:0、coreml、intel:gpu、directml:0、rocm:0、migraphx:0、xnnpack。
--verbose [<BOOL>]true画像ごとの結果と処理時間を出力します。
--classesすべてクラスIDで検出結果をフィルタリングします。例: 0、"0,1,2"、または"[0, 1, 2]"。

[<BOOL>]は値を省略できるフラグです。値を指定せずに指定すると(--rect)、trueに設定され、--rect falseでオフになります。従来の--halfフラグも引き続き使用でき、--quantize 16に対応付けられ、Pythonパッケージと同じ非推奨警告が表示されます。

ライブラリのクイックスタート#

モデルを読み込んで予測を実行します。クラス名、タスクの種類、画像サイズなどのモデルメタデータは、ONNXファイルから自動的に読み込まれます。

use ultralytics_inference::YOLOModel;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Metadata (classes, task, imgsz) is parsed from the model.
    let mut model = YOLOModel::load("yolo26n.onnx")?;

    let results = model.predict("image.jpg")?;

    for result in &results {
        if let Some(boxes) = &result.boxes {
            for i in 0..boxes.len() {
                let class_id = boxes.cls()[i] as usize;
                let conf = boxes.conf()[i];
                let name = result.names.get(&class_id).map_or("unknown", |s| s.as_str());
                println!("{name} {conf:.2}");
            }
        }
    }

    Ok(())
}

ビルダーAPIを使用して、InferenceConfigでしきい値、画像サイズ、精度、デバイスを設定します:

use ultralytics_inference::{Device, InferenceConfig, Quantization, YOLOModel};

let config = InferenceConfig::new()
    .with_confidence(0.5)
    .with_iou(0.45)
    .with_imgsz(640, 640)
    .with_device(Device::Cuda(0))
    .with_quantize(Quantization::Fp16);

let mut model = YOLOModel::load_with_config("yolo26n.onnx", config)?;
let results = model.predict("image.jpg")?;

タスクごとに、Resultsの異なるフィールドに値が設定されます。以下の各タブは、単独で実行可能な完全なプログラムです。モデルとサンプル入力は初回実行時に自動的にダウンロードされます。独自のファイルを使って実行するには、predict_default()をpredict("image.jpg")に置き換えます。

use ultralytics_inference::YOLOModel;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut model = YOLOModel::load("yolo26n.onnx")?;
    let results = model.predict_default()?;

    for result in &results {
        if let Some(boxes) = &result.boxes {
            println!("{} detections", boxes.len());
            let xyxy = boxes.xyxy(); // rows of [x1, y1, x2, y2]
            for i in 0..boxes.len() {
                let class_id = boxes.cls()[i] as usize;
                let name = result.names.get(&class_id).map_or("unknown", |s| s.as_str());
                println!("  {name} {:.2} {:?}", boxes.conf()[i], xyxy.row(i).to_vec());
            }
        }
    }

    Ok(())
}

サポート対象のタスク#

Ultralyticsのタスクはすべてサポートされています。--modelを省略すると、選択したタスクに対応するnanoモデルが自動的にダウンロードされます。

タスク--task出力デフォルトモデル
検出detectバウンディングボックスとクラスyolo26n.onnx
インスタンスセグメンテーションsegmentボックスとインスタンスごとのマスクyolo26n-seg.onnx
セマンティックセグメンテーションsemanticピクセル単位のクラスマップyolo26n-sem.onnx
深度推定depthメートル単位のピクセルごとの深度マップyolo26n-depth.onnx
分類classifyクラス確率yolo26n-cls.onnx
姿勢推定poseボックスとキーポイントyolo26n-pose.onnx
方向付きボックスobb回転バウンディングボックスyolo26n-obb.onnx

--ocrは、任意の検出、セグメンテーション、またはOBBモデルにシーンテキスト読み取り機能を追加します。--modelを指定しない場合は、yolo26n-text.onnxテキスト検出器が実行されます。シーンテキストOCRをご覧ください。

モデルの互換性#

ONNXにエクスポートしたUltralyticsモデルは、ローカルファイルから読み込めます。標準のYOLO26、YOLO11、YOLOv8のモデル名と、サイズn、s、m、l、xでは、自動ダウンロードを利用できます。

モデルファミリー自動ダウンロード可能なバリアント
YOLO26yolo26{n,s,m,l,x}.onnx、-seg、-sem、-depth、-cls、-pose、-obb、および-text
YOLO11yolo11{n,s,m,l,x}.onnx、-seg、-cls、-pose、-obb
YOLOv8yolov8{n,s,m,l,x}.onnx、-seg、-cls、-pose、-obb

セマンティックセグメンテーション(-sem)、深度推定(-depth)、および-textシーンテキスト検出器はYOLO26専用です。--ocr(Apache-2.0)で使用するPaddleOCRのPP-OCRv6_medium_rec.onnx認識器とPP-LCNet_x0_25_textline_ori.onnx方向分類器も自動でダウンロードされます。RT-DETR検出モデルも実行できますが、自動ダウンロードには対応していません。まずONNXにエクスポートしてください。ネイティブのOpenVINO IRエクスポートはopenvino-native機能で実行できます。OpenVINO IRモデルをご覧ください。

入力ソース#

--source引数(およびライブラリのSource型)は、文字列から自動判定されるさまざまな種類の入力を受け付けます:

ソース例備考
画像image.jpg単一ファイル。
ディレクトリimages/フォルダー内のすべての画像。
Globimages/*.jpgシェル形式のパターン。
動画video.mp4video機能が必要です。
ウェブカメラ0video機能が必要です。
ストリームrtsp://...video機能が必要です。
URLhttps://example.com/image.jpgリモート画像のダウンロード。

タイル推論#

航空写真や衛星写真のように小さな物体を含む大きな画像は、重なり合うウィンドウに分割してから、Pythonのtile引数と同様に1つの結果へ統合できます。ウィンドウは20%重なり、ボックスは元画像の座標に戻され、クラスごとに重複が除去されます。動的バッチエクスポートでは、--batchを指定すると、1回の推論呼び出しで複数のウィンドウを処理します。すべてのタスクに対応しています。

# 640 px windows; a bare --tile uses --imgsz
ultralytics-inference predict --model yolo26n-obb.onnx --source aerial.jpg --tile 640
use ultralytics_inference::{InferenceConfig, YOLOModel};

// with_tile(0) uses the inference size
let config = InferenceConfig::new().with_tile(640);
let mut model = YOLOModel::load_with_config("yolo26n.onnx", config)?;
let results = model.predict("aerial.jpg")?;

シーンテキストOCR#

YOLO26-Text検出器は単語を回転ボックスとして検出し、TextRecognizerによって、PythonのOCRソリューションと同じ認識器であるPaddleOCR PP-OCRv6で読み取ります。検出モデルのボックスとセグメンテーションモデルのマスクも使用できます。マスクは輪郭を囲む最小面積の矩形から読み取り、輪郭はポリゴンとして保持します。各切り抜き画像は正立するよう回転され、方向分類器が上下逆さまと判定したテキストは、反対向きに回転して再度読み取ります。認識結果は読み順で返されます。認識器は検出器と同じデバイスで動作します。

# Auto-downloads yolo26n-text.onnx and the PaddleOCR models
ultralytics-inference predict --ocr --source sign.jpg

# Any size of the text detector, on the GPU
ultralytics-inference predict --ocr --model yolo26x-text.onnx --source sign.jpg --device cuda:0

ライブラリのサンプルではimageクレートを使って画像を読み込むため、cargo add imageを使ってパッケージと一緒に追加してください。

use ultralytics_inference::YOLOModel;
use ultralytics_inference::ocr::{DEFAULT_ORIENTATION, DEFAULT_RECOGNIZER, TextRecognizer};

let mut detector = YOLOModel::load("yolo26n-text.onnx")?;
let mut ocr = TextRecognizer::new(&detector, DEFAULT_RECOGNIZER, DEFAULT_ORIENTATION)?;
let image = image::open("sign.jpg")?;
let result = detector.predict_image(&image, "sign.jpg".into())?.remove(0);
for text in ocr.read(&image, &result)? {
    println!("{} {:.2} {:?}", text.text, text.confidence, text.polygon);
}

predict --ocrはPythonソリューションと同じように各テキストを描画し、--line-width、--show-labels、--show-confも適用されます。

デバイスと実行プロバイダー#

GPUおよびアクセラレータのバックエンドはCargo機能としてコンパイルされ、--device(CLI)またはDevice(ライブラリ)を使って実行時に選択します。デバイスを指定しない場合、ビルドに組み込まれたプロバイダーは固定の優先順位(TensorRT、CUDAの順など)で登録されるため、デフォルト機能のみのビルドではCPUで実行されます。

デバイス文字列Deviceバリアントビルド機能ハードウェア
cpuDevice::Cpu組み込み任意のCPU
cuda:0Device::Cuda(0)cudaNVIDIA GPU
tensorrt:0Device::TensorRt(0)tensorrtNVIDIA GPU、最適化済み
coremlDevice::CoreMlcoremlApple Silicon / macOS
intel:cpuDevice::IntelCpuopenvinoまたはopenvino-nativeIntel CPU
intel:gpuDevice::IntelGpuopenvinoまたはopenvino-nativeIntel GPU
intel:npuDevice::IntelNpuopenvinoまたはopenvino-nativeIntel NPU
directml:0Device::DirectMl(0)directmlWindows GPU
rocm:0Device::Rocm(0)rocmAMD GPU
migraphx:0Device::MiGraphX(0)migraphxAMD GPU(Linux x64)
xnnpackDevice::Xnnpackxnnpack最適化済みCPU
# Build the CLI with the providers you need
cargo install ultralytics-inference --features cuda,tensorrt

OpenVINO IRモデル#

openvino-native機能を有効にすると、--modelはネイティブのOpenVINOエクスポート(.xmlファイル、またはyolo export format=openvinoのフォルダー)も受け付け、ONNX RuntimeではなくOpenVINOランタイムで実行します。すべてのタスクをintel:cpu、intel:gpu、intel:npuで実行でき、ライブラリはYOLOModel::load("yolo26n_openvino_model")で読み込みます。ビルド時にOpenVINOをインストールする必要はありません。ランタイムは最初のモデルを開くときに読み込まれます。セットアップについてはOpenVINOガイドをご覧ください。

yolo export model=yolo26n.pt format=openvino # add quantize=16, quantize=8, dynamic=True, or batch=4
ultralytics-inference predict --model yolo26n_openvino_model --source bus.jpg --device intel:gpu

GPUアクセラレーションとCUDA前処理#

NVIDIAハードウェアでは、cuda機能でCUDA実行プロバイダーが有効になり、tensorrtを追加すると、さらなる最適化のためにTensorRTプロバイダーが有効になります(OCR認識器も実行するcudaを含みます)。推論レイテンシを可能な限り短縮するには、cuda-preprocess機能で前処理をGPU上で実行します。

cuda-preprocessは、レターボックスリサイズ、正規化、HWCからCHWへのレイアウト変換を、単一の融合CUDAカーネルとして実行し、その結果をゼロコピーのデバイステンソルとしてモデルに渡します。生の8ビットフレームは引き続きGPUにアップロードされ、ディスクリートGPUではピン留めされたステージングバッファーを経由します。このカーネルによって省かれるのは、CPUでのリサイズ、正規化、レイアウト変換、および前処理済みテンソルの個別アップロードです。これらの効果は、高スループットのバッチやリアルタイムストリームで特に大きくなります。

# Build with fused GPU preprocessing (implies cuda + tensorrt)
cargo build --release --features cuda-preprocess

以下の条件をすべて満たす場合、高速パスがAPIの変更なしに自動的に使用されます。機能がコンパイルに含まれていること、デバイスがCUDA、TensorRT、または未指定であること、タスクが検出、セグメンテーション、セマンティックセグメンテーション(単一画像のみ)、深度推定、姿勢推定、またはOBBであること、モデルの入力がFP32であることです。デフォルトで有効になっており、モデルごとに無効化できます。

use ultralytics_inference::{Device, InferenceConfig};

let config = InferenceConfig::new()
    .with_device(Device::TensorRt(0))
    .with_cuda_preprocess(false); // force CPU preprocessing
CUDAツールキットのバージョンを合わせる

cuda-preprocessはビルド時に対応するCUDAツールキットを必要とし、実行時には融合前処理カーネルにNVRTCを使用します。バージョン要件とトラブルシューティングについては、CUDAとTensorRTのアクセラレーションガイドを参照してください。

Cargo機能#

機能はビルド時に有効にします。デフォルトでは、アノテーションとライブ表示に対応しています。

機能デフォルト用途
annotateはいボックス、マスク、キーポイント、ラベル、OCRテキストを描画します。--saveに必要です。
visualizeはい--showのリアルタイムウィンドウ表示。
videoいいえ動画ファイルの読み込みと書き込み(FFmpeg 6~9が必要です)。
cudaいいえNVIDIA CUDA実行プロバイダー。
tensorrtいいえNVIDIA TensorRT実行プロバイダー(cudaを含みます)。
cuda-preprocessいいえGPU前処理を融合します(cuda、tensorrtを有効にし、CUDA Toolkitが必要です)。
coremlいいえApple CoreML実行プロバイダー。
openvinoいいえIntel OpenVINO実行プロバイダー(LinuxおよびWindows x64)。
openvino-nativeいいえOpenVINOランタイムを使用するネイティブOpenVINO IR(.xml)モデル。
rocmいいえAMD ROCm実行プロバイダー(独自のONNX Runtimeビルドが必要です)。
migraphxいいえAMD MIGraphX実行プロバイダー(Linux x64)。
directmlいいえWindows DirectML実行プロバイダー。
xnnpackいいえCPU推論を最適化するXNNPACK実行プロバイダー。

関連するプロバイダーをまとめた便利なグループ: nvidia(cuda、tensorrt)、amd(rocm、migraphx)、intel(openvino、onednn)、mobile(nnapi、coreml、qnn)、all(annotate、visualize、video)。追加のプロバイダーonednn、nnapi、qnn、acl、tvm、rknpu、cann、webgpu、azureも利用できます。

CLIのインストール時またはライブラリの追加時に機能を有効にします:

cargo install ultralytics-inference --features video
cargo install ultralytics-inference --features cuda,tensorrt
[dependencies]
ultralytics-inference = { version = "0.0.58", features = ["video"] }

出力と保存#

デフォルトでは、予測結果にアノテーションが付けられ、連番の実行ディレクトリに保存されます:

runs/
└── detect/
    └── predict/          # then predict2, predict3, ...
        └── image.jpg     # annotated result

サブフォルダー名はタスク(runs/segment/、runs/pose/など)に対応します。動画ソースの場合、アノテーション済みの出力は動画ファイルとして書き込まれます。個々のフレームを書き込むには、--save-framesを渡します。semanticタスクでは、--save-jsonにより、ピクセル単位のクラスマップがresults/サブフォルダーにPNGとして書き込まれます。depthタスクでは、色付けされた深度マップがソース画像に重ね合わされ、Ultralytics Pythonのplot()出力と同じ形式になります。アノテーション済み画像と動画の保存にはannotate機能が必要ですが、セマンティッククラスマップのPNGエクスポートには必要ありません。動画の入力と出力にはvideo機能が必要です。

描画はPythonのResults.plot()に準拠します。線幅は画像の平均辺長の0.3%(最小2 px)がデフォルトで、ラベルは各ボックスの上に配置され、スペースがない場合はボックス内に配置されます。インスタンスマスクも同じ方法でブレンドされるため、保存画像はPythonと一致します。--line-width、--show-labels、--show-conf、--show-boxesは、同名のPython引数と同様に動作します。ライブラリでは、これらをAnnotateOptions経由で渡します。

use ultralytics_inference::annotate::{AnnotateOptions, annotate_image_with_options};

let options = AnnotateOptions {
    line_width: Some(3),
    show_conf: false,
    ..Default::default()
};
let annotated = annotate_image_with_options(&image, &results[0], &options);

セグメンテーションマスクはPythonと同様に推論サイズで生成されます。元の画像サイズで生成するには、--retina-masks(またはInferenceConfig::with_retina_masks(true))を渡してください。

よくある質問#

  • いいえ。このクレートは、ONNX Runtimeを通じてエクスポート済みのONNXモデルを直接実行します。事前にUltralyticsパッケージでモデルをトレーニングまたはエクスポートする場合にのみ、Pythonが必要です。

  • YOLO26、YOLO11、YOLOv8を含む、ONNXにエクスポートされたUltralytics YOLOモデルを実行できます。既知のモデル名は自動的にダウンロードされます。また、任意のローカル.onnxファイルを--modelで指定することもできます。

  • Pythonパッケージから、たとえばONNXインテグレーションを使ってエクスポートするか、初回実行時にCLIで選択したタスクに対応する標準nanoモデルをダウンロードできます。

  • はい。--ocrはYOLO26-Text検出器とPaddleOCRを使ってシーンテキストを読み取ります。これはPythonのOCRソリューションと同様で、独自の検出モデルやセグメンテーションモデルのボックスまたはマスクにも対応します。シーンテキストOCRをご覧ください。

  • タイル推論を使用します。--tile 640は画像を重なり合う640 pxのウィンドウに分割し、検出結果を1つに統合します。

  • システムに FFmpeg 6~9 がインストールされ、video 機能が有効になっていれば可能です。動画ファイル、ウェブカメラ、RTSP/RTMP/HTTP ストリームに対応しています。

  • どちらもデフォルトで有効になっています。annotate は画像にボックス、マスク、キーポイント、クラスラベルを描画し、--save で注釈付きの結果を書き出すために必要です。visualize は --show 用のライブウィンドウを開きます。プログラムから結果を返すだけの小規模なヘッドレスビルドにするには、cargo build --no-default-features で無効にしてください(必要に応じて個別の機能を再度有効にできます)。

  • このページでは概要を説明しています。公開されているすべての構造体、メソッド、設定オプションを網羅した、型ごとの完全な API リファレンスは、ソースから直接生成され、docs.rs で公開されています。

コントリビューター

コメント

質問したり、結果を共有したり、ほかの人をサポートしたりできます。