Link to this sectionRust용 Ultralytics Inference#

Ultralytics Inference is a high-performance YOLO inference library and command-line tool written in Rust. It runs exported ONNX models through ONNX Runtime to deliver fast, memory-safe predictions on images, videos, webcams, and streams, with no Python runtime required at inference time.

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

Link to this section왜 Rust 추론인가요?#

• 네이티브 속도와 작은 설치 공간. 인터프리터 없이 네이티브 바이너리로 컴파일되므로 서버, 컨테이너 및 엣지 장치에 이상적입니다.
• 메모리 안전성. Rust의 소유권 모델은 가비지 컬렉터 없이도 런타임 오류를 근본적으로 제거합니다.
• 모든 YOLO 작업 지원. 단일 API로 탐지, 세그먼트, 포즈, OBB, 분류 및 의미론적 세그먼트를 수행합니다.
• 폭넓은 하드웨어 지원. 빌드 시 CPU 외에도 CUDA, TensorRT, CoreML, OpenVINO, DirectML, ROCm 및 XNNPACK 실행 공급자를 선택할 수 있습니다.
• GPU 측 전처리. 선택적인 퓨즈드(fused) CUDA 커널은 레터박스, 정규화 및 레이아웃 변환을 장치에서 수행하여 제로 카피(zero-copy) 입력 경로를 유지합니다.
• 자동 다운로드. 알려진 YOLO 모델 이름과 샘플 에셋은 처음 사용할 때 자동으로 다운로드됩니다.

Link to this section설치#

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

Link to this sectionCLI 빠른 시작#

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

# 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

일반 플래그:

Link to this section라이브러리 빠른 시작#

모델을 로드하고 예측을 실행합니다. 클래스 이름, 작업 유형, 이미지 크기와 같은 모델 메타데이터는 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(())
}

Link to this section지원되는 작업#

모든 Ultralytics 작업이 지원됩니다. --model이 생략되면 선택한 작업에 맞는 나노(nano) 모델이 자동으로 다운로드됩니다.

Link to this section모델 호환성#

ONNX로 내보낸 모든 Ultralytics 모델은 로컬 파일에서 로드할 수 있습니다. n, s, m, l, x 크기의 표준 YOLO26, YOLO11 및 YOLOv8 모델 이름에 대해서는 자동 다운로드가 가능합니다:

의미론적 세그먼트(-sem)는 YOLO26 전용입니다.

Link to this section입력 소스#

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

Link to this section장치 및 실행 공급자#

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

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

Link to this sectionGPU 가속 및 CUDA 전처리#

NVIDIA 하드웨어에서 cuda 기능은 CUDA 실행 공급자를 활성화하며, tensorrt는 추가 최적화를 위한 TensorRT 공급자를 추가합니다. 최상의 지연 시간을 위해 cuda-preprocess 기능은 전처리를 GPU에서 수행합니다.

cuda-preprocess는 레터박스 리사이징, 정규화, HWC-to-CHW 레이아웃 변환을 단일 융합된 CUDA 커널로 실행한 다음, 결과를 제로 카피(zero-copy) 디바이스 텐서로 모델에 전달합니다. 이는 이미지당 CPU 전처리 비용과 호스트-투-디바이스 복사 비용을 제거하며, 이는 고처리량 배치 및 실시간 스트림에서 매우 중요합니다.

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

빠른 경로(fast path)는 다음 조건이 모두 충족될 경우 API 변경 없이 자동으로 사용됩니다: 기능이 컴파일되어 포함됨, 디바이스가 CUDA 또는 TensorRT임, 작업이 detect, segment, pose, OBB 또는 semantic segmentation 중 하나임, 모델이 FP32 입력을 사용함. 이는 기본적으로 활성화되어 있으며 모델별로 비활성화할 수 있습니다:

use ultralytics_inference::{Device, InferenceConfig};

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

Link to this sectionCargo 기능#

기능은 빌드 시점에 활성화됩니다. 기본값은 주석(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.18", features = ["video"] }

Link to this section출력 및 저장#

기본적으로 예측 결과는 주석이 달리고 자동으로 증가하는 실행 디렉토리에 저장됩니다:

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

하위 폴더는 작업 이름과 일치합니다 (runs/segment/, runs/pose/ 등). 비디오 소스의 경우 주석이 달린 출력은 비디오 파일로 기록됩니다. 개별 프레임을 쓰려면 --save-frames를 전달하십시오. semantic 작업의 경우 --save-json은 results/ 하위 폴더 아래에 픽셀별 클래스 맵 PNG를 작성합니다. 주석이 달린 이미지 및 비디오 저장에는 annotate 기능이 필요하며, 시맨틱 클래스 맵 PNG 내보내기에는 필요하지 않습니다. 비디오 입력 및 출력에는 video 기능이 필요합니다.

Link to this sectionFAQ#

Link to this sectionPython이 설치되어 있어야 하나요?#

아니오. 크레이트는 ONNX 런타임을 통해 내보낸 ONNX 모델을 직접 실행합니다. Python은 Ultralytics 패키지를 사용하여 모델을 미리 학습하거나 export할 경우에만 필요합니다.

Link to this section어떤 모델을 실행할 수 있나요?#

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

Link to this section모델 파일은 어떻게 얻나요?#

Python 패키지에서 예를 들어 ONNX integration을 통해 내보내거나, 첫 실행 시 CLI가 선택한 작업에 맞는 표준 나노 모델을 다운로드하게 하십시오.

Link to this section비디오가 지원되나요?#

예, video 기능이 활성화되어 있고 시스템에 FFmpeg 7+가 설치되어 있어야 합니다. 비디오 파일, 웹캠, RTSP/RTMP/HTTP 스트림을 지원합니다.

Link to this sectionannotate 및 visualize 기능은 무엇을 하나요?#

둘 다 기본적으로 활성화되어 있습니다. annotate는 이미지에 박스, 마스크, 키포인트, 클래스 레이블을 그리고 --save가 주석 결과물을 작성하는 데 필요합니다. visualize는 --show를 위한 라이브 창을 엽니다. 프로그래밍 방식으로만 결과를 반환하는 더 가벼운 헤드리스 빌드를 원하면 cargo build --no-default-features를 사용하여 비활성화하십시오 (필요에 따라 개별 기능을 다시 추가하십시오).

Link to this section전체 API 참조는 어디에 있나요?#

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