1. Главная
  2. Хаб
  3. Сценарии
  4. Семантический поиск и RAG на PostgreSQL с pgvector

Сценарий 35

Семантический поиск и RAG на PostgreSQL с pgvector

Храним тексты и их эмбеддинги в Managed PostgreSQL, строим HNSW-индекс и ищем похожие документы одним SQL-запросом. Поисковую нагрузку уводим на реплику для чтения, чтобы она не мешала записи.

45 минСредний5 шагов PostgreSQL обновлено

Содержание
  1. 01Создайте базу с расширением vector
  2. 02Создайте таблицу и HNSW-индекс
  3. 03Загрузите документы с эмбеддингами
  4. 04Ищите похожие документы
  5. 05Уведите поиск на реплику для чтения
  6. Проверка результата
  7. Как удалить ресурсы
  8. Типичные ошибки
  9. Сколько стоит

Что получится

База kb с расширением vector, таблица документов с эмбеддингами и HNSW-индексом, скрипт на Python, который загружает тексты и ищет ближайшие к вопросу, и реплика для чтения, на которую уходят поисковые запросы.

Что понадобится

  • Аккаунт h3llo.cloud и проект.
  • Python 3.10+ и psql на вашем компьютере или сервере.
  • Модель эмбеддингов на ваш выбор: локальная (в примере — intfloat/multilingual-e5-small через sentence-transformers) или внешний API. Размерность вектора в таблице должна совпадать с размерностью модели.
  1. Шаг 1. Создайте базу с расширением vector

    HNSW-индекс живёт в памяти: чем больше векторов, тем больше RAM нужно базе. Для пробы хватит 2 vCPU и 4 ГБ.

    Консоль

    1. В меню проекта откройте Базы данных и нажмите Создать базу данных (если базы уже есть — Создать).
    2. СУБД — PostgreSQL 17.11. vCPU — 2, RAM — 4 ГБ, Диски — 20 ГБ. Имя базы данных — kb-db.
    3. Публичный IPv4 — «Вкл.», чтобы подключиться со своего компьютера. Резервное копирование — «Вкл»: без готовой копии реплику не создать.
    4. В блоке «База и владелец»: Имя базы kb, Владелец kb, Расширения — vector.
    5. Нажмите Создать базу данных.

    CLI

    Терминал
    h3 db create --name kb-db --engine postgres --version 17.11 --cpu 2 --memory 4Gi --size 20 --white-ip
    h3 db list                                   # дождитесь статуса RUNNING
    h3 db user create <db-id> --name kb --connection-limit 50
    h3 db database create <db-id> --name kb --owner kb --extensions vector
    h3 db user credentials <db-id> kb            # пароль пользователя kb

    Terraform

    Terraform
    resource "h3_database" "kb" {
      project_id = var.project_id
      name     = "kb-db"
      engine   = "postgres"
      version  = "17.11"
      cpu      = 2
      memory   = "4Gi"
      size     = "20Gi"
      white_ip = true
    }
    # пользователь и база kb с расширением vector — в консоли или через CLI:
    # в провайдере нет ресурса логической базы

    Проверка

    Статус базы — «Работает». В «Пользователи и базы» у базы kb статус «Готов» и в колонке «Расширения» — vector.

    Если не получилось

    • «Расширения ставятся в новую базу: укажите её имя» — расширение выбирается вместе с именем базы. Для встроенной базы app расширения не меняются.
  2. Шаг 2. Создайте таблицу и HNSW-индекс

    Размерность vector(384) — под модель из примера. У другой модели своя размерность: 768, 1024, 1536 и т. д.

    Индекс HNSW ищет приближённо, но быстро. Оператор <=> — косинусное расстояние, индекс должен быть построен с тем же классом операторов vector_cosine_ops.

    На вашем компьютере
    psql "host=<IP> port=5432 dbname=kb user=kb sslmode=require" <<'SQL'
    CREATE TABLE docs (
      id        bigserial PRIMARY KEY,
      source    text,
      body      text NOT NULL,
      embedding vector(384) NOT NULL
    );
    CREATE INDEX docs_embedding_hnsw ON docs USING hnsw (embedding vector_cosine_ops);
    SQL

    Проверка

    Таблица и индекс на месте:

    Терминал
    psql "host=<IP> port=5432 dbname=kb user=kb sslmode=require" -c '\d docs'

    Если не получилось

    • permission denied to create extension — вы выполнили CREATE EXTENSION вручную. Не нужно: расширение уже включила платформа, а суперпользователя у клиента нет.
  3. Шаг 3. Загрузите документы с эмбеддингами

    Скрипт режет тексты на абзацы, считает эмбеддинги и пишет их в основную базу. Модель e5 ожидает префиксы passage: для документов и query: для вопросов.

    Установка
    python3 -m venv .venv && . .venv/bin/activate
    pip install "psycopg[binary]" pgvector sentence-transformers
    export KB_RW="postgresql://kb:<пароль>@<IP основной базы>:5432/kb?sslmode=require"
    load.py
    import os, sys, pathlib
    import psycopg
    from pgvector.psycopg import register_vector
    from sentence_transformers import SentenceTransformer
    
    model = SentenceTransformer("intfloat/multilingual-e5-small")   # 384 измерения
    
    with psycopg.connect(os.environ["KB_RW"]) as conn:
        register_vector(conn)
        for path in sys.argv[1:]:
            parts = [p.strip() for p in pathlib.Path(path).read_text().split("\n\n") if p.strip()]
            vectors = model.encode([f"passage: {p}" for p in parts], normalize_embeddings=True)
            with conn.cursor() as cur:
                cur.executemany(
                    "INSERT INTO docs (source, body, embedding) VALUES (%s, %s, %s)",
                    [(path, p, v) for p, v in zip(parts, vectors)],
                )
            print(path, len(parts))
    Запуск
    python load.py docs/*.md

    Проверка

    Скрипт печатает число абзацев по каждому файлу, а в таблице появились строки:

    Терминал
    psql "$KB_RW" -c 'SELECT count(*), pg_size_pretty(pg_total_relation_size($$docs$$)) FROM docs;'
  4. Шаг 4. Ищите похожие документы

    hnsw.ef_search — сколько кандидатов просматривает индекс: больше — точнее и медленнее. По умолчанию 40.

    search.py
    import os, sys
    import psycopg
    from pgvector.psycopg import register_vector
    from sentence_transformers import SentenceTransformer
    
    model = SentenceTransformer("intfloat/multilingual-e5-small")
    q = model.encode(f"query: {sys.argv[1]}", normalize_embeddings=True)
    
    dsn = os.environ.get("KB_RO", os.environ["KB_RW"])   # реплика, если задана
    with psycopg.connect(dsn) as conn:
        register_vector(conn)
        conn.execute("SET hnsw.ef_search = 100")
        rows = conn.execute(
            "SELECT source, left(body, 120), 1 - (embedding <=> %s) AS score "
            "FROM docs ORDER BY embedding <=> %s LIMIT 5",
            (q, q),
        ).fetchall()
    for source, text, score in rows:
        print(f"{score:.3f}  {source}  {text}")
    Запуск
    python search.py "как восстановить базу на момент времени"

    Для RAG передайте найденные фрагменты в контекст языковой модели вместе с вопросом. Какую модель использовать — решаете вы: база хранит только векторы и тексты.

    Проверка

    Скрипт выводит пять фрагментов с оценкой близости. Чтобы убедиться, что работает индекс, посмотрите план — в нём должен быть Index Scan using docs_embedding_hnsw:

    Терминал
    psql "$KB_RW" -c "EXPLAIN SELECT id FROM docs ORDER BY embedding <=> (SELECT embedding FROM docs LIMIT 1) LIMIT 5;"
  5. Шаг 5. Уведите поиск на реплику для чтения

    Реплика — отдельная база только для чтения, она догоняет основную по потоку WAL. Загрузка и переиндексация идут на основной базе, поиск — на реплике. Пользователи, пароли и расширения у реплики те же, что у источника.

    Консоль

    1. Убедитесь, что в разделе «Резервные копии» базы kb-db есть хотя бы одна готовая копия (или нажмите Сделать копию сейчас).
    2. В разделе «Реплики для чтения» нажмите Создать реплику. Имя kb-ro, vCPU и RAM — как у основной, Диск, ГБ — не меньше диска основной базы, Публичный адрес — включите для пробы. Нажмите Создать.

    CLI

    Терминал
    h3 db replica create <db-id> --name kb-ro --white-ip
    h3 db replica status <replica-id>          # STREAMING и лаг в секундах

    Terraform

    Terraform
    # провайдер h3llo-cloud/h3 0.3+
    resource "h3_database" "kb_ro" {
      project_id = var.project_id
      name       = "kb-ro"
      engine     = "postgres"
      cpu        = 2
      memory     = "4Gi"
      size       = "20Gi"            # не меньше, чем у источника
      white_ip   = true
      replica_of = h3_database.kb.id # у источника должна быть готовая копия
    }
    Поиск через реплику
    export KB_RO="postgresql://kb:<пароль>@<IP реплики>:5432/kb?sslmode=require"
    python search.py "как восстановить базу на момент времени"

    Проверка

    В списке реплик у kb-ro состояние «Стриминг», в колонке «Лаг» — секунды. Запись на реплику запрещена:

    Терминал
    psql "$KB_RO" -c "INSERT INTO docs (body, embedding) SELECT body, embedding FROM docs LIMIT 1;"
    # ERROR:  cannot execute INSERT in a read-only transaction

    Если не получилось

    • «Для реплики нужны бэкапы этой базы и хотя бы одна готовая копия» — включите резервное копирование и дождитесь первой копии.
    • Долгий запрос на реплике прерывается с canceling statement due to conflict with recovery — увеличьте «Задержка применения при долгих запросах» в настройках реплики или включите «Обратная связь с основной базой (hot_standby_feedback)».

Проверка результата

Один и тот же вопрос возвращает одинаковые фрагменты с основной базы и с реплики (с поправкой на лаг). Свежий документ, загруженный в основную базу, через несколько секунд находится и на реплике.

Терминал
psql "$KB_RO" -c 'SELECT count(*) FROM docs;'
psql "$KB_RW" -c 'SELECT count(*) FROM docs;'

Как удалить ресурсы

Сначала удаляется реплика, потом источник: базу с репликами удалить нельзя («Сначала удалите или отвяжите реплики»).

CLI

Терминал
h3 db delete <replica-id> --release-eip
h3 db delete <db-id> --release-eip
  1. Базы данных → kb-ro → меню «…» → Удалить, отметьте «Освободить IP-адрес (иначе он останется в проекте)» → Подтвердить.
  2. То же для kb-db. Резервные копии удаляются вместе с базой.
  3. Проверьте IP адреса: свободные адреса продолжают оплачиваться.

Типичные ошибки

Какой индекс выбрать: HNSW или IVFFlat?

HNSW — быстрее и точнее на поиске, его можно строить на пустой таблице, но он дольше строится и занимает больше памяти. IVFFlat строится быстрее, но его нужно создавать после загрузки данных. Для большинства RAG-задач подходит HNSW.

Построение индекса на миллионах строк идёт очень долго

Выполните `SET maintenance_work_mem = '1GB'` в сессии перед `CREATE INDEX` (не больше доступной RAM) или временно увеличьте RAM базы. Индекс удобнее строить после массовой загрузки.

Можно ли хранить векторы компактнее?

Да: в pgvector есть тип `halfvec` (половинная точность) — вдвое меньше места при почти той же точности поиска. Индекс строится с `halfvec_cosine_ops`.

Как фильтровать по метаданным вместе с векторным поиском?

Добавьте условие `WHERE source = ...` в запрос. При сильной фильтрации поднимите `hnsw.ef_search` или включите `SET hnsw.iterative_scan = relaxed_order` — иначе индекс может вернуть меньше строк, чем `LIMIT`.

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

Сколько стоит

≈ 10,05 ₽ в час · 7 236 ₽ в месяц при работе 24/7

vCPU основной базы2 × 900 ₽
RAM основной базы, ГБ4 × 360 ₽
Диск до 20 000 IOPS*, ГБ20 × 14,40 ₽
vCPU реплики2 × 900 ₽
RAM реплики, ГБ4 × 360 ₽
Диск реплики до 20 000 IOPS*, ГБ20 × 14,40 ₽
Публичные IPv4 базы и реплики2 × 90 ₽

Реплика оплачивается как обычная база: vCPU, RAM и диск. Резервные копии — по объёму по цене S3. Для пробы реплику можно не создавать: поиск работает и на основной базе.

Цены из прайс-листа, по которому работает биллинг; списание поминутное, месяц — 720 часов. Если удалить ресурсы после проверки, сценарий обойдётся в рубли.

Новым пользователям — 4 000 ₽ на 30 дней на любые сервисы: бонуса хватит, чтобы попробовать этот сценарий целиком. Бонус начисляется после подтверждения телефона и привязки карты.

* IOPS растут с объёмом диска; точные значения для вашего объёма видны в консоли при выборе.