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 model ONNX đã export thông qua ONNX Runtime để đưa ra dự đoán nhanh, an toàn bộ nhớ trên ảnh, video, webcam và luồng dữ liệu mà không cần runtime Python khi 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 để chạy dự đoán nhanh và xử lý batch, hoặc làm thư viện được nhúng trực tiếp vào ứng dụng Rust. Công cụ hỗ trợ mọi tác vụ của Ultralytics và nhiều backend phần cứng thông qua giao diện thiết bị thống nhất. Đối với inference trên trình duyệt, cùng repository này phát hành package npm @ultralytics/yolo; xem hướng dẫn thiết lập.

Vì sao nên dùng Rust cho inference?#

• Tốc độ native và footprint nhỏ. Biên dịch thành binary native không cần trình thông dịch, lý tưởng cho máy chủ, container và thiết bị biên.
• 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 tác vụ YOLO. Phát hiện, phân đoạn, phân đoạn ngữ nghĩa, ước tính độ sâu, phân loại, pose và OBB từ một API.
• Hỗ trợ phần cứng rộng. CPU cùng CUDA, TensorRT, CoreML, OpenVINO, DirectML, ROCm và XNNPACK; các execution provider được chọn tại thời điểm build.
• Tiền xử lý trên GPU. Kernel CUDA hợp nhất tùy chọn thực hiện letterbox, chuẩn hóa và chuyển đổi layout trên GPU, rồi chuyển kết quả cho model mà không cần rời khỏi thiết bị.
• Tự động tải xuống. Tên model YOLO đã biết và tài nguyên mẫu sẽ tự động được tải xuống 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 cài đặt FFmpeg 6 đến 9 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

Bắt đầu nhanh với CLI#

CLI cung cấp subcommand predict. Nếu không có đối số, CLI sẽ tải model phát hiện nano và ảnh mẫu, chạy inference rồi lưu kết quả đã được chú thích 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 --quantize 16

Các cờ thường dùng:

Hướng dẫn bắt đầu nhanh với thư viện#

Tải model và chạy dự đoán. Metadata của model như tên lớp, loại tác vụ và kích thước ảnh được tự động đọc từ tệp 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(())
}

Dùng InferenceConfig để kiểm soát ngưỡng, kích thước ảnh, độ chính xác và thiết bị bằng builder API:

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")?;

Mỗi tác vụ điền dữ liệu vào một trường 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 ngay; model và đầu vào mẫu sẽ tự động được tải xuống trong lần chạy đầu tiên. Thay predict_default() bằng predict("image.jpg") để chạy trên các tệp 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 tác vụ được hỗ trợ#

Hỗ trợ tất cả tác vụ của Ultralytics. Khi bỏ qua --model, model nano tương ứng với tác vụ đã chọn sẽ được tự động tải xuống.

Khả năng tương thích của model#

Có thể tải mọi model Ultralytics được export sang ONNX từ tệp cục bộ. Tính năng tự động tải xuống áp 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:

Phân đoạn ngữ nghĩa (-sem) và ước tính độ sâu (-depth) chỉ có trên YOLO26. Model detection RT-DETR cũng chạy được nhưng không được tự động tải xuống: trước tiên hãy export model sang ONNX.

Nguồn đầu vào#

Đối số --source (và kiểu Source trong thư viện) chấp nhận nhiều loại đầu vào, được tự động nhận diện từ chuỗi:

Thiết bị và execution provider#

Các backend GPU và bộ tăng tốc được biên dịch dưới dạng Cargo feature và được chọn khi chạy bằng --device (CLI) hoặc Device (thư viện). Nếu không chỉ định thiết bị, các provider được biên dịch vào bản build sẽ được đăng ký theo thứ tự ưu tiên cố định (TensorRT trước, sau đó đến CUDA, v.v.), vì vậy bản build chỉ có các feature mặc định sẽ chạy trên CPU.

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

Tăng tốc GPU và tiền xử lý CUDA#

Trên phần cứng NVIDIA, feature cuda bật execution provider CUDA, còn tensorrt bổ sung provider TensorRT để tối ưu hóa thêm. Để đạt độ trễ thấp nhất có thể, feature cuda-preprocess chuyển bước tiền xử lý sang GPU.

cuda-preprocess thực hiện resize letterbox, chuẩn hóa và chuyển đổi layout HWC sang CHW bằng một CUDA kernel hợp nhất, sau đó đưa kết quả vào model dưới dạng tensor trên thiết bị mà không cần sao chép. Frame thô 8 bit vẫn được tải lên GPU, thông qua buffer trung gian được ghim trên GPU rời; kernel loại bỏ các bước resize, chuẩn hóa và chuyển đổi layout trên CPU, cũng như lần tải lên riêng cho tensor đã tiền xử lý. Điều này đặc biệt quan trọng với batch thông lượng cao và luồng thời gian thực.

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

Đường xử lý nhanh được tự động sử dụng mà không cần thay đổi API khi đáp ứng tất cả điều kiện sau: feature được biên dịch, thiết bị là CUDA hoặc TensorRT, tác vụ là detect, segment, pose, OBB, phân đoạn ngữ nghĩa (chỉ ảnh đơn) hoặc ước tính độ sâu, và model sử dụng đầu vào FP32. Tính năng này được bật theo mặc định và có thể tắt cho 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 hỗ trợ chú thích và hiển thị trực tiếp.

Các nhóm tiện ích gộp 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.50", features = ["video"] }

Đầu ra và lưu kết quả#

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

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

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

Câu hỏi thường gặp#