Ultralytics Inference cho Rust#

Ultralytics Inference là thư viện inference YOLO hiệu năng cao và công cụ dòng lệnh được viết bằng Rust. Thư viện chạy các model ONNX đã export thông qua ONNX Runtime để cung cấp dự đoán nhanh, an toàn bộ nhớ trên hình ảnh, video, webcam và stream mà không yêu cầu runtime Python trong thời gian inference.

Dự án được đóng gói dưới dạng một crate duy nhất, ultralytics-inference, có thể sử dụng theo hai cách: làm CLI cho các tác vụ dự đoán nhanh và xử lý theo batch, hoặc làm library được nhúng trực tiếp vào ứng dụng Rust. Crate hỗ trợ mọi task của Ultralytics và nhiều hardware backend thông qua một device interface thống nhất.

Tại sao inference bằng Rust?#

• Tốc độ native và footprint nhỏ. Biên dịch thành binary native không có interpreter, lý tưởng cho server, container và edge device.
• An toàn bộ nhớ. Mô hình ownership của Rust loại bỏ nhiều nhóm lỗi runtime mà không cần garbage collector.
• Mọi task YOLO. Detect, segment, semantic segmentation, depth estimation, classify, pose và OBB từ một API.
• Hỗ trợ hardware rộng. CPU cùng các execution provider CUDA, TensorRT, CoreML, OpenVINO, DirectML, ROCm và XNNPACK được chọn tại thời điểm build.
• Preprocessing trên GPU. CUDA kernel fused tùy chọn giữ các bước letterbox, normalize và chuyển đổi layout trên device để tạo input path zero-copy.
• Tự động download. Tên model YOLO đã biết và các asset mẫu sẽ được tự động download trong lần sử dụng đầu tiên.

Cài đặt#

Yêu cầu Rust 1.89 trở lên. Tính năng video cũng yêu cầu FFmpeg 7+ được cài đặt trên hệ thống.

# 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

Quickstart CLI#

CLI cung cấp subcommand predict. Khi không có tham số, subcommand này sẽ download model detection nano và hình ảnh mẫu, chạy inference rồi lưu kết quả đã annotate vào 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

Các flag phổ biến:

Quickstart library#

Load một model và chạy prediction. Metadata của model như tên class, loại task và kích thước hình ảnh sẽ được tự động đọc từ file 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(())
}

Sử dụng InferenceConfig để kiểm soát threshold, kích thước hình ảnh, precision và device bằng builder 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")?;

Mỗi task điền dữ liệu vào một field khác nhau trên Results. Mỗi tab bên dưới là một chương trình hoàn chỉnh có thể chạy; model và input mẫu sẽ được tự động download trong lần chạy đầu tiên. Thay predict_default() bằng predict("image.jpg") để chạy trên các file của riêng bạn.

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(())
}

Các task được hỗ trợ#

Mọi task của Ultralytics đều được hỗ trợ. Khi --model bị bỏ qua, model nano tương ứng với task đã chọn sẽ được tự động download.

Tính tương thích của model#

Bất kỳ model Ultralytics nào được export sang ONNX đều có thể được load từ file cục bộ. Tính năng auto-download khả dụng cho các tên model YOLO26, YOLO11 và YOLOv8 tiêu chuẩn với các kích thước n, s, m, l và x:

Semantic segmentation (-sem) và depth estimation (-depth) chỉ dành cho YOLO26.

Nguồn input#

Tham số --source (và type Source trong library) chấp nhận nhiều loại input, được tự động nhận diện từ chuỗi:

Device và execution provider#

Inference mặc định chạy trên CPU. Các backend GPU và accelerator được build vào dưới dạng Cargo feature và được chọn tại runtime bằng --device (CLI) hoặc Device (library).

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

GPU acceleration và CUDA preprocessing#

Trên hardware NVIDIA, feature cuda bật CUDA execution provider, còn tensorrt bổ sung TensorRT provider để tối ưu hóa hơn nữa. Để đạt latency thấp nhất có thể, feature cuda-preprocess chuyển preprocessing sang GPU.

cuda-preprocess thực hiện resize letterbox, normalization và chuyển đổi layout từ HWC sang CHW dưới dạng một CUDA kernel fused duy nhất, sau đó đưa kết quả vào model dưới dạng device tensor zero-copy. Điều này loại bỏ chi phí preprocessing trên CPU cho từng hình ảnh và thao tác copy từ host sang device, đặc biệt quan trọng đối với batch throughput cao và stream real-time.

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

Fast path được tự động sử dụng, không cần thay đổi API, khi tất cả điều kiện sau được đáp ứng: feature đã được build, device là CUDA hoặc TensorRT, task là detect, segment, pose, OBB, semantic segmentation hoặc depth estimation, và model sử dụng input FP32. Tính năng này được bật mặc định và có thể tắt theo từng model:

use ultralytics_inference::{Device, InferenceConfig};

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

Cargo feature#

Các feature được bật tại thời điểm build. Các feature mặc định bao gồm annotation và live display.

Các nhóm tiện ích đóng gói những provider liên quan: nvidia (cuda, tensorrt), amd (rocm, migraphx), intel (openvino, onednn), mobile (nnapi, coreml, qnn) và all (annotate, visualize, video). Các provider bổ sung như nnapi, qnn, xnnpack, webgpu và các provider khác cũng khả dụng.

Bật các feature khi cài đặt CLI hoặc thêm thư viện:

cargo install ultralytics-inference --features video
cargo install ultralytics-inference --features cuda,tensorrt

[dependencies]
ultralytics-inference = { version = "0.0.35", features = ["video"] }

Kết quả đầu ra và lưu trữ#

Theo mặc định, các prediction được chú thích và lưu vào một thư mục run có số thứ tự tự tăng:

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

Thư mục con tương ứng với task (runs/segment/, runs/pose/, v.v.). Đối với các nguồn video, kết quả đầu ra đã chú thích được ghi thành một tệp video; truyền --save-frames để thay vào đó ghi từng frame riêng lẻ. Đối với task semantic, --save-json ghi các PNG class-map theo từng pixel trong thư mục con results/. Đối với task depth, depth map được tô màu sẽ được trộn lên ảnh nguồn, tương ứng với kết quả plot() của Ultralytics Python. Việc lưu ảnh và video đã chú thích yêu cầu feature annotate; việc xuất PNG semantic class-map thì không. Input và output video yêu cầu feature video.

FAQ#