Rust向けUltralytics Inference#

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

このプロジェクトは単一のcrate、ultralytics-inferenceとして提供され、2通りの方法で使用できます。迅速な予測やバッチジョブ向けのCLIとして使用する方法と、Rustアプリケーションに直接組み込むライブラリとして使用する方法です。すべてのUltralytics タスクに対応し、統一されたデバイスインターフェースを通じて幅広いハードウェアバックエンドを利用できます。

Rust推論を使用する理由#

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

インストール#

Rust 1.89以降が必要です。video featureを使用する場合は、システムにFFmpeg 7以降もインストールする必要があります。

# 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 --half

一般的なフラグ：

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

モデルを読み込み、予測を実行します。クラス名、タスクタイプ、画像サイズなどのモデルメタデータは、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(())
}

InferenceConfigを使用して、builder APIでしきい値、画像サイズ、精度、デバイスを制御します。

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

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

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専用です。

入力ソース#

--source引数（およびライブラリのSource型）は、文字列から自動検出されるさまざまな入力形式を受け付けます。

デバイスとExecution Provider#

推論はデフォルトでCPU上で実行されます。GPUおよびアクセラレーターのバックエンドはCargo featuresとしてビルド時に組み込まれ、--device（CLI）またはDevice（ライブラリ）で実行時に選択されます。

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

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

NVIDIAハードウェアでは、cuda featureによってCUDA Execution Providerが有効になり、tensorrtによってさらなる最適化のためのTensorRT Providerが追加されます。可能な限り低いレイテンシーを実現するには、cuda-preprocess featureによって前処理をGPU上に移します。

cuda-preprocessは、レターボックスリサイズ、正規化、HWCからCHWへのレイアウト変換を単一の融合CUDAカーネルとして実行し、その結果をゼロコピーのデバイステンソルとしてモデルに入力します。これにより、画像ごとのCPU前処理コストとホストからデバイスへのコピーが不要になります。これは、高スループットのバッチやリアルタイムストリームで特に効果的です。

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

以下の条件をすべて満たす場合、高速パスがAPIを変更せずに自動的に使用されます。featureがコンパイルに組み込まれていること、デバイスがCUDAまたはTensorRTであること、タスクがdetect、segment、pose、OBB、semantic segmentation、またはdepth estimationであること、そしてモデルがFP32入力を使用することです。デフォルトで有効になっており、モデルごとに無効化できます。

use ultralytics_inference::{Device, InferenceConfig};

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

Cargo features#

Featuresはビルド時に有効化されます。デフォルトでは、注釈付けとライブ表示が有効です。

便利なグループには、関連するProviderがまとめられています。nvidia（cuda、tensorrt）、amd（rocm、migraphx）、intel（openvino、onednn）、mobile（nnapi、coreml、qnn）、all（annotate、visualize、video）があります。nnapi、qnn、xnnpack、webgpuなど、その他のProviderも利用できます。

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

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

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

FAQ#