Skip to main content
Version: 1.15.1

Развертывание векторной базы данных (Weaviate)

Ainergy поддерживает создание сервиса векторной базы данных на сервере Weaviate.

Сервер​

Сервер Weaviate — это автономный экземпляр векторной базы данных, развертываемый как отдельный Docker-образ. Сервер предназначен для хранения коллекций данных и векторной базы данных, используемых для семантического поиска и работы с векторными запросами.

Взаимодействие с сервером осуществляется через API. Сервер Weaviate может запускаться независимо от основного проекта, что позволяет использовать его как самостоятельный сервис или интегрировать в существующую инфраструктуру.

Клиент​

Клиент — это асинхронный API-клиент, в котором реализованы необходимые методы для работы с векторной базой.

Развертывание​

Клиент и сервер развертываются с помощью Docker Compose и работают в рамках одной Docker-сети. Сервер изолирован от внешнего доступа — взаимодействие с ним осуществляется только внутри сети. Клиент предоставляет внешнее API с авторизацией по Bearer-токену.

Установка и запуск​

Выберите версию и следуйте инструкции по установке.

В этой версии изменена конфигурация окружения. Обязательны только переменная AUTH_TOKEN и подключение к эмбеддеру. Реранкер и Docling по умолчанию выключены и включаются отдельными флагами. Остальные переменные необязательны.

caution

Если вы обновляете сервис с версии 1.0.4, измените файлы .env и compose.yml по разделу Обновление с версии 1.0.4. В версии 1.0.5 изменились значения по умолчанию: без изменений Docling и переранжирование могут оказаться выключены.

  1. Создайте целевую директорию:

    mkdir -p vectordb
    cd vectordb

  2. Создайте файл .env в целевой директории и скопируйте в него минимальную конфигурацию. Вместо <api-auth-token> укажите токен, с которым клиенты будут обращаться к API сервиса, вместо <nexus-auth-token> – токен доступа к Nexus. Адрес Nexus и модель эмбеддера указаны для примера.

    # Bearer-токен для авторизации запросов к API сервиса
    AUTH_TOKEN=<api-auth-token>

    # Подключение к эмбеддеру через Nexus
    NEXUS_BASE_URL=https://prod-ru1-api.ainergy.ru
    NEXUS_AUTH_TOKEN=<nexus-auth-token>
    NEXUS_EMBEDDING_ENDPOINT=/v1/embeddings
    NEXUS_EMBEDDING_MODEL=ain.qwen3-embedding-4b.embedding

    С этой конфигурацией поиск работает без переранжирования, а сервис принимает только файлы pdf и docx. Чтобы включить реранкер или Docling либо подключить эмбеддер напрямую, без Nexus, дополните файл по разделу Конфигурация окружения.

  3. Создайте файл compose.yml и скопируйте в него следующее содержание. Контейнер vectordb-cron создает резервные копии данных в хранилище S3. Если резервное копирование не нужно, удалите из файла блок vectordb-cron. Если нужно, заполните переменные по разделу Резервное копирование.

compose.yml
networks:
  default:
    name: ainergy-net
    external: true

services:
  vectordb-client:
    container_name: vectordb-client
    image: harbor.ainergy.ru/vdb/vectordb-client:1.0.5
    ports:
      - "3002:8000"
    env_file:
      - .env
    restart: always
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s
    depends_on:
      - vectordb-server

  vectordb-server:
    container_name: vectordb-server
    image: harbor.ainergy.ru/vdb/vectordb-server:1.0.5
    ports:
      - 8081:8080
      - 50052:50051
    volumes:
      - ./data:/var/lib/vectordb
    environment:
      QUERY_DEFAULTS_LIMIT: 25
      AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: 'true'
      PERSISTENCE_DATA_PATH: '/var/lib/vectordb'
      CLUSTER_HOSTNAME: 'node1'
    restart: unless-stopped
    networks:
      default:
        aliases:
          - weaviate

  vectordb-cron:
    container_name: vectordb-cron
    image: harbor.ainergy.ru/vdb/vectordb-cron:1.0.5
    volumes:
      - ./cron/logs:/logs
      - ./data:/app/data
    depends_on:
      - vectordb-server
      - vectordb-client
    env_file:
      - .env
    restart: always

  1. Создайте Docker-сеть:

    docker network create ainergy-net

    Если сеть ainergy-net уже создана, пропустите этот шаг.

  2. Скачайте образы:

    docker compose pull

  3. Запустите контейнеры:

    docker compose up -d

  4. Проверьте статус:

    docker compose ps

    В колонке STATUS у контейнера vectordb-client должно быть указано Up ... (healthy). Статус healthy означает, что сервис запущен и отвечает. Доступность Weaviate и эмбеддера при этом не проверяется.

    Другие статусы:

    • Up ... (health: starting) – контейнер запускается, первая проверка еще не пройдена. Повторите команду через минуту.
    • Restarting – ошибка в конфигурации, сервис завершается при запуске. Причина указана в журнале контейнера, который выводит команда docker compose logs vectordb-client. Перечень причин приведен в разделе Конфигурация окружения.
    • unhealthy – сервис запущен, но три раза подряд не ответил на проверку за 10 секунд. Например, во время разбора большого файла pdf встроенным парсером. Дождитесь окончания обработки: после следующей успешной проверки статус сменится на healthy. Если статус не меняется, проверьте журнал контейнера.

Конфигурация окружения​

Сервис не запускается и записывает причину в журнал контейнера vectordb-client, если:

  • не задана переменная AUTH_TOKEN;
  • не заполнены обязательные переменные выбранного способа подключения к эмбеддеру;
  • включен реранкер или Docling, но не заполнены переменные подключения к нему;
  • значение HYBRID_FUSION_TYPE отличается от relative_score и ranked;
  • значение HYBRID_SEARCH_ALPHA выходит за пределы от 0 до 1;
  • значение CHUNK_OVERLAP больше или равно CHUNK_SIZE;
  • значение OCR_TIMEOUT больше DOCLING_POLL_TIMEOUT;
  • значение HTTP_CLIENT_MAX_KEEPALIVE_CONNECTIONS больше HTTP_CLIENT_MAX_CONNECTIONS;
  • модель SPACY_MODEL не установлена в образе;
  • значение переменной недопустимо по типу, диапазону или списку значений, например RERANKER_TYPE отличается от qwen и cross_encoder или значение EMBEDDING_TIMEOUT, RERANKER_TIMEOUT или DOCLING_TIMEOUT меньше или равно нулю.

Значения переменных реранкера и Docling проверяются, даже если эти сервисы выключены.

После изменения файла .env пересоздайте контейнеры командой docker compose up -d. Команда docker compose restart новые значения не применяет.

Полный список переменных с комментариями приведен в примере файла .env.example. Обязательные переменные отмечены в комментариях. Адреса, маршруты, модели, токены, ключи, параметры DO_OCR и OCR_* и переменные резервного копирования указаны для примера. Для остальных переменных указаны значения по умолчанию.

.env.example
# ============================================================================
# Конфигурация векторной базы данных VectorDB
# Обязательно: AUTH_TOKEN и все переменные выбранного способа подключения
# к эмбеддеру. Адреса, маршруты, модели, токены, ключи, параметры DO_OCR
# и OCR_* и переменные раздела III указаны для примера, остальные
# значения - значения по умолчанию.
# ============================================================================

# ============================================================================
# I. ВНЕШНИЕ СЕРВИСЫ
# ============================================================================
# 0. Адрес и токен Nexus. Обязательны, если хотя бы один сервис
#    подключен через Nexus.
NEXUS_BASE_URL=https://prod-ru1-api.ainergy.ru
NEXUS_AUTH_TOKEN=<nexus-auth-token>

# ----------------------------------------------------------------------------
# 1. Эмбеддер (обязателен)
# ----------------------------------------------------------------------------
# 1.1. Способ подключения: False - через Nexus, True - напрямую по API.
#      Заполните переменные выбранного способа, переменные другого не используются.
USE_API_EMBEDDINGS=False

# 1.2. Время ожидания и повторы.
EMBEDDING_TIMEOUT=10.0        # время ожидания ответа эмбеддера, сек
EMBEDDING_MAX_RETRIES=4       # число повторов после отказа; всего попыток - на одну больше
EMBEDDING_BATCH_SIZE=16       # число чанков в одном запросе к эмбеддеру

# 1.3. Подключение через Nexus (обязательно при USE_API_EMBEDDINGS=False)
NEXUS_EMBEDDING_ENDPOINT=/v1/embeddings
NEXUS_EMBEDDING_MODEL=ain.qwen3-embedding-4b.embedding

# 1.4. Подключение напрямую по API
#      (обязательно при USE_API_EMBEDDINGS=True, кроме ключа)
EMBEDDING_API_URL=https://qwen3-embeddings.ai-services.ainergy.ru/v1/embeddings
EMBEDDING_API_KEY=            # укажите ключ, если API требует авторизации
EMBEDDING_MODEL=qwen/qwen3-embedding-4b

# ----------------------------------------------------------------------------
# 2. Реранкер - переранжирование результатов поиска (необязателен)
# ----------------------------------------------------------------------------
# 2.1. Включение. При False переменные подключения к реранкеру не используются,
#      но их значения проверяются при запуске.
RERANK_ENABLED=False

# 2.2. Способ подключения и тип реранкера.
#      RERANKER_TYPE должен соответствовать модели, иначе качество поиска снижается:
#        cross_encoder - bge, jina, mxbai и подобные модели
#        qwen          - Qwen3-Reranker
USE_API_RERANKER=False
RERANKER_TYPE=qwen

# 2.3. Время ожидания и повторы.
RERANKER_TIMEOUT=10.0         # время ожидания ответа реранкера, сек
RERANKER_MAX_RETRIES=2        # число повторов после отказа

# 2.4. Подключение через Nexus
NEXUS_RERANKER_ENDPOINT=/v2/rerank
NEXUS_RERANKER_MODEL=ain.qwen3-reranker-4b.rerank

# 2.5. Подключение напрямую по API
RERANKER_API_URL=https://qwen3-reranker.ai-services.ainergy.ru/v2/rerank
RERANKER_API_KEY=             # укажите ключ, если API требует авторизации
RERANKER_MODEL=qwen3_reranker

# ----------------------------------------------------------------------------
# 3. Docling - извлечение текста из документов (необязателен)
# ----------------------------------------------------------------------------
# 3.1. Включение. При False переменные подключения к Docling не используются,
#      но их значения проверяются при запуске,
#      сервис принимает только файлы pdf и docx.
DOCLING_ENABLED=False

# 3.2. Способ подключения: False - через Nexus, True - напрямую по API.
USE_API_DOCLING=False

# 3.3. Время ожидания.
DOCLING_TIMEOUT=10.0          # время ожидания ответа на один запрос к Docling, сек
DOCLING_POLL_INTERVAL=2.0     # интервал проверки готовности документа, сек
DOCLING_POLL_TIMEOUT=600.0    # сколько сервис ждет готовности документа от Docling, сек

# 3.4. Параметры извлечения текста. Передаются в Docling с каждым файлом.
#      Значения указаны для примера. Если параметр не задан,
#      Docling использует собственное значение.
DO_OCR=True                   # распознавать текст на сканах и изображениях
OCR_ENGINE=easyocr            # движок распознавания
OCR_PDF_BACKEND=dlparse_v4    # способ разбора PDF
OCR_TIMEOUT=300.0             # предел обработки документа внутри Docling, сек; не больше DOCLING_POLL_TIMEOUT

# 3.5. Подключение через Nexus. Нужны все три маршрута.
NEXUS_DOCLING_ASYNC=ain.docling.convert_async
NEXUS_DOCLING_POLL=ain.docling.poll_status
NEXUS_DOCLING_RESULT=ain.docling.result

# 3.6. Подключение напрямую по API Docling.
DOCLING_API_URL=https://docling.ai-services.ainergy.ru
DOCLING_API_KEY=              # укажите ключ, если API требует авторизации


# ============================================================================
# II. НАСТРОЙКИ СЕРВИСА
# ============================================================================
# 1. Поиск.
# Вес векторной части от 0 до 1: 1.0 - только векторный поиск, 0.0 - только BM25.
# Используется, если alpha не передан в запросе.
HYBRID_SEARCH_ALPHA=0.7

# Способ объединения результатов векторного поиска и BM25:
#   relative_score - по нормированным оценкам
#   ranked         - по рангам (RRF)
HYBRID_FUSION_TYPE=relative_score

# Число соседних чанков с каждой стороны, текст которых добавляется
# к найденному. Используется, если window не передан в запросе.
RETRIEVE_WINDOW_SIZE=1

# 2. Лемматизация и стоп-слова для полнотекстового поиска.
SPACY_MODEL=ru_core_news_sm   # модель лемматизации; в образ входит только ru_core_news_sm
STOPWORDS_LANGUAGE=ru         # язык списка стоп-слов

# 3. Загрузка документов: нарезка на чанки.
CHUNK_SIZE=1000             # длина чанка в символах
CHUNK_OVERLAP=200           # перекрытие чанков в символах, меньше CHUNK_SIZE

# Индексы BM25 и HNSW. Применяются только при создании коллекции.
BM25_B=0.75                 # нормализация по длине документа (0..1)
BM25_K1=1.2                 # насыщение от частоты терма
HNSW_EF=-1                  # точность поиска; -1 - подбирается автоматически
HNSW_EF_CONSTRUCTION=128    # качество построения индекса

# 4. Работа сервиса.
# Предельное число соединений для каждого из клиентов эмбеддера, реранкера
# и Docling. KEEPALIVE - не больше MAX.
HTTP_CLIENT_MAX_CONNECTIONS=1000
HTTP_CLIENT_MAX_KEEPALIVE_CONNECTIONS=500

# Журнал.
LOG_LEVEL=INFO      # TRACE | DEBUG | INFO | SUCCESS | WARNING | ERROR | CRITICAL
LOG_DIAGNOSE=False  # True - добавлять в журнал ошибок значения переменных кода.
                    # Только для отладки: в журнал попадают тела запросов и токены

# Подключение к серверу Weaviate.
WEAVIATE_HOST=weaviate      # имя сервера в Docker-сети
WEAVIATE_PORT=8080
WEAVIATE_GRPC_PORT=50051

# Bearer-токен для авторизации запросов к API сервиса (обязательно).
AUTH_TOKEN=<api-auth-token>

# ============================================================================
# III. РЕЗЕРВНОЕ КОПИРОВАНИЕ (контейнер vectordb-cron)
# Для резервного копирования нужны все переменные, значения указаны для примера.
# Если SCHEDULE не задана, копирование запускается каждую минуту.
# ============================================================================
AWS_ENDPOINT=<s3-endpoint>
AWS_ACCESS_KEY_ID=<s3-access-key>
AWS_SECRET_ACCESS_KEY=<s3-secret-key>
AWS_BUCKET_NAME=ainergy
AWS_FOLDER_NAME=vdb
SCHEDULE=0 0 * * *

# Служебная переменная контейнера, не меняйте.
PYTHONPATH=/app

Внешние сервисы​

VectorDB использует три внешних сервиса: эмбеддер, реранкер и Docling. Каждый из них подключается через Nexus или напрямую по API. Способ подключения задается для каждого внешнего сервиса своим флагом:

Внешний сервисФлаг способа подключенияЧерез Nexus (False)Напрямую по API (True)
ЭмбеддерUSE_API_EMBEDDINGSNEXUS_BASE_URL, NEXUS_AUTH_TOKEN, NEXUS_EMBEDDING_ENDPOINT, NEXUS_EMBEDDING_MODELEMBEDDING_API_URL, EMBEDDING_MODEL, при необходимости EMBEDDING_API_KEY
РеранкерUSE_API_RERANKERNEXUS_BASE_URL, NEXUS_AUTH_TOKEN, NEXUS_RERANKER_ENDPOINT, NEXUS_RERANKER_MODELRERANKER_API_URL, RERANKER_MODEL, при необходимости RERANKER_API_KEY
DoclingUSE_API_DOCLINGNEXUS_BASE_URL, NEXUS_AUTH_TOKEN, NEXUS_DOCLING_ASYNC, NEXUS_DOCLING_POLL, NEXUS_DOCLING_RESULTDOCLING_API_URL, при необходимости DOCLING_API_KEY

Заполните переменные того способа, который выбран флагом. Переменные другого способа не используются.

Без Docling текст из документов извлекают встроенные парсеры. Они поддерживают только форматы pdf и docx, файлы других форматов отклоняются с кодом 400. Docling добавляет поддержку форматов pptx, xlsx, html, csv, md, изображений png и jpg и распознавание текста на сканах.

Чтобы включить внешний сервис, установите его флаг и заполните переменные подключения к нему:

Внешний сервисФлаг включенияВыключен (False, по умолчанию)Включен (True)
РеранкерRERANK_ENABLEDПереранжирование не выполняется, переменные подключения к реранкеру не используются.Заполните переменные подключения к реранкеру.
DoclingDOCLING_ENABLEDРаботают только встроенные парсеры, переменные подключения к Docling не используются.Заполните переменные подключения к Docling.

При запуске сервис записывает в журнал предупреждение о каждом выключенном внешнем сервисе.

Поиск​

Поиск – гибридный: векторный поиск сочетается с полнотекстовым поиском BM25. Если реранкер включен, результаты переранжируются. Поиск настраивается переменными окружения и параметрами тела запроса. Параметры тела запроса описаны в статье Конечные точки.

ПараметрГде задаетсяОписание
alphaТело запроса, HYBRID_SEARCH_ALPHAВес векторной части, от 0 до 1: 1.0 – только векторный поиск, 0.0 – только BM25. Если параметр не передан в запросе, используется значение HYBRID_SEARCH_ALPHA.
rerankТело запроса, RERANK_ENABLEDЗначение false выключает переранжирование для запроса. Если параметр не передан в запросе, используется значение RERANK_ENABLED. Если RERANK_ENABLED=False, запрос со значением true возвращает ошибку 400.
windowТело запроса, RETRIEVE_WINDOW_SIZEРасширяет контекст: текст найденного чанка дополняется текстом соседних чанков того же документа, не больше указанного числа с каждой стороны. Отдельными элементами ответа соседние чанки не возвращаются. Значение 0 выключает расширение. Если параметр не передан в запросе, используется значение RETRIEVE_WINDOW_SIZE, по умолчанию 1.
HYBRID_FUSION_TYPE.envСпособ объединения результатов векторного поиска и BM25:
  • relative_score – по нормированным оценкам, значение по умолчанию;
  • ranked – по рангам (RRF).
RERANKER_TYPE.envФормат запросов к реранкеру:
  • qwen – для модели Qwen3-Reranker, значение по умолчанию;
  • cross_encoder – для моделей bge, jina, mxbai.

Если значение не соответствует модели, реранкер отвечает без ошибок в журнале, но качество поиска снижается. Чтобы сравнить результаты без переранжирования, передайте в запросе "rerank": false.

SPACY_MODEL.envМодель spaCy для лемматизации чанков и запроса. По лемматизированному тексту выполняется поиск BM25. Модель должна быть установлена в образе, в образ входит только ru_core_news_sm. Значение по умолчанию: ru_core_news_sm.
BM25_B, BM25_K1.envПараметры BM25. Применяются только при создании коллекции.
STOPWORDS_LANGUAGE.envЯзык списка стоп-слов для BM25. Применяется только при создании коллекции. Значение по умолчанию: ru.
HNSW_EF, HNSW_EF_CONSTRUCTION.envПараметры индекса HNSW: баланс точности и скорости поиска, качество построения индекса. Применяются только при создании коллекции.

Если реранкер не ответил, поиск возвращает результаты без переранжирования, а ошибка записывается в журнал контейнера vectordb-client.

caution

Чтобы применить новые значения BM25_*, STOPWORDS_LANGUAGE и HNSW_* к существующей коллекции, создайте ее заново и повторно загрузите документы.

Смена SPACY_MODEL не затрагивает загруженные документы: они остаются обработанными прежней моделью, и полнотекстовый поиск по ним становится менее точным. Меняйте модель до загрузки документов либо загрузите документы повторно.

Резервное копирование​

Резервные копии создает контейнер vectordb-cron. Для его работы заполните в файле .env все переменные:

ПеременнаяОписание
AWS_ENDPOINTУкажите адрес хранилища S3.
AWS_ACCESS_KEY_IDУкажите идентификатор ключа доступа к хранилищу.
AWS_SECRET_ACCESS_KEYУкажите секретный ключ доступа к хранилищу.
AWS_BUCKET_NAMEУкажите имя бакета.
AWS_FOLDER_NAMEУкажите имя папки в бакете.
SCHEDULEУкажите расписание резервного копирования в формате cron, например 0 0 * * * – один раз в сутки. Если переменная не задана, резервное копирование запускается каждую минуту.

Значений по умолчанию у переменных AWS_* нет. Если хотя бы одна из них не задана, резервное копирование завершается ошибкой, которая записывается в файл ./cron/logs/output.log. Если не задана и SCHEDULE, ошибка записывается каждую минуту и файл растет. В журнале docker compose logs эта ошибка не видна.

Резервная копия сохраняется в бакет по пути <AWS_FOLDER_NAME>/<время создания в формате Unix>/<AWS_FOLDER_NAME>.zip.

Примеры конфигураций​

Каждый пример – полный файл .env без переменных резервного копирования. Переменные, которых нет в примере, принимают значения по умолчанию. Для резервного копирования добавьте переменные по разделу Резервное копирование или удалите из compose.yml блок vectordb-cron.

С реранкером
AUTH_TOKEN=<api-auth-token>

NEXUS_BASE_URL=https://prod-ru1-api.ainergy.ru
NEXUS_AUTH_TOKEN=<nexus-auth-token>
NEXUS_EMBEDDING_ENDPOINT=/v1/embeddings
NEXUS_EMBEDDING_MODEL=ain.qwen3-embedding-4b.embedding

RERANK_ENABLED=True
RERANKER_TYPE=qwen
NEXUS_RERANKER_ENDPOINT=/v2/rerank
NEXUS_RERANKER_MODEL=ain.qwen3-reranker-4b.rerank
С Docling
AUTH_TOKEN=<api-auth-token>

NEXUS_BASE_URL=https://prod-ru1-api.ainergy.ru
NEXUS_AUTH_TOKEN=<nexus-auth-token>
NEXUS_EMBEDDING_ENDPOINT=/v1/embeddings
NEXUS_EMBEDDING_MODEL=ain.qwen3-embedding-4b.embedding

DOCLING_ENABLED=True
NEXUS_DOCLING_ASYNC=ain.docling.convert_async
NEXUS_DOCLING_POLL=ain.docling.poll_status
NEXUS_DOCLING_RESULT=ain.docling.result
С разными способами подключения

Эмбеддер и Docling подключены напрямую по API, реранкер – через Nexus.

AUTH_TOKEN=<api-auth-token>

USE_API_EMBEDDINGS=True
EMBEDDING_API_URL=https://qwen3-embeddings.ai-services.ainergy.ru/v1/embeddings
EMBEDDING_API_KEY=<embedding-api-key>
EMBEDDING_MODEL=qwen/qwen3-embedding-4b

RERANK_ENABLED=True
USE_API_RERANKER=False
RERANKER_TYPE=qwen
NEXUS_BASE_URL=https://prod-ru1-api.ainergy.ru
NEXUS_AUTH_TOKEN=<nexus-auth-token>
NEXUS_RERANKER_ENDPOINT=/v2/rerank
NEXUS_RERANKER_MODEL=ain.qwen3-reranker-4b.rerank

DOCLING_ENABLED=True
USE_API_DOCLING=True
DOCLING_API_URL=https://docling.ai-services.ainergy.ru
DOCLING_API_KEY=<docling-api-key>
Все внешние сервисы включены

Эмбеддер, реранкер и Docling подключены через Nexus, время ожидания и параметры поиска и загрузки документов заданы явно.

AUTH_TOKEN=<api-auth-token>

NEXUS_BASE_URL=https://prod-ru1-api.ainergy.ru
NEXUS_AUTH_TOKEN=<nexus-auth-token>

# Эмбеддер
NEXUS_EMBEDDING_ENDPOINT=/v1/embeddings
NEXUS_EMBEDDING_MODEL=ain.qwen3-embedding-4b.embedding
EMBEDDING_TIMEOUT=10.0
EMBEDDING_MAX_RETRIES=4
EMBEDDING_BATCH_SIZE=16

# Реранкер
RERANK_ENABLED=True
RERANKER_TYPE=qwen
NEXUS_RERANKER_ENDPOINT=/v2/rerank
NEXUS_RERANKER_MODEL=ain.qwen3-reranker-4b.rerank
RERANKER_TIMEOUT=10.0
RERANKER_MAX_RETRIES=2

# Docling
DOCLING_ENABLED=True
NEXUS_DOCLING_ASYNC=ain.docling.convert_async
NEXUS_DOCLING_POLL=ain.docling.poll_status
NEXUS_DOCLING_RESULT=ain.docling.result
DOCLING_TIMEOUT=10.0
DOCLING_POLL_INTERVAL=2.0
DOCLING_POLL_TIMEOUT=600.0
DO_OCR=True
OCR_ENGINE=easyocr
OCR_PDF_BACKEND=dlparse_v4
OCR_TIMEOUT=300.0

# Поиск и загрузка документов
HYBRID_SEARCH_ALPHA=0.7
HYBRID_FUSION_TYPE=relative_score
RETRIEVE_WINDOW_SIZE=1
CHUNK_SIZE=1000
CHUNK_OVERLAP=200

Обновление с версии 1.0.4​

Коллекции, созданные в версии 1.0.4, работают без повторной загрузки. Исключение – параметр window: в коллекциях версии 1.0.4 текст соседних чанков к результатам поиска не добавляется. Чтобы расширение контекста работало, создайте коллекцию заново и загрузите документы повторно.

  1. Проверьте, что в файле .env задана переменная AUTH_TOKEN. Если эмбеддер подключен через Nexus, проверьте также переменные NEXUS_BASE_URL, NEXUS_AUTH_TOKEN, NEXUS_EMBEDDING_ENDPOINT и NEXUS_EMBEDDING_MODEL. Значений по умолчанию у них нет, без них сервис не запустится.

  2. Измените файл .env:

    ПеременнаяДействие
    DOCLING_ENABLEDДобавьте со значением True, если используете Docling. Без нее сервис принимает только файлы pdf и docx.
    RERANK_ENABLEDУкажите True, если используете переранжирование. Значение по умолчанию изменилось на False.
    NEXUS_RERANKER_ENDPOINTЕсли реранкер подключен через Nexus, укажите /v2/rerank.
    NEXUS_RERANKER_MODELЕсли реранкер подключен через Nexus с моделью ain.qwen3-reranker-4b-v2api.rerank из инструкции версии 1.0.4, замените ее на ain.qwen3-reranker-4b.rerank.
    RERANKER_TYPEЕсли модель реранкера – не Qwen3-Reranker, например bge, укажите cross_encoder.
    HTTP_CLIENT_TIMEOUTЕсли переменная задана, удалите ее. Вместо нее используются EMBEDDING_TIMEOUT, RERANKER_TIMEOUT и DOCLING_TIMEOUT, значение по умолчанию у каждой – 10 секунд.
    NEXUS_DOCLING_SYNCЕсли переменная задана, удалите ее. Переменная не используется.

  3. Замените содержимое файла compose.yml на приведенное в шаге 3 установки. Если установка версии 1.0.4 работает в сети vdb-net, укажите это имя в параметре networks.default.name. Если вы меняли compose.yml версии 1.0.4, например удаляли блок vectordb-cron или меняли порты, перенесите эти изменения в новый файл.

  4. Скачайте образы:

    docker compose pull

  5. Остановите контейнеры и скопируйте каталог ./data. Копия позволит вернуть данные, если обновление пройдет неудачно:

    docker compose down

  6. Запустите контейнеры:

    docker compose up -d

  7. Проверьте статус, как описано в шаге 7 установки.

Конечные точки API​

После развертывания API доступно на порту, указанном в файле compose.yml, по умолчанию – 3002. При развертывании через Ansible порт задается переменной vdb_connection_port. Список методов приведен в статье Конечные точки.

Доступ к API​

  • Client API: http://localhost:3002
  • Weaviate API: http://localhost:8081 (только для отладки)
  • Документация Swagger: http://localhost:3002/docs

Управление​

  • Остановка: docker compose down
  • Перезапуск: docker compose restart. Изменения файла .env эта команда не применяет – после изменения .env выполните docker compose up -d.
  • Логи: docker compose logs -f
  • Обновление образов: docker compose pull && docker compose up -d. Чтобы перейти на новую версию, замените теги образов в compose.yml по инструкции этой версии.

Примечания​

  • Переменные окружения задаются в файле .env.
  • Данные Weaviate сохраняются в папке ./data.
  • Резервные копии создаются автоматически согласно расписанию SCHEDULE.
  • Порты можно изменить в файле compose.yml при необходимости.

Работа с фильтрацией и метаданными​

Формат загрузки документов​

В VectorDB документы загружаются с текстом и метаданными. Метаданные – это словарь с произвольными ключами и значениями. Поддерживаемые типы: String, Integer, Float, Boolean, Date по стандарту ISO-8601.

Пример загрузки текста с метаданными:

{
  "metadata": {
    "sys_id": "12345",
    "status": "active",
    "priority": 1,
    "flag": true,
    "type": "project_management",
    "created": "2024-01-01T00:00:00Z"
  },
  "text": "Документ о системе управления проектами..."
}

Пример загрузки файла с метаданными:

{
  "metadata": {
    "sys_id": "67890",
    "status": "draft",
    "priority": 2,
    "flag": false,
    "type": "safety_instruction",
    "created": "2024-01-02T00:00:00Z"
  },
  "file": "<файл>"
}
  • Метаданные автоматически определяют схему коллекции (тип поля определяется по первому загруженному значению).
  • Для значений типа Boolean используйте true/false (без кавычек).
  • Для дат используйте формат YYYY-MM-DDTHH:MM:SSZ.

Фильтрация при поиске (ретриве) документов​

Для поиска документов с фильтрацией используйте конечную точку /get_relevant_documents с параметром metadata – строкой фильтра.

Ниже предоставлена информация об особенностях поддерживаемых VectorDB операторов условий.

Примеры фильтров​

Условие поискаПример
По строкеstatus=active
По числуpriority=1
По булевому значениюflag=true
По дате:created=2024-01-01T00:00:00Z
Несколько условий (оператор AND)status=active^priority=1
Несколько условий (оператор OR)(status=active^priority=1)^OR(status=draft)
Сложные условия с операторами AND/OR и скобками:(status=active^priority=1)^OR(type=report)
Оператор INstatus IN ('active', 'draft')
Оператор LIKE (поиск по подстроке)typeLIKEreport
Операторы сравненияpriority>1, priority<=2, created>=2024-01-01T00:00:00Z

Примеры сложных фильтров​

ЗадачаФильтр
Все документы со статусом active и приоритетом 1status=active^priority=1
Документы с (status=active и priority=1) или с type=report(status=active^priority=1)^OR(type=report)
Документы с флагом trueflag=true
Документы, созданные после 2024-01-01created>2024-01-01T00:00:00Z
Документы с типом из спискаtype IN ('project_management', 'financial_report')

Примеры запросов​

Пример 1
{
  "collection_names": ["test_collection"],
  "metadata": "(status=active^priority=1)^OR(type=report)"
}
Пример 2
{
  "collection_names": ["test_collection"],
  "metadata": "flag=true"
}
Поддерживаемые операторы
ОператорОписаниеПример
=Равноstatus=active
!=Не равноpriority!=1
>Большеpriority>1
<Меньшеpriority<2
>=Больше или равноpriority>=1
<=Меньше или равноpriority<=2
INВ спискеstatus IN ('active', 'draft')
LIKEСодержит подстрокуtypeLIKEreport
BETWEENДиапазон значений (включительно)priority BETWEEN value1@value2
STARTSWITHНачинается с (регистрозависимо)title STARTSWITH Инц
ENDSWITHЗаканчивается на (регистрозависимо)website ENDSWITH .com
ONТочное совпадение datetimecreated_at ON 2024-01-15T10:30:00Z
NOTONИсключение datetimeupdated_at NOTON 2024-01-01T09:00:00Z
ISEMPTYПроверка на пустотуemail ISEMPTY
ISNOTEMPTYПроверка на заполненностьemail ISNOTEMPTY
^Логическое И (AND)status=active^priority=1
^ORЛогическое ИЛИ (OR)(status=active^priority=1)^OR(type=draft)
( )Группировка условий(status=active^priority=1)^OR(type=report)
Операторы для частей даты и времени
ОператорОписаниеПример
YEAR_ISГод части даты равен значениюcreatedYEAR_IS2024
MONTH_ISМесяц части даты равен значениюcreatedMONTH_IS2
QUARTER_ISКвартал части даты равен значениюcreatedQUARTER_IS1
WEEK_ISНеделя части даты равна значениюcreatedWEEK_IS10
DAY_ISДень месяца части даты равен значениюcreatedDAY_IS15
DAY_OF_WEEK_ISДень недели части даты равен значениюcreatedDAY_OF_WEEK_IS1
HOUR_ISЧас части времени равен значениюcreatedHOUR_IS10
Поддерживаемые типы данных
  • String: любые текстовые значения.
  • Float: вещественные числа.
  • Integer: целые числа.
  • BigInt: большие числа (больше 2^53), автоматически поддерживаются как строки с дублированным числовым полем.
  • Boolean: true/false (без кавычек).
  • Date/Time: строки в формате RFC 3339 (2024-01-01T00:00:00Z).
Формат фильтра
  • Операторы сравнения:
    =, !=, >, <, >=, <=, IN, LIKE
  • Логические операторы:
    • ^ – И
    • ^OR – ИЛИ
    • Скобки () используются для группировки условий.
  • Пробелы допускаются между элементами фильтра и не влияют на парсинг.
Особенности фильтрации
  • Скобки позволяют строить вложенные и комбинированные условия с AND/OR.
  • Пробелы между условиями и операторами игнорируются.
  • Операторы могут быть записаны как с пробелами, так и без:
    status = active, status=active, status =active – все варианты корректны.
  • Значения Boolean фильтруются как flag=true или flag=false (без кавычек).
  • Значения BigInt (числа больше 2^53) автоматически поддерживаются:
    • При загрузке создается дублированное числовое поле для корректного поиска.
    • Фильтрация работает как для строкового, так и для числового представления: transaction_id=123456789012345678901, amount>9007199254740993.
  • Оператор IN поддерживает списки строк, чисел, дат:
    priority IN (1, 2, 3), status IN ('active', 'draft')
  • Оператор LIKE ищет по подстроке:
    typeLIKEreport – эквивалентно поиску по "report".
  • Операторы AND (^) и OR (^OR) можно комбинировать с помощью скобок для построения сложных логических выражений.
  • Операторы STARTSWITH/ENDSWITH чувствительны к регистру и работают с точными совпадениями.
  • Оператор BETWEEN поддерживает числа, даты и время с включением граничных значений.
  • Операторы ISEMPTY/ISNOTEMPTY проверяют наличие/отсутствие значений в полях.

Рекомендации​

  • Для сложных фильтров используйте скобки для группировки.
  • Для булевых значений используйте true/false без кавычек.
  • Для дат используйте формат YYYY-MM-DDTHH:MM:SSZ.
  • Для списков используйте оператор IN с запятыми и без кавычек для чисел.
  • Пробелы в фильтрах допускаются и не влияют на результат.