Rust용 Ultralytics Inference#

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

이 프로젝트는 단일 크레이트인 ultralytics-inference으로 배포되며, 빠른 예측 및 배치 작업을 위한 CLI 또는 Rust 응용 프로그램에 직접 내장되는 라이브러리의 두 가지 방식으로 사용할 수 있습니다. 모든 Ultralytics 작업과 균일한 장치 인터페이스를 통한 다양한 하드웨어 백엔드를 지원합니다.

왜 Rust 추론인가요?#

• 네이티브 속도와 작은 용량. 인터프리터 없이 네이티브 바이너리로 컴파일되므로 서버, 컨테이너 및 에지 장치에 이상적입니다.
• 메모리 안전성. Rust의 소유권 모델은 가비지 컬렉터 없이도 런타임 오류를 근본적으로 제거합니다.
• 모든 YOLO 태스크. 하나의 API로 객체 검출, 인스턴스 분할, 의미론적 분할, 깊이 추정, 분류, 포즈 및 OBB를 수행합니다.
• 폭넓은 하드웨어 지원. 빌드 시 CPU 외에도 CUDA, TensorRT, CoreML, OpenVINO, DirectML, ROCm 및 XNNPACK 실행 공급자를 선택할 수 있습니다.
• GPU 측 전처리. 선택적인 퓨즈드(fused) CUDA 커널은 레터박스, 정규화 및 레이아웃 변환을 장치에서 수행하여 제로 카피(zero-copy) 입력 경로를 유지합니다.
• 자동 다운로드. 알려진 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(())
}

InferenceConfig을 사용하여 빌더 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이 생략되면 선택한 작업에 맞는 나노 모델이 자동으로 다운로드됩니다.

모델 호환성#

ONNX로 내보낸 모든 Ultralytics 모델을 로컬 파일에서 로드할 수 있습니다. 표준 YOLO26, YOLO11 및 YOLOv8 모델 이름의 경우 n, s, m, l, x 크기로 자동 다운로드를 사용할 수 있습니다.

의미론적 분할(-sem) 및 깊이 추정(-depth)은 YOLO26 전용입니다.

입력 소스#

--source 인수(및 라이브러리의 Source 타입)는 문자열에서 자동 감지되는 다양한 입력 형식을 허용합니다.

장치 및 실행 공급자#

추론은 기본적으로 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 기능은 CUDA 실행 제공자를 활성화하고, tensorrt은 추가 최적화를 위해 TensorRT 제공자를 추가합니다. 가장 낮은 지연 시간을 위해 cuda-preprocess 기능은 전처리를 GPU로 이동합니다.

cuda-preprocess은 레터박스 크기 조절, 정규화 및 HWC-to-CHW 레이아웃 변환을 단일 융합 CUDA 커널로 실행한 다음, 제로 코피 디바이스 텐서로 모델에 결과를 공급합니다. 이는 이미지별 CPU 전처리 비용과 호스트 간 복사 비용을 제거하며, 이는 고처리량 배치 및 실시간 스트림에 가장 중요합니다.

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

다음 조건이 모두 충족되면 API 변경 없이 패스트 패스(fast path)가 자동으로 사용됩니다: 기능이 컴파일되어 포함된 경우, 장치가 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 기능#

기능은 빌드 시점에 활성화됩니다. 기본값은 주석(annotation) 및 라이브 디스플레이를 포함합니다.

편의 그룹은 관련 제공자를 번들로 묶습니다: 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가 results/ 하위 폴더 아래에 픽셀별 클래스 맵 PNG를 기록합니다. depth 작업의 경우 컬러화된 깊이 맵이 소스 이미지 위에 혼합되어 Ultralytics Python plot() 출력과 일치합니다. 주석이 추가된 이미지 및 비디오 저장은 annotate 기능이 필요하며, 의미론적 클래스 맵 PNG 내보내기는 그렇지 않습니다. 비디오 입력 및 출력에는 video 기능이 필요합니다.

FAQ#

Python이 설치되어 있어야 하나요?#

아니요. 크레이트는 ONNX Runtime을 통해 내보낸 ONNX 모델을 직접 실행합니다. Python은 미리 Ultralytics 패키지로 모델을 학습시키거나 내보낼 때만 필요합니다.

어떤 모델을 실행할 수 있나요?#

YOLO26, YOLO11, YOLOv8을 포함하여 ONNX로 내보낸 모든 Ultralytics YOLO 모델입니다. 알려진 모델 이름은 자동으로 다운로드되며, --model을 로컬 .onnx 파일로 지정할 수도 있습니다.

모델 파일은 어떻게 얻나요?#

ONNX integration을 사용하여 Python 패키지에서 내보내거나, 첫 실행 시 CLI가 선택한 작업에 대한 표준 나노 모델을 다운로드하도록 하세요.

비디오가 지원되나요?#

네, video 기능이 활성화되어 있고 시스템에 FFmpeg 7 이상이 설치되어 있으면 가능합니다. 여기에는 비디오 파일, 웹캠, RTSP/RTMP/HTTP 스트림이 포함됩니다.

annotate 및 visualize 기능은 어떤 역할을 하나요?#

둘 다 기본적으로 활성화되어 있습니다. annotate은 이미지에 상자, 마스크, 키포인트 및 클래스 레이블을 그리며 --save이 주석이 추가된 결과를 기록하는 데 필요합니다. visualize는 --show을 위한 라이브 창을 엽니다. 프로그래밍 방식으로 페이로드 결과만 반환하는 더 작고 헤드리스 빌드의 경우 cargo build --no-default-features로 비활성화하세요(필요에 따라 개별 기능을 다시 추가).

전체 API 참조는 어디에 있나요?#

이 페이지는 개요 수준의 설명입니다. 모든 공개 구조체, 메서드 및 구성 옵션에 대한 완전한 타입별 API 참조는 소스에서 직접 생성되어 docs.rs에 게시됩니다.