Rust용 Ultralytics 추론#

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

프로젝트는 ultralytics-inference이라는 단일 크레이트로 제공되며, 빠른 예측 및 배치 작업을 위한 CLI로 사용하거나 Rust 애플리케이션에 직접 포함하는 라이브러리로 사용할 수 있습니다. 모든 Ultralytics 작업과 통합 디바이스 인터페이스를 통해 다양한 하드웨어 백엔드를 지원합니다. 브라우저 추론을 위해 동일한 저장소에서 @ultralytics/yolo npm 패키지도 제공하며, 설정 가이드를 참조하세요.

Rust 추론을 선택하는 이유는 무엇인가요?#

• 네이티브 속도와 작은 설치 공간. 인터프리터 없이 네이티브 바이너리로 컴파일되므로 서버, 컨테이너 및 엣지 디바이스에 적합합니다.
• 메모리 안전성. Rust의 소유권 모델은 가비지 컬렉터 없이도 다양한 런타임 오류를 방지합니다.
• 모든 YOLO 작업. 하나의 API로 검출, 인스턴스 세그멘테이션, 시맨틱 세그멘테이션, 깊이 추정, 분류, 포즈 및 OBB를 처리합니다.
• 폭넓은 하드웨어 지원. 빌드 시 선택되는 실행 제공자는 CPU와 CUDA, TensorRT, CoreML, OpenVINO, DirectML, ROCm 및 XNNPACK을 지원합니다.
• GPU 측 전처리. 선택 사항인 융합 CUDA 커널이 GPU에서 레터박스, 정규화 및 레이아웃 변환을 실행하고, 디바이스에서 벗어나지 않고 결과를 모델에 전달합니다.
• 자동 다운로드. 알려진 YOLO 모델 이름과 샘플 에셋은 처음 사용할 때 자동으로 다운로드됩니다.

설치#

Rust 1.89 이상이 필요합니다. video 기능을 사용하려면 시스템에 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는 픽셀별 클래스 맵 PNG를 results/ 하위 폴더에 기록합니다. depth 작업에서는 색상화된 깊이 맵을 소스 이미지에 혼합하여 Ultralytics Python plot() 출력과 일치시킵니다. 주석이 추가된 이미지와 비디오를 저장하려면 annotate 기능이 필요하지만, 시맨틱 클래스 맵 PNG 내보내기에는 필요하지 않습니다. 비디오 입력 및 출력에는 video 기능이 필요합니다.

자주 묻는 질문#