Dịch vụ AI

Cách tích hợp phát hiện PPE

Gửi một ảnh của hiện trường và nhận về ai đang mặc thiết bị bảo hộ nào, kèm bounding box cho từng người và từng vật dụng tìm thấy.

Chọn endpoint

Cả 3 endpoint đều nhận cùng một request và trả về cùng một cấu trúc kết quả. Chỉ khác nhau ở loại thiết bị nào được tính vào việc đánh giá tuân thủ.

Endpoint	Kiểm tra
`POST /v1/ai/ppe-detection/detect`	Khẩu trang và mũ bảo hộ cùng lúc. Một người chỉ được tính là tuân thủ khi mang đủ cả hai.
`POST /v1/ai/ppe-detection/detect-mask`	Chỉ kiểm tra khẩu trang.
`POST /v1/ai/ppe-detection/detect-helmet`	Chỉ kiểm tra mũ bảo hộ, gồm mũ bảo hiểm và mũ cứng.

Nội dung request

Gửi dạng multipart/form-data với một ảnh:

Trường	Ý nghĩa
`image`	image là bắt buộc. JPEG hoặc PNG, tối đa 5 MB. Đánh giá tối đa 15 người trong ảnh.

Ví dụ

Ví dụ này gọi endpoint tổng quát; hai endpoint còn lại là request giống hệt, chỉ khác URL.

curl -X POST https://core.roammoon.com/v1/ai/ppe-detection/detect \
  -H "X-API-Key: rm_live_YOUR_KEY" \
  -F "image=@site-entrance.jpg"

Kết quả trả về

Trả về một mục cho mỗi người tìm thấy, kèm bounding box riêng và các vật dụng phát hiện được trên người đó:

JSON

{
  "requiredEquipmentTypes": ["FACE_COVER", "HEAD_COVER"],
  "persons": [
    {
      "id": 0,
      "confidence": 99.8,
      "boundingBox": { "left": 0.12, "top": 0.05, "width": 0.31, "height": 0.62 },
      "compliant": true,
      "bodyParts": [
        {
          "name": "FACE",
          "confidence": 99.9,
          "equipment": [
            {
              "type": "FACE_COVER",
              "confidence": 98.5,
              "boundingBox": { "left": 0.18, "top": 0.09, "width": 0.14, "height": 0.11 },
              "covers": true,
              "coversConfidence": 99.1
            }
          ]
        }
      ]
    }
  ]
}

Khi không có ai trong ảnh

persons là một mảng rỗng. Đây vẫn là lệnh gọi thành công và vẫn bị tính phí, vì API đã hoàn thành việc của nó, chỉ là không có ai để báo cáo.

JSON

{
  "requiredEquipmentTypes": ["FACE_COVER"],
  "persons": []
}

Các trường quan trọng

Trường	Ý nghĩa
`persons`	Một mục cho mỗi người mà Rekognition tìm thấy trong ảnh, không theo thứ tự nào cả.
`persons[].compliant`	true khi người này mang đủ mọi loại thiết bị mà endpoint kiểm tra, false khi thiếu ít nhất một loại, null khi không xác định được, thường là do độ tin cậy phát hiện của một vật dụng thấp hơn mức tối thiểu được cấu hình, dù vật dụng đó vẫn xuất hiện trong bodyParts.
`persons[].bodyParts`	Mặt và đầu, chỉ hiển thị khi Rekognition thực sự xác định được bộ phận đó.
`bodyParts[].equipment`	Các vật dụng bảo hộ phát hiện được trên bộ phận cơ thể đó.
`equipment[].covers`	Vật dụng đó có thực sự che phủ bộ phận cơ thể tìm thấy gần nó hay không. Một chiếc khẩu trang kéo xuống cằm vẫn được phát hiện, nhưng covers sẽ là false.
`boundingBox`	Tỷ lệ theo chiều rộng và chiều cao của chính ảnh, 0–1, tính từ góc trên bên trái. Tự vẽ lên ảnh bạn đã có, vì API này không bao giờ vẽ sẵn khung lên ảnh.

Tính phí

Chỉ khi phát hiện thành công và trả về kết quả thì mới bị trừ 10 credit, ở bất kỳ endpoint nào trong 3 endpoint. Mọi trường hợp thất bại đều được hoàn lại, dù là ảnh bị từ chối hay chính dịch vụ không xử lý được.

Chính sách tính phí là charge-on-success: credit được giữ chỗ khi tiếp nhận request và chỉ thực sự trừ khi xử lý thành công. Thất bại thì hoàn lại.

Mẹo để có kết quả tốt

Dùng cả khung cảnh, đừng cắt ảnh theo từng người, vì bounding box được tính theo ảnh bạn gửi, nên cắt sát chỉ khiến mô hình có ít dữ liệu hơn để xử lý.
Người ở xa hoặc bị che khuất nhiều là nguyên nhân phổ biến nhất khiến compliant bị thiếu hoặc không xác định. Hãy đưa camera lại gần hơn hoặc tăng độ phân giải trước khi kết luận là không có thiết bị.
Đây là phát hiện thiết bị, không phải chứng nhận an toàn. Hãy coi đây là bước sàng lọc đầu tiên để biết cần kiểm tra gì, và luôn có con người xem xét lại trước khi dùng kết quả này để ra quyết định về quyền truy cập hay kỷ luật.

Lỗi

Mọi lỗi đều dùng chung một cấu trúc. Hãy xử lý theo trường code, không phải theo message, vì message có thể thay đổi.

JSON

{
  "error": {
    "code": "INVALID_PPE_DETECTION_REQUEST",
    "message": "The \"image\" field must be an image file."
  }
}

HTTP	Mã lỗi	Nên làm gì
401	`API_KEY_REQUIRED`	Thiếu header X-API-Key.
401	`API_KEY_INVALID`	Key sai, đã bị vô hiệu hóa hoặc hết hạn. Kiểm tra lại hoặc tạo key mới.
403	`API_KEY_FORBIDDEN`	Key không có quyền dùng dịch vụ này.
400	`INVALID_PPE_DETECTION_REQUEST`	Trường "image" bị thiếu, rỗng, hoặc Rekognition không xử lý được. Không bị trừ credit.
402	`CREDIT_LIMIT_EXCEEDED`	Hết credit trong chu kỳ. Nâng gói hoặc chờ sang chu kỳ mới.
413	`IMAGE_TOO_LARGE`	Ảnh vượt quá 5 MB. Hãy nén hoặc thu nhỏ ảnh.
415	`UNSUPPORTED_IMAGE_TYPE`	Chỉ hỗ trợ JPEG và PNG.
429	`RATE_LIMIT_EXCEEDED`	Vượt giới hạn request mỗi phút.
429	`PPE_DETECTION_SERVICE_BUSY`	Dịch vụ phát hiện đang quá tải. Thử lại sau vài giây.
502	`PPE_DETECTION_UPSTREAM_ERROR`	Mô hình phát hiện PPE không xử lý được request. Có thể thử lại.
503	`PPE_DETECTION_SERVICE_MISCONFIGURED`	Dịch vụ chưa được cấu hình đúng. Đây là lỗi phía vận hành, thử lại cũng không giải quyết được.

Thử lại an toàn

429 và 502 có thể thử lại, dùng exponential backoff. Các lỗi khác trả về cùng kết quả khi thử lại. Chỉ lần phát hiện thành công mới bị trừ phí, nên thử lại sau khi thất bại không tốn thêm gì. Ngoại lệ là timeout mạng: nếu lần gọi đầu thực ra đã thành công, lần thử lại sẽ tính phí như một lệnh gọi thứ hai.

Tiếp theo: Tham chiếu API →