Cài đặt extension pgvector trên PostgreSQL
Phương pháp 1: Cài đặt từ APT Repository (Khuyên dùng cho Ubuntu 24.04)
Phương pháp này nhanh nhất và ổn định nhất trên Ubuntu 24.04 vì pgvector đã được đóng gói sẵn trong repository chính thức của PostgreSQL.
Tại sao: Tránh việc biên dịch từ nguồn gây phức tạp với các dependency C++ và quản lý gói.
Kết quả mong đợi: Package pgvector được cài đặt vào thư mục module của PostgreSQL.
Trước tiên, cập nhật danh sách gói và cài đặt package pgvector tương ứng với phiên bản PostgreSQL bạn đã cài đặt trong Phần 2 (giả sử là PostgreSQL 16).
sudo apt update
sudo apt install postgresql-16-pgvector
Nếu bạn đang dùng phiên bản khác (ví dụ PostgreSQL 15), thay đổi số 16 thành 15 trong tên package.
Kiểm tra package đã được cài đặt:
dpkg -l | grep pgvector
Kết quả mong đợi: Xuất hiện dòng ii postgresql-16-pgvector trong danh sách, xác nhận thư viện đã có mặt trong hệ thống.
Phương pháp 2: Biên dịch từ nguồn (Source Code)
Dành cho trường hợp repository APT không có gói tương thích hoặc bạn cần phiên bản dev mới nhất chưa được đóng gói.
Tại sao: Cần khi muốn tùy chỉnh code hoặc dùng tính năng mới nhất mà package APT chưa cập nhật.
Kết quả mong đợi: File vector.so được biên dịch và copy vào thư mục share/contrib của PostgreSQL.
Trước hết, cài đặt các công cụ build cần thiết (build-essential, git, cmake) nếu chưa có.
sudo apt install -y build-essential git cmake postgresql-server-dev-16
Clone repository pgvector từ GitHub chính thức.
git clone https://github.com/pgvector/pgvector.git
cd pgvector
Tạo thư mục build và chạy cmake để chuẩn bị cấu hình, sau đó chạy make để biên dịch.
mkdir build && cd build
cmake ..
make
Copy file module vector.so vào thư mục extension của PostgreSQL. Đường dẫn mặc định thường là /usr/lib/postgresql/16/lib/.
sudo make install
Verify bằng cách kiểm tra file so có tồn tại trong thư mục lib.
ls -l /usr/lib/postgresql/16/lib/vector.so
Kết quả mong đợi: File vector.so xuất hiện với quyền đọc cho user postgres.
Kích hoạt extension trong Database
Đăng nhập vào PostgreSQL và tạo extension
Sau khi cài đặt gói, extension chưa được kích hoạt trong database cụ thể nào. Bạn cần chạy lệnh SQL để tạo schema và objects.
Tại sao: PostgreSQL sử dụng cơ chế "lazy loading" cho extension; extension chỉ tồn tại khi được tạo (CREATE EXTENSION) trong database.
Kết quả mong đợi: Extension pgvector xuất hiện trong danh sách extensions của database.
Đăng nhập vào shell của PostgreSQL với user postgres.
sudo -u postgres psql
Chuyển đến database bạn muốn sử dụng (ví dụ: ai_demo). Nếu chưa có, hãy tạo mới.
CREATE DATABASE ai_demo;
\c ai_demo
Thực thi lệnh tạo extension. Lệnh này sẽ load file vector.so và chạy script khởi tạo.
CREATE EXTENSION vector;
Verify extension đã được tạo thành công.
\dx
Kết quả mong đợi: Trong bảng danh sách extension, bạn thấy dòng vector với version (ví dụ: 0.6.0).
Khắc sự cố "could not load library" (Nếu gặp)
Nếu lệnh CREATE EXTENSION báo lỗi ERROR: could not load library "vector", thường do đường dẫn shared_preload_libraries hoặc quyền truy cập file .so.
Tại sao: PostgreSQL không tìm thấy file thư viện trong thư mục shared_preload_libraries hoặc quyền file bị sai.
Kết quả mong đợi: PostgreSQL có thể tìm và load được file vector.so.
Kiểm tra lại đường dẫn thư mục extension trong postgresql.conf.
sudo nano /etc/postgresql/16/main/postgresql.conf
Đảm bảo tham số shared_preload_libraries (nếu có) hoặc load_path bao gồm đúng thư mục lib. Tuy nhiên với pgvector, thường chỉ cần file nằm đúng chỗ là được. Kiểm tra quyền file:
sudo chown postgres:postgres /usr/lib/postgresql/16/lib/vector.so
sudo chmod 644 /usr/lib/postgresql/16/lib/vector.so
Khởi động lại dịch vụ PostgreSQL để đảm bảo hệ thống nhận diện thư viện mới.
sudo systemctl restart postgresql
Lặp lại lệnh CREATE EXTENSION vector; sau khi khởi động lại.
Hiểu và Kiểm tra cấu trúc dữ liệu Vector
Tạo bảng chứa vector và dữ liệu mẫu
Bây giờ chúng ta sẽ tạo bảng thực tế để lưu trữ embeddings. pgvector sử dụng kiểu dữ liệu vector(n) trong đó n là số chiều (dimension).
Tại sao: Cần định nghĩa rõ kích thước vector để PostgreSQL tối ưu hóa không gian lưu trữ và tính toán khoảng cách.
Kết quả mong đợi: Bảng documents được tạo với cột embedding có kiểu vector.
Tạo bảng documents với 3 cột: id, content và embedding (giả sử vector 1536 chiều, phổ biến cho model text-embedding-ada-002 hoặc BGE).
CREATE TABLE documents (
id SERIAL PRIMARY KEY,
content TEXT,
embedding vector(1536)
);
Chèn dữ liệu mẫu vào bảng. Chúng ta sẽ tạo vector ngẫu nhiên để test cấu trúc.
INSERT INTO documents (content, embedding)
VALUES
('PostgreSQL là một hệ quản trị cơ sở dữ liệu mạnh mẽ', ARRAY[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0]::vector),
('Ubuntu 24.04 là bản phát hành mới nhất của Linux', ARRAY[0.5, 0.4, 0.3, 0.2, 0.1, 0.0, -0.1, -0.2, -0.3, -0.4]::vector);
Lưu ý: Trong ví dụ trên tôi dùng ARRAY để tạo vector ngắn (10 chiều) cho dễ nhìn, nhưng trong thực tế LlamaIndex sẽ điền 1536 giá trị float.
Thực hiện tìm kiếm tương tự (Similarity Search)
pgvector cung cấp các toán tử so sánh khoảng cách: ->> (L2 distance), <-> (Inner product), <#> (Cosine distance).
Tại sao: Để xác minh pgvector có thể tính toán khoảng cách giữa các vector và trả về kết quả theo thứ tự.
Kết quả mong đợi: Query trả về dòng có vector gần nhất với vector query theo thứ tự khoảng cách tăng dần.
Thực hiện truy vấn tìm kiếm vector gần nhất với một vector query mẫu (dùng khoảng cách Cosine <#>).
SELECT content, embedding '[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0]' AS distance
FROM documents
ORDER BY embedding '[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0]'
LIMIT 5;
Kiểm tra kết quả: Dòng đầu tiên phải là 'PostgreSQL là một hệ quản trị...' với khoảng cách distance gần bằng 0.
Tối ưu hóa với chỉ mục HNSW (Tùy chọn nhưng quan trọng)
Đối với dữ liệu lớn, tìm kiếm tuyến tính sẽ rất chậm. pgvector hỗ trợ chỉ mục HNSW (Hierarchical Navigable Small World) để tăng tốc độ tìm kiếm.
Tại sao: HNSW giảm độ phức tạp từ O(N) xuống O(log N), cần thiết khi dataset có hàng triệu vector.
Kết quả mong đợi: Chỉ mục hnsw_idx được tạo và query tìm kiếm chạy nhanh hơn.
Tạo chỉ mục HNSW cho cột embedding sử dụng metric cosine.
CREATE INDEX hnsw_idx ON documents USING hnsw (embedding vector_cosine_ops);
Verify chỉ mục đã được tạo.
\d+ documents
Kết quả mong đợi: Trong phần Indexes của bảng, xuất hiện dòng hnsw_idx.
Chạy lại query tìm kiếm ở trên, PostgreSQL sẽ tự động sử dụng chỉ mục này (có thể kiểm tra bằng lệnh EXPLAIN ANALYZE).
EXPLAIN ANALYZE
SELECT content
FROM documents
ORDER BY embedding '[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1.0]'
LIMIT 1;
Kiểm tra kết quả: Trong output, dòng Index Scan using hnsw_idx thay vì Seq Scan.
Điều hướng series:
Mục lục: Series: Triển khai Database AI với pgvector, LlamaIndex và Ubuntu 24.04
« Phần 2: Cài đặt và cấu hình PostgreSQL trên Ubuntu 24.04
Phần 4: Cài đặt Python, LlamaIndex và các thư viện hỗ trợ »