Cài đặt Ultralytics
Cài đặt Ultralytics trong môi trường sạch, đọc báo cáo kiểm tra yolo để xác nhận thiết bị, rồi kiểm chứng thiết lập bằng một lần dự đoán.
Một lần huấn luyện âm thầm chuyển sang dùng CPU có thể mất cả ngày thay vì một giờ, và bạn sẽ không nhận ra cho đến khi quá muộn. Lỗi cài đặt cũng bộc lộ theo cách tương tự: giữa chừng một bài học, dưới dạng lỗi import hoặc thiếu GPU.
Dành mười phút ở đây sẽ giúp ngăn cả hai vấn đề. Bạn sẽ cài package ultralytics vào một môi trường mới, đọc kỹ từng dòng trong báo cáo yolo checks, rồi chạy dự đoán YOLO26 đầu tiên để xác minh mọi thành phần đã kết nối.
Thực hành
Tạo môi trường sạch#
Package ultralytics cài được trên Python 3.8 trở lên, nhưng các bản PyTorch hiện tại cần Python 3.10 trở lên, vì vậy hãy bắt đầu dự án mới với phiên bản hiện hành như 3.12. Môi trường ảo mới giúp package và các dependency của nó không ảnh hưởng đến những dự án khác:
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
python --version # 3.10 or newerHướng dẫn bắt đầu nhanh của Ultralytics trình bày cách thiết lập tương tự bằng Conda hoặc Docker, nếu bạn thích dùng các công cụ đó.
Cài đúng PyTorch, sau đó cài Ultralytics#
Ultralytics chạy trên PyTorch và pip sẽ cài bản PyTorch mặc định nếu chưa có bản nào. Bản mặc định này là nguyên nhân chính dẫn đến các vấn đề kiểu "sao lại dùng CPU?", vì vậy hãy chọn bản phù hợp trước:
| Máy của bạn | Việc cần làm trước tiên | Tiếp theo |
|---|---|---|
| GPU NVIDIA | Cài bản CUDA từ bộ chọn PyTorch phù hợp với driver của bạn | pip install ultralytics sẽ giữ lại bản đó |
| Máy Mac Apple Silicon | Không cần làm gì: bản mặc định đã bao gồm MPS | pip install ultralytics |
| Chỉ dùng CPU | Không cần làm gì | pip install ultralytics |
pip install ultralyticsChỉ với một lệnh, bạn cài được package Python ultralytics, công cụ dòng lệnh yolo và các dependency như OpenCV, NumPy.
Đọc báo cáo yolo checks#
yolo checks in ra các phiên bản và phần cứng mà Ultralytics sẽ sử dụng. Đầu ra thực tế từ MacBook, đã lược bớt:
Ultralytics 8.4.175 🚀 Python-3.12.12 torch-2.14.1 CPU (Apple M5 Pro)
Setup complete ✅ (18 CPUs, 48.0 GB RAM, 594.4/926.3 GB disk)
OS macOS-27.0.1-arm64-arm-64bit
Python 3.12.12
Install pip
GPU NoneGiải thích từng dòng:
Ultralytics 8.4.175 ... torch-2.14.1: phiên bản package và PyTorch. Hãy ghi các phiên bản này trong mọi báo cáo lỗi.CPU (Apple M5 Pro): thiết bị sẽ được dùng khi bạn không truyềndevice. Đây là dòng quan trọng.Setup complete ✅: quá trình cài đặt hoạt động bình thường.GPU None: PyTorch không phát hiện GPU CUDA. Đây là điều bình thường trên máy Mac, nhưng là vấn đề trên máy NVIDIA.
Dựa vào thiết bị được nêu ở dòng 1 để xử lý:
Bạn không cần GPU cho khóa học này: mọi ví dụ đều được thiết kế để hoàn thành trong vài phút trên CPU laptop. GPU trở nên quan trọng khi bạn huấn luyện ở quy mô đầy đủ, thường nhanh hơn 10× hoặc hơn.
Kiểm chứng bằng một lần dự đoán#
Một lần dự đoán sẽ kiểm tra toàn bộ stack: tải trọng số YOLO26 nano, lấy ảnh, chạy model và ghi ra một bản sao có chú thích.
yolo predict model=yolo26n.pt source=https://ultralytics.com/images/bus.jpgimage 1/1 bus.jpg: 640x480 4 persons, 1 bus, 20.1ms
Speed: 0.7ms preprocess, 20.1ms inference, 0.5ms postprocess per image at shape (1, 3, 640, 480)
Results saved to runs/detect/predict640x480 4 persons, 1 bus: ảnh được thay đổi kích thước thành 640×480 cho model, model phát hiện được năm đối tượng.20.1ms: thời gian inference trên CPU này. Hãy ghi lại kết quả; đây là baseline tốc độ đầu tiên của bạn.runs/detect/predict: vị trí lưubus.jpgcó chú thích. Chạy lại lệnh, bạn sẽ nhận đượcpredict-2: Ultralytics không bao giờ ghi đè lần chạy trước.
Mọi giá trị mặc định trong lệnh đó — confidence, kích thước ảnh, vị trí lưu — đều được liệt kê trong tài liệu tham chiếu cấu hình.
Khắc phục các vấn đề thường gặp#
Triệu chứng: yolo checks hiển thị CPU và GPU None trên máy có GPU NVIDIA, khiến quá trình huấn luyện chậm đến khó chịu. Nguyên nhân: pip đã cài bản PyTorch chỉ hỗ trợ CPU. Cách khắc phục: gỡ cài đặt torch và torchvision, cài bản CUDA từ trình chọn PyTorch, rồi chạy lại yolo checks cho đến khi dòng đầu tiên hiển thị CUDA:0.
Nguyên nhân: môi trường ảo chưa được kích hoạt trong terminal này, vì vậy script yolo không nằm trong PATH. Cách khắc phục: chạy source .venv/bin/activate (hoặc lệnh tương đương trên Windows) trong mỗi terminal mới trước khi sử dụng yolo.
| Triệu chứng | Nguyên nhân | Cách khắc phục |
|---|---|---|
requirements: ... not found, attempting AutoUpdate, sau đó là No module named pip | Môi trường được tạo mà không có pip, nên Ultralytics không thể tự động cài thêm package | Cài package được nêu bằng công cụ của môi trường, ví dụ: uv pip install lap |
| Tải trọng số hoặc dataset bị quá thời gian chờ | Mạng chặn các asset phát hành trên GitHub | Tải yolo26n.pt một lần ở nơi khác rồi truyền vào đường dẫn cục bộ |
PermissionError đang ghi vào runs/ | Thư mục làm việc chỉ có quyền đọc | Chạy cd trong thư mục dự án có quyền ghi |
Nếu gặp vấn đề khác, hướng dẫn các vấn đề thường gặp tổng hợp những cách khắc phục đã biết; các issue đã đóng trong repository Ultralytics thường cũng có câu trả lời — hãy tìm kiếm trước khi mở issue mới.
Hiển thị lời giải
python -m venv .venv
source .venv/bin/activate
# NVIDIA only: install the CUDA PyTorch build from pytorch.org first
pip install ultralytics
yolo checks
yolo predict model=yolo26n.pt source=https://ultralytics.com/images/bus.jpgVersions: Ultralytics 8.4.175, torch 2.14.1
Device: CPU (Apple M5 Pro); use device=mps for the Apple GPU
bus.jpg: 20.1 ms inference at 640x480Trên CPU laptop, thời gian bus.jpg thường vào khoảng 10–60 ms; trên GPU NVIDIA đời mới, chỉ vài mili giây. Nếu yolo checks nêu sai thiết bị, hãy khắc phục PyTorch trước khi tiếp tục.