Посібник з використання розширення pgvector PostgreSQL у ServBay

pgvector — це потужне стороннє розширення для бази даних PostgreSQL, яке додає тип даних «вектор» та високоефективні методи індексації векторів, такі як IVFFlat і HNSW. Завдяки цьому PostgreSQL може нативно зберігати вектори та виконувати пошук схожих векторів, що робить його ідеальним вибором для побудови AI-додатків, рекомендованих систем, розпізнавання зображень та обробки природної мови, де необхідна робота з багатовимірними векторами.

ServBay — інтегроване локальне веб-середовище розробки, в якому вже встановлено PostgreSQL і розширення pgvector. Це значно спрощує роботу з векторними базами даних у локальному середовищі розробника. У цьому матеріалі ви знайдете докладні інструкції щодо того, як використовувати pgvector у ServBay.

Що таке pgvector і чому це важливо?

У багатьох сучасних застосуваннях дані вже не обмежуються структурованими текстом та числами. З розвитком штучного інтелекту та машинного навчання дані часто подаються у вигляді багатовимірних векторів, також відомих як embeddings. Вектори відображають семантичну інформацію або ознаки: наприклад, візуальні характеристики зображень, сенс тексту чи уподобання користувачів.

Розширення pgvector дозволяє PostgreSQL безпосередньо зберігати ці вектори та ефективно виконувати пошук схожості між ними (також відомий як "пошук найближчих сусідів"). Це означає, що для пошуку схожих елементів достатньо стандартного SQL, не потрібно використовувати окрему векторну базу даних. Технічний стек стає простішим.

Попередні вимоги

Перед початком роботи з pgvector, переконайтеся, що виконані наступні умови:

ServBay вже встановлено та запущено на macOS.
У списку "Packages" (Пакети) ServBay активовано пакет PostgreSQL. Якщо він ще не увімкнений — знайдіть PostgreSQL в інтерфейсі ServBay і увімкніть його.

Активація розширення pgvector у PostgreSQL в ServBay

ServBay завчасно встановлює файли розширення pgvector у каталозі встановлення PostgreSQL. Вам не потрібно завантажувати чи компілювати їх вручну — достатньо активувати розширення в потрібній базі даних.

Дотримуйтесь наступних кроків для активації pgvector в PostgreSQL ServBay:

Підключення до бази даних PostgreSQL: Використайте командний рядок psql для підключення до інстансу PostgreSQL, що встановлений у ServBay. Типова конфігурація дозволяє локальні підключення, користувач — часто 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: порт PostgreSQL (типово у ServBay — 5432).
Створення розширення vector: Після успішного підключення в консолі psql виконайте SQL-команду для активації розширення:
sql
```
CREATE EXTENSION vector;
```
1
Якщо розширення вже активоване, команда повідомить про це.
Перевірка встановлення: Для перевірки, що pgvector активовано — перегляньте встановлені розширення:
sql
```
\dx
```
1
У результатах має відображатися розширення 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)
```
1
2
3
4
5
6
(Примітка: номер версії залежить від інтеграції pgvector у вашій версії ServBay)

Налаштування та використання 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 (Hierarchical Navigable Small World): Зазвичай дає вищу якість та швидший пошук, але створюється довше й споживає більше пам’яті.

Як створити обидва індекси для колонки vector таблиці embeddings:

Створення індексу IVFFlat:

sql

-- Перед цим рекомендовано оновити статистику таблиці через 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: обсяг пошуку при побудові (впливає на час і якість індексу)
-- Параметри підбираються під дані та цілі — читайте документацію pgvector
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.

Знайти 5 векторів із найменшою L2-відстанню до [0.2, 0.3, 0.4]:

sql

SELECT
    id,
    vector,
    -- Обчислення L2-відстані до запитуваного вектора
    vector <-> '[0.2, 0.3, 0.4]' AS distance
FROM
    embeddings
ORDER BY
    distance -- Зростаюче (чим менше — тим схожіше)
LIMIT 5;

Пошук за схожістю (Similarity Search)

Схоже на попередній, але часто показується оцінка схожості.

Знайти 5 векторів із найменшою косинусною (cosine) відстанню до [0.2, 0.3, 0.4]:

sql

SELECT
    id,
    vector,
    -- Обчислення косинусної відстані до запитуваного
    vector <=> '[0.2, 0.3, 0.4]' AS cosine_distance
FROM
    embeddings
ORDER BY
    cosine_distance -- Зростаюче (менше — схожіше)
LIMIT 5;

Візуалізація векторних даних (опціонально)

Візуалізація багатовимірних даних корисна для аналізу їх розподілу та кластеризації. Для 2D/3D-векторів можна будувати scatter plot, а для високовимірних застосовуються проекції через PCA або t-SNE.

Нижче — приклад простої 3D-візуалізації за допомогою Python і Matplotlib.

Налаштування Python-середовища: Виконайте інсталяцію Python (у межах чи поза ServBay). Якщо ви використовуєте Python із ServBay, переконайтеся, що він активований. Додатково установіть бібліотеку для роботи з PostgreSQL (psycopg2) та візуалізації (matplotlib):
bash
```
# Стандартне встановлення через pip
pip install psycopg2 matplotlib

# Якщо використовуєте Python із ServBay, можливо, потрібно запускати pip із каталогу bin
# /Applications/ServBay/软件包/python/bin/pip install psycopg2 matplotlib
```
1
2
3
4
5
Актуалізуйте команду pip залежно від шляху до вашого Python.

Створення Python-скрипту: Створіть файл, наприклад 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-графіку

# Параметри підключення до бази даних — змініть відповідно до ваших налаштувань
db_params = {
    "dbname": "your_database_name", # Ваша база даних
    "user": "servbay",              # Користувач PostgreSQL (зазвичай servbay або postgres)
    "password": "",                 # Пароль (локально може бути пустим)
    "host": "localhost",            # PostgreSQL у ServBay типово на localhost
    "port": "5432"                  # Типовий порт ServBay PostgreSQL
}

conn = None
cur = None

try:
    # Підключення до бази даних
    conn = psycopg2.connect(**db_params)
    cur = conn.cursor()

    # Запит на вибірку векторів
    # psycopg2 читає тип vector як рядок, потрібно парсити в ручну
    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("Попередження: Вектори мають неоднаковий розмір або не 3D — неможливо побудувати графік.")
         exit()


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

    # Побудова 3D scatter plot
    fig = plt.figure()
    ax = fig.add_subplot(111, projection='3d')
    ax.scatter(x, y, z)

    ax.set_xlabel('Вимір 1')
    ax.set_ylabel('Вимір 2')
    ax.set_zlabel('Вимір 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()

Запуск скрипту: Виконайте у терміналі:
bash
```
python visualize_vectors.py
```
1
Скрипт підключиться до PostgreSQL, завантажить векторні дані та згенерує вікно з 3D-графіком через Matplotlib.

Часті питання (FAQ)

П: Не бачу розширення vector у виході команди \dx. Що робити? В: Переконайтеся, що виконали команду CREATE EXTENSION vector; й вона не згенерувала помилки. Якщо результат не змінився, перевірте, що пакет PostgreSQL у ServBay встановлений і активований. Файли розширення pgvector повинні знаходитися у підкаталозі share/extension PostgreSQL. Якщо їх немає — перевстановіть або оновіть пакет PostgreSQL.
П: Отримую помилку аутентифікації при підключенні до бази даних. Як вирішити? В: Перевірте, що всі параметри (ім'я користувача, пароль, хост, порт) у команді psql чи Python-скрипті відповідають налаштуванням ServBay. Для локальних інсталяцій користувач — зазвичай servbay чи postgres, пароль може бути порожнім.
П: Як обрати значення параметрів індексів lists, m, ef_construction? В: Ці параметри сильно впливають на швидкість і якість пошуку, універсальних рекомендацій немає. Варто експериментувати, враховуючи розмір, вимірність ваших даних, вимоги до швидкодії та точності. Рекомендується вивчити офіційну документацію pgvector.

Підсумок

pgvector додає до зрілої системи PostgreSQL потужності векторних баз даних, полегшуючи розробку AI і проєктів із векторним пошуком локально. ServBay, попередньо інтегруючи pgvector, значно спрощує налаштування середовища.

Згідно з цим посібником, ви можете легко активувати pgvector у PostgreSQL ServBay, створювати таблиці з векторами, індексувати їх для швидких запитів і виконувати пошук за схожістю. Використовуючи решту інструментів ServBay, ви зможете ефективно створювати й тестувати сучасні веб-додатки та аналітичні проєкти.

Посібник з використання розширення pgvector PostgreSQL у ServBay ​

Що таке pgvector і чому це важливо? ​

Попередні вимоги ​

Активація розширення pgvector у PostgreSQL в ServBay ​

Налаштування та використання pgvector ​

Створення таблиці з векторними даними ​

Індексація векторів для підвищення продуктивності запитів ​

Векторні запити з pgvector ​

Пошук найближчих сусідів (Nearest Neighbor Search) ​

Пошук за схожістю (Similarity Search) ​

Візуалізація векторних даних (опціонально) ​

Часті питання (FAQ) ​

Підсумок ​