Rust用 Ultralytics Inference#

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

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

Rustでの推論を選ぶ理由は？#

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

インストール#

Rust 1.89 以降が必要です。ビデオ機能にはさらに、システムに 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 サブコマンドを公開します。引数なしで実行すると、ナノ検出モデルとサンプル画像をダウンロードし、推論を実行して、注釈付きの結果を 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(())
}

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

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 が省略された場合、選択されたタスクに一致するナノモデルが自動的にダウンロードされます。

モデル互換性#

ONNX にエクスポートされた任意の Ultralytics モデルをローカルファイルからロードできます。標準の YOLO26、YOLO11、および YOLOv8 モデル名の自動ダウンロードは、n、s、m、l、および x のサイズで利用可能です。

セマンティックセグメンテーション（-sem）と深度推定（-depth）は YOLO26 専用です。

入力ソース#

--source 引数（およびライブラリ内の Source タイプ）は、文字列から自動検出される多くの入力タイプを受け入れます。

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

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

# 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 カーネルとして実行し、結果をゼロコピーのデバイステンスとしてモデルに供給します。これにより、画像ごとの 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

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.33", features = ["video"] }

出力と保存#

デフォルトでは、予測結果はアノテーションが付加され、自動的にインクリメントされる実行ディレクトリに保存されます：

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

サブフォルダはタスク（runs/segment/、runs/pose/ など）に対応します。ビデオソースの場合、注釈付きの出力はビデオファイルとして書き込まれます。個々のフレームを代わりに書き込むには --save-frames を渡します。semantic タスクの場合、--save-json はピクセルごとのクラスマップ PNG を results/ サブフォルダの下に書き込みます。depth タスクの場合、カラー化された深度マップがソース画像にブレンドされ、Ultralytics Python の plot() 出力と一致します。注釈付きの画像とビデオの保存には annotate 機能が必要ですが、セマンティッククラスマップ PNG のエクスポートには必要ありません。ビデオの入力と出力には video 機能が必要です。

よくある質問 (FAQ)#