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에서 탐지(Detect), 세그멘테이션(Segment), 포즈(Pose), OBB, 분류(Classify), 의미론적 세그멘테이션(Semantic segmentation) 및 깊이 추정(Depth estimation)을 지원합니다.
• 폭넓은 하드웨어 지원. 빌드 시 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

# Depth estimation (auto-downloads yolo26n-depth.onnx)
ultralytics-inference predict --task depth --source image.jpg

# Depth with the DepthAnything-style palette (disparity is already the default)
ultralytics-inference predict --task depth --source image.jpg --colormap spectral

# Depth normalized by depth value instead (near = low color, far = high color)
ultralytics-inference predict --task depth --source image.jpg --depth-viz metric

# 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) 및 깊이 추정(-depth)은 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

다음 조건이 모두 충족되면 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

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.29", 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를 기록합니다. depth 작업의 경우 주석이 달린 이미지는 원본 옆에 컬러화된 깊이 맵이 나란히 기록됩니다. 주석이 달린 이미지 및 비디오 저장을 위해서는 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에 게시되어 있습니다.