Rust용 Ultralytics Inference#

Ultralytics Inference는 Rust로 작성된 고성능 YOLO 추론 라이브러리이자 명령줄 도구입니다. ONNX 모델을 ONNX Runtime을 통해 실행하여 추론 시 Python 런타임 없이 이미지, 동영상, 웹캠 및 스트림에서 빠르고 메모리 안전한 예측을 제공합니다.

이 프로젝트는 단일 crate인 ultralytics-inference으로 제공되며, 두 가지 방식으로 사용할 수 있습니다. 빠른 예측과 배치 작업을 위한 CLI로 사용하거나, Rust 애플리케이션에 직접 임베드되는 라이브러리로 사용할 수 있습니다. 모든 Ultralytics task를 지원하며, 통합된 디바이스 인터페이스를 통해 다양한 하드웨어 백엔드를 지원합니다.

Rust 추론을 사용하는 이유#

• 네이티브 속도와 작은 풋프린트. 인터프리터 없이 네이티브 바이너리로 컴파일되므로 서버, 컨테이너 및 엣지 디바이스에 적합합니다.
• 메모리 안전성. Rust의 소유권 모델은 가비지 컬렉터 없이도 다양한 런타임 오류를 원천적으로 제거합니다.
• 모든 YOLO task. 하나의 API에서 detect, segment, semantic segmentation, depth estimation, classify, pose 및 OBB를 지원합니다.
• 폭넓은 하드웨어 지원. CPU와 CUDA, TensorRT, CoreML, OpenVINO, DirectML, ROCm 및 XNNPACK 실행 프로바이더를 빌드 시 선택할 수 있습니다.
• GPU 측 전처리. 선택적 fused CUDA kernel을 사용하면 letterbox, normalize 및 레이아웃 변환을 디바이스에서 처리하여 zero-copy 입력 경로를 유지합니다.
• 자동 다운로드. 알려진 YOLO 모델 이름과 샘플 asset은 처음 사용할 때 자동으로 다운로드됩니다.

설치#

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 detection 모델과 샘플 이미지를 다운로드하고, 추론을 실행한 뒤 주석이 추가된 결과를 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

일반적인 플래그:

라이브러리 빠른 시작#

모델을 로드하고 prediction을 실행합니다. class name, task type 및 image size와 같은 모델 metadata는 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로 threshold, image size, precision 및 device를 제어할 수 있습니다.

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")?;

각 task는 Results의 서로 다른 field를 채웁니다. 아래의 각 탭은 완전하게 실행 가능한 프로그램이며, 모델과 샘플 입력은 처음 실행할 때 자동으로 다운로드됩니다. 자신의 파일에서 실행하려면 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(())
}

지원되는 task#

모든 Ultralytics task를 지원합니다. --model을 생략하면 선택한 task에 해당하는 nano 모델이 자동으로 다운로드됩니다.

모델 호환성#

ONNX로 export된 모든 Ultralytics 모델은 로컬 파일에서 로드할 수 있습니다. 표준 YOLO26, YOLO11 및 YOLOv8 모델 이름은 n, s, m, l 및 x 크기에서 자동 다운로드할 수 있습니다.

Semantic segmentation(-sem)과 depth estimation(-depth)은 YOLO26에서만 지원됩니다.

입력 소스#

--source 인수와 라이브러리의 Source type은 문자열에서 자동으로 감지되는 다양한 입력 형식을 지원합니다.

디바이스 및 실행 프로바이더#

추론은 기본적으로 CPU에서 실행됩니다. GPU 및 accelerator 백엔드는 Cargo feature로 컴파일되며, --device(CLI) 또는 Device(라이브러리)를 사용하여 런타임에 선택합니다.

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

GPU 가속 및 CUDA 전처리#

NVIDIA 하드웨어에서 cuda feature는 CUDA 실행 프로바이더를 활성화하며, tensorrt은 추가 최적화를 위한 TensorRT 프로바이더를 추가합니다. 가능한 가장 낮은 latency를 위해 cuda-preprocess feature는 전처리를 GPU에서 수행합니다.

cuda-preprocess은 letterbox resizing, normalization 및 HWC-to-CHW 레이아웃 변환을 하나의 fused CUDA kernel로 실행한 다음, 그 결과를 zero-copy device tensor로 모델에 전달합니다. 이를 통해 이미지별 CPU 전처리 비용과 host-to-device 복사가 제거되며, 이는 처리량이 높은 batch와 실시간 stream에서 특히 중요합니다.

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

다음 조건을 모두 충족하면 빠른 경로가 API 변경 없이 자동으로 사용됩니다. feature가 컴파일되어 있고, device가 CUDA 또는 TensorRT이며, task가 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 feature#

Feature는 빌드 시 활성화됩니다. 기본값에는 annotation 및 live display가 포함됩니다.

편의성 그룹은 관련 프로바이더를 묶습니다: nvidia(cuda, tensorrt), amd(rocm, migraphx), intel(openvino, onednn), mobile(nnapi, coreml, qnn) 및 all(annotate, visualize, video)입니다. nnapi, qnn, xnnpack, webgpu과 같은 추가 프로바이더 및 기타 프로바이더도 사용할 수 있습니다.

CLI를 설치하거나 라이브러리를 추가할 때 feature를 활성화합니다.

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

하위 폴더는 task에 해당합니다(runs/segment/, runs/pose/ 등). 비디오 소스의 경우 주석이 추가된 출력은 비디오 파일로 기록되며, 개별 프레임으로 기록하려면 --save-frames를 전달합니다. semantic task에서는 --save-json가 픽셀별 클래스 맵 PNG를 results/ 하위 폴더에 기록합니다. depth task에서는 색상화된 깊이 맵이 소스 이미지 위에 혼합되며, Ultralytics Python plot() 출력과 일치합니다. 주석이 추가된 이미지와 비디오를 저장하려면 annotate feature가 필요하지만, semantic 클래스 맵 PNG 내보내기에는 필요하지 않습니다. 비디오 입력 및 출력에는 video feature가 필요합니다.

FAQ#