Skip to main content
Version: 1.13.0

Развертывание векторной базы данных (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 файл в целевой директории, скопируйте в него следующее содержание и заполните необходимой информацией:

.env
# Nexus API Configuration
NEXUS_EMBEDDING_MODEL=ain.qwen3-embedding-4b.embedding
NEXUS_RERANKER_MODEL=ain.qwen3-reranker-4b-v2api.rerank
NEXUS_EMBEDDING_ENDPOINT=/v1/embeddings
NEXUS_RERANKER_ENDPOINT=/v1/rerank
NEXUS_AUTH_TOKEN=xxx — укажите токен для нексусов.
NEXUS_BASE_URL=https://prod-ru1-api.ainergy.ru

# Docling
NEXUS_DOCLING_SYNC=ain.docling.convert_sync
NEXUS_DOCLING_ASYNC=ain.docling.convert_async
NEXUS_DOCLING_POLL=ain.docling.poll_status
NEXUS_DOCLING_RESULT=ain.docling.result

# Weaviate Configuration
AUTH_TOKEN=xxx — укажите Client-API HTTP Bearer токен для авторизации.
WEAVIATE_HOST=weaviate
WEAVIATE_PORT=8080
WEAVIATE_GRPC_PORT=50051
CHUNK_SIZE=1000
CHUNK_OVERLAP=200

PYTHONPATH=/app

# Опционально для бэкапов при использовании vectordb-cron
AWS_ENDPOINT=xxx — укажите путь к вашему хранилищу S3.
AWS_ACCESS_KEY_ID=xxx — укажите логин.
AWS_SECRET_ACCESS_KEY=xxx — укажите пароль.
AWS_BUCKET_NAME=xxx — укажите имя бакета.
AWS_FOLDER_NAME=xxx — укажите название папки внутри бакета, куда будет сохраняться резервная копия данных.

# Cron Schedule
SCHEDULE=0 0 * * * — укажите частоту формирования резервной копии данных в формате Cron.
  1. Создайте файл compose.yml, скопируйте в него следующее содержание и заполните необходимой информацией:
compose.yml
networks:
  default:
    name: vdb-net
    external: true

services:
  vectordb-client:
    container_name: vectordb-client
    image: harbor.ainergy.ru/vdb/vectordb-client:1.0.3
    ports:
      - "3002:8000"
    env_file:
      - .env
    restart: unless-stopped
    depends_on:
      - vectordb-server

  vectordb-server:
    container_name: vectordb-server
    image: harbor.ainergy.ru/vdb/vectordb-server:1.0.3
    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.3
    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

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

    docker compose pull

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

    docker compose up -d

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

    docker compose ps

    Развертывание векторной базы данных через Ansible​

  5. Заполните файл окружения roles/vectordb/defaults/main.yml как указано ниже:

Файл main.yml
# Docker образы
vdb_server_image_name: harbor.ainergy.ru/vdb/vectordb-server
vdb_client_image_name: harbor.ainergy.ru/vdb/vectordb-client
vdb_cron_image_name: harbor.ainergy.ru/vdb/vectordb-cron
vdb_server_image_tag: "1.0.3"
vdb_client_image_tag: "1.0.3"
vdb_cron_image_tag: "1.0.3"

# Сеть
vdb_network_name: vdb-net

# Порт подключения к API
vdb_connection_port: 3002

# Nexus конфигурация
vdb_connect_auth_token: "your-auth-token"
vdb_connect_nexus_auth_token: "your-nexus-token"
vdb_connect_nexus_url: "https://your-nexus-api.example.com"
vdb_connect_nexus_embedding: "your-embedding-model"
vdb_connect_nexus_reranker: "your-reranker-model"
vdb_connect_nexus_docling_sync: "ain.docling.convert_sync"
vdb_connect_nexus_docling_async: "ain.docling.convert_async"
vdb_connect_nexus_docling_poll: "ain.docling.poll_status"
vdb_connect_nexus_docling_result: "ain.docling.result"

# Необязательно (значения по умолчанию):
vdb_data_dir: ./data                           # директория для данных
vdb_server_http_port: 8081                     # HTTP порт Weaviate
vdb_server_grpc_port: 50052                    # gRPC порт Weaviate
vdb_network_external: true                     # использовать внешнюю сеть
Описание переменных в файле main.yml

Обязательные к заполнению (roles/vectordb/defaults/main.yml)

Образы Docker:

  • vdb_server_image_name — образ Weaviate сервера
  • vdb_client_image_name — образ клиентского API
  • vdb_cron_image_name — образ cron для бэкапов
  • vdb_server_image_tag — тег образа сервера
  • vdb_client_image_tag — тег образа клиента
  • vdb_cron_image_tag — тег образа cron

Сеть и порты:

  • vdb_connection_port — порт для подключения к клиенту
  • vdb_network_name — имя сети Docker

Конфигурация нексуса:

  • vdb_connect_auth_token — токен авторизации API
  • vdb_connect_nexus_auth_token — токен авторизации Nexus
  • vdb_connect_nexus_url — URL Nexus API
  • vdb_connect_nexus_embedding — имя Nexus эмбеддингов
  • vdb_connect_nexus_reranker — имя Nexus реранкера
  • vdb_connect_nexus_docling_sync — имя Nexus Docling sync
  • vdb_connect_nexus_docling_async — имя Nexus Docling async
  • vdb_connect_nexus_docling_poll — имя Nexus Docling poll
  • vdb_connect_nexus_docling_result — имя Nexus Docling result

Необязательные (имеют значения по умолчанию)

  • vdb_deployment_user — пользователь для развертывания (по умолчанию: root)
  • vdb_deployment_group — группа для развертывания (по умолчанию: root)
  • vdb_data_dir — директория для данных (по умолчанию: ./data)
  • vdb_server_internal_host_name — внутреннее имя хоста сервера (по умолчанию: weaviate)
  • vdb_server_internal_port — внутренний HTTP порт сервера (по умолчанию: 8080)
  • vdb_server_grpc_internal_port — внутренний gRPC порт сервера (по умолчанию: 50051)
  • vdb_internal_network_name — имя внутренней сети (по умолчанию: vdb-net)
  • vdb_network_external — внешняя сеть (по умолчанию: true)
  • vdb_server_http_port — внешний HTTP порт сервера (по умолчанию: 8081)
  • vdb_server_grpc_port — внешний gRPC порт сервера (по умолчанию: 50052)
  • vdb_client_internal_port — внутренний порт клиента (по умолчанию: 8000)
  • vdb_connect_nexus_embedding_endpoint — путь до эмбеддингов (по умолчанию: /v1/embeddings)
  • vdb_connect_nexus_reranker_endpoint — путь до реранкера (по умолчанию: /v1/rerank)
  • vdb_query_defaults_limit — лимит результатов по умолчанию (по умолчанию: 25)
  • vdb_authentication_anonymous_access_enabled — анонимный доступ (по умолчанию: 'true')
  • vdb_cluster_hostname — имя хоста кластера (по умолчанию: 'node1')
  • vdb_server_network_alias — сетевой алиас (по умолчанию: 'weaviate')
  • vdb_logs_dir — директория для логов (по умолчанию: ./cron/logs)
  • vdb_chunk_size — размер чанка (по умолчанию: 1000)
  • vdb_chunk_overlap — перекрытие чанков (по умолчанию: 200)

Настройки бэкапов (опционально):

  • vdb_backup_aws_endpoint — путь до хранилища S3
  • vdb_backup_aws_access_key_id — AWS Access Key
  • vdb_backup_secret_access_key — AWS Secret Key
  • vdb_backup_bucket_name — имя бакета
  • vdb_backup_folder_name — имя папки в бакете
  • vdb_backup_schedule — расписание cron (по умолчанию: '0 0 * * *')
  1. Запустите развертывание Ansible:
ansible-playbook -i inventory/inventory.yaml deploy.yaml
  1. Проверьте работу:

Откройте в браузере: http://localhost:3002/docs

Удаление Ansible​

ansible-playbook -i inventory/inventory.yaml deploy.yaml -e "task=remove"

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

После развертывания API доступно по адресу: http://localhost: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
  • Логи: docker compose logs -f
  • Обновление: docker compose pull && docker compose up -d

Примечания​

  • Все переменные окружения должны быть настроены в .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 с запятыми и без кавычек для чисел.
  • Пробелы в фильтрах допускаются и не влияют на результат.