Link to this sectionUltralytics Inference cho Rust#

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

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 để dự đoán nhanh và xử lý hàng loạt, hoặc như một thư viện được nhúng 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 loạt các phần cứng backend thông qua giao diện thiết bị đồng nhất.

Link to this sectionTại sao lại chọn inference bằng Rust?#

• Tốc độ native và dung lượng nhỏ. Biên dịch thành file binary native không cần trình thông dịch, lý tưởng cho máy chủ, container và edge devices.
• 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 task YOLO. Detect, segment, pose, OBB, classify và semantic segmentation 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.

Link to this sectionCài đặt#

Yêu cầu Rust 1.89 trở lên. Tính năng video yêu cầu cài đặt thêm 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

Link to this sectionHướng dẫn nhanh CLI#

CLI cung cấp subcommand predict. Nếu không có đối số nào, nó sẽ tải xuống một model detection nano và các hình ảnh mẫu, chạy inference và lưu 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

# 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:

Link to this sectionHướ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 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 sẽ điền vào một trường khác nhau trên Results. Mỗi tab dưới đây là một chương trình hoàn chỉnh, có thể chạy được; model và input mẫu sẽ tự động tải xuống trong lần chạy đầu tiên. Thay đổi predict_default() thành predict("image.jpg") để chạy trên 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(())
}

Link to this sectionCác task được hỗ trợ#

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

Link to this sectionTính tương thích của model#

Bất kỳ model Ultralytics nào được export sang ONNX đều có thể được tải từ file 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:

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

Link to this sectionNguồn input#

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

Link to this sectionThiết bị và execution provider#

Inference 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 runtime với --device (CLI) hoặc Device (thư viện).

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

Link to this sectionTă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 (execution provider) CUDA, và tensorrt thêm nhà cung cấp TensorRT để tối ưu hóa hơn nữa. Để có độ trễ thấp nhất có thể, tính năng cuda-preprocess sẽ chuyển việc 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 dưới dạng một nhân CUDA hợp nhất, sau đó đưa kết quả vào mô hình dưới dạng thiết bị tensor không sao chép (zero-copy). Điều này loại bỏ chi phí tiền xử lý trên CPU cho mỗi ảnh và việc sao chép từ host sang device, điều này quan trọng nhất đối với các lô (batch) thông lượng cao và các 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 được sử dụng tự động mà không cần thay đổi API khi đáp ứng 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, hoặc semantic segmentation, và mô hình sử dụng đầu vào FP32. Nó được bật theo mặc định và có thể tắt cho từng mô hình:

use ultralytics_inference::{Device, InferenceConfig};

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

Link to this sectionCá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.18", features = ["video"] }

Link to this sectionĐầ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 tác vụ (runs/segment/, runs/pose/, v.v.). Đối với nguồn video, đầu ra được chú thích được ghi dưới dạng tệp video; truyền --save-frames để ghi từng khung hình riêng lẻ thay thế. Đối với tác vụ semantic, --save-json ghi các PNG bản đồ lớp theo pixel trong thư mục con results/. Việc lưu hình ảnh và video được chú thích yêu cầu tính năng 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 tính năng video.

Link to this sectionCâu hỏi thường gặp#

Link to this sectionTôi có cần cài đặt Python không?#

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

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

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

Link to this sectionLà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ô hình nano tiêu chuẩn cho tác vụ đã chọn trong lần chạy đầu tiên.

Link to this sectionVideo có được hỗ trợ không?#

Có, với tính năng video được kích hoạ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à luồng RTSP/RTMP/HTTP.

Link to this sectionCác tính năng annotate và visualize làm gì?#

Cả hai đều được kích hoạt theo mặc định. annotate vẽ các hộp, mặt nạ, điểm khóa và nhãn lớp lên hình ảnh và là bắt buộc để --save ghi kết quả đã chú thích. visualize mở một cửa sổ trực tiếp cho --show. Để có 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ẻ khi cần).

Link to this sectionTham chiếu API đầy đủ nằm ở đâu?#

Trang này là một cái nhìn tổng quan cấp cao. Tham chiếu API đầy đủ, theo 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.