Что получится
База kb с расширением vector, таблица документов с эмбеддингами и HNSW-индексом, скрипт на Python, который загружает тексты и ищет ближайшие к вопросу, и реплика для чтения, на которую уходят поисковые запросы.
Что понадобится
- Аккаунт h3llo.cloud и проект.
- Python 3.10+ и
psqlна вашем компьютере или сервере. - Модель эмбеддингов на ваш выбор: локальная (в примере —
intfloat/multilingual-e5-smallчерез sentence-transformers) или внешний API. Размерность вектора в таблице должна совпадать с размерностью модели.
-
Шаг 1. Создайте базу с расширением vector
HNSW-индекс живёт в памяти: чем больше векторов, тем больше RAM нужно базе. Для пробы хватит 2 vCPU и 4 ГБ.
Консоль
- В меню проекта откройте Базы данных и нажмите Создать базу данных (если базы уже есть — Создать).
- СУБД — PostgreSQL 17.11. vCPU — 2, RAM — 4 ГБ, Диски — 20 ГБ. Имя базы данных —
kb-db. - Публичный IPv4 — «Вкл.», чтобы подключиться со своего компьютера. Резервное копирование — «Вкл»: без готовой копии реплику не создать.
- В блоке «База и владелец»: Имя базы
kb, Владелецkb, Расширения —vector. - Нажмите Создать базу данных.
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 # пароль пользователя kbTerraform
Terraformresource "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. Создайте таблицу и 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. Загрузите документы с эмбеддингами
Скрипт режет тексты на абзацы, считает эмбеддинги и пишет их в основную базу. Модель 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.pyimport 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. Ищите похожие документы
hnsw.ef_search— сколько кандидатов просматривает индекс: больше — точнее и медленнее. По умолчанию 40.search.pyimport 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. Уведите поиск на реплику для чтения
Реплика — отдельная база только для чтения, она догоняет основную по потоку WAL. Загрузка и переиндексация идут на основной базе, поиск — на реплике. Пользователи, пароли и расширения у реплики те же, что у источника.
Консоль
- Убедитесь, что в разделе «Резервные копии» базы
kb-dbесть хотя бы одна готовая копия (или нажмите Сделать копию сейчас). - В разделе «Реплики для чтения» нажмите Создать реплику. Имя
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 - Базы данных →
kb-ro→ меню «…» → Удалить, отметьте «Освободить IP-адрес (иначе он останется в проекте)» → Подтвердить. - То же для
kb-db. Резервные копии удаляются вместе с базой. - Проверьте 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`.
Связанные продукты и материалы
- Сценарий · 35 минManaged PostgreSQL для приложения: пользователь, pgvector и восстановление на момент времени
- Сценарий · 40 минПриложение в Managed Kubernetes из своего реестра образов
- Сценарий · 45 минСайт на облачном сервере: публичный IP, домен и HTTPS
- Сценарий · 25 минРезервные копии сервера в S3 по расписанию: rclone, cron и ротация
- ПродуктPostgreSQL
Сколько стоит
≈ 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 дней на любые сервисы: бонуса хватит, чтобы попробовать этот сценарий целиком. Бонус начисляется после подтверждения телефона и привязки карты.