Suy luận#

Ultralytics Platform cung cấp inference trên trình duyệt để kiểm thử các model đã huấn luyện và endpoint chuyên dụng để truy cập theo chương trình.

Tab Predict#

Mỗi model có weights đều có 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 ảnh lên, dùng ảnh mẫu hoặc mở webcam
4. Xem lớp phủ theo tác vụ, tóm tắt dự đoán, thời gian và phản hồi thô

Model không có weights sẽ hiển thị trạng thái trống — trước tiên hãy huấn luyện model hoặc tải weights lên.

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

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

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

    classDef start fill:#4CAF50,color:#fff
    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff

Tải ảnh lên#

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

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

Ảnh mẫu#

Bảng dự đoán hiển thị tối đa hai ảnh mẫu từ dataset được liên kết với model, ưu tiên split val, tiếp theo là test, rồi train. Nếu không liên kết dataset, hệ thống sẽ dùng ảnh mẫu mặc định:

Đối với model OBB, thay vào đó sẽ hiển thị ảnh trên không chụp thuyền và sân bay.

Webcam#

Chọn Webcam phía trên vùng hình ảnh để 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 tự động chạy trên khung hình đã chụp
4. Nhấp Quay lại webcam để trở về luồng trực tiếp

Trên tab Predict của deployment riêng, webcam thay vào đó chạy inference liên tục. Xem Inference từ camera trực tiếp.

Xem kết quả#

Kết quả inference hiển thị đầu ra phù hợp với tác vụ của model: box, mask, keypoint, box định hướng, điểm phân loại, vùng bao phủ ngữ nghĩa hoặc bản đồ độ sâu. Kết quả đối tượng sử dụng màu lớp của dataset khi có sẵn. Bảng cũng hiển thị thời gian tiền xử lý, inference, hậu xử lý và mạng.

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

Khi có kết quả, hai điều khiển sẽ xuất hiện trên bản xem trước: nhấp vào ảnh để phóng to mà vẫn giữ nguyên lớp phủ, và dùng nút tải xuống để lưu ảnh JPEG có chú thích của kết quả hiện tại.

Tham số inference#

Điều chỉnh hành vi suy luận bằng ba thanh trượt bên dưới ảnh (model độ sâu chỉ hiển thị Kích thước ảnh):

Ngưỡng confidence#

Lọc dự đoán theo confidence:

• Cao hơn (0.5+): Ít dự đoán hơn nhưng chắc chắn hơn
• Thấp hơn (0.1-0.25): Nhiều dự đoán hơn, nhưng có thể lẫn nhiễu
• Mặc định (0.25): Cân bằng cho hầu hết 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 BBox chồng lấp hơn
• Thấp hơn (0.3-0.5): Loại bỏ các detection chồng lấp quyết liệt hơn
• Mặc định (0.7): Cân bằng hành vi NMS cho hầu hết trường hợp sử dụng

Predict trên deployment#

Mỗi endpoint chuyên dụng đang chạy đều có một tab Predict trên trang deployment. Tab này sử dụng dịch vụ suy luận riêng của deployment thay vì dịch vụ predict dùng chung, cho phép bạn kiểm thử endpoint đã triển khai ngay trên trình duyệt.

Trên endpoint sẵn sàng hoạt động, ảnh đã xử lý cũng được tính vào tab Monitoring. Các ví dụ và biểu đồ tổng hợp trong tab Monitoring là dữ liệu tạm thời, gọn nhẹ được lưu trong bộ nhớ; việc dừng, khởi động lại, triển khai lại, thay đổi kích thước hoặc thay thế model có thể xóa dữ liệu này. Hãy lưu các ví dụ vào dataset để giữ lại.

Inference từ camera trực tiếp#

Trên tab Predict của deployment bạn sở hữu, chọn Webcam hoặc Camera IP để chạy endpoint trên video trực tiếp:

Inference trực tiếp sử dụng API key được gắn với endpoint và chỉ chủ sở hữu workspace mới có thể tải API key này; với các thành viên nhóm khác, webcam chỉ chụp từng frame và Camera IP không khả dụng, tương tự tab Predict của model. Camera IP phải có thể truy cập từ internet: endpoint từ chối các địa chỉ mạng cục bộ như 192.168.x.x. Mỗi kết quả ứng với frame mới nhất, vì vậy các frame sẽ bị bỏ qua nếu inference xử lý không kịp. Thay đổi thanh trượt sẽ áp dụng cho frame webcam tiếp theo và khởi động lại luồng camera IP. Inference trực tiếp tạm dừng khi tab trình duyệt bị ẩn. Nhấp vào phần xem trước để chụp một frame, hoặc chọn Ngắt kết nối để dừng xem camera IP.

Camera chạy nền#

Endpoint có kích thước CPU và bộ nhớ tùy chỉnh có thể tiếp tục theo dõi một camera IP sau khi bạn ngắt kết nối hoặc đóng trang. Khi camera đã kết nối hiển thị kết quả, bật Tiếp tục chạy ở chế độ nền. Phần đầu deployment hiển thị Camera đang bật, và kết quả được gửi đến tab Monitoring dưới dạng ví dụ tạm thời cùng số liệu thống kê dự đoán.

• Cài đặt: Camera chạy nền luôn sử dụng confidence mặc định (0.25), IoU (0.7) và kích thước hình ảnh huấn luyện của model; các thanh trượt không áp dụng cho camera này.
• Chi phí: Camera chạy trên instance luôn sẵn sàng của endpoint mà không tính thêm phí; mức phí thời gian hoạt động theo giờ vẫn được áp dụng dù camera bật hay tắt.
• Thay đổi: Bật, tắt hoặc chuyển camera sẽ khởi động lại instance của endpoint. Việc này giữ endpoint ở trạng thái sẵn sàng nhưng xóa dữ liệu monitoring tạm thời.
• Dừng: Tắt công tắc. Ngắt kết nối hoặc đóng trang sẽ không dừng camera; thay đổi kích thước endpoint về kích thước mặc định sẽ loại bỏ camera. Nếu camera ngoại tuyến, endpoint tiếp tục thử kết nối lại.
• Vòng đời endpoint: Dừng endpoint sẽ dừng camera và các khoản phí; khởi động lại endpoint sẽ tiếp tục sử dụng camera đã lưu.

Endpoint kích thước mặc định hỗ trợ inference trực tiếp từ webcam và camera IP nhưng không có tùy chọn chạy nền. Để lưu camera chạy nền qua API, hãy sử dụng thao tác deployment camera.

Truyền kết quả từ API#

Gửi URL RTSP hoặc RTSPS dưới dạng source kèm header Accept: text/event-stream đến URL endpoint chuyên dụng để nhận kết quả dưới dạng sự kiện do máy chủ gửi:

curl -N -X POST \
  "https://YOUR_DEPLOYMENT_URL.run.app/predict" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream" \
  -F "source=rtsp://user:password@camera.example.com:554/stream" \
  -F "conf=0.25"

Mỗi sự kiện frame chứa images theo cấu trúc response, với tọa độ chuẩn hóa (0-1), URL dữ liệu JPEG preview của frame và metadata chứa tên tác vụ và class. Chỉ conf, iou và imgsz được áp dụng; việc truyền URL camera chạy nền của endpoint sẽ sử dụng cài đặt mặc định. Sự kiện chỉ có status sẽ không chứa frame; sự kiện có thông báo error (không đọc được camera hoặc endpoint không thể chạy model) sẽ kết thúc luồng. Luồng cũng đóng khi endpoint khởi động lại hoặc yêu cầu hết thời gian chờ; nếu luồng kết thúc mà không có lỗi, hãy kết nối lại với thời gian chờ tăng dần. Route dự đoán của Platform API và SDK không hỗ trợ truyền luồng; hãy gửi yêu cầu camera đến URL endpoint bằng API key được gắn với endpoint. Yêu cầu camera source không có header sẽ trả về 400.

API của endpoint chuyên dụng#

Thẻ API Docs trong tab Predict của model chứa các yêu cầu mẫu bằng Python, JavaScript và cURL, được điền sẵn các giá trị confidence, IoU và kích thước ảnh hiện đặt trên thanh trượt. URL và key chỉ là giá trị giữ chỗ cho đến khi bạn triển khai model — nút Deploy bên cạnh các tab mã sẽ chuyển đến tab Deploy của model. Sau khi triển khai, tab kết quả Docs trong tab Predict của trang deployment sẽ điền URL của endpoint đó và, với chủ sở hữu workspace, cả API key được liên kết, sẵn sàng để sao chép và chạy.

Xác thực#

Đưa API key vào các yêu cầu:

Authorization: Bearer YOUR_API_KEY

Endpoint#

Endpoint chuyên dụng nhận yêu cầu tại URL riêng:

POST https://YOUR_DEPLOYMENT_URL.run.app/predict

Suy luận dùng chung sử dụng Platform API cùng đường dẫn đầy đủ của model:

POST https://platform.ultralytics.com/api/models/{owner}/{project}/{model}/predict

Cả hai đều chấp nhận cùng phần nội dung multipart/form-data và trả về cùng cấu trúc phản hồi. Khi dùng Python SDK, hãy dùng client.models.predict(owner, project, model, body=...) cho suy luận dùng chung hoặc client.deployments.predict(owner, deployment, body=...) cho deployment chuyên dụng. Cả hai phương thức SDK đều gọi Platform API, vì vậy các giới hạn tốc độ và giới hạn kích thước yêu cầu của API này vẫn được áp dụng. Để tránh các giới hạn đó, hãy gửi POST trực tiếp đến URL của endpoint chuyên dụng như minh họa trong Yêu cầu. Ví dụ suy luận dùng chung:

from ultralytics_platform import Platform

client = Platform()  # reads ULTRALYTICS_API_KEY
with open("image.jpg", "rb") as f:
    results = client.models.predict("acme-vision", "inspection", "v3", body={"file": f, "conf": 0.25})

Yêu cầu#

import requests

url = "https://YOUR_DEPLOYMENT_URL.run.app/predict"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
data = {"conf": 0.25, "iou": 0.7, "imgsz": 640}

with open("image.jpg", "rb") as image_file:
    response = requests.post(url, headers=headers, files={"file": image_file}, data=data)
print(response.json())

Tham số yêu cầu#

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,
        "classNames": ["person", "bicycle", "car", "..."],
        "functionTimeAlive": 1284.51,
        "functionTimeCall": 0.018,
        "task": "detect",
        "version": {
            "ultralytics": "8.x.x",
            "torch": "2.6.0",
            "torchvision": "0.21.0",
            "python": "3.13.0"
        }
    }
}

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

Phản hồi theo từng 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}
}

Giới hạn tốc độ#

API model dùng chung bị giới hạn 20 yêu cầu/phút cho mỗi API key, người gọi đã đăng nhập hoặc IP ẩn danh. Tuyến predict của deployment trên Platform (POST /api/deployments/{owner}/{deployment}/predict) cũng có cùng giới hạn. Khi bị giới hạn tốc độ, API trả về 429 kèm header Retry-After. Xem tài liệu tham khảo đầy đủ về giới hạn tốc độ để biết các danh mục endpoint.

Xử lý lỗi#

Các phản hồi lỗi thường gặp:

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