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

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

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

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

В современных приложениях данные часто представлены не только в виде текстов и чисел, но и как высокоразмерные векторы (embeddings). Такие векторы отражают семантику или признаки данных — например, визуальные особенности изображения, смысл текста или предпочтения пользователей.

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

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

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

ServBay установлен и запущен на macOS.
В списке компонентов 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.
Создание расширения vector
После успешного подключения в консоли psql выполните SQL-команду для включения pgvector:
sql
```
CREATE EXTENSION vector;
```
1
Если расширение уже существует, появится соответствующее сообщение.

Проверка установки
Узнать, активировано ли расширение, можно с помощью вывода списка расширений:

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)

(Примечание: номер версии зависит от версии pgvector, интегрированной в ServBay.)

Настройка и использование 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 compression): подходит для крупных наборов данных при умеренных требованиях к качеству поиска; создается быстро.
HNSW (иерархический навигируемый малый мир): обеспечивает лучшее качество и высокую скорость поиска, но создание индекса дольше и больше потребляет памяти.

Примеры создания индексов для столбца vector в таблице embeddings:

Создание индекса 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: при построении индекса задаёт ширину поиска (search scope);
-- влияет на время и качество индекса/объем памяти.
-- Подберите параметры под ваши задачи.
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)

Поиск векторов наиболее похожих на запрос (c минимальным расстоянием). Используйте 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 ближайших по косинусной дистанции к [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-графики; для больших размерностей используют понижения размерности (PCA, t-SNE).

Пример: визуализация 3-мерных векторов с помощью Python и библиотеки Matplotlib.

Подготовка среды Python
Настройте Python-среду внутри или вне ServBay. При использовании Python через ServBay, его компонент должен быть активирован. Для подключения к PostgreSQL понадобится psycopg2, для визуализации — matplotlib:
bash
```
# Если используете системный Python или свой собственный
pip install psycopg2 matplotlib

# Если используете Python ServBay, возможно понадобится запустить pip по пути к нему:
# /Applications/ServBay/软件包/python/bin/pip install psycopg2 matplotlib
```
1
2
3
4
5
Корректируйте команду pip по пути вашей среды.

Создание скрипта Python
Создайте файл (например, visualize_vectors.py) и скопируйте код ниже. Настройте параметры подключения к базе исходя из вашей конфигурации (dbname, user, password, host, port).

python

import psycopg2
import matplotlib.pyplot as plt
from mpl_toolkits.mplot3d import Axes3D # Импорт для построения 3D scatter-графиков

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

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

    # Парсим строки векторов — преобразуем в списки float
    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-график невозможно.")
         exit()

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

    # 3D scatter-график
    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 scatter-графиком через Matplotlib.

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

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

Итоги

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

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

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

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

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

Включение расширения pgvector в PostgreSQL (ServBay) ​

Настройка и использование pgvector ​

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

Создание векторных индексов для ускорения поиска ​

Поиск по векторам с использованием pgvector ​

Поиск ближайших соседей (Nearest Neighbor Search) ​

Поиск схожих векторов (Similarity Search) ​

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

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

Итоги ​