Hướng dẫn sử dụng tiện ích mở rộng pgvector với PostgreSQL trong ServBay

pgvector là một tiện ích mở rộng mạnh mẽ bên thứ ba cho PostgreSQL, bổ sung kiểu dữ liệu vector cùng các phương pháp lập chỉ mục vector hiệu quả như IVFFlat và HNSW. Điều này giúp PostgreSQL hỗ trợ lưu trữ vector và truy vấn tương đồng vector một cách nguyên bản - lý tưởng để xây dựng các ứng dụng AI, hệ thống gợi ý, nhận diện hình ảnh hay xử lý ngôn ngữ tự nhiên, nơi cần xử lý dữ liệu vector có số chiều lớn.

ServBay là môi trường phát triển Web tích hợp tại local, đã được cài sẵn PostgreSQL cùng tiện ích mở rộng pgvector, giúp đơn giản hóa việc sử dụng cơ sở dữ liệu vector ngay trên máy của bạn. Bài viết này sẽ hướng dẫn chi tiết các bước sử dụng pgvector trong ServBay.

pgvector là gì và tại sao nó quan trọng?

Ở nhiều ứng dụng hiện đại, dữ liệu không chỉ giới hạn ở văn bản hoặc số dạng bảng mà còn được biểu diễn dưới dạng vector nhiều chiều, gọi là “embeddings”. Các vector này nắm bắt thông tin đặc trưng hoặc ý nghĩa của dữ liệu như đặc trưng hình ảnh, ý nghĩa văn bản hay sở thích của người dùng.

Tiện ích mở rộng pgvector giúp PostgreSQL lưu trữ trực tiếp các vector này và thực hiện các truy vấn tìm kiếm tương tự vector (thường gọi là “tìm kiếm lân cận gần nhất”). Nhờ đó, bạn có thể sử dụng ngôn ngữ SQL quen thuộc để truy vấn những dữ liệu tương đồng mà không cần triển khai thêm một hệ quản trị cơ sở dữ liệu vector riêng, đơn giản hóa kiến trúc kỹ thuật của bạn.

Điều kiện tiên quyết

Để bắt đầu sử dụng pgvector, hãy đảm bảo bạn đã đáp ứng các điều kiện sau:

Đã cài đặt và chạy ServBay trên macOS.
Gói PostgreSQL đã được bật trong danh sách “Packages” của ServBay. Nếu chưa bật, hãy mở giao diện ServBay và chuyển trạng thái của PostgreSQL thành “Enabled”.

Kích hoạt tiện ích mở rộng pgvector trong PostgreSQL của ServBay

ServBay đã tích hợp sẵn file tiện ích mở rộng pgvector vào thư mục cài đặt PostgreSQL, nên bạn không cần tải hoặc biên dịch thủ công. Bạn chỉ cần kích hoạt nó trong cơ sở dữ liệu mong muốn.

Các bước bật pgvector trong PostgreSQL trên ServBay như sau:

Kết nối đến cơ sở dữ liệu PostgreSQL: Bạn có thể dùng công cụ dòng lệnh psql để kết nối đến PostgreSQL do ServBay cung cấp. Cấu hình mặc định của PostgreSQL trong ServBay thường cho phép kết nối local, với user mặc định là postgres hoặc servbay và cổng mặc định là 5432. Nếu cài đặt của bạn khác, hãy kiểm tra hướng dẫn cấu hình cơ sở dữ liệu của ServBay.
Mở Terminal và dùng lệnh sau (điều chỉnh tên user và database theo thực tế):
bash
```
psql -U servbay -d your_database_name -h localhost -p 5432
```
1
- -U servbay: Chỉ định user, thường là servbay hoặc postgres.
- -d your_database_name: Tên database muốn kết nối. Nếu database chưa tồn tại, bạn cần tạo trước (ví dụ: CREATE DATABASE servbay_demo_db;).
- -h localhost: Kết nối đến máy local.
- -p 5432: Sử dụng cổng mặc định 5432 cho PostgreSQL ServBay.
Tạo extension vector: Sau khi kết nối thành công, tại prompt của psql, chạy lệnh SQL sau để bật tiện ích mở rộng pgvector:
sql
```
CREATE EXTENSION vector;
```
1
Nếu extension đã tồn tại, hệ thống sẽ báo rằng đã có sẵn.

Kiểm tra cài đặt: Bạn có thể liệt kê các extension đã cài bằng lệnh:

sql

\dx

Kết quả trả về sẽ có thông tin về tiện ích mở rộng vector và phiên bản của nó.

                           List of installed extensions
   Name   | Version |   Schema   |                         Description
----------+---------+------------+--------------------------------------------------------------
 plpgsql  | 1.0     | pg_catalog | PL/pgSQL procedural language
 vector   | 0.7.0   | public     | vector data type and ivfflat and hnsw access methods
(2 rows)

(Lưu ý: số phiên bản có thể khác tùy bản ServBay bạn cài)

Cấu hình & sử dụng pgvector

Sau khi bật extension, bạn có thể tạo bảng và thao tác với dữ liệu vector.

Tạo bảng lưu trữ vector

Trước tiên, cần tạo bảng để lưu vector. pgvector bổ sung kiểu dữ liệu mới VECTOR(dimensions), trong đó dimensions là số chiều của vector.

Ví dụ tạo bảng embeddings lưu vector 3 chiều:

sql

CREATE TABLE embeddings (
    id SERIAL PRIMARY KEY,
    -- Định nghĩa một cột vector 3 chiều
    vector VECTOR(3)
);

Chèn thử một số vector mẫu:

sql

INSERT INTO embeddings (vector) VALUES
('[0.1, 0.2, 0.3]'),
('[0.4, 0.5, 0.6]'),
('[0.7, 0.8, 0.9]'),
('[0.15, 0.25, 0.35]'),
('[0.6, 0.5, 0.4]'); -- Thêm nhiều dữ liệu để truy vấn mẫu rõ ràng hơn

Lưu ý: Các giá trị vector phải đặt trong dấu ngoặc vuông [], phân tách bằng dấu phẩy.

Tạo chỉ mục vector để tăng tốc truy vấn

Với bảng có nhiều dữ liệu vector, việc tạo chỉ mục sẽ giúp tìm kiếm tương tự nhanh hơn. pgvector hỗ trợ hai loại chỉ mục diện IVFFlat và HNSW. Chọn loại chỉ mục phù hợp tùy mục đích (tốc độ, tài nguyên, độ chính xác...):

IVFFlat (Inverted File Index với nén Flat): Phù hợp dataset lớn, yêu cầu tốc độ xây dựng nhanh, chấp nhận độ recall thấp hơn chút.
HNSW (Hierarchical Navigable Small World): Đem lại recall cao và tốc độ truy vấn nhanh, bù lại tốc độ xây chỉ mục chậm hơn, tốn RAM hơn.

Ví dụ tạo chỉ mục IVFFlat và HNSW cho cột vector của bảng embeddings:

Tạo chỉ mục IVFFlat:

sql

-- Khuyến nghị: Chạy ANALYZE để thu thập thông tin thống kê trước khi tạo chỉ mục IVFFlat
ANALYZE embeddings;

-- Tạo chỉ mục IVFFlat
-- WITH (lists = 100): số lượng inverted lists, nên điều chỉnh tùy size dữ liệu
-- Chỉ số lớn -> xây chậm hơn, tốn RAM, tốc độ truy vấn và recall tăng.
-- Theo tài liệu: lists ≈ sqrt(số dòng).
CREATE INDEX idx_ivfflat_vector ON embeddings USING ivfflat (vector) WITH (lists = 100);

Tạo chỉ mục HNSW:

sql

-- Tạo chỉ mục HNSW
-- WITH (m = 16, ef_construction = 200): thông số cho chỉ mục HNSW.
-- m: số kết nối tối đa/mỗi node, ảnh hưởng tốc truy vấn & RAM.
-- ef_construction: phạm vi tìm kiếm khi xây chỉ mục, ảnh hưởng RAM/thời gian xây và recall.
-- Điều chỉnh tùy thực tế dataset/hiệu năng yêu cầu.
CREATE INDEX idx_hnsw_vector ON embeddings USING hnsw (vector) WITH (m = 16, ef_construction = 200);

Lưu ý: Các tham số chỉ mục như lists, m, ef_construction ảnh hưởng lớn đến tốc độ - độ chính xác, nên cần kiểm thử, tối ưu tùy dataset và nhu cầu. Đọc thêm trong tài liệu chính thức pgvector để tối ưu hóa.

Truy vấn dữ liệu với pgvector

pgvector cung cấp nhiều toán tử để tính toán khoảng cách/hệ số tương đồng giữa các vector:

<->: Khoảng cách L2 (Euclidean). Đo khoảng cách thẳng giữa hai vector.
<#>: Tích trong (Inner Product) - liên quan đến độ tương đồng cosine, dùng so sánh hướng vector.
<=>: Khoảng cách cosine (1 - độ tương đồng cosine). Dùng đo tính giống nhau về hướng (không phụ thuộc độ lớn vector).

Một số truy vấn phổ biến với vector:

Truy vấn lân cận gần nhất (Nearest Neighbor Search)

Truy xuất các vector gần (tương đồng nhất) với một vector truy vấn. Dùng ORDER BY và toán tử khoảng cách, giới hạn bằng LIMIT:

Tìm 5 vector có khoảng cách L2 nhỏ nhất với [0.2, 0.3, 0.4]:

sql

SELECT
    id,
    vector,
    -- Tính khoảng cách L2 đến vector truy vấn
    vector <-> '[0.2, 0.3, 0.4]' AS distance
FROM
    embeddings
ORDER BY
    distance -- Sắp xếp tăng dần (gần nhất đầu tiên)
LIMIT 5;

Truy vấn tương đồng vector

Tương tự lân cận gần nhất, nhưng có thể trả về điểm tương đồng:

Tìm 5 vector có khoảng cách cosine nhỏ nhất với [0.2, 0.3, 0.4] và hiển thị giá trị khoảng cách:

sql

SELECT
    id,
    vector,
    -- Tính khoảng cách cosine đến vector truy vấn
    vector <=> '[0.2, 0.3, 0.4]' AS cosine_distance
FROM
    embeddings
ORDER BY
    cosine_distance -- Tăng dần (càng gần càng giống)
LIMIT 5;

Trực quan hóa dữ liệu vector (tùy chọn)

Việc trực quan hóa dữ liệu vector nhiều chiều giúp bạn hình dung phân bố và các cụm dữ liệu. Với vector 2D/3D, có thể vẽ trực tiếp scatter plot. Với dữ liệu nhiều chiều hơn, cần giảm số chiều (PCA, t-SNE) trước khi vẽ.

Ví dụ sử dụng Python cùng Matplotlib để trực quan hóa dữ liệu vector 3D:

Chuẩn bị môi trường Python: Bạn có thể dùng Python bên ngoài hoặc tích hợp trong ServBay. Nếu dùng Python của ServBay, hãy bật package Python. Cài thư viện PostgreSQL psycopg2 và vẽ biểu đồ matplotlib:
bash
```
# Nếu dùng Python cài riêng hoặc mặc định của macOS
pip install psycopg2 matplotlib

# Nếu dùng Python tích hợp ServBay, dùng pip tương ứng trong thư mục bin
# /Applications/ServBay/软件包/python/bin/pip install psycopg2 matplotlib
```
1
2
3
4
5
Điều chỉnh đường dẫn pip tùy môi trường Python bạn sử dụng.

Tạo script Python: Tạo file Python tên (ví dụ: visualize_vectors.py), sao chép code sau. Chỉnh lại các thông số kết nối PostgreSQL (dbname, user, password, host, port):

python

import psycopg2
import matplotlib.pyplot as plt
from mpl_toolkits.mplot3d import Axes3D # Nhập module vẽ scatter 3D

# Thông số kết nối database - thay bằng thông số ServBay của bạn
db_params = {
    "dbname": "your_database_name", # Tên database của bạn
    "user": "servbay",              # User PostgreSQL ServBay (servbay hoặc postgres)
    "password": "",                 # Mật khẩu DB (có thể rỗng nếu kết nối local)
    "host": "localhost",            # PostgreSQL chạy local
    "port": "5432"                  # Cổng mặc định
}

conn = None
cur = None

try:
    # Kết nối PostgreSQL
    conn = psycopg2.connect(**db_params)
    cur = conn.cursor()

    # Truy vấn dữ liệu vector
    # Lưu ý: psycopg2 mặc định sẽ đọc kiểu vector thành chuỗi '[x, y, z]'
    # Cần tự phân tích hoặc dùng phiên bản psycopg2/pgvector mới để tự động hóa
    # Ở đây giả sử đọc được chuỗi và parse thủ công
    cur.execute("SELECT vector FROM embeddings")
    vectors_raw = cur.fetchall()

    # Phân tích chuỗi vector về dạng danh sách số
    vectors = []
    for row in vectors_raw:
        vec_str = row[0].strip('[]')
        coords = [float(c) for c in vec_str.split(',')]
        vectors.append(coords)

    if not vectors:
        print("Không tìm thấy dữ liệu vector.")
        exit()

    # Kiểm tra toàn bộ vector 3 chiều
    if any(len(v) != 3 for v in vectors):
         print("Cảnh báo: Vector không đồng nhất chiều hoặc không phải 3D, không thể vẽ trực tiếp.")
         exit()

    x = [v[0] for v in vectors]
    y = [v[1] for v in vectors]
    z = [v[2] for v in vectors]

    # Vẽ scatter plot 3D
    fig = plt.figure()
    ax = fig.add_subplot(111, projection='3d')
    ax.scatter(x, y, z)

    ax.set_xlabel('Dimension 1')
    ax.set_ylabel('Dimension 2')
    ax.set_zlabel('Dimension 3')
    ax.set_title('3D Vector Visualization')

    plt.show()

except psycopg2.Error as e:
    print(f"Lỗi kết nối hoặc truy vấn database: {e}")
except Exception as e:
    print(f"Đã xảy ra lỗi: {e}")
finally:
    # Đóng kết nối database
    if cur:
        cur.close()
    if conn:
        conn.close()

Chạy script: Chạy script Python từ terminal:
bash
```
python visualize_vectors.py
```
1
Script sẽ kết nối tới PostgreSQL, đọc dữ liệu vector và vẽ scatter plot 3D bằng Matplotlib.

Câu hỏi thường gặp (FAQ)

Hỏi: Tôi không thấy extension vector khi dùng lệnh \dx thì phải làm sao? Đáp: Đầu tiên đảm bảo bạn đã chạy lệnh CREATE EXTENSION vector; và không gặp lỗi. Nếu chưa được, kiểm tra gói PostgreSQL của ServBay đã cài đúng và đã bật hay chưa. File tiện ích mở rộng pgvector nằm trong thư mục share/extension của PostgreSQL. Nếu file bị thiếu, hãy cài lại hoặc cập nhật gói PostgreSQL của ServBay.
Hỏi: Khi kết nối database bị báo lỗi xác thực, làm thế nào xử lý? Đáp: Kiểm tra username, password, host và port trong lệnh psql hoặc trong script Python của bạn đã khớp với cấu hình của ServBay chưa. Kết nối local thường dùng user servbay hoặc postgres và có thể không yêu cầu mật khẩu.
Hỏi: Chỉ mục vector các tham số như lists, m, ef_construction chọn thế nào? Đáp: Các tham số này ảnh hưởng lớn đến hiệu năng - khả năng truy xuất của hệ thống, không có giá trị cố định tốt nhất. Hãy thử nghiệm và tối ưu dựa trên số lượng dữ liệu, số chiều, yêu cầu độ trễ và độ chính xác mong muốn. Xem hướng dẫn chi tiết trong tài liệu chính thức pgvector.

Tổng kết

pgvector đưa sức mạnh của vector database vào hệ quản trị PostgreSQL ổn định và phổ biến, giúp lập trình viên dễ dàng phát triển các ứng dụng AI, tìm kiếm vector ngay trong môi trường local. ServBay đã cài đặt sẵn pgvector, tối ưu hóa quá trình setup cho bạn.

Làm theo chỉ dẫn trong bài viết, bạn sẽ dễ dàng bật pgvector trên PostgreSQL của ServBay, tạo bảng vector, tối ưu hóa truy vấn với chỉ mục, thực hiện các tìm kiếm tương đồng vector... Kết hợp các công cụ phát triển khác có sẵn trên ServBay, bạn hoàn toàn chủ động xây dựng – thử nghiệm dự án Web và AI hiện đại, đậm chất hiệu quả ngay trên máy tính cá nhân.

Hướng dẫn sử dụng tiện ích mở rộng pgvector với PostgreSQL trong ServBay ​

pgvector là gì và tại sao nó quan trọng? ​

Điều kiện tiên quyết ​

Kích hoạt tiện ích mở rộng pgvector trong PostgreSQL của ServBay ​

Cấu hình & sử dụng pgvector ​

Tạo bảng lưu trữ vector ​

Tạo chỉ mục vector để tăng tốc truy vấn ​

Truy vấn dữ liệu với pgvector ​

Truy vấn lân cận gần nhất (Nearest Neighbor Search) ​

Truy vấn tương đồng vector ​

Trực quan hóa dữ liệu vector (tùy chọn) ​

Câu hỏi thường gặp (FAQ) ​

Tổng kết ​