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

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

Сервер

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

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

Клиент

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

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

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

Конфигурация эмбеддингов и реранкера

Система поддерживает два типа API:

1. Nexus API (по умолчанию для эмбеддингов):

   • USE_OPENAI_LIKE_EMBEDDINGS=False
   • Использует переменные NEXUS_*

2. OpenAI-совместимое API:

   • USE_OPENAI_LIKE_EMBEDDINGS=True
   • USE_OPENAI_LIKE_RERANKER=True
   • Использует переменные EMBEDDING_API_URL, RERANKER_API_URL

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

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

   mkdir -p vectordb
   cd vectordb

2. Создайте .env файл в целевой директории и вставьте в него текст из файла.

3. Создайте файл compose.yml с содержимым из файла.

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

   docker network create ainergy-net

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

   docker compose pull

6. Запустите сервисы:

   docker compose up -d

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

   docker compose ps

Доступ к API

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

Управление

• Остановка: docker compose down
• Перезапуск: docker compose restart
• Логи: docker compose logs -f
• Обновление: docker compose pull && docker compose up -d

Структура папок

vectordb/
├── .env                   # Конфигурация
├── compose.yml            # Docker Compose файл
├── data/                  # Данные Weaviate
└── cron/
    └── logs/              # Логи cron задач

Примечания

---

• Все переменные окружения должны быть настроены в .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)
Оператор IN	status IN ('active', 'draft')
Оператор LIKE (поиск по подстроке)	typeLIKEreport
Операторы сравнения	priority>1, priority<=2, created>=2024-01-01T00:00:00Z

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

Задача	Фильтр
Все документы со статусом active и приоритетом 1	status=active^priority=1
Документы с (status=active и priority=1) или с type=report	(status=active^priority=1)^OR(type=report)
Документы с флагом true	flag=true
Документы, созданные после 2024-01-01	created>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	Точное совпадение datetime	created_at ON 2024-01-15T10:30:00Z
NOTON	Исключение datetime	updated_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 с запятыми и без кавычек для чисел.
• Пробелы в фильтрах допускаются и не влияют на результат.