Dịch vụ AI
Cách tích hợp phân loại hình ảnh
Gửi một ảnh và nhận về các nhãn khả năng cao nhất cho nội dung trong ảnh, kèm điểm số độ tin cậy.
Phù hợp và không phù hợp với việc gì
resnet-50 xếp một ảnh vào 1 trong 1.000 danh mục tổng quát của ImageNet, ví dụ "chó golden retriever" hay "cốc cà phê", chứ không nhận diện một cá thể hay sản phẩm cụ thể nào. Nó không thể phân biệt sản phẩm của bạn với một sản phẩm tương tự, không đọc được chữ, không nhận diện một người cụ thể, và không đếm được có bao nhiêu vật thể trong ảnh. Nếu đưa vào một ảnh và kỳ vọng ra kết quả chính xác cho một vật thể cụ thể, bạn sẽ nhận về một nhãn nghe có vẻ chắc chắn nhưng sai, đó là do dùng sai bài toán chứ không phải mô hình kém.
Với khuôn mặt, dùng so sánh khuôn mặt. Với việc xác định thiết bị bảo hộ người đang mang, dùng phát hiện thiết bị bảo hộ. Cả hai dịch vụ đó cũng không nhận diện một vật thể cụ thể trong đời sống hằng ngày, hiện tại nền tảng này chưa có dịch vụ nào làm được việc đó, vì việc đó cần một mô hình huấn luyện riêng theo đúng danh mục của bạn chứ không phải danh mục tổng quát của ImageNet.
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 10 MB. |
Ví dụ
curl -X POST https://core.roammoon.com/v1/ai/image-classification/classify \
-H "X-API-Key: rm_live_YOUR_KEY" \
-F "image=@photo.jpg"Kết quả trả về
Trả về mọi nhãn mà mô hình cân nhắc, sắp theo độ tin cậy giảm dần:
{
"predictions": [
{ "label": "Egyptian cat", "confidence": 0.91 },
{ "label": "tabby, tabby cat", "confidence": 0.06 },
{ "label": "tiger cat", "confidence": 0.02 }
]
}Các trường quan trọng
| Trường | Ý nghĩa |
|---|---|
predictions | Một mục cho mỗi nhãn mô hình trả về, sắp theo độ tin cậy. |
predictions[].label | Tên nhãn dự đoán, lấy từ 1.000 danh mục ImageNet mà resnet-50 được huấn luyện. |
predictions[].confidence | Độ tin cậy của mô hình cho nhãn này, 0-1. |
Tính phí
Chỉ khi phân loại thành công và trả về kết quả thì mới bị trừ 1 credit. 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 mô hình 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
- Một chủ thể rõ ràng, chiếm phần đáng kể khung hình cho kết quả tốt nhất, vì resnet-50 phân loại toàn bộ ảnh chứ không định vị vật thể bên trong.
- Nhãn lấy từ 1.000 danh mục của ImageNet, chủ yếu là đồ vật, động vật và khung cảnh thường gặp, nên chủ thể lạ có thể ra nhãn hợp lý nhưng không thật chính xác.
- Coi đây là bước sàng lọc nhanh, không phải kết quả chắc chắn. Dự đoán có độ tin cậy thấp nên được xem lại trước khi dùng để tự động quyết định điều gì.
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.
{
"error": {
"code": "UNSUPPORTED_IMAGE_TYPE",
"message": "Image classification accepts JPEG or PNG images only."
}
}| 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_IMAGE_CLASSIFICATION_REQUEST | Trường "image" bị thiếu hoặc rỗng. 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á 10 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. |
| 502 | IMAGE_CLASSIFICATION_UPSTREAM_ERROR | Mô hình phân loại hình ảnh không xử lý được request. Có thể thử lại. |
Thử lại an toàn
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ân loại 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.