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

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

ServBay 做為一款整合式本機 Web 開發環境，已預載了 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 的資料庫設定說明。
開啟終端機，使用以下命令連線（請依實際帳號及資料庫命名調整）：
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 的資料表，用於儲存三維向量：

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（倒排檔索引搭配平面壓縮）：適合大規模資料但召回率要求較低場景。建立速度較快。
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;

向量資料視覺化（選用）

將高維向量資料視覺化，有助理解資料分布與聚集。對於二維或三維向量可直接繪製散點圖；更高維向量可藉降維技術（如 PCA 或 t-SNE）投影至二／三維再視覺化。

以下示例以 Python 及 Matplotlib 庫，圖示 3 維向量資料。

準備 Python 環境：您可於 ServBay 內／外部建立 Python 環境。如使用 ServBay 提供之 Python 套件，請先啟用。並需安裝 PostgreSQL 連線庫 psycopg2 與繪圖庫 matplotlib：
bash
```
# 若使用系統預設或自行安裝的 Python
pip install psycopg2 matplotlib

# 若用 ServBay 之 Python，可能需使用 ServBay 的工具或直接於 bin 路徑安裝
# /Applications/ServBay/套件/python/bin/pip install psycopg2 matplotlib
```
1
2
3
4
5
請依您的 Python 路徑調整 pip 命令。

建立 Python 腳本：建立 Python 檔（如 visualize_vectors.py），複製以下程式碼。請依你的 ServBay PostgreSQL 設定修改連線參數（dbname, user, password, host, port）。

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:
        # 移除中括號，逗號分隔，轉 float
        vec_str = row[0].strip('[]')
        coords = [float(c) for c in vec_str.split(',')]
        vectors.append(coords)

    if not vectors:
        print("無向量資料查詢結果。")
        exit()

    # 提取向量各座標
    # 確保皆為 3 維，此處假設為 3 維
    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 向量視覺化')

    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）

問：vector 擴充套件未出現在 \dx 輸出怎麼辦？ 答：請先確認已正確執行 CREATE EXTENSION vector; 命令且無錯誤訊息。如仍無法顯示，請檢查 ServBay PostgreSQL 套件是否安裝並啟用，pgvector 擴充檔案應處於 PostgreSQL 的 share/extension 子目錄下。若檔案遺失，建議重新安裝或更新 ServBay 的 PostgreSQL 套件。
問：連線資料庫時顯示認證失敗怎辦？ 答：請確認 psql 命令或 Python 程式用到的使用者、密碼、主機及埠號與 ServBay PostgreSQL 設定一致。本機連線時，預設使用者多為 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） ​

結論 ​