Ultralytics YOLO27: Tham gia danh sách chờ.
Get Started
Xây dựng bằng Ultralytics Platform·Triển khai và giám sát·Bài học 8/10
Bài họctrung cấp

Theo dõi tình trạng và độ chính xác

Đọc các chỉ số endpoint và thống kê dự đoán của Platform, gửi cảnh báo từ health check được lên lịch và phát hiện suy giảm độ chính xác bằng tác vụ holdout.

Endpoint có thể trả về 200 OK cho mọi request trong khi độ chính xác giảm 5 điểm vì ca đêm đã giảm độ sáng đèn. Platform cho biết tình trạng hoạt động của từng endpoint, nhưng không gửi thông báo cảnh báo và không thể đánh giá độ chính xác nếu thiếu nhãn. Bài học này xây dựng hai bước kiểm tra theo lịch để khắc phục khoảng trống đó, đồng thời diễn tập cảnh báo độ chính xác bằng cách mô phỏng ca đêm.

Kết quả

Bạn có thể chạy bước kiểm tra endpoint theo lịch để thoát với mã khác 0 khi vượt ngưỡng độ trễ, lỗi hoặc tình trạng sức khỏe, và chạy tác vụ holdout để ghi lại lịch sử độ chính xác cũng như cảnh báo khi có suy giảm thực sự.

Lộ trình cấp tốc
Nếu bạn đã nắm rõ cách thực hiện, đây là phiên bản tóm tắt.
  1. Theo dõi các thẻ HTTP Requests, Error Rate và P95 Latency; mở Logs với bộ lọc Errors.

  2. Dùng SDK ultralytics-platform để thăm dò tình trạng sức khỏe và chỉ số theo lịch 5 phút; thoát với mã 1 khi vượt ngưỡng.

  3. Hàng tuần, đánh giá best.pt đã triển khai bằng tập holdout có nhãn; cảnh báo nếu mAP giảm hơn 1 điểm.

  4. Lưu các ví dụ hữu ích từ Monitoring vào dataset trước khi endpoint khởi động lại; các ví dụ này được lưu trong bộ nhớ.

Thực hành

Thông tin Platform hiển thị#

Tab Deployments trong hồ sơ Ultralytics Platform với bản đồ thế giới hiển thị các ghim khu vực và các thẻ tổng quan Active Deployments, HTTP Requests, HTTP Error Rate và HTTP P95 Latency

Tín hiệuVị tríThời gian lưu trữ
HTTP requests, tỷ lệ lỗi (4xx và 5xx), độ trễ P95Các thẻ trên trang deployment và tab Deployments, được làm mới mỗi phútCác thẻ bao phủ 24 giờ; API cung cấp dữ liệu từ 1 giờ đến 30 ngày
Tình trạng sức khỏeThẻ Endpoint trong tab OverviewTrực tiếp; tự động thử lại khi endpoint không khỏe mạnh
LogsTab Logs: 20 mục mới nhất, bộ lọc ErrorsAPI trả về tối đa 200 mục mỗi request, có phân trang
Thống kê dự đoán và ví dụ tạm thời (tối đa 100 ảnh)Tab MonitoringChỉ lưu trong bộ nhớ của instance đang phục vụ

Tab Monitoring của deployment trên Ultralytics Platform hiển thị thư viện ảnh ví dụ tạm thời với các dự đoán phía trên mục Prediction Statistics

Hai điểm cần lưu ý ảnh hưởng đến mọi nội dung khác. Chỉ thu thập chỉ số khi endpoint ở trạng thái Ready, và xóa deployment sẽ chấm dứt quyền truy cập vào lịch sử. Thống kê và ví dụ trong tab Monitoring sẽ mất mỗi khi endpoint dừng, khởi động lại, đổi kích thước hoặc thay model: đây là chế độ xem trực tiếp, không phải kho lưu trữ.

Ví dụ thực tế: Kiểm tra endpoint theo lịch#

Platform chuyển thẻ tỷ lệ lỗi sang màu đỏ khi vượt 5%, còn Slack có thể thông báo khi deployment sẵn sàng hoặc không khởi động được, nhưng không có cảnh báo theo ngưỡng. Chạy bước kiểm tra này mỗi 5 phút bằng cron, CI hoặc agent giám sát, và gửi cảnh báo khi mã thoát khác 0:

from ultralytics_platform import Platform

OWNER, DEPLOYMENT = "your-username", "yolo26n-iowa"  # from the deployment page URL
P95_BUDGET_MS, MAX_ERROR_RATE = 300, 1.0  # errorRate is a percentage

with Platform() as client:  # reads ULTRALYTICS_API_KEY
    health = client.deployments.health(OWNER, DEPLOYMENT)
    summary = client.deployments.metrics(OWNER, DEPLOYMENT, range="1h", view="overview")["summary"]
    print(
        f"healthy={health['healthy']} requests={summary['totalRequests']} "
        f"p95={summary['p95LatencyMs']:.0f} ms errors={summary['errorRate']:.2f}%"
    )
    if not health["healthy"] or summary["p95LatencyMs"] > P95_BUDGET_MS or summary["errorRate"] > MAX_ERROR_RATE:
        for entry in client.deployments.logs(OWNER, DEPLOYMENT, severity="ERROR,WARNING", limit=5)["entries"]:
            print(entry["timestamp"], entry["severity"], entry["message"][:120])
        raise SystemExit(1)  # non-zero exit lets cron, CI, or your pager treat it as an alert

Khi chạy với API giả lập trả về endpoint khỏe mạnh, chương trình in một dòng rồi thoát với mã 0; với P95_BUDGET_MS = 100, cùng dữ liệu sẽ thoát với mã 1:

healthy=True requests=1200 p95=180 ms errors=0.40%
  • health ping endpoint và trả về healthy, status và latencyMs. Lệnh này cũng đánh thức endpoint đã tự giảm về 0, nên lịch 5 phút đồng thời đóng vai trò ping giữ endpoint luôn ấm.
  • metrics(..., view="overview") trả về totalRequests, errorRate (một tỷ lệ phần trăm) và p95LatencyMs cho khoảng thời gian.
  • logs lấy các lỗi và cảnh báo mới nhất, để thông báo cảnh báo đi kèm manh mối đầu tiên.

Cài đặt SDK bằng pip install -U ultralytics-platform (SDK yêu cầu Python 3.11+). Chỉ gửi cảnh báo khi vi phạm ngưỡng liên tục, chẳng hạn ba lần kiểm tra thất bại liên tiếp, và bổ sung một dòng hướng dẫn xử lý cho mỗi cảnh báo.

Ví dụ thực tế: Theo dõi độ chính xác bằng tập holdout#

Chỉ số request không thể đo độ chính xác; tập holdout thì có thể: 200–500 ảnh gần với dữ liệu production, được gán nhãn cẩn thận, nằm trong phiên bản dataset riêng tư và chưa từng được dùng để huấn luyện. Hàng tuần, đánh giá checkpoint đã triển khai và nối kết quả vào file lịch sử:

import json
import sys
from datetime import date
from pathlib import Path

from ultralytics import YOLO

DEPLOYED = "pills-v1.pt"  # the exact best.pt behind the endpoint
HOLDOUT = sys.argv[1] if len(sys.argv) > 1 else "medical-pills.yaml"  # labeled, never trained on

metrics = YOLO(DEPLOYED).val(data=HOLDOUT, split="val", plots=False, verbose=False)
history = Path("holdout_history.jsonl")
rows = [json.loads(line) for line in history.read_text().splitlines()] if history.exists() else []
row = {"date": date.today().isoformat(), "data": HOLDOUT, "map50_95": round(float(metrics.box.map), 4)}
history.write_text("".join(json.dumps(r) + "\n" for r in [*rows, row]))

baseline = rows[0]["map50_95"] if rows else row["map50_95"]
drop = baseline - row["map50_95"]
print(f"holdout mAP50-95 {row['map50_95']:.3f} (baseline {baseline:.3f}, drop {drop:+.3f})")
if drop > 0.01:  # more than 1 mAP point below the deployment-day baseline
    raise SystemExit("ALERT: holdout accuracy regressed - open the retraining runbook")

Lần chạy đầu tiên ghi lại baseline vào ngày triển khai. Sau đó, hãy diễn tập cảnh báo trước khi cần dùng: script này tạo bản sao "ca đêm" của tập holdout, giữ nguyên nhãn và ảnh nhưng giảm độ sáng xuống 15%:

import shutil
from pathlib import Path

import cv2

from ultralytics.data.utils import check_det_dataset

src = Path(check_det_dataset("medical-pills.yaml")["path"])
dst = Path("pills-night")
(dst / "images/val").mkdir(parents=True, exist_ok=True)
for img in (src / "images/val").glob("*.jpg"):  # darken every holdout image to mimic a dim night shift
    cv2.imwrite(str(dst / "images/val" / img.name), (cv2.imread(str(img)) * 0.15).astype("uint8"))
shutil.copytree(src / "labels/val", dst / "labels/val", dirs_exist_ok=True)  # same labels, darker pixels
Path("pills-night.yaml").write_text(f"path: {dst.resolve()}\ntrain: images/val\nval: images/val\nnames:\n  0: pill\n")
print("wrote pills-night.yaml")
$ python holdout_check.py
holdout mAP50-95 0.659 (baseline 0.659, drop +0.000)
$ python simulate_night_shift.py
wrote pills-night.yaml
$ python holdout_check.py pills-night.yaml
holdout mAP50-95 0.609 (baseline 0.659, drop +0.050)
ALERT: holdout accuracy regressed - open the retraining runbook

Mọi request trong ca đêm vẫn sẽ trả về 200 chỉ trong vài mili giây, nhưng model đã mất 5 điểm mAP. Chỉ tập holdout mới phát hiện được điều này. Mỗi quý, làm mới tập holdout bằng ảnh production mới được gán nhãn, và đặt lại baseline mỗi khi triển khai model mới. Hướng dẫn giám sát model và bài học Khả năng quan sát và suy giảm phân phối trình bày các kiểm định thống kê về drift.

Đọc tab Monitoring để phát hiện drift#

Prediction Statistics trong tab Monitoring của deployment trên Ultralytics Platform, gồm Predictions over Time, Inference Time, biểu đồ donut Top Classes và biểu đồ histogram Predictions per Image

Ghi nhận hình dạng biểu đồ trong tuần triển khai, rồi so sánh về sau. Confidence đo mức độ chắc chắn chứ không đo độ chính xác, vì vậy hãy xem các chỉ số này cùng với tập holdout:

Tình huốngNguyên nhân có khả năngHành động
Confidence giảm, kết quả holdout vẫn ổn địnhThay đổi miền dữ liệu vô hạiTheo dõi; lưu ví dụ cho phiên bản dataset tiếp theo
Confidence và kết quả holdout cùng giảmĐộ chính xác thực sự suy giảmHuấn luyện lại (bài học 10)
Kích thước hoặc vị trí bounding box thay đổi đột ngộtCamera bị di chuyển, thay ống kính hoặc thay đổi địa điểmKiểm tra camera trước khi chỉnh sửa model
Số dự đoán trên mỗi ảnh giảm, confidence ổn địnhCamera ngoại tuyến, khung cảnh ít hoạt động hơn hoặc lỗi clientĐiều tra các thành phần phía thượng nguồn
Độ trễ P95 tăng, thời gian suy luận không đổiXử lý request, kích thước payload hoặc năng lực hệ thốngHạ tầng, không phải model

Đưa ảnh production trở lại quy trình#

Trong tab Monitoring, chọn ví dụ rồi nhấp Save to dataset; các ví dụ được đưa qua quy trình nhập dữ liệu thông thường cùng với dự đoán và lưu deploymentId cùng khu vực trong metadata. Template Collect Uncertain Detections của Agents thực hiện tương tự cho toàn bộ dataset: dự đoán qua deployment của bạn rồi sao chép ảnh có detection trong một khoảng confidence vào dataset để rà soát.

Hộp thoại Lưu ví dụ vào tập dữ liệu của Ultralytics Platform với bộ chọn tập dữ liệu và nút Lưu 4 ảnh trên tab Monitoring

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

Ví dụ giám sát biến mất khi khởi động lại

Triệu chứng: các ví dụ bạn định gán nhãn biến mất sau khi thay đổi kích thước hoặc đổi model. Cách khắc phục: chúng được lưu trong bộ nhớ của instance phục vụ. Hãy lưu chúng vào dataset và chờ quá trình tiếp nhận dữ liệu hoàn tất trước khi dừng, thay đổi kích thước hoặc thay thế model.

Baseline không được đặt lại sau khi deploy

Triệu chứng: cảnh báo holdout bật ngay sau khi triển khai model tốt hơn, hoặc không bao giờ bật lại. Cách khắc phục: baseline là hàng đầu tiên trong lịch sử. Hãy bắt đầu một holdout_history.jsonl mới (hoặc ghi lại một hàng baseline mới) mỗi khi thay model.

Lỗi 429 trông giống như sự cố ngừng dịch vụ

Triệu chứng: tỷ lệ lỗi tăng đột biến trong lúc lưu lượng truy cập tăng mạnh, trong khi trạng thái health vẫn xanh. Cách khắc phục: phản hồi 429 được tính là lỗi nhưng có nghĩa là “đã đạt giới hạn năng lực”. Hãy kiểm tra log; nếu là lỗi 429, hãy phân bổ lưu lượng qua nhiều endpoint hơn hoặc dùng kích thước tùy chỉnh lớn hơn.

Dùng thử

Lên lịch chạy endpoint_check.py trên deployment của bạn mỗi 5 phút và xác nhận tiến trình thoát với mã 1 khi bạn đặt P95_BUDGET_MS thấp hơn P95 thực tế. Chạy holdout_check.py với best.pt đã triển khai và tập holdout để ghi lại baseline, sau đó diễn tập cảnh báo bằng một bản sao suy giảm của tập holdout (tối hơn, mờ hơn hoặc từ camera khác). Cuối cùng, lưu ít nhất 10 ví dụ Monitoring vào một tập dữ liệu rà soát.

Điều kiện hoàn thành
Bạn đã hoàn thành bài học khi tất cả các điều kiện sau đều đúng.
  • Kiểm tra endpoint chạy theo lịch và khi cố tình kích hoạt ngưỡng vi phạm, tiến trình sẽ thoát với trạng thái 1.

  • holdout_history.jsonl chứa một hàng baseline và lần diễn tập hồi quy đã in dòng ALERT.

  • Ít nhất 10 ví dụ production được lưu trong một tập dữ liệu rà soát cùng với metadata của deployment.

Hiển thị lời giải

Đáp án mẫu cho endpoint viên thuốc: một mục cron */5 * * * * python endpoint_check.py || ./page-oncall.sh với P95_BUDGET_MS = 300 và MAX_ERROR_RATE = 1.0; đặt ngân sách ở mức 100 ms khi P95 thực tế là 180 ms sẽ khiến tiến trình thoát với mã 1 và gửi cảnh báo, vậy nên cấu hình hoạt động đúng. Tác vụ CI hằng tuần chạy holdout_check.py với DEPLOYED = "pills-v2.pt" trên phiên bản tập holdout riêng tư gồm 300 ảnh: baseline 0.69. Lần diễn tập ca đêm làm chỉ số giảm 0.05 và in dòng ALERT với mã thoát 1; điều này khiến tác vụ CI thất bại và gửi thông báo đến kênh. Mười hai ví dụ Monitoring từ ca tối được đưa vào pill-review bằng Save to dataset, mỗi ví dụ được gắn thẻ deploymentId và europe-west1.

Tiếp theo là gì

Trước khi mở rộng quy mô, hãy xác định dữ liệu của bạn được lưu ở đâu, ai có thể xem dữ liệu và bạn sẽ xóa dữ liệu như thế nào: khu vực và tuân thủ.

Đăng nhập để lưu tiến độ