Inference

Ultralytics Platform cung cấp API inference để kiểm tra các model đã được huấn luyện. Sử dụng tab Predict trên trình duyệt để xác thực nhanh hoặc REST API để truy cập theo lập trình.

Tab Dự đoán (Predict)

Mỗi model đều bao gồm một tab Predict để chạy inference trên trình duyệt:

1. Điều hướng đến model của bạn
2. Nhấp vào tab Predict
3. Tải lên một hình ảnh, sử dụng ví dụ mẫu hoặc mở webcam của bạn
4. Xem các kết quả dự đoán ngay lập tức với các lớp phủ bounding box

Phương thức đầu vào

Bảng predict hỗ trợ nhiều phương thức đầu vào:

graph LR
    A[Upload Image] --> D[Auto-Inference]
    B[Example Image] --> D
    C[Webcam Capture] --> D
    D --> E[Results + Overlays]

    style D fill:#2196F3,color:#fff
    style E fill:#4CAF50,color:#fff

Tải lên hình ảnh

Kéo thả hoặc nhấp để tải lên:

• Định dạng hỗ trợ: JPEG, PNG, WebP, AVIF, HEIC, JP2, TIFF, BMP, DNG, MPO
• Kích thước tối đa: 10MB
• Tự động inference: Kết quả sẽ tự động xuất hiện sau khi tải lên

Hình ảnh ví dụ

Bảng predict hiển thị các hình ảnh ví dụ từ tập dữ liệu được liên kết với model của bạn. Nếu không có tập dữ liệu nào được liên kết, các ví dụ mặc định sẽ được sử dụng:

Đối với các model OBB, các hình ảnh chụp từ trên không về tàu thuyền và sân bay sẽ được hiển thị thay thế.

Webcam

Nhấp vào thẻ webcam để bắt đầu luồng camera trực tiếp:

1. Cấp quyền truy cập camera khi được nhắc
2. Nhấp vào bản xem trước video để chụp một khung hình
3. Inference chạy tự động trên khung hình đã chụp
4. Nhấp lại để khởi động lại webcam

Xem kết quả

Kết quả inference hiển thị:

• Bounding boxes với các nhãn lớp dưới dạng lớp phủ SVG
• Điểm tin cậy (Confidence scores) cho mỗi lần phát hiện
• Màu sắc lớp từ bảng màu của tập dữ liệu của bạn (hoặc bảng màu mặc định của Ultralytics)
• Phân tích tốc độ: Thời gian tiền xử lý, inference, hậu xử lý và thời gian mạng

Bảng kết quả hiển thị:

Tham số Inference

Điều chỉnh hành vi phát hiện với các tham số trong phần Parameters có thể thu gọn:

Ngưỡng tin cậy

Lọc các dự đoán theo độ tin cậy:

• Cao hơn (0.5+): Ít dự đoán hơn nhưng độ chắc chắn cao hơn
• Thấp hơn (0.1-0.25): Nhiều dự đoán hơn, có thể có nhiễu
• Mặc định (0.25): Cân bằng cho hầu hết các trường hợp sử dụng

Ngưỡng IoU

Kiểm soát Non-Maximum Suppression:

• Cao hơn (0.7+): Cho phép nhiều hộp chồng lấp hơn
• Thấp hơn (0.3-0.5): Hợp nhất các kết quả phát hiện gần nhau mạnh mẽ hơn
• Mặc định (0.7): Hành vi NMS cân bằng cho hầu hết các trường hợp sử dụng

Triển khai Predict

Mỗi endpoint chuyên dụng đang chạy đều bao gồm một tab Predict trực tiếp trên thẻ triển khai của nó. Điều này sử dụng dịch vụ inference của chính bản triển khai đó thay vì dịch vụ predict dùng chung, cho phép bạn kiểm tra endpoint đã triển khai của mình ngay từ trình duyệt.

REST API

Truy cập inference theo lập trình:

Xác thực

Bao gồm khóa API của bạn trong các yêu cầu:

Authorization: Bearer YOUR_API_KEY

Endpoint

POST https://platform.ultralytics.com/api/models/{modelId}/predict

Yêu cầu

import requests

url = "https://platform.ultralytics.com/api/models/MODEL_ID/predict"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
files = {"file": open("image.jpg", "rb")}
data = {"conf": 0.25, "iou": 0.7, "imgsz": 640}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())

Phản hồi

{
    "images": [
        {
            "shape": [1080, 1920],
            "results": [
                {
                    "class": 0,
                    "name": "person",
                    "confidence": 0.92,
                    "box": { "x1": 100, "y1": 50, "x2": 300, "y2": 400 }
                },
                {
                    "class": 2,
                    "name": "car",
                    "confidence": 0.87,
                    "box": { "x1": 400, "y1": 200, "x2": 600, "y2": 350 }
                }
            ],
            "speed": {
                "preprocess": 1.2,
                "inference": 12.5,
                "postprocess": 2.3
            }
        }
    ],
    "metadata": {
        "imageCount": 1,
        "functionTimeCall": 0.018,
        "model": "model.pt",
        "version": {
            "ultralytics": "8.x.x",
            "torch": "2.6.0",
            "torchvision": "0.21.0",
            "python": "3.13.0"
        }
    }
}

Các trường phản hồi

Phản hồi Đặc thù theo Tác vụ

Định dạng phản hồi thay đổi tùy theo tác vụ:

{
  "class": 0,
  "name": "person",
  "confidence": 0.92,
  "box": {"x1": 100, "y1": 50, "x2": 300, "y2": 400}
}

Thanh toán

Inference dùng chung (tab Predict và endpoint /api/models/{id}/predict) được bao gồm mà không phát sinh thêm chi phí trên tất cả các gói. Không có phí cho mỗi yêu cầu đối với inference dùng chung.

Đối với các khối lượng công việc production yêu cầu throughput cao hơn, hãy triển khai dedicated endpoint.

Giới hạn Tốc độ (Rate Limits)

Inference dùng chung bị giới hạn ở mức 20 yêu cầu/phút cho mỗi API key. Khi bị điều tiết, API sẽ trả về mã 429 cùng với header Retry-After. Xem tài liệu tham khảo rate limit đầy đủ cho tất cả các danh mục endpoint.

Xử lý Lỗi

Các phản hồi lỗi phổ biến:

Câu hỏi thường gặp (FAQ)

Tôi có thể chạy inference trên video không?

Cả hai phương pháp inference đều chấp nhận tệp video:

• Dedicated endpoints chấp nhận trực tiếp các tệp video. Các định dạng được hỗ trợ (tối đa 100 MB): ASF, AVI, GIF, M4V, MKV, MOV, MP4, MPEG, MPG, TS, WEBM, WMV. Mỗi khung hình được xử lý riêng lẻ và kết quả được trả về cho từng khung hình. Xem dedicated endpoints để biết chi tiết.
• Shared inference (/api/models/{id}/predict) sử dụng cùng dịch vụ predict và chấp nhận các định dạng video tương tự. Tuy nhiên, Predict tab trên trình duyệt trong UI chỉ cho phép tải lên hình ảnh — hãy sử dụng trực tiếp REST API hoặc dedicated endpoint cho các quy trình làm việc với video. Shared endpoint cũng bị giới hạn tốc độ ở mức 20 req/phút, vì vậy dedicated endpoints là lựa chọn tốt hơn cho các khối lượng công việc video nặng.

Làm thế nào để tôi nhận được hình ảnh đã chú thích?

API trả về các dự đoán dưới dạng JSON. Để trực quan hóa:

1. Sử dụng các dự đoán để vẽ hộp tại cục bộ
2. Sử dụng phương thức plot() của Ultralytics:

from ultralytics import YOLO

model = YOLO("yolo26n.pt")
results = model("image.jpg")
results[0].save("annotated.jpg")

Xem tài liệu Predict mode để biết đầy đủ về API kết quả và các tùy chọn trực quan hóa.

Kích thước hình ảnh tối đa là bao nhiêu?

• Giới hạn tải lên: 10MB
• Khuyến nghị: <5MB để có inference nhanh
• Tự động thay đổi kích thước: Hình ảnh được thay đổi kích thước theo tham số Image Size đã chọn

Các hình ảnh lớn sẽ được tự động thay đổi kích thước trong khi vẫn giữ nguyên tỷ lệ khung hình.

Tôi có thể chạy batch inference không?

API hiện tại xử lý mỗi hình ảnh cho mỗi yêu cầu. Đối với batch:

1. Gửi các yêu cầu đồng thời
2. Sử dụng dedicated endpoint để có throughput cao hơn
3. Xem xét inference cục bộ cho các batch lớn

import concurrent.futures

import requests

url = "https://predict-abc123.run.app/predict"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
images = ["img1.jpg", "img2.jpg", "img3.jpg"]

def predict(image_path):
    with open(image_path, "rb") as f:
        return requests.post(url, headers=headers, files={"file": f}).json()

with concurrent.futures.ThreadPoolExecutor(max_workers=4) as executor:
    results = list(executor.map(predict, images))