Công cụ hỗ trợ

Hướng dẫn build FAISS GPU v1.12.0 trên Ubuntu 24.04 (CUDA + Python 3.12)

22/12/2025
Lê Hoàng Hưng
No Comments

Bài viết này hướng dẫn build FAISS GPU v1.12.0 trên Ubuntu 24.04.3 với CUDA và Python 3.12, không dùng Conda, phù hợp cho hệ thống AI production.

Mục lục

  1. Tổng quan FAISS GPU
  2. Cài đặt
  3. Lỗi thường gặp & cách khắc phục
  4. FAQ – Câu hỏi thường gặp

1. Tổng quan FAISS GPU

FAISS (Facebook AI Similarity Search) là thư viện tối ưu cho tìm kiếm vector.
Phiên bản GPU tận dụng CUDA để tăng tốc các tác vụ similarity search.

FAISS CPU vs FAISS GPU – Nên dùng loại nào?

Tiêu chí FAISS CPU FAISS GPU
Phần cứng Chỉ CPU NVIDIA GPU + CUDA
Tốc độ Trung bình Nhanh hơn 5–50 lần
Dataset lớn Không tối ưu Rất phù hợp
Use case Demo, dataset nhỏ Face recognition, OCR, Vector DB
✔ Dataset < 100k vector → FAISS CPU đủ dùng
✔ Dataset lớn, realtime → FAISS GPU là lựa chọn bắt buộc

Yêu cầu hệ thống

  • Ubuntu 24.04.3
  • NVIDIA Driver
  • CUDA Toolkit 12.x/13.x (Trong bài viết chúng tôi sử dụng phiên bản 13.1)
  • Python 3.12.x (Có sẵn trong ubuntu 24.04)
  • SWIG ≥ 4.2.0

2. Cài đặt

Cài đặt dependencies

sudo apt update
sudo apt install -y build-essential cmake git \
libopenblas-dev liblapack-dev python3-dev \
python3-pip python3-venv swig

Clone FAISS v1.12.0

cd /var
git clone https://github.com/facebookresearch/faiss.git faiss
cd faiss
git checkout v1.12.0

Tạo Python Virtual Environment

python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install numpy

Cấu hình build với CMake

mkdir build && cd build
cmake .. -DFAISS_ENABLE_GPU=ON -DFAISS_ENABLE_PYTHON=ON \
-DBUILD_TESTING=OFF -DCMAKE_BUILD_TYPE=Release

Build & Install FAISS

make -j$(nproc)
sudo make install
sudo ldconfig

Cài Python bindings

cd faiss/python
pip install .

Kiểm tra FAISS GPU

3. Các lỗi thường gặp & cách khắc phục

Bảng dưới đây tổng hợp các lỗi phổ biến khi build FAISS GPU v1.12.0 trên Ubuntu 24.04.3, kèm theo nguyên nhân thường gặp và hướng xử lý được khuyến nghị.

Lỗi / Triệu chứng Nguyên nhân khả dĩ Hướng khắc phục
Không thấy dòng Found CUDA khi chạy CMake CUDA Toolkit chưa được cài đúng cách hoặc
nvcc không nằm trong PATH.
  • Kiểm tra CUDA bằng nvcc --version.
  • Đảm bảo đã cài CUDA Toolkit 12.x/13.x phù hợp với driver.
  • Thêm CUDA vào PATH và LD_LIBRARY_PATH,
    sau đó chạy lại CMake.
Lỗi liên quan SWIG hoặc thông báo swig not found SWIG chưa được cài hoặc phiên bản quá cũ
(FAISS yêu cầu SWIG ≥ 4.2.0).
  • Kiểm tra phiên bản bằng swig -version.
  • Cài hoặc nâng cấp SWIG bằng
    sudo apt install swig
    hoặc build từ source nếu cần.
Lỗi fatal error: cblas.h: No such file or directory Thiếu thư viện BLAS/LAPACK dành cho development.
  • Cài libopenblas-dev và liblapack-dev.
  • Chạy lại cmake .. rồi make.
Permission denied khi chạy pip install . Không sử dụng virtual environment hoặc
chạy pip với sudo.
  • Không dùng sudo pip.
  • Kích hoạt lại venv bằng source venv/bin/activate.
  • Chạy lại pip install . trong thư mục
    faiss/python.
ModuleNotFoundError: No module named 'faiss' Đang chạy Python không thuộc virtual environment đã cài FAISS hoặc dùng sai phiên bản Python.
  • Kiểm tra which python trong venv.
  • Kiểm tra gói bằng pip show faiss hoặc pip show faiss-gpu.
  • Luôn kích hoạt venv trước khi chạy script.
Number of GPUs: 0 dù máy có GPU Driver NVIDIA hoặc CUDA không nhận GPU,
hoặc GPU chưa được pass-through trong container/VM.
  • Kiểm tra GPU bằng nvidia-smi.
  • Nếu dùng Docker, chạy container với --gpus all.
  • Đảm bảo driver NVIDIA và CUDA tương thích.
Lỗi liên quan Python version không khớp Build FAISS bằng một phiên bản Python
nhưng chạy bằng phiên bản khác.
  • Đảm bảo toàn bộ quá trình build và run
    dùng cùng Python 3.12.x.
  • Sử dụng venv để tránh nhầm lẫn môi trường.
Lời khuyên:
Nếu gặp lỗi khó xác định, hãy xóa toàn bộ thư mục build/ và thực hiện lại quá trình build từ đầu theo đúng thứ tự trong bài.

4. FAQ – Câu hỏi thường gặp khi build FAISS GPU

1. FAISS GPU có chạy được nếu không có NVIDIA GPU không?

Không. FAISS GPU bắt buộc cần GPU NVIDIA và CUDA. Nếu máy không có GPU, bạn chỉ có thể dùng FAISS CPU.

2. FAISS GPU có hỗ trợ Python 3.12 không?

Có. Từ phiên bản FAISS 1.12.0, Python 3.12 được hỗ trợ chính thức và hoạt động ổn định trên Ubuntu 24.04.

3. Có nên dùng Conda để cài FAISS GPU?

Không khuyến khích trong môi trường production. Conda thường gây xung đột CUDA, driver và Python system. Hướng dẫn trong bài dùng venv + system CUDA là cách ổn định nhất.

4. Vì sao import faiss nhưng get_num_gpus() trả về 0?

Nguyên nhân phổ biến:

  • Build thiếu -DFAISS_ENABLE_GPU=ON
  • CUDA không đúng version
  • Python binding cài từ wheel CPU-only

Giải pháp: Xóa thư mục build/ và build lại toàn bộ từ đầu.

5. FAISS GPU nhanh hơn CPU bao nhiêu lần?

Tùy index và dataset, nhưng trong thực tế:

  • Flat index: nhanh hơn ~10–20 lần
  • IVF / PQ index: nhanh hơn ~5–50 lần

Chúc các bạn thành công!

Leave a Reply