Rust向けUltralytics Inference#

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

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

Rustで推論する理由#

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

インストール#

Rust 1.89以降が必要です。動画機能を使用するには、システムに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

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

共通フラグ:

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

モデルを読み込んで予測を実行します。クラス名、タスクの種類、画像サイズなどのモデルメタデータは、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モデルが自動的にダウンロードされます。

モデルの互換性#

ONNXにエクスポートされたUltralyticsモデルは、いずれもローカルファイルから読み込めます。YOLO26、YOLO11、YOLOv8の標準的なモデル名は、サイズn、s、m、l、xであれば自動ダウンロードできます:

セマンティックセグメンテーション（-sem）と深度推定（-depth）はYOLO26のみで利用できます。RT-DETRの検出モデルも実行できますが、自動ダウンロードには対応していません。先にONNXにエクスポートしてください。

入力ソース#

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

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

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

# Build the CLI with the providers you need
cargo install ultralytics-inference --features cuda,tensorrt

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

NVIDIAハードウェアでは、cuda機能によりCUDA実行プロバイダーが有効になり、tensorrtを追加すると、さらなる最適化のためにTensorRTプロバイダーが有効になります。可能な限り低いレイテンシを実現するには、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であること、タスクがdetect、segment、pose、OBB、セマンティックセグメンテーション（単一画像のみ）、または深度推定であること、そしてモデルの入力がFP32であることです。デフォルトで有効になっており、モデルごとに無効化できます:

use ultralytics_inference::{Device, InferenceConfig};

let config = InferenceConfig::new()
    .with_device(Device::TensorRt(0))
    .with_cuda_preprocess(false); // force CPU preprocessing

Cargo機能#

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

関連するプロバイダーをまとめた便利なグループ: nvidia（cuda、tensorrt）、amd（rocm、migraphx）、intel（openvino、onednn）、mobile（nnapi、coreml、qnn）、all（annotate、visualize、video）。nnapi、qnn、xnnpack、webgpuなど、ほかのプロバイダーも利用できます。

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

cargo install ultralytics-inference --features video
cargo install ultralytics-inference --features cuda,tensorrt

[dependencies]
ultralytics-inference = { version = "0.0.50", 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機能が必要です。

よくある質問#