Vấn đề
Bạn khởi chạy một Docker container để huấn luyện mô hình, nhưng script của bạn bị lỗi ngay lập tức. Thay vì các log huấn luyện như mong đợi, bạn thấy một thông báo lỗi cụ thể:
ImportError: libcuda.so.1: cannot open shared object file: No such file or directory
Điều này xảy ra khi các thư viện Python như PyTorch hoặc TensorFlow cố gắng giao tiếp với GPU nhưng thất bại. Mặc dù máy chủ (host) của bạn có thể đã cài đặt driver NVIDIA mới nhất, nhưng các Docker container được thiết kế để cô lập. Chúng không thể nhìn thấy phần cứng GPU hoặc các file driver của máy chủ trừ khi bạn thiết lập cầu nối một cách rõ ràng.
Tại sao lỗi này xảy ra
File libcuda.so.1 là giao diện cốt lõi cho driver NVIDIA. Không giống như các thư viện CUDA (như libcudnn) mà bạn có thể tích hợp sẵn vào Docker image, thư viện driver phải nằm trên hệ điều hành máy chủ. Nếu bạn không yêu cầu Docker ánh xạ các driver máy chủ này vào container, các ứng dụng AI của bạn sẽ không thể nhận diện được phần cứng.
Các bước khắc phục
Bước 1: Kiểm tra Driver trên máy chủ
Đầu tiên, hãy xác nhận rằng máy chủ của bạn nhận diện được GPU. Chạy lệnh này trong terminal chính:
nvidia-smi
Bạn sẽ thấy một bảng hiển thị model GPU (ví dụ: RTX 4090 hoặc A100) và phiên bản driver (ví dụ: 535.129.03). Nếu lệnh này thất bại, bạn phải cài đặt driver NVIDIA trên máy chủ trước khi tiếp tục thiết lập Docker.
Bước 2: Cài đặt NVIDIA Container Toolkit
Các bản cài đặt Docker tiêu chuẩn không hỗ trợ GPU. Bạn cần NVIDIA Container Toolkit để cho phép container truy cập vào file libcuda.so.1 của máy chủ. Làm theo các bước sau cho Ubuntu hoặc Debian:
# Thêm kho lưu trữ gói
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
&& curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
sudo tee /etc/stderr/apt/sources.list.d/nvidia-container-toolkit.list
# Cài đặt bộ công cụ
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
# Khởi động lại Docker daemon để áp dụng runtime mới
sudo systemctl restart docker
Bước 3: Khởi chạy Docker với quyền truy cập GPU
Cài đặt bộ công cụ là chưa đủ; bạn phải kích hoạt nó khi khởi chạy container. Sử dụng flag --gpus all để chuyển driver vào. Hãy thử lệnh kiểm tra này:
docker run --rm --gpus all nvidia/cuda:12.0-base-ubuntu22.04 nvidia-smi
Nếu bạn thích sử dụng docker-compose, hãy đảm bảo file yaml của bạn bao gồm phần deploy. Điều này bắt buộc đối với Docker Compose phiên bản 1.28.0 trở lên:
services:
ai-app:
image: pytorch/pytorch:2.1.0-cuda12.1-cudnn8-runtime
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: all
capabilities: [gpu]
Bước 4: Thiết lập các biến Capability
Trong một số trường hợp đặc biệt, container vẫn không "nhìn thấy" các thư viện driver. Bạn có thể ép buộc ánh xạ bằng cách thêm các biến môi trường sau vào Dockerfile hoặc lệnh chạy:
NVIDIA_VISIBLE_DEVICES=allNVIDIA_DRIVER_CAPABILITIES=compute,utility
Xác minh kết quả
Để chắc chắn 100% rằng thư viện đã được ánh xạ, hãy chạy một trình kiểm tra Python nhanh trong môi trường container:
docker run --rm --gpus all python:3.10-slim python3 -c "import ctypes; print(ctypes.util.find_library('cuda'))"
Nếu kết quả trả về là libcuda.so.1, thiết lập của bạn đã chính xác. Nếu kết quả là None, driver vẫn chưa được chuyển qua đúng cách.
Đối với người dùng PyTorch, đây là bài kiểm tra cuối cùng:
python3 -c "import torch; print(torch.cuda.is_available())"
Kết quả True có nghĩa là lỗi ImportError của bạn đã chính thức được khắc phục.
Kinh nghiệm thực tế
Việc quản lý các phiên bản driver trên các máy chủ khác nhau có thể trở nên phức tạp. Khi tôi tải xuống các bản driver cụ thể hoặc script thiết lập cho môi trường production, tôi thường sử dụng Hash Generator của ToolCraft để xác minh tính toàn vẹn SHA-256 của chúng. Điều này giúp ngăn ngừa các vấn đề do tải xuống bị lỗi hoặc file không khớp trong quá trình triển khai.
Một mẹo cuối cùng: hãy chú ý đến tính tương thích của phiên bản. Phiên bản driver trên máy chủ phải bằng hoặc cao hơn phiên bản CUDA mà container yêu cầu. Nếu máy chủ của bạn có Driver 510 (CUDA 11.6), nhưng container yêu cầu CUDA 12.0, bạn có thể sẽ gặp lại lỗi libcuda.so.1 lần nữa.