Руководство по использованию расширения pgvector в ServBay для PostgreSQL

pgvector — это мощное стороннее расширение для базы данных PostgreSQL, которое добавляет поддержку векторного типа данных и эффективных векторных индексов, таких как IVFFlat и HNSW. Благодаря этому PostgreSQL может нативно работать с хранением векторов и поиском по схожести, что делает его отличным выбором при создании AI-приложений, рекомендательных систем, систем распознавания изображений и обработки естественного языка, где требуется работа с высокоразмерными векторными данными.

ServBay — это интегрированная локальная среда веб-разработки, уже включающая в себя PostgreSQL и расширение pgvector, что значительно упрощает активацию и работу с векторной БД в вашем окружении. В этой статье подробно описывается, как использовать pgvector в ServBay.

Что такое pgvector и почему это важно?

Во многих современных приложениях данные уже не ограничиваются только структурированным текстом и числами. Особенно с ростом популярности искусственного интеллекта и машинного обучения данные часто представлены в виде высокоразмерных векторов — «embeddings». Такие векторы отражают семантическую информацию и особенности данных: визуальные характеристики изображений, смысл текста, предпочтения пользователей и др.

Расширение pgvector позволяет PostgreSQL напрямую хранить такие векторы и выполнять быстрый поиск по схожести векторов («поиск ближайших соседей»). Это значит, что вы можете привычным языком SQL искать наиболее похожие на заданный вектор записи, без необходимости хранения данных в отдельной векторной базе, что упрощает архитектуру.

Предварительные требования

Перед началом работы с pgvector убедитесь, что выполнены следующие условия:

1. Установлен и запущен ServBay на macOS.
2. В списке «Пакеты» (Packages) в ServBay активирован пакет PostgreSQL. Если PostgreSQL еще не включён, откройте интерфейс приложения ServBay, найдите PostgreSQL и установите его статус как «Включено».

Активация расширения pgvector в PostgreSQL, установленном через ServBay

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

Пошаговая инструкция по включению pgvector в PostgreSQL под ServBay:

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: порт 5432 (стандартный для PostgreSQL в ServBay).

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

   CREATE EXTENSION vector;

   Если расширение уже создано, появится уведомление об этом.

3. Проверьте успешную установку: Для проверки, успешно ли включено расширение, выведите список расширений:

   \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 (обратный файловый индекс с flat-компрессией): Хорошо подходит для больших данных, где умеренно важна полнота поиска. Быстро строится.
• HNSW (иерархический граф): Обычно обеспечивает более высокое качество поиска и скорость, но может дольше строиться и требовать больше памяти.

Примеры создания индексов по столбцу 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: ширина поиска при построении индекса (влияет на качество, память, время построения)
   -- Параметры стоит подбирать под реальные данные и задачи
   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)

Находит топ-N самых схожих с заданным вектором (наименьшее расстояние) с помощью ORDER BY + оператор расстояния + LIMIT.

1. Поиск 5 ближайших к вектору [0.2, 0.3, 0.4] по L2-расстоянию:

   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-графиков. Для векторов большой размерности потребуется сначала понизить размерность (PCA, t-SNE и др.), а затем строить график.

Ниже — пример быстрой визуализации 3-мерных векторов с помощью Python и Matplotlib.

1. Подготовьте Python-окружение: Вы можете настроить Python как вне среды ServBay, так и внутри неё. Если используете системный или свой Python, установите библиотеки psycopg2 для подключения PostgreSQL и 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 scatter-графика
   
   # Параметры подключения к БД — подставьте свои значения!
   db_params = {
       "dbname": "your_database_name", # Ваше имя БД
       "user": "servbay",              # Ваш пользователь PostgreSQL (чаще всего servbay или postgres)
       "password": "",                 # Пароль, если есть (для локали часто не требуется)
       "host": "localhost",            # Обычно ServBay PostgreSQL работает на localhost
       "port": "5432"                  # Стандартный порт для PostgreSQL в ServBay
   }
   
   conn = None
   cur = None
   
   try:
       # Соединение с PostgreSQL
       conn = psycopg2.connect(**db_params)
       cur = conn.cursor()
   
       # Получение векторов из таблицы
       # Внимание: psycopg2 зачастую возвращает вектор, как строку '[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()
   
       # Проверка размера векторов
       if any(len(v) != 3 for v in vectors):
           print("Ошибка: размерность векторов не 3 — визуализация не выполнена.")
           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('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()

3. Запустите скрипт: В терминале выполните команду:

   python visualize_vectors.py

   Скрипт подключится к вашей БД PostgreSQL, скачает данные и откроет окно с 3D scatter-графиком векторов.

Часто задаваемые вопросы (FAQ)

• Вопрос: Расширение vector не отображается в выводе \dx. Что делать? Ответ: Сначала убедитесь, что вы выполняли команду CREATE EXTENSION vector; и ошибок не было. Если расширения всё ещё нет — проверьте, правильно ли установлен и включён пакет PostgreSQL в ServBay. Файлы pgvector должны быть в каталоге share/extension вашей установки PostgreSQL. Если их нет — попробуйте переустановить или обновить пакет PostgreSQL в ServBay.
• Вопрос: При подключении к базе возникает ошибка аутентификации. Ответ: Проверьте, совпадают ли имя пользователя, пароль, имя хоста и порт в ваших командах psql или скриптах Python с настройками PostgreSQL в ServBay. Для локальных соединений пользователь часто servbay или postgres, пароль может не требоваться.
• Вопрос: Как выбрать параметры индексации lists, m, ef_construction? Ответ: Эти параметры существенно влияют на производительность и полноту поиска. Универсального значения нет — экспериментируйте, исходя из объёма и размерности данных, требований по скорости запроса и точности. Подробные рекомендации есть в документации pgvector.

Заключение

pgvector добавляет полноценную векторную функциональность в стабильную, зрелую систему PostgreSQL, открывая разработчикам новые возможности для быстрого и удобного прототипирования AI и прочих векторных приложений локально. ServBay, включающий предустановленный pgvector, делает старт ещё проще.

С помощью данного руководства вы сможете быстро включить и настроить pgvector в PostgreSQL под ServBay, создать таблицы для хранения векторов, использовать эффективные индексы для ускорения поиска и реализовать различные варианты поиска по схожести между векторами. В комбинации с другими инструментами и средой разработки от ServBay — вы легко развернёте современные веб-проекты и анализ данных прямо на своём Mac.