PyCoral trên Pi 5: 8 bước chạy Coral TPU trong Docker

Coral Edge TPU là một trong những cách rẻ nhất để thêm suy luận AI vào Raspberry Pi 5: module ăn khoảng 2W, xử lý 4 TOPS ở dạng số nguyên 8-bit, và gánh phần nhận diện để CPU rảnh. PyCoral là thư viện Python quen thuộc nhất để điều khiển thiết bị này, nhưng cài PyCoral trên Pi 5 khó hơn trên Pi 4 vì hai rào cản: kích thước trang bộ nhớ của kernel và phiên bản Python.

Trình tự dưới đây dựa trên tài liệu PyCoral của Pineboards, được The Pi Hut lưu lại sau khi Pineboards đóng cửa. Cách làm là đóng gói PyCoral trong container Docker chạy Debian 10: userspace cũ nằm gọn trong container, kernel của Pi 5 vẫn là kernel chính thức.

Mục lục

PyCoral là gì và vì sao phải chạy trong Docker

PyCoral không phải framework huấn luyện. Nó là lớp bọc Python mỏng trên libedgetpu, runtime C++ của Google, cộng thêm bộ mô hình mẫu. Công việc thật sự diễn ra ở ba lớp: kernel Pi 5 nạp driver gasket, driver này tạo node thiết bị /dev/apex_0, rồi libedgetpu gửi tensor vào node đó và nhận kết quả về. PyCoral chỉ gói lại các bước gọi hàm cho gọn: pycoral.utils.edgetpu để mở thiết bị, pycoral.adapters để nạp mô hình và đọc kết quả.

Có hai lý do khiến pip install pycoral thất bại trên Raspberry Pi OS Bookworm. Thứ nhất, wheel của PyCoral chỉ phát hành cho Python 3.6 tới 3.9, còn Bookworm dùng Python 3.11, nên pip báo không tìm được bản phù hợp. Thứ hai, kernel mặc định của Pi 5 biên dịch với trang bộ nhớ 16KB, còn driver gasket giả định trang 4KB: driver vẫn nạp, thiết bị vẫn hiện trong lspci, nhưng mọi lần mở /dev/apex_0 đều thất bại.

Docker giải quyết cả hai rào cản của PyCoral cùng lúc. Container dùng chung kernel với máy host, nên kernel vẫn phải là bản 4KB page, nhưng toàn bộ userspace bên trong là Debian 10 với Python 3.7, đúng phiên bản PyCoral cần. Node /dev/apex_0 được truyền vào container bằng đúng một tham số, không phải hạ cấp Python của máy.

Chuẩn bị phần cứng và phần mềm

Danh sách tối thiểu cho một lần dựng mới:

Raspberry Pi 5, bản 4GB đủ cho ví dụ trong bài; 8GB thoải mái hơn khi chạy kèm Frigate NVR.
Thẻ nhớ microSD 32GB trở lên, cài Raspberry Pi OS Bookworm 64-bit.
HAT PCIe M.2 cho Pi 5. Khe PCIe của Pi 5 chỉ có một làn (x1) nên mọi HAT đều dùng chung đường này.
Coral Edge TPU bản M.2, có hai loại khoá: A+E key và B+M key. Bản B+M key dài 2230 cắm vừa khe M của M.2 HAT+ chính hãng; bản A+E key cần HAT có khe A+E.
Nguồn USB-C 27W (5V 5A). TPU chỉ ăn 2W nhưng HAT và ổ cứng ăn thêm, nguồn yếu gây lỗi PCIe ngẫu nhiên.
Tản nhiệt cho Pi 5. Suy luận liên tục không nóng bằng giải mã video nhưng vẫn nên có quạt.

Module Google Coral Edge TPU gắn qua HAT PCIe để chạy PyCoral trên Raspberry Pi 5 — Module Coral Edge TPU bản M.2: đây là phần cứng mà PyCoral điều khiển qua node /dev/apex_0.

Một lưu ý về nguồn hàng: Google đã ngừng sản xuất Coral Edge TPU và Pineboards đã đóng cửa, nên shop không còn bán hai món chính của bài này. Hướng dẫn vẫn giữ nguyên vì Coral cũ vẫn chạy tốt và vẫn mua lại được. Nếu dùng HAT AI khác, tên overlay và gói driver sẽ khác, đừng dán nguyên tên overlay của Pineboards. Nếu chưa có Coral, Raspberry Pi AI HAT+ 13 TOPS (Hailo-8L) là lựa chọn đang bán tại shop, nhưng driver khác hoàn toàn.

Bước 1: Cập nhật Raspberry Pi OS

Hệ điều hành vừa ghi ra thẻ thường chưa có bản vá nào, nhưng vẫn nên cập nhật vì driver gasket phải biên dịch lại theo đúng kernel đang chạy. Chạy hai lệnh sau:

sudo apt update 
sudo apt upgrade

Nếu bản cập nhật kéo theo kernel mới, khởi động lại một lần trước khi sửa config.txt.

Bước 2: Sửa config.txt cho PCIe và kernel 4K page

Mở file cấu hình khởi động. Trên Bookworm đường dẫn là /boot/firmware/config.txt; bản cũ dùng /boot/config.txt và sửa nhầm file thì không có tác dụng gì. Thêm hai dòng sau vào cuối file:

kernel=kernel8.img 
dtoverlay=pineboards-hat-ai

Dòng kernel=kernel8.img chọn kernel biên dịch với trang bộ nhớ 4KB thay cho bản mặc định 16KB của Pi 5. Dòng dtoverlay=pineboards-hat-ai nạp overlay thiết bị của HAT Pineboards, khai báo chân PCIe và thứ tự cấp nguồn cho TPU. Khe PCIe trên Pi 5 vốn đã bật mặc định trong các bản Raspberry Pi OS gần đây.

Nếu dùng HAT khác, thay tên overlay theo tài liệu của HAT đó, hoặc bỏ hẳn dòng dtoverlay nếu HAT tự khai báo qua EEPROM HAT+. Kiểm tra bằng ls /boot/firmware/overlays | grep pineboards: không có file .dtbo nghĩa là firmware đang chạy không hỗ trợ HAT này.

Khởi động lại rồi kiểm tra hai thứ. uname -a phải in ra hậu tố -v8, ví dụ 6.6.31+rpt-rpi-v8; nếu vẫn thấy v8+ hoặc 2712 thì dòng kernel chưa được áp dụng. Tiếp theo lspci | grep Coral phải trả về System peripheral: Global Unichip Corp. Coral Edge TPU. Không thấy thiết bị nghĩa là vấn đề nằm ở phần cứng hoặc overlay, chưa liên quan gì tới PyCoral.

Tuyệt đối không thêm dtparam=pciex1_gen=3 khi gắn Coral. TPU chỉ chạy ổn định ở PCIe Gen2; ép Gen3 thì vài phút đầu có vẻ nhanh hơn rồi lỗi bus hàng loạt.

Bước 3: Cài driver gasket và apex

Bản gốc dừng ở đây và trỏ sang hướng dẫn cấu hình Coral Edge TPU của The Pi Hut, vì hai bài cùng một bộ tài liệu Pineboards. Trình tự gồm năm việc: thêm kho gói của Google, cài libedgetpu, biên dịch driver gasket bằng DKMS, thêm quy tắc udev, rồi khởi động lại. Các khối lệnh dưới đây giữ nguyên văn từ hướng dẫn đó.

Thêm kho gói Coral và khoá ký của kho:

echo "deb https://packages.cloud.google.com/apt coral-edgetpu-stable main" | sudo tee /etc/apt/sources.list.d/coral-edgetpu.list

curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -

Cài libedgetpu cùng các gói cần cho DKMS. libedgetpu1-std chạy ở xung tiêu chuẩn, khoảng 2W; bản libedgetpu1-max đẩy xung cao hơn, ăn điện nhiều hơn, chỉ nên dùng khi đã có tản nhiệt tốt.

sudo apt-get install cmake libedgetpu1-std devscripts debhelper dkms dh-dkms

Sau đó lấy mã nguồn driver gasket, biên dịch thành gói .deb rồi cài:

git clone https://github.com/google/gasket-driver.git

cd gasket-driver
sudo debuild -us -uc -tc -b

cd ..
sudo dpkg -i gasket-dkms_1.0-18_all.deb

Thêm quy tắc udev để node thiết bị thuộc nhóm apex thay vì chỉ root đọc được, rồi thêm user hiện tại vào nhóm đó:

sudo sh -c "echo 'SUBSYSTEM==\"apex\", MODE=\"0660\", GROUP=\"apex\"' >> /etc/udev/rules.d/65-apex.rules"

sudo groupadd apex
sudo adduser $USER apex

Khởi động lại. Sau khi vào lại, sudo lspci -v phải hiện dòng Kernel driver in use: apex trong mục thiết bị Coral, và ls -l /dev/apex_0 phải có node. Nếu chưa có, xem bảng xử lý sự cố ở cuối bài trước khi đi tiếp.

Phần cài driver này cũng đã được viết lại theo ngữ cảnh camera an ninh trong bài Cài Frigate NVR trên Raspberry Pi 5 với Google Coral TPU, nếu bạn muốn xem thêm cách kiểm tra module sau khi cài.

Bước 4: Cài Docker từ kho chính thức

Cài Docker từ kho của Docker chứ không dùng gói docker.io của Debian, vì bản trong kho Debian thường cũ và thiếu plugin buildx. Khối lệnh đầu thêm khoá GPG và khai báo kho:

# Add Docker's official GPG key:
sudo apt-get update 
sudo apt-get install ca-certificates curl 
sudo install -m 0755 -d /etc/apt/keyrings 
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc 
sudo chmod a+r /etc/apt/keyrings/docker.asc

# Add the repository to Apt sources:
echo \ 
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \ 
  $(. /etc/os-release && echo \"$VERSION_CODENAME\") stable" | \ 
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null 
sudo apt-get update

Rồi cài các gói cần thiết:

sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Muốn bỏ tiền tố sudo mỗi lần gọi docker thì thêm user vào nhóm docker bằng sudo usermod -aG docker $USER rồi đăng nhập lại. Nhóm này tương đương quyền root, chỉ làm trên máy cá nhân.

Bước 5: Viết Dockerfile cho PyCoral

Tạo thư mục làm việc và một file tên Dockerfile với nội dung sau. Đây là bản của Jeff Geerling, được bài gốc dùng lại nguyên vẹn:

FROM debian:10
 
WORKDIR /home 
ENV HOME /home 
RUN cd ~ 
RUN apt-get update 
RUN apt-get install -y git nano python3-pip python-dev pkg-config wget usbutils curl
 
RUN echo "deb https://packages.cloud.google.com/apt coral-edgetpu-stable main" \ 
| tee /etc/apt/sources.list.d/coral-edgetpu.list 
RUN curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | apt-key add - 
RUN apt-get update 
RUN apt-get install -y edgetpu-examples

Ba chi tiết đáng chú ý. Image nền là debian:10 (buster) vì bản này có Python 3.7, đúng phiên bản wheel PyCoral hỗ trợ; image mới hơn dùng Python 3.11 và không cài được PyCoral. Lệnh apt-key add cũng chỉ còn chạy trên Debian cũ, nên đừng đổi image nền. Gói edgetpu-examples mang theo mô hình mẫu, file nhãn và ảnh thử.

Bước 6: Build image PyCoral

Build image bằng lệnh dưới đây. Lệnh giữ nguyên như bài gốc, chỉ thay một ký tự: bản gốc in ra dấu gạch ngang kiểu chữ trước chữ t, chép vào terminal sẽ báo lỗi cú pháp, nên phải dùng dấu trừ ASCII.

sudo docker build -t "coral" .

Lần build đầu tải vài trăm MB và mất vài phút trên Pi 5, phần lớn là thời gian apt cài gói; image sau khi xong nặng khoảng 1GB. Nếu build dừng vì mạng, chạy lại lệnh build, Docker sẽ dùng lại các lớp đã tải xong.

Bước 7: Kiểm tra thiết bị và chạy container

Trước khi nghĩ tới container, kiểm tra node thiết bị mà PyCoral sẽ dùng trên máy host:

ls /dev | grep apex_0

Kết quả phải có dòng apex_0. Sau đó chạy container, truyền node thiết bị vào trong và mở shell:

sudo docker run -it --device /dev/apex_0:/dev/apex_0 coral /bin/bash

Tham số --device là điểm mấu chốt: nó ánh xạ node của máy host vào container, không có nó thì bên trong container không có thiết bị nào để suy luận. -it giữ phiên tương tác để gõ lệnh. Đây là container dùng một lần, thoát ra là mất, nên kết quả cần giữ phải chép ra ngoài hoặc mount thư mục.

Bước 8: Chạy ví dụ phân loại ảnh

Trong shell của container, chạy ví dụ phân loại ảnh có sẵn:

python3 /usr/share/edgetpu/examples/classify_image.py \
--model /usr/share/edgetpu/examples/models/mobilenet_v2_1.0_224_inat_bird_quant_edgetpu.tflite \
--label /usr/share/edgetpu/examples/models/inat_bird_labels.txt \
--image /usr/share/edgetpu/examples/images/bird.bmp

Lệnh này đưa ảnh con chim mẫu qua mô hình MobileNet v2 đã lượng tử hoá và biên dịch cho Edge TPU. Kết quả mong đợi:

--------------------------- 
Poecile atricapillus (Black-capped Chickadee) 
Score :  0.44140625 
--------------------------- 
Poecile carolinensis (Carolina Chickadee) 
Score :  0.29296875

Con số Score do PyCoral trả về là xác suất của mô hình, không phải độ tin cậy của thiết bị: 0.44 nghĩa là mô hình cho rằng ảnh giống chim Chickadee đầu đen 44%. Hai loài trong ví dụ trông giống nhau với mắt người nên điểm thấp là bình thường. Lệnh chạy xong mà không lỗi nghĩa là chuỗi từ kernel tới PyCoral đã thông. Thoát container bằng CTRL+D.

Coral TPU nhanh đến mức nào

Điểm mạnh của Coral không nằm ở việc chạy mô hình lớn, mà ở chi phí điện và độ trễ. Một ảnh 224×224 qua MobileNet v2 lượng tử hoá mất vài mili giây trên TPU, còn cùng mô hình đó chạy trên 4 nhân CPU của Pi 5 mất hàng chục mili giây. Với 5 khung hình mỗi giây từ vài camera, TPU gần như rảnh.

Giới hạn cần biết trước khi mua: Edge TPU chỉ chạy mô hình đã lượng tử hoá 8-bit và biên dịch bằng trình biên dịch của Coral; mô hình float32 tải vào sẽ báo lỗi ngay khi khởi tạo, không phải chạy chậm. Nó cũng không huấn luyện được và không chạy mô hình ngôn ngữ lớn. Với phân loại ảnh và phát hiện vật thể thì quá đủ.

Xử lý sự cố thường gặp

Bảng dưới đây gom các lỗi đã gặp khi dựng PyCoral trên Pi 5, xếp theo thứ tự từ phần cứng lên tới ứng dụng:

Hiện tượng	Nguyên nhân	Cách xử lý
`uname -a` vẫn ra kernel 16KB page, hậu tố `v8+` hoặc `2712`	Chưa thêm `kernel=kernel8.img`, hoặc sửa nhầm `/boot/config.txt` trên Bookworm	Sửa `/boot/firmware/config.txt`, khởi động lại, kiểm tra lại hậu tố `-v8`
`lspci` không thấy Coral	Cáp FPC lỏng, HAT không nhận PCIe, hoặc thiếu overlay	Cắm lại cáp, kiểm tra `dtoverlay` của đúng HAT, xem thêm `lspci -nn`
Firmware báo không tìm thấy overlay pineboards-hat-ai	Firmware đang chạy không có file .dtbo đó	Kiểm tra `ls /boot/firmware/overlays`, đổi sang overlay của HAT bạn dùng
Không có `/dev/apex_0` dù `lspci` thấy thiết bị	Thiếu driver gasket/apex, hoặc kernel sai kích thước trang	Cài lại driver theo bước 3, xem `dmesg \| grep -i apex`
Container báo không mở được `/dev/apex_0`	Quên tham số `--device` khi `docker run`	Thêm `--device /dev/apex_0:/dev/apex_0`
`pip install pycoral` báo không có bản phù hợp	Python 3.11 trên Bookworm, wheel chỉ có tới 3.9	Dùng container Debian 10 như bài, đừng cài trực tiếp lên máy
`docker build` báo unknown shorthand flag	Dấu gạch ngang kiểu chữ trong lệnh gốc	Gõ lại bằng dấu trừ ASCII: `docker build -t "coral" .`
Ví dụ báo lỗi định dạng mô hình	Mô hình chưa lượng tử hoá hoặc chưa biên dịch cho Edge TPU	Dùng file `*_edgetpu.tflite`, không dùng .tflite thường

Ứng dụng thực tế

Ứng dụng phổ biến nhất của cấu hình này là Frigate NVR: Coral làm bộ phát hiện vật thể, Pi 5 lo giải mã luồng camera và ghi hình. Container PyCoral trong bài là môi trường để thử mô hình và đo tốc độ trước khi đưa vào Frigate, vì Frigate có image riêng và khai báo detector theo kiểu edgetpu với thiết bị pci. Bài Cài Frigate NVR trên Raspberry Pi 5 với Google Coral TPU đã có cấu hình mẫu dùng đúng node vừa tạo ở bước 3.

Ngoài camera an ninh, cùng bộ phần cứng đó còn dùng cho: đếm sản phẩm trên băng tải, phân loại ảnh nông sản ngay tại vườn khi không có mạng, đọc đồng hồ công tơ bằng cách phát hiện vùng số rồi cắt ảnh cho mô hình nhỏ, và lọc ảnh trước khi gửi lên cloud. Nguyên tắc chung là để TPU phát hiện, logic nghiệp vụ viết bằng Python trên CPU. Nếu camera là camera IP thông thường, xem bài Hướng dẫn dùng hai camera trên Raspberry Pi 5 để chọn cáp và cổng MIPI.

Nếu cần nhận diện khuôn mặt hoặc nhiều vật thể trong khung hình lớn, cân nhắc Raspberry Pi AI HAT+ 26 TOPS hoặc Hailo-8L: hai module này chạy được mô hình nặng hơn nhiều, nhưng driver và API khác hoàn toàn, Frigate khai báo theo kiểu hailo8l. Với camera IP thông thường, Coral vẫn là mức giá dễ chịu nhất.

Một chi tiết vận hành: nếu gắn Coral qua HAT có thêm khe NVMe, hãy nhớ cả hai dùng chung một làn PCIe x1, nên ghi đĩa nặng trong lúc suy luận có thể làm chậm cả hai. Cách an toàn là để hệ điều hành trên thẻ nhớ và dùng NVMe cho dữ liệu ghi hình.

Ba điểm cần nhớ khi cài PyCoral trên Raspberry Pi 5: kernel phải là bản 4KB page, node /dev/apex_0 phải tồn tại trước khi chạy container, và PyCoral phải nằm trong userspace Python 3.7 chứ không phải Python 3.11 của Bookworm. Làm đúng ba việc đó thì phần còn lại chỉ là những lệnh Docker quen thuộc, và PyCoral sẽ chạy ổn định qua nhiều lần khởi động lại.

Nếu đang tìm phần cứng thay thế vì Coral đã ngừng sản xuất, hãy cân nhắc giữa mua Coral cũ với giá hợp lý và chuyển sang Hailo-8L: Coral nhẹ điện, chín về driver, PyCoral có tài liệu sẵn và được cộng đồng Frigate hỗ trợ lâu năm; Hailo mạnh hơn nhưng tài liệu tiếng Việt còn ít.

Nguồn: The Pi Hut