---
language:
- vi
license: agpl-3.0
library_name: ultralytics
pipeline_tag: object-detection
tags:
- yolo
- yolov8
- onnx
- torchscript
- tensorrt
- int8
- fp16
- vision
- object-detection
- traffic-sign
- vietnam
---

**Ngôn ngữ tài liệu**

- 🇺🇸 English: README.md
- 🇻🇳 Tiếng Việt: README.vi.md

# VTSR

VTSR là mô hình phát hiện đối tượng YOLOv8n được huấn luyện để nhận diện 56 lớp biển báo giao thông Việt Nam.

Kho lưu trữ này tập trung vào các phiên bản mô hình đã được tối ưu hóa cho triển khai thực tế, được xuất từ checkpoint PyTorch FP32 gốc, bao gồm ONNX INT8, TensorRT INT8 và TorchScript FP16.

## Demo

Demo tương tác được triển khai trên Hugging Face Spaces:

https://huggingface.co/spaces/liamxdev/vtsr

Hiện tại demo sử dụng mô hình ONNX INT8 để suy luận tương thích với CPU.

## Thông tin mô hình

| Thuộc tính         | Giá trị                         |
| ------------------ | ------------------------------- |
| Nhiệm vụ           | Phát hiện đối tượng             |
| Kiến trúc          | YOLOv8n                         |
| Số lớp             | 56                              |
| Kích thước đầu vào | 640 × 640                       |
| Mô tả nhãn         | `label-mapping.json`            |
| Tập dữ liệu        | Vietnam Traffic Sign Dataset v3 |
| Giấy phép          | AGPL-3.0                        |

Mô hình trả về các mã biển báo giao thông như `P-102`, `R-303`, `W-224`... Mô tả tiếng Việt tương ứng của các mã này được cung cấp trong tệp `label-mapping.json`.

## Các tệp mô hình

| Tệp                  | Độ chính xác | Nền tảng mục tiêu                         |
| -------------------- | ------------ | ----------------------------------------- |
| `vtsr.pt`            | FP32         | PyTorch                                   |
| `vtsr_int8.onnx`     | INT8         | ONNX Runtime, CPU, triển khai đa nền tảng |
| `vtsr.torchscript`   | FP16         | Runtime hỗ trợ TorchScript                |
| `vtsr.engine`        | INT8         | NVIDIA TensorRT và Jetson                 |
| `label-mapping.json` | —            | Mô tả mã biển báo giao thông              |

> Checkpoint PyTorch FP32 gốc không được cung cấp trong kho này. Chỉ các phiên bản tối ưu hóa cho triển khai được phân phối.

## Cách sử dụng

Cài đặt thư viện:

```bash
pip install ultralytics
```

Chạy suy luận:

```python
from ultralytics import YOLO

# Các định dạng được hỗ trợ:
# vtsr.pt
# vtsr_int8.onnx
# vtsr.torchscript
# vtsr.engine

model = YOLO("vtsr_int8.onnx")

results = model.predict(
    source="traffic.jpg",
    imgsz=640,
    conf=0.25,
)

results[0].save("result.jpg")
```

Xem `label-mapping.json` để tra cứu mô tả tiếng Việt của các mã biển báo.

## Tải từ Hugging Face Hub

```python
from huggingface_hub import hf_hub_download

repo_id = "liamxdev/vtsr"

model_path = hf_hub_download(
    repo_id=repo_id,
    filename="vtsr_int8.onnx",
)

mapping_path = hf_hub_download(
    repo_id=repo_id,
    filename="label-mapping.json",
)
```

Các tệp khác cũng có thể được tải theo cách tương tự:

* `vtsr.pt`
* `vtsr.torchscript`
* `vtsr.engine`

## Benchmark

Xem `benchmark.md` để biết các số liệu về độ trễ (latency) và thông lượng (throughput).

## Các lớp được hỗ trợ

Mô hình hỗ trợ 56 mã biển báo giao thông Việt Nam thuộc các nhóm chính:

* `P-*`: Biển báo cấm.
* `R-*`: Biển báo hiệu lệnh và chỉ dẫn bắt buộc.
* `W-*`: Biển báo cảnh báo nguy hiểm.
* `S-*` và `DP-*`: Biển phụ hoặc biển báo đặc biệt có trong tập dữ liệu huấn luyện.

Xem `label-mapping.json` để biết danh sách đầy đủ và ý nghĩa của từng biển báo.

## Dữ liệu huấn luyện

Mô hình được huấn luyện trên phiên bản 3 của Vietnam Traffic Sign Dataset được công bố trên Roboflow Universe.

Theo thông tin từ bộ dữ liệu, dữ liệu được phát hành theo giấy phép CC BY 4.0.

## Mục đích sử dụng

* Học tập và nghiên cứu.
* Nguyên mẫu phân tích cảnh giao thông.
* Demo nhận diện biển báo giao thông Việt Nam.
* Triển khai trên CPU thông qua ONNX Runtime.
* Triển khai trên GPU NVIDIA và Jetson thông qua TensorRT.
* Triển khai nhẹ với TorchScript.

## Hạn chế

* Mô hình chỉ nhận diện được 56 lớp biển báo có trong `label-mapping.json`.
* Chất lượng phát hiện có thể giảm đối với biển báo nhỏ, mờ, bị che khuất, hư hỏng, thiếu sáng hoặc có góc chụp bất thường.
* Hình ảnh nằm ngoài phân phối dữ liệu huấn luyện có thể gây bỏ sót hoặc nhận diện sai.
* Kết quả nhận diện không thay thế cho việc diễn giải biển báo chính thức hoặc các quyết định lái xe quan trọng liên quan đến an toàn.
* Các mô hình lượng tử hóa hoặc giảm độ chính xác có thể có sai khác về độ chính xác so với checkpoint PyTorch gốc.
* TensorRT Engine phụ thuộc phần cứng và có thể cần được tạo lại cho các kiến trúc GPU khác nhau.

## Giấy phép

Mô hình được xuất từ Ultralytics YOLO và được phân phối theo giấy phép AGPL-3.0.

Việc ghi nhận nguồn dữ liệu và các điều khoản của giấy phép CC BY 4.0 đối với bộ dữ liệu được áp dụng riêng.

Đối với nhu cầu cấp phép thương mại cho các thành phần của Ultralytics, vui lòng tham khảo:

https://www.ultralytics.com/license

## Trích dẫn

```bibtex
@misc{vietnam_traffic_sign_altsi_dataset,
  title        = {Vietnam Traffic Sign Dataset},
  author       = {giang},
  year         = {2024},
  publisher    = {Roboflow Universe},
  howpublished = {\url{https://universe.roboflow.com/giang-yp9g1/vietnam-traffic-sign-altsi}}
}
```