Dedicated Endpoints#

Ultralytics Platform cho phép triển khai các model YOLO tới các endpoint chuyên biệt trên 42 khu vực toàn cầu. Mỗi endpoint là một service đơn thuê (single-tenant) với tính năng scale-to-zero, một URL endpoint duy nhất và hệ thống giám sát độc lập.

Tạo Endpoint#

Từ Tab Triển Khai (Deploy)#

Triển khai một model từ tab Deploy của model đó:

1. Điều hướng đến model của bạn
2. Nhấp vào tab Deploy
3. Xem bản đồ thế giới và bảng khu vực, được sắp xếp theo độ trễ được đo lường từ vị trí của bạn
4. Nhấp vào Deploy trong hàng khu vực bạn muốn sử dụng

Việc triển khai bắt đầu ngay lập tức mà không cần bước đặt tên: tên được tạo từ tên model và thành phố vùng (ví dụ: yolo26n-iowa). Model phải có trọng số (weights), nếu không tab này sẽ hiển thị trạng thái trống thay vì bảng vùng.

Từ Trang Triển Khai (Deployments)#

Tạo một deployment từ trang Deploy toàn cục trong thanh bên (sidebar):

1. Nhấp New Deployment
2. Chọn một model từ trình chọn model, nơi liệt kê các model đã hoàn thành của bạn
3. Chọn một vùng từ bản đồ thu nhỏ hoặc bảng độ trễ (latency)
4. Xem lại tên triển khai được tạo tự động, bạn có thể chỉnh sửa tên này tại đây
5. Nhấp Deploy Model

Vòng đời Triển khai#

stateDiagram-v2
    [*] --> Creating: Deploy
    Creating --> Deploying: Service starting
    Deploying --> Ready: Service URL published
    Ready --> Stopping: Stop
    Ready --> Deploying: Replace model
    Stopping --> Stopped: Stopped
    Stopped --> Deploying: Start
    Deploying --> Stopped: Start failed
    Ready --> [*]: Delete
    Stopped --> [*]: Delete
    Creating --> Failed: Error
    Deploying --> Failed: Error
    Failed --> [*]: Delete

    classDef proc fill:#2196F3,color:#fff
    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff
    classDef extern fill:#607D8B,color:#fff
    class Creating,Deploying,Stopping proc
    class Ready out
    class Failed error
    class Stopped extern

Kết nối Slack alerts để nhận thông báo khi một deployment sẵn sàng hoặc khởi động thất bại.

Chọn khu vực#

Lựa chọn từ 42 khu vực trên toàn thế giới. Bản đồ khu vực tương tác và bảng dữ liệu hiển thị:

• Ghim khu vực: Được mã màu theo độ trễ trên dải màu từ xanh lá cây sang đỏ (khu vực nhanh hơn có màu xanh hơn, khu vực chậm hơn có màu đỏ hơn)
• Các vùng đã triển khai: Được đánh dấu bằng huy hiệu "Deployed" trong bảng
• Các vùng đang triển khai: Chỉ báo nhấp nháy động trên ghim (pin) và hàng trong bảng
• Làm nổi bật hai chiều: Di chuột trên bản đồ làm nổi bật hàng bảng và ngược lại

Bảng khu vực trên tab Deploy của model bao gồm:

Bảng này có thể tìm kiếm theo thành phố, quốc gia và khu vực (zone), đồng thời được sắp xếp theo độ trễ theo mặc định.

Các Khu Vực Khả Dụng#

Cấu hình Endpoint#

Hộp Thoại Triển Khai Mới#

Hộp thoại New Deployment thu thập ba thông tin đầu vào:

Bên dưới tên, bảng Resources ở chế độ chỉ đọc đi kèm với huy hiệu Custom resources coming soon. Tài nguyên hiện không thể cấu hình: mọi endpoint chạy dưới dạng một thể hiện (instance) đơn lẻ, tự động thu nhỏ về 0 khi không hoạt động (idle).

Tab Deploy (Triển khai nhanh)#

Triển khai từ tab Deploy của model sử dụng các tài nguyên cố định và tên được tạo tự động tương tự, không có bước hộp thoại. Bản triển khai sẽ xuất hiện ngay lập tức trong danh sách Active Deployments bên dưới bảng vùng trong quá trình được tạo.

Quản lý Endpoint#

Chế độ xem#

Danh sách triển khai hỗ trợ ba chế độ xem:

Thẻ triển khai (Chế độ xem thẻ)#

Mỗi thẻ triển khai trong chế độ xem thẻ hiển thị:

• Header: Tên, cờ vùng, huy hiệu trạng thái và các nút thao tác khả dụng cho trạng thái hiện tại — thay thế (replace) và dừng (stop) khi ở trạng thái Ready, bắt đầu (start) khi ở trạng thái Stopped, xóa bất kỳ lúc nào
• Endpoint URL: URL có thể sao chép cùng với liên kết dẫn đến tài liệu API riêng của endpoint
• Metrics: Số lượng yêu cầu (24h), độ trễ P95, tỷ lệ lỗi, hoặc "No traffic yet"
• Health check: Chỉ báo trạng thái trực tiếp với độ trễ và làm mới thủ công
• Tabs: Logs, Code và Predict
• Footer: Tiền tố khóa API gắn liền với bản triển khai và ngày nó sẵn sàng
• Status message: Nguyên nhân gây lỗi, khi một bản triển khai gặp sự cố

URL, số liệu (metrics), kiểm tra trạng thái (health check) và các tab chỉ xuất hiện khi bản triển khai ở trạng thái Ready. Tab Logs hiển thị các mục nhật ký (log) gần đây với bộ lọc mức độ nghiêm trọng (All / Errors). Tab Code hiển thị các ví dụ mã nguồn sẵn sàng sử dụng bằng Python, JavaScript và cURL với URL endpoint của bạn, cộng với khóa API được liên kết dành cho chủ sở hữu không gian làm việc (xem phần Monitoring). Tab Predict cung cấp bảng dự đoán nội dòng (inline predict panel) để kiểm thử trực tiếp trên bản triển khai.

Thay thế model#

Thay thế model đằng sau một endpoint sẵn sàng mà không làm thay đổi URL của nó:

1. Mở bản triển khai ở chế độ xem Cards
2. Nhấp vào Replace model
3. Chọn một model đã hoàn thành khác từ cùng một workspace
4. Tùy chọn chỉnh sửa tên bản triển khai
5. Nhấp vào Replace Model

Model hiện tại tiếp tục phục vụ trong khi bản thay thế khởi động. Khi bản thay thế sẵn sàng, lưu lượng truy cập sẽ chuyển sang model mới. ID triển khai, URL, vùng và khóa API giữ nguyên; tên hiển thị chỉ thay đổi khi bạn nhập tên mới. Nếu việc thay thế thất bại, model và tên trước đó sẽ vẫn tiếp tục hoạt động.

Việc thay thế yêu cầu tất cả các điều kiện sau và sẽ bị từ chối nếu không thỏa mãn:

• Bản triển khai ở trạng thái Ready và không có thao tác vòng đời nào khác đang diễn ra
• Model thay thế có trọng số và thuộc cùng một không gian làm việc với bản triển khai
• Model thay thế không phải là model đang được triển khai

Trạng thái triển khai#

Endpoint URL#

Mỗi endpoint có một URL duy nhất, ví dụ:

https://predict-<deployment-id>-<hash>-<region>.a.run.app

Nhấp vào nút sao chép để sao chép URL. Nhấp vào biểu tượng tài liệu để mở tài liệu tham khảo API của endpoint. Endpoint phục vụ các đường dẫn sau:

Quản lý vòng đời#

Kiểm soát trạng thái endpoint của bạn:

graph LR
    R[Ready]:::out -->|Stop| S[Stopped]:::extern
    S -->|Start| R
    R -->|Delete| D[Deleted]:::error
    S -->|Delete| D

    classDef out fill:#9C27B0,color:#fff
    classDef error fill:#F44336,color:#fff
    classDef extern fill:#607D8B,color:#fff

Dừng Endpoint#

Dừng một endpoint khi bạn không muốn nó chấp nhận yêu cầu:

1. Nhấp vào biểu tượng tạm dừng trên thẻ triển khai
2. Trạng thái endpoint chuyển sang "Stopping" sau đó là "Stopped"

Các endpoint đã dừng:

• Không chấp nhận yêu cầu, đồng thời không báo cáo số liệu hoặc trạng thái sức khỏe
• Giữ nguyên URL, vùng và khóa API đã liên kết, đồng thời có thể được khởi động lại bất cứ lúc nào
• Vẫn được tính vào hạn mức triển khai trong gói của bạn — hãy xóa endpoint để giải phóng ô của nó

Xóa Endpoint#

Xóa vĩnh viễn một endpoint:

1. Nhấp vào biểu tượng xóa (thùng rác) trên thẻ triển khai
2. Xác nhận xóa trong hộp thoại

Các bản triển khai cũng bị xóa khi model hoặc dự án của chúng bị xóa vĩnh viễn, hoặc khi model hay dự án nằm trong thùng rác đạt đến cuối thời gian lưu giữ.

Sử dụng Endpoint#

Xác thực#

Mỗi bản triển khai được gắn với một khóa API duy nhất từ không gian làm việc sở hữu model. Hãy đưa khóa này vào các yêu cầu:

Authorization: Bearer YOUR_API_KEY

Endpoint chỉ chấp nhận khóa được liên kết lúc tạo, do đó không có khóa nào khác mở được — kể cả một khóa hoạt động khác trong cùng không gian làm việc. Để kiểm soát khóa nào được liên kết, hãy triển khai thông qua API được xác thực bằng khóa của chủ sở hữu không gian làm việc: chính xác khóa đó sẽ được liên kết và bạn đã nắm giữ nó. Các bản triển khai được tạo theo bất kỳ cách nào khác (Giao diện nền tảng - Platform UI, hoặc lệnh gọi API được xác thực với tư cách là thành viên nhóm) sẽ tự động liên kết một trong các khóa hoạt động của không gian làm việc sở hữu — hãy xác định khóa đó bằng tiền tố khóa hiển thị ở chân trang thẻ triển khai và yêu cầu chủ sở hữu không gian làm việc cung cấp giá trị của nó, vì chỉ chủ sở hữu mới có thể xem giá trị khóa (xem API Keys). Các thành viên trong nhóm không có khóa được liên kết vẫn có thể chạy suy luận thông qua proxy dự đoán Platform trong trình duyệt.

Yêu cầu Endpoint Trực tiếp#

Gửi các yêu cầu sản xuất trực tiếp đến URL hiển thị trên thẻ triển khai. Các yêu cầu này không đi qua bộ giới hạn tốc độ API của Platform (API rate limiter), do đó giới hạn 20 yêu cầu/phút của tính năng dự đoán không được áp dụng. Endpoint vẫn có giới hạn năng lực riêng:

• Một thể hiện đơn lẻ phục vụ mỗi endpoint, xử lý một số lượng giới hạn các yêu cầu cùng một lúc
• Các yêu cầu không thể được phục vụ kịp thời sẽ trả về 429 kèm theo tiêu đề Retry-After
• Một yêu cầu duy nhất có thể chạy tối đa 1 giờ, cho phép suy luận video hoàn tất
• Các phản hồi lớn hơn 1 KB được nén gzip và các yêu cầu trình duyệt xuyên nguồn (cross-origin) được cho phép

Ví dụ về yêu cầu#

import requests

# Deployment endpoint
url = "https://YOUR_DEPLOYMENT_URL.run.app/predict"

# Headers with your deployment API key
headers = {"Authorization": "Bearer YOUR_API_KEY"}

# Inference parameters
data = {"conf": 0.25, "iou": 0.7, "imgsz": 640}

# Send image for inference
with open("image.jpg", "rb") as f:
    response = requests.post(url, headers=headers, data=data, files={"file": f})

print(response.json())

Tham số yêu cầu#

Xem Depth responses để biết cách bits thay đổi bản đồ chiều sâu (depth map) được trả về và cách giải mã nó.

Định dạng phản hồi#

Giống như shared inference với các trường dành riêng cho từng tác vụ.

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