Triển khai và gọi endpoint

Inference dùng chung hay endpoint riêng#

Mọi model đều có thể được gọi thông qua API inference dùng chung của Platform, phù hợp cho việc kiểm thử. Lưu lượng production nên dùng endpoint riêng:

Tạo và định cấu hình kích thước Endpoint#

Mở tab Deploy của model. Trình duyệt đo độ trễ đến cả 42 khu vực (14 ở châu Mỹ, 13 ở châu Âu, 12 ở châu Á-Thái Bình Dương, 3 ở Trung Đông và châu Phi), rồi sắp xếp bảng theo độ trễ:

Nhấp Deploy ở hàng gần với người gọi nhất, xem lại CPU, bộ nhớ, giá và tên được tạo (chẳng hạn yolo26n-iowa), rồi nhấp Create Deployment. Bạn cũng có thể bắt đầu từ New Deployment trong tab Deployments trên hồ sơ của mình:

Chọn kích thước theo dạng lưu lượng:

Các gói cho phép 3 (Free), 10 (Pro) hoặc không giới hạn (Enterprise) deployment; endpoint đã dừng vẫn được tính. Endpoint nhận lưu lượng khi huy hiệu hiển thị Ready:

Ví dụ thực tế: Client hoạt động ổn định trong môi trường production#

Mỗi endpoint có URL dạng https://predict-<id>-<hash>-<region>.a.run.app, phục vụ /predict (POST), /health và trang tương tác /docs. Endpoint chỉ chấp nhận API key được liên kết khi tạo; chủ sở hữu workspace sẽ thấy key được điền sẵn trong tab Predict của deployment, bên dưới Docs, cạnh các đoạn mã Python, JavaScript và cURL. Các đoạn mã chỉ gửi một request; mã production cũng phải xử lý được khởi động nguội và instance quá tải:

import os
import time
from collections import Counter

import httpx

URL = "https://YOUR_DEPLOYMENT_URL.run.app/predict"
HEADERS = {"Authorization": f"Bearer {os.environ['ULTRALYTICS_API_KEY']}"}  # the deployment's bound key, server-side only

def predict(client, path, conf=0.25, attempts=4):
    """POST one image; retry timeouts, 429, and 5xx with backoff; fail fast on other errors."""
    for attempt in range(attempts):
        try:
            with open(path, "rb") as f:
                r = client.post(URL, headers=HEADERS, data={"conf": conf}, files={"file": f}, timeout=90)
            if r.status_code < 400:
                return r.json()
            if r.status_code != 429 and r.status_code < 500:
                r.raise_for_status()  # 401 wrong key, 413 too large: retrying won't help
            wait, reason = float(r.headers.get("Retry-After", 2**attempt)), r.status_code
        except httpx.TimeoutException:  # a scaled-to-zero endpoint can take up to a minute to wake
            wait, reason = 2**attempt, "timeout"
        print(f"attempt {attempt + 1}: {reason}, retrying in {wait:.0f} s")
        time.sleep(wait)
    raise RuntimeError(f"endpoint still unavailable after {attempts} attempts")

with httpx.Client() as client:
    response = predict(client, "bus.jpg")
for image in response["images"]:
    counts = Counter(d["name"] for d in image["results"])
    print(f"{sum(counts.values())} objects {dict(counts)} in {image['speed']['inference']:.1f} ms")

Chúng tôi đã kiểm thử với một stub cục bộ, phản hồi 429 một lần rồi trả về kết quả YOLO26n thực cho bus.jpg theo định dạng phản hồi của endpoint:

attempt 1: 429, retrying in 2 s
5 objects {'bus': 1, 'person': 4} in 34.9 ms

Xem từng dòng, đây là những quyết định quan trọng:

• timeout=90 xử lý thời gian khởi động nguội có thể lên đến khoảng một phút; timeout mặc định của hầu hết HTTP client ngắn hơn nhiều.
• Các lỗi 429 và 5xx được thử lại, đồng thời tuân theo Retry-After khi endpoint gửi giá trị này. Mỗi endpoint phục vụ từ một instance duy nhất và giảm tải bằng 429 khi bận.
• Các lỗi 4xx khác khiến request thất bại ngay: 401 nghĩa là key không đúng và 413 nghĩa là body vượt quá 32 MB; cả hai lỗi đều không tự khắc phục.
• Phản hồi chứa một mục cho mỗi ảnh (hoặc mỗi khung hình video) trong images, mỗi mục có results (class, name, confidence, box với x1, y1, x2, y2) và speed tính bằng mili giây.

Các trường form tùy chọn gồm conf (mặc định 0.25), iou (0.7), imgsz (kích thước huấn luyện của model), vid_stride cho video và normalize=true cho tọa độ trong khoảng 0–1. Lệnh cURL tương đương có một dòng cho mỗi trường:

curl -X POST "https://YOUR_DEPLOYMENT_URL.run.app/predict" \
  -H "Authorization: Bearer $ULTRALYTICS_API_KEY" \
  -F "file=@bus.jpg" -F "conf=0.25" -F "iou=0.7" -F "imgsz=640"

Phát hành phiên bản mới mà không đổi URL#

Replace model trên trang deployment sẽ thay bằng một model khác đã hoàn tất trong cùng workspace. Model cũ tiếp tục phục vụ cho đến khi model mới sẵn sàng; URL, khu vực và key vẫn giữ nguyên. Nếu quá trình triển khai thất bại, model trước đó vẫn hoạt động. Để khôi phục, thực hiện cùng thao tác và chọn model trước đó, vì vậy hãy giữ model đó trong project. Update configuration thay đổi kích thước ngay tại chỗ, còn Stop tạm dừng tính phí và giữ nguyên URL.

Một số thay đổi cần endpoint mới: khu vực đã cố định (muốn chuyển thì phải xóa rồi tạo lại, kèm URL mới), và custom domain không được hỗ trợ; vì vậy, hãy đặt gateway của riêng bạn ở phía trước nếu người gọi cần hostname mang thương hiệu ổn định. Để chạy bên ngoài Platform, hãy export model (Export for Deployment) hoặc tự host model sau Triton Inference Server.

Các lỗi thường gặp#