Ultralytics Inference cho Rust#

Ultralytics Inference là một thư viện suy luận YOLO hiệu suất cao và là công cụ dòng lệnh được viết bằng Rust. Nó chạy các model ONNX đã được xuất thông qua ONNX Runtime để cung cấp các dự đoán nhanh chóng, an toàn về bộ nhớ trên hình ảnh, video, webcam và luồng dữ liệu, không yêu cầu runtime Python tại thời điểm suy luận.

Dự án được phân phối dưới dạng một crate duy nhất, ultralytics-inference, mà bạn có thể sử dụng theo hai cách: như một CLI cho các dự đoán nhanh và tác vụ hàng loạt, hoặc như một thư viện được tích hợp trực tiếp vào ứng dụng Rust của bạn. Nó hỗ trợ mọi task của Ultralytics và một tập hợp rộng các backend phần cứng thông qua giao diện thiết bị thống nhất.

Tại sao lại chọn inference bằng Rust?#

• Tốc độ native và dung lượng nhỏ gọn. Biên dịch thành tệp nhị phân native không có trình thông dịch, rất lý tưởng cho máy chủ, container và thiết bị biên.
• An toàn bộ nhớ. Ownership model của Rust loại bỏ hoàn toàn các loại lỗi runtime mà không cần garbage collector.
• Tất cả các tác vụ YOLO. Phát hiện, phân đoạn, phân đoạn ngữ nghĩa, ước tính chiều sâu, phân loại, pose và OBB từ một API duy nhất.
• Hỗ trợ phần cứng rộng rãi. CPU cộng với các execution provider như CUDA, TensorRT, CoreML, OpenVINO, DirectML, ROCm và XNNPACK được lựa chọn tại thời điểm build.
• Tiền xử lý phía GPU. Một kernel CUDA được hợp nhất tùy chọn giữ letterbox, normalize và chuyển đổi layout trên thiết bị để có đường dẫn input zero-copy.
• Tự động tải xuống. Các tên model YOLO đã biết và các asset mẫu sẽ tự động 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 bổ sung yêu cầu phải cài đặt FFmpeg 7+ 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

Hướng dẫn nhanh CLI#

CLI cung cấp một lệnh con predict. Khi không có đối số, nó sẽ tải xuống một model phát hiện nano và các hình ảnh mẫu, chạy suy luận và lưu các kết quả đã 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 --half

Các flag phổ biến:

Hướng dẫn nhanh cho thư viện#

Tải model và chạy dự đoán. Metadata của model như tên lớp, loại task và kích thước hình ảnh được đọc tự động 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 các ngưỡng, kích thước hình ảnh, độ chính xác và thiết bị bằng API builder:

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 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 được; model và các đầu vào mẫu sẽ tự động tải xuống trong lần chạy đầu tiên. Thay thế 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 task được hỗ trợ#

Tất cả các task của Ultralytics đều được hỗ trợ. Khi --model bị bỏ qua, model nano phù hợp cho task đã chọn sẽ tự động được tải xuống.

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

Bất kỳ model Ultralytics nào được xuất sang ONNX đều có thể được tải từ tệp cục bộ. Tính năng tự động tải xuống có sẵn cho các tên model chuẩn YOLO26, YOLO11 và YOLOv8 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 chiều sâu (-depth) chỉ dành riêng cho YOLO26.

Nguồn input#

Đố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 phát hiện từ chuỗi:

Thiết bị và execution provider#

Suy luận chạy trên CPU theo mặc định. Các backend GPU và bộ tăng tốc được biên dịch dưới dạng Cargo features và được chọn tại thời điểm chạy bằng --device (CLI) hoặc Device (thư viện).

# 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, tính năng cuda kích hoạt nhà cung cấp thực thi CUDA, và tensorrt bổ sung nhà cung cấp TensorRT để tối ưu hóa thêm. Để có độ trễ thấp nhất có thể, tính năng cuda-preprocess chuyển quá trình tiền xử lý sang GPU.

cuda-preprocess thực hiện thay đổi kích thước letterbox, chuẩn hóa và chuyển đổi bố cục HWC sang CHW thành một kernel CUDA được hợp nhất duy nhất, sau đó cung cấp kết quả cho model dưới dạng tensor thiết bị không sao chép (zero-copy). Điều này loại bỏ chi phí tiền xử lý CPU trên mỗi hình ảnh và việc sao chép từ host sang device, điều quan trọng nhất đối với các batch có 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 dẫn nhanh (fast path) được sử dụng tự động mà không cần thay đổi API khi thỏa mãn tất cả các điều kiện sau: tính năng đã được biên dịch, thiết bị là CUDA hoặc TensorRT, tác vụ là detect, segment, pose, OBB, semantic segmentation hoặc depth estimation, 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

Các tính năng của Cargo#

Các tính năng được kích hoạt tại thời điểm biên dịch. Các giá trị mặc định bao gồm chú thích và hiển thị trực tiếp.

Các nhóm tiện ích gom các nhà cung cấp liên quan: nvidia (cuda, tensorrt), amd (rocm, migraphx), intel (openvino, onednn), mobile (nnapi, coreml, qnn) và all (annotate, visualize, video). Các nhà cung cấp bổ sung như nnapi, qnn, xnnpack, webgpu và các nhà cung cấp khác cũng có sẵn.

Kích hoạt các tính năng 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.33", features = ["video"] }

Đầu ra và lưu trữ#

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 dần:

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

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

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

Tôi có cần cài đặt Python không?#

Không. Crate này chạy các model ONNX đã được xuất trực tiếp thông qua ONNX Runtime. Python chỉ cần thiết nếu bạn đào tạo hoặc xuất model bằng gói Ultralytics trước đó.

Tôi có thể chạy những mô hình nào?#

Bất kỳ model Ultralytics YOLO nào được xuất sang ONNX, bao gồm YOLO26, YOLO11 và YOLOv8. Các tên model đã biết sẽ tự động tải xuống; bạn cũng có thể trỏ --model tới bất kỳ tệp .onnx cục bộ nào.

Làm thế nào để tôi có được tệp mô hình?#

Xuất từ gói Python, ví dụ với tích hợp ONNX hoặc để CLI tải xuống một model nano chuẩn cho task đã chọn trong lần chạy đầu tiên.

Video có được hỗ trợ không?#

Có, với tính năng video được bật và FFmpeg 7+ được cài đặt trên hệ thống. Điều này bao gồm các tệp video, webcam và các luồng RTSP/RTMP/HTTP.

Các tính năng annotate và visualize có tác dụng gì?#

Cả hai đều được bật theo mặc định. annotate vẽ các hộp, mặt nạ, keypoint và nhãn lớp lên hình ảnh và là bắt buộc để --save ghi lại kết quả được chú thích. visualize mở một cửa sổ trực tiếp cho --show. Đối với một bản dựng headless nhỏ hơn chỉ trả về kết quả theo chương trình, hãy tắt chúng bằng cargo build --no-default-features (thêm lại các tính năng riêng lẻ nếu cần).

Tham chiếu API đầy đủ nằm ở đâu?#

Trang này là tổng quan cấp cao. Tài liệu tham khảo API hoàn chỉnh theo từng kiểu cho mọi struct, phương thức và tùy chọn cấu hình công khai được xuất bản trên docs.rs, được tạo trực tiếp từ mã nguồn.