Tạo Ví dụ Tối thiểu có thể Tái lập (MRE) cho các Báo cáo Lỗi

When submitting a bug report for Ultralytics YOLO repositories, it's essential to provide a Minimum Reproducible Example (MRE). An MRE is a small, self-contained piece of code that demonstrates the problem you're experiencing. Providing an MRE helps maintainers and contributors understand the issue and work on a fix more efficiently. This guide explains how to create an MRE when submitting bug reports to Ultralytics YOLO repositories.

Cách ly Vấn đề

Bước đầu tiên để tạo MRE là cách ly vấn đề. Hãy loại bỏ bất kỳ mã hoặc phần phụ thuộc nào không cần thiết và không liên quan trực tiếp đến vấn đề. Tập trung vào phần mã cụ thể đang gây ra sự cố và loại bỏ mọi đoạn mã không liên quan.

Sử dụng các Model và Tập dữ liệu Công khai

Khi tạo MRE, hãy sử dụng các model và tập dữ liệu có sẵn công khai để tái lập vấn đề. Ví dụ, hãy sử dụng model yolo26n.pt và tập dữ liệu coco8.yaml. Điều này đảm bảo rằng những người bảo trì và cộng tác viên có thể dễ dàng chạy ví dụ của bạn và điều tra vấn đề mà không cần quyền truy cập vào dữ liệu độc quyền hoặc các model tùy chỉnh.

Bao gồm Tất cả các Phần phụ thuộc Cần thiết

Đảm bảo tất cả các phần phụ thuộc cần thiết đều được bao gồm trong MRE của bạn. Nếu mã của bạn dựa vào các thư viện bên ngoài, hãy chỉ định các gói cần thiết và phiên bản của chúng. Lý tưởng nhất là hãy liệt kê các phần phụ thuộc trong báo cáo lỗi của bạn bằng cách sử dụng yolo checks nếu bạn đã cài đặt ultralytics hoặc pip list cho các công cụ khác.

Viết Mô tả Rõ ràng về Vấn đề

Cung cấp mô tả rõ ràng và ngắn gọn về vấn đề bạn đang gặp phải. Giải thích hành vi mong đợi và hành vi thực tế mà bạn đang gặp phải. Nếu có thể, hãy đính kèm bất kỳ thông báo lỗi hoặc nhật ký (log) liên quan nào.

Định dạng Mã của Bạn đúng cách

Định dạng mã của bạn đúng cách bằng cách sử dụng các khối mã trong phần mô tả vấn đề. Điều này giúp người khác dễ dàng đọc và hiểu mã của bạn hơn. Trên GitHub, bạn có thể tạo một khối mã bằng cách bao mã của mình bằng ba dấu backtick (```) và chỉ định ngôn ngữ:

```python
# Your Python code goes here
```

Kiểm tra MRE của Bạn

Trước khi gửi MRE, hãy kiểm tra nó để đảm bảo rằng nó tái lập chính xác vấn đề. Hãy chắc chắn rằng người khác có thể chạy ví dụ của bạn mà không gặp bất kỳ lỗi hoặc sửa đổi nào.

Ví dụ về MRE

Dưới đây là một ví dụ về MRE cho một báo cáo lỗi giả định:

Mô tả lỗi:

Khi chạy suy luận (inference) trên một hình ảnh có 0 kênh, tôi nhận được lỗi liên quan đến kích thước của tensor đầu vào.

MRE:

import torch

from ultralytics import YOLO

# Load the model
model = YOLO("yolo26n.pt")

# Load a 0-channel image
image = torch.rand(1, 0, 640, 640)

# Run the model
results = model(image)

Thông báo lỗi:

RuntimeError: Expected input[1, 0, 640, 640] to have 3 channels, but got 0 channels instead

Phần phụ thuộc:

torch==2.3.0
ultralytics==8.2.0

In this example, the MRE demonstrates the issue with a minimal amount of code, uses a public model ("yolo26n.pt"), includes all necessary dependencies, and provides a clear description of the problem along with the error message.

Bằng cách tuân theo các hướng dẫn này, bạn sẽ giúp những người bảo trì và cộng tác viên của các kho lưu trữ YOLO của Ultralytics hiểu và giải quyết vấn đề của bạn hiệu quả hơn.

Câu hỏi thường gặp (FAQ)

Làm thế nào để tôi tạo một Ví dụ Tối thiểu có thể Tái lập (MRE) hiệu quả cho các báo cáo lỗi trong các kho lưu trữ YOLO của Ultralytics?

Để tạo một Ví dụ Tối thiểu có thể Tái lập (MRE) hiệu quả cho các báo cáo lỗi trong các kho lưu trữ YOLO của Ultralytics, hãy làm theo các bước sau:

Cách ly Vấn đề: Loại bỏ bất kỳ mã hoặc phần phụ thuộc nào không liên quan trực tiếp đến vấn đề.
Sử dụng các Model và Tập dữ liệu Công khai: Sử dụng các tài nguyên công khai như yolo26n.pt và coco8.yaml để dễ dàng tái lập hơn.
Bao gồm Tất cả các Phần phụ thuộc Cần thiết: Chỉ định các gói bắt buộc và phiên bản của chúng. Bạn có thể liệt kê các phần phụ thuộc bằng cách sử dụng yolo checks nếu bạn đã cài đặt ultralytics hoặc sử dụng pip list.
Viết Mô tả Rõ ràng về Vấn đề: Giải thích hành vi mong đợi và hành vi thực tế, bao gồm mọi thông báo lỗi hoặc nhật ký.
Định dạng Mã của Bạn đúng cách: Sử dụng các khối mã để định dạng mã của bạn, giúp việc đọc dễ dàng hơn.
Kiểm tra MRE của Bạn: Đảm bảo MRE của bạn tái lập vấn đề mà không cần sửa đổi.

Để có hướng dẫn chi tiết, hãy xem Tạo Ví dụ Tối thiểu có thể Tái lập.

Tại sao tôi nên sử dụng các model và tập dữ liệu công khai trong MRE của mình cho các báo cáo lỗi YOLO của Ultralytics?

Việc sử dụng các model và tập dữ liệu công khai trong MRE đảm bảo rằng những người bảo trì có thể dễ dàng chạy ví dụ của bạn mà không cần quyền truy cập vào dữ liệu độc quyền. Điều này giúp giải quyết vấn đề nhanh chóng và hiệu quả hơn. Ví dụ, việc sử dụng model yolo26n.pt và tập dữ liệu coco8.yaml giúp chuẩn hóa và đơn giản hóa quá trình gỡ lỗi. Tìm hiểu thêm về các model và tập dữ liệu công khai trong phần Sử dụng các Model và Tập dữ liệu Công khai.

Tôi nên bao gồm những thông tin gì trong báo cáo lỗi của mình cho YOLO của Ultralytics?

Một báo cáo lỗi toàn diện cho YOLO của Ultralytics nên bao gồm:

Mô tả Rõ ràng: Giải thích vấn đề, hành vi mong đợi và hành vi thực tế.
Thông báo Lỗi: Bao gồm bất kỳ thông báo lỗi hoặc nhật ký liên quan nào.
Phần phụ thuộc: Liệt kê các phần phụ thuộc cần thiết và phiên bản của chúng.
MRE: Cung cấp một Ví dụ Tối thiểu có thể Tái lập.
Các Bước để Tái lập: Nêu rõ các bước cần thiết để tái lập vấn đề.

Để có danh sách kiểm tra đầy đủ, hãy tham khảo phần Viết Mô tả Rõ ràng về Vấn đề.

Làm thế nào tôi có thể định dạng mã của mình đúng cách khi gửi báo cáo lỗi trên GitHub?

Để định dạng mã của bạn đúng cách khi gửi báo cáo lỗi trên GitHub:

Sử dụng ba dấu backtick (```) để tạo khối mã.
Chỉ định ngôn ngữ lập trình để tô sáng cú pháp, ví dụ: ```python.
Đảm bảo mã của bạn được thụt lề chính xác để dễ đọc.

Ví dụ:

```python
# Your Python code goes here
```

Để biết thêm các mẹo về định dạng mã, hãy xem Định dạng Mã của Bạn đúng cách.

Có những lỗi phổ biến nào cần kiểm tra trước khi gửi MRE cho báo cáo lỗi?

Trước khi gửi MRE, hãy đảm bảo rằng bạn:

Xác minh vấn đề có thể tái lập được.
Đảm bảo tất cả các phần phụ thuộc đã được liệt kê và chính xác.
Loại bỏ bất kỳ mã không cần thiết nào.
Kiểm tra MRE để đảm bảo nó tái lập vấn đề mà không cần sửa đổi.

Để có danh sách kiểm tra chi tiết, hãy truy cập phần Kiểm tra MRE của Bạn.

Contributors

GLglenn-jocher⁵ PDpderrenger¹

Created 17 thg 1, 2025Updated 4 tháng trước