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

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

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

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

У багатьох сучасних сценаріях дані вже не є лише структурованим текстом чи числами. Особливо з розвитком AI та машинного навчання, дані часто подаються як багатовимірні вектори, також відомі як "embeddings". Такі вектори "захоплюють" семантичну інформацію або характеристики — наприклад, візуальні ознаки зображень, сенс тексту чи вподобання користувача.

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

Передумови

Перш ніж почати працювати з pgvector, переконайтеся, що виконані такі умови:

1. Встановлено та запущено ServBay на macOS.
2. У списку «Пакети» (Packages) ServBay активовано пакет PostgreSQL. Якщо він не увімкнений, знайдіть PostgreSQL в інтерфейсі ServBay і перемкніть у статус «Увімкнено».

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

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

Послідовність дій для включення pgvector у БД PostgreSQL:

1. Підключення до бази PostgreSQL: Використайте інструмент командного рядка psql для підключення до PostgreSQL, який надає ServBay. Зазвичай конфігурація дозволяє локальне підключення, типовий користувач — postgres або servbay, порт за замовчуванням 5432. Якщо у вас інші налаштування — звіртеся з документацією ServBay.

   Відкрийте термінал і виконайте команду (замість значень підставте свої дані):

   psql -U servbay -d your_database_name -h localhost -p 5432

   • -U servbay: вказує користувача (або використайте postgres).
   • -d your_database_name: ім'я вашої бази. Якщо її не створено — створіть (наприклад: CREATE DATABASE servbay_demo_db;).
   • -h localhost: локальний сервер.
   • -p 5432: порт PostgreSQL (типово у ServBay).

2. Створення розширення vector: Після підключення до бази виконайте у консолі psql таку SQL-команду для активації розширення:

   CREATE EXTENSION vector;

   Якщо розширення вже існує, з'явиться відповідне повідомлення.

3. Перевірка встановлення: Переконайтеся, що pgvector успішно активовано, перелічивши встановлені розширення:

   \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)

   (Зверніть увагу: номер версії може різнитися залежно від версії pgvector, що інтегрована у ваш ServBay)

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

Після активації розширення pgvector можна створювати й управляти векторними даними у вашій базі.

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

Спочатку створіть таблицю для зберігання ваших векторів. pgvector надає новий тип даних VECTOR(dimensions), де dimensions — кількість вимірів.

Приклад створення таблиці embeddings для зберігання 3-вимірних векторів:

CREATE TABLE embeddings (
    id SERIAL PRIMARY KEY,
    -- Визначення 3-вимірного векторного стовпця
    vector VECTOR(3)
);

Тепер можна додати кілька прикладів векторів:

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 (Inverted File Index з Flat-компресією): добре підходить для більших датасетів із невисокими вимогами до повноти (recall). Швидше створюється.
• HNSW (Hierarchical Navigable Small World): зазвичай забезпечує кращу точність і швидший пошук, але індексація довша й потребує більше пам’яті.

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

1. IVFFlat-індекс:

   -- Перед створенням IVFFlat-індексу бажано виконати ANALYZE для збору статистики
   ANALYZE embeddings;
   
   -- Створення IVFFlat-індексу
   -- WITH (lists = 100): задає кількість інвертованих списків. Регулюйте залежно від обсягу даних.
   -- Чим більший lists, тим повільніше індексація, але більша точність.
   -- Рекомендується lists = sqrt(кількості рядків).
   CREATE INDEX idx_ivfflat_vector ON embeddings USING ivfflat (vector) WITH (lists = 100);

2. HNSW-індекс:

   -- Створення HNSW-індексу
   -- WITH (m = 16, ef_construction = 200): параметри HNSW-індексу.
   -- m: макс. кількість звʼязків на вузол. Впливає на зʼєднаність, ефективність, пам’ять.
   -- ef_construction: діапазон пошуку при побудові. Впливає на швидкість/пам’ять та якість (recall).
   -- Параметри треба підбирати експериментально під свої задачі.
   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), пов’язаний із косинусною подібністю; вимірює схожість напряму.
• <=>: косинусна відстань (1 - косинусна подібність). Враховує напрямок вектора, ігноруючи його довжину.

Приклади поширених векторних запитів:

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

Знаходимо вектори, найближчі за відстанню до заданого (тобто найбільш схожі). Потрібно використати ORDER BY з оператором відстані й обмежити результат через LIMIT.

1. Знайти 5 векторів із таблиці, найближчих за L2-відстанню до [0.2, 0.3, 0.4]:

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

Пошук схожих векторів (Similarity Search)

Аналогічно до попереднього, але з акцентом на показі оцінки схожості.

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

   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), щоб спроєктувати дані у 2D/3D-простір.

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

1. Підготовка Python-середовища: Налаштуйте Python у чи поза межами ServBay. Якщо використовується Python із ServBay, переконайтеся, що він активний. Встановіть бібліотеки psycopg2 і matplotlib:

   # Якщо використовуєте системний або власноруч встановлений Python
   pip install psycopg2 matplotlib
   
   # Для пакета Python у ServBay — через його pip
   # /Applications/ServBay/软件包/python/bin/pip install psycopg2 matplotlib

   Уточнюйте шлях pip залежно від вашого середовища.

2. Створіть Python-скрипт: Збережіть наступний код у файлі (наприклад, visualize_vectors.py). Обов'язково змініть параметри підключення (dbname, user, password, host, port) згідно вашого середовища ServBay.

   import psycopg2
   import matplotlib.pyplot as plt
   from mpl_toolkits.mplot3d import Axes3D # Імпортуємо модуль для 3D-скатерплоту
   
   # Параметри підключення до БД — відкоригуйте під свою конфігурацію ServBay
   db_params = {
       "dbname": "your_database_name", # Назва вашої БД
       "user": "servbay",              # Ім’я користувача ServBay (зазвичай servbay або postgres)
       "password": "",                 # Пароль БД (для локального підключення може бути порожнім)
       "host": "localhost",            # Сервер зазвичай localhost
       "port": "5432"                  # Порт за замовчуванням
   }
   
   conn = None
   cur = None
   
   try:
       # Підключення до бази PostgreSQL
       conn = psycopg2.connect(**db_params)
       cur = conn.cursor()
   
       # Запит на отримання векторних даних
       # Примітка: psycopg2 читає тип vector як рядок '[x, y, z]'.
       # Необхідно вручну розпарсити строку або скористатися новішими можливостями бібліотеки.
       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()
   
       # Витягуємо координати
       # Припускаємо, що всі вектори 3-вимірні
       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-скатерплоту
       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()

3. Запуск скрипту: Запустіть скрипт із терміналу:

   python visualize_vectors.py

   Скрипт під'єднається до вашої БД PostgreSQL, отримає вектори і побудує 3D-графік у вікні через Matplotlib.

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

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

Висновок

pgvector додає до зрілої та стабільної СУБД PostgreSQL потужні можливості векторної бази даних, полегшуючи локальну розробку AI- і data-driven застосунків. Завдяки інтеграції в ServBay розширення ще простіше активувати у локальному середовищі.

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