ServBay 中使用 pgvector PostgreSQL 擴充套件指南

pgvector 是 PostgreSQL 資料庫一個功能強大的第三方擴充套件，為 PostgreSQL 增加了向量資料型態以及高效的向量索引方法，如 IVFFlat 和 HNSW。這讓 PostgreSQL 能夠原生支援向量儲存與相似度搜尋，是建構 AI 應用、推薦系統、影像辨識和自然語言處理等需處理高維向量資料的理想選擇。

作為整合型在地 Web 開發環境，ServBay 已預先整合 PostgreSQL 與 pgvector 擴充套件，大幅簡化在本機開發環境啟用和使用向量資料庫的流程。本文將詳解如何在 ServBay 中運用 pgvector。

什麼是 pgvector？它有何重要性？

在許多現代應用場景下，資料早已不只是結構化文字和數值。隨著人工智慧與機器學習發展，資料經常以高維向量（即“embeddings”）方式呈現，捕捉了資料的語意或特徵，例如圖片的視覺特徵、文字的含義，或是用戶的偏好。

pgvector 擴充讓 PostgreSQL 能直接儲存這些向量，並執行高效率的向量相似度搜尋（即最近鄰搜尋）。這代表您能用熟悉的 SQL 語言直接查找與目標向量最相似的資料項目，無需將向量資料儲存於獨立向量資料庫，進一步簡化技術架構。

前置條件

開始使用 pgvector 前，請確保您符合以下條件：

已於 macOS 上安裝並啟動 ServBay。
已於 ServBay 的「套件」（Packages）列表中啟用 PostgreSQL 套件。若尚未啟用，請於 ServBay 介面中找到 PostgreSQL，並將其狀態設為「已啟用」。

在 ServBay 的 PostgreSQL 啟用 pgvector 擴充套件

ServBay 已將 pgvector 擴充檔案預載於 PostgreSQL 安裝路徑，不需手動下載或編譯。您只需於需要用到 pgvector 的資料庫內啟用即可。

以下是在 ServBay 的 PostgreSQL 資料庫啟用 pgvector 的步驟：

連線至 PostgreSQL 資料庫：您可以使用 psql 命令行工具連接至 ServBay 提供的 PostgreSQL 執行個體。ServBay 所安裝的 PostgreSQL 通常允許本地連線，預設用戶名可能為 postgres 或 servbay，預設埠號為 5432。若您的 ServBay 配置有異，請查閱 ServBay 資料庫設定說明。
打開終端機，執行下列指令（請依實際情況調整用戶名與資料庫名稱）：
bash
```
psql -U servbay -d your_database_name -h localhost -p 5432
```
1
- -U servbay: 指定用戶名為 servbay（或 postgres）。
- -d your_database_name: 指定欲連接的資料庫名稱。若資料庫不存在，請先建立（例如 CREATE DATABASE servbay_demo_db;）。
- -h localhost: 指定主機為本機。
- -p 5432: 指定埠號為 5432（ServBay PostgreSQL 預設埠）。
建立 vector 擴充套件：連線成功後，在 psql 提示符下執行以下 SQL 指令，以啟用 pgvector 擴充：
sql
```
CREATE EXTENSION vector;
```
1
若擴充已存在，系統可能會提示其已存在。

驗證安裝：您可列出所有已安裝的擴充套件，以確認 pgvector 是否成功啟用：

sql

\dx

在輸出清單中應能看到名為 vector 的擴充及其版本資訊。

                           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)

（注意：版本號可能因 ServBay 整合的 pgvector 版本而有所不同）

設定與使用 pgvector

啟用 pgvector 擴充後，即可在資料庫內建立及管理向量資料。

建立含向量資料的資料表

首先需建立資料表以存放您的向量資料。pgvector 提供新型態 VECTOR(dimensions)，其中 dimensions 為向量維度。

以下範例建立名為 embeddings 的資料表，用以存放 3 維向量：

sql

CREATE TABLE embeddings (
    id SERIAL PRIMARY KEY,
    -- 定義一個 3 維向量欄位
    vector VECTOR(3)
);

可插入一些範例向量資料：

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]'); -- 可加入更多資料，便於後續查詢示範更明顯

注意：向量值需以中括號 [] 包裹，元素之間以逗號分隔。

建立向量索引提升查詢效能

若資料表儲存大量向量資料，建立索引對向量相似度搜尋效能極為關鍵。pgvector 支援 IVFFlat 與 HNSW 兩種主要索引類型。選用何種索引取決於您的需求（如查詢速度、索引建置時間、記憶體用量、召回率等）。

IVFFlat（倒排索引加 Flat 壓縮）：適合資料量大且召回率要求不那麼高的狀況，索引建立速度較快。
HNSW（分層可導航小世界圖）：通常提供更高召回率及更快查詢，但建索引較慢且記憶體用量較高。

下方為在 embeddings 資料表上，針對 vector 欄位分別建立 IVFFlat 與 HNSW 索引的示例：

建立 IVFFlat 索引：

sql

-- 建立 IVFFlat 索引前建議先執行 ANALYZE 收集統計資訊
ANALYZE embeddings;

-- 建立 IVFFlat 索引
-- WITH (lists = 100)：指定倒排清單數量。建議依資料量調整。
-- lists 愈多，建立較慢，查詢時需掃描的清單較多（可能變慢），但召回率較佳。
-- 官方建議 lists = sqrt(資料筆數)。
CREATE INDEX idx_ivfflat_vector ON embeddings USING ivfflat (vector) WITH (lists = 100);

建立 HNSW 索引：

sql

-- 建立 HNSW 索引
-- WITH (m = 16, ef_construction = 200): HNSW 索引相關參數。
-- m：每個節點最大連接數，影響索引連通性、查詢效能與記憶體。
-- ef_construction：建索引時使用的搜尋範圍，影響建索引時間、記憶體及最終召回率。
-- 參數建議依實際資料和效能需求調校。
CREATE INDEX idx_hnsw_vector ON embeddings USING hnsw (vector) WITH (m = 16, ef_construction = 200);

注意：索引參數（如 lists、m、ef_construction）會顯著影響索引效能與召回率。選擇適合數值需視您的資料與查詢模式，建議多實驗。可參考 pgvector 官方文件以獲得更詳細參數說明與調校建議。

利用 pgvector 進行向量查詢

pgvector 提供多種運算元以計算向量間距離，支援相似度查詢。常用距離運算元包括：

<->：L2 距離（歐式距離），常用於計算向量間直線距離。
<#>：內積（Inner Product），和餘弦相似度相關，常用於評估方向相似性。
<=>：餘弦距離（Cosine Distance），即 1 - 餘弦相似度，衡量向量方向的近似性，與向量長度無關。

以下是幾種常見的向量查詢範例：

最近鄰查詢（Nearest Neighbor Search）

尋找與指定查詢向量距離最近（最相似）的前幾筆資料。通常使用 ORDER BY 搭配距離運算元，並以 LIMIT 限制結果數。

查詢與向量 [0.2, 0.3, 0.4] L2 距離最近的前 5 筆資料：

sql

SELECT
    id,
    vector,
    -- 計算與查詢向量的 L2 距離
    vector <-> '[0.2, 0.3, 0.4]' AS distance
FROM
    embeddings
ORDER BY
    distance -- 距離由小到大排序（愈小愈相近）
LIMIT 5;

向量相似度查詢（Similarity Search）

與最近鄰查詢類似，但更著重於呈現相似度分數。

查詢與向量 [0.2, 0.3, 0.4] 餘弦距離最近的前 5 筆資料，並顯示距離：

sql

SELECT
    id,
    vector,
    -- 計算與查詢向量的餘弦距離
    vector <=> '[0.2, 0.3, 0.4]' AS cosine_distance
FROM
    embeddings
ORDER BY
    cosine_distance -- 距離由小到大排序（愈小愈相似）
LIMIT 5;

向量資料視覺化（可選）

將高維向量資料視覺化，可幫助理解資料分布與聚類狀況。針對 2D 或 3D 向量，可直接繪製散點圖；高維向量則多使用降維技術（如 PCA、t-SNE）先投影到 2D 或 3D，方能視覺化。

此處提供利用 Python 與 Matplotlib 套件視覺化 3 維向量的簡易範例。

準備 Python 環境：您可於 ServBay 環境內外各自建立 Python 環境。如使用 ServBay 提供的 Python 套件，請確認已啟用。須安裝 PostgreSQL 連線套件 psycopg2 與繪圖套件 matplotlib：
bash
```
# 若用系統預設 Python 或自行安裝版本
pip install psycopg2 matplotlib

# 若用 ServBay 的 Python，需用 ServBay 提供的命令列工具或直接走其 bin 目錄下的 pip
# /Applications/ServBay/套件/python/bin/pip install psycopg2 matplotlib
```
1
2
3
4
5
請依您的 Python 路徑調整 pip 指令。

建立 Python 腳本：建立一 .py 檔（例如 visualize_vectors.py），複製下列程式。連線參數（dbname, user, password, host, port）請依您的 ServBay PostgreSQL 設定調整。

python

import psycopg2
import matplotlib.pyplot as plt
from mpl_toolkits.mplot3d import Axes3D # 匯入繪製 3D 散點圖的模組

# 資料庫連線參數－請依您的 ServBay 設定修改
db_params = {
    "dbname": "your_database_name", # 請更換為您的資料庫名稱
    "user": "servbay",              # 請更換為 ServBay PostgreSQL 用戶名（通常為 servbay 或 postgres）
    "password": "",                 # 請更換為您的資料庫密碼（本地連線可為空）
    "host": "localhost",            # ServBay PostgreSQL 通常運行在 localhost
    "port": "5432"                  # ServBay PostgreSQL 的預設埠
}

conn = None
cur = None

try:
    # 連線到 PostgreSQL 資料庫
    conn = psycopg2.connect(**db_params)
    cur = conn.cursor()

    # 查詢向量資料
    # 注意：psycopg2 預設會將 vector 型態的 '[x, y, z]' 讀為字串
    # 需自行解析，或仰賴新版 pgvector 與 psycopg2 驅動協助自動轉換
    # 這裡假設讀到的是字串，並進行簡易解析
    cur.execute("SELECT vector FROM embeddings")
    vectors_raw = cur.fetchall()

    # 字串轉數值清單
    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("未查詢到向量資料。")
        exit()

    # 取得向量座標
    # 確認所有向量為三維，否則無法繪 3D 圖
    if any(len(v) != 3 for v in vectors):
         print("警告：向量維度不一致或非 3 維，無法繪製 3D 圖。")
         # 可選擇畫 2D 或直接離開
         exit()


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

    # 繪製 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"資料庫連線或查詢錯誤: {e}")
except Exception as e:
    print(f"發生錯誤: {e}")
finally:
    # 關閉資料庫連線
    if cur:
        cur.close()
    if conn:
        conn.close()

執行腳本：於終端執行 Python 腳本：
bash
```
python visualize_vectors.py
```
1
腳本將連到 PostgreSQL，讀取向量資料，並用 Matplotlib 顯示 3D 散點圖。

常見問題（FAQ）

問：\\dx 輸出沒有看到 vector 擴充怎麼辦？ 答：請先確認已正確執行 CREATE EXTENSION vector; 且未報錯。若未見，請檢查您的 ServBay PostgreSQL 套件是否安裝與啟用，pgvector 應出現在 PostgreSQL 的 share/extension 子目錄。如果檔案遺失，建議重新安裝或更新 ServBay 的 PostgreSQL 套件。
問：連接資料庫時認證失敗怎麼辦？ 答：請確認您在 psql 命令或 Python 腳本用的用戶名、密碼、主機與埠號，是否與 ServBay 的 PostgreSQL 設定相符。對本地連線，ServBay 通常預設用戶為 servbay 或 postgres，且可能未設密碼。
問：向量索引參數 lists、m、ef_construction 該如何挑選？ 答：這些參數會顯著影響查詢效能與召回率，並無一套通用最佳值。通常需根據資料量、向量維度、查詢延遲與召回目標進行多次實驗調適。官方文件既有詳細建議，請參閱 pgvector 官方文檔。

總結

pgvector 將強大向量資料庫能力引入 PostgreSQL，讓開發者能輕鬆在本地開發 AI 與向量應用。ServBay 預載 pgvector 擴充，進一步簡化環境建置。

依本指南，您可於 ServBay PostgreSQL 輕鬆啟用 pgvector，建立向量資料表、善用高效索引加速查詢，並執行多樣化向量相似度搜尋。配合 ServBay 其他開發工具，您將能更高效地打造、測試現代 Web 應用與資料密集型計畫。

ServBay 中使用 pgvector PostgreSQL 擴充套件指南 ​

什麼是 pgvector？它有何重要性？ ​

前置條件 ​

在 ServBay 的 PostgreSQL 啟用 pgvector 擴充套件 ​

設定與使用 pgvector ​

建立含向量資料的資料表 ​

建立向量索引提升查詢效能 ​

利用 pgvector 進行向量查詢 ​

最近鄰查詢（Nearest Neighbor Search） ​

向量相似度查詢（Similarity Search） ​

向量資料視覺化（可選） ​

常見問題（FAQ） ​

總結 ​