Перейти к основному содержимому

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

GenAI поддерживает создание сервиса векторной базы данных на сервере 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.

    # Опциональные параметры гибридного поиска 
    HYBRID_SEARCH_ALPHA=0.7 — рекомендуется выбирать <0.5 для технических документов и >0.5 для общего, естественного языка. Применяется, если вес вектора не указан пользователем в запросе.
    HYBRID_FUSION_TYPE=relative_score — тип слияния (relative_score — по нормированным скорам, по умолчанию; ranked — по рангам (RRF))
    RERANK_ENABLED=True — включение переранжирования. Применяется, если обратное не указано пользователем в запросе.

    # Опциональные параметры индексирования BM25 и HNSW (применяются только при создании новой коллекции)
    BM25_B=0.75 – нормализация по длине документа (0..1)
    BM25_K1=1.2 – насыщение от частоты терма
    HNSW_EF=-1 – ef на поиске; -1 = динамический ef (баланс recall/скорость)
    HNSW_EF_CONSTRUCTION=128 – ef при построении индекса (качество графа vs время индексации)

  3. Создайте файл 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.4
        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.4
        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.4
        volumes:
          - ./cron/logs:/logs
          - ./data:/app/data
        depends_on:
          - vectordb-server
          - vectordb-client
        env_file:
          - .env
        restart: always

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

    docker network create vdb-net

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

    docker compose pull

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

    docker compose up -d

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

    docker compose ps

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

  1. Заполните файл окружения 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.4"
    vdb_client_image_tag: "1.0.4"
    vdb_cron_image_tag: "1.0.4"

    # Сеть
    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                     # использовать внешнюю сеть

    # Опциональные параметры гибридного поиска 
    vdb_hybrid_search_alpha: 0.7
    vdb_hybrid_fusion_type: "relative_score"
    vdb_rerank_enabled: true

    # Опциональные параметры индексирования BM25 и HNSW (применяются только при создании новой коллекции)
    vdb_bm25_b: 0.75                               # нормализация по длине документа (0..1)
    vdb_bm25_k1: 1.2                               # насыщение от частоты терма
    vdb_hnsw_ef: -1                                # ef на поиске; -1 = динамический ef (баланс recall/скорость)
    vdb_hnsw_ef_construction: 128                  # ef при построении индекса (качество графа vs время индексации)
    Описание переменных в файле 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 * * *')

    Параметры гибридного поиска (опционально):

    • vdb_hybrid_search_alpha — вес вектора (1.0 = вектор, 0.0 = BM25, по умолчанию: 0.7). Рекомендуется выбирать <0.5 для технических документов и >0.5 для общего, естественного языка. Применяется, если вес вектора не указан пользователем в запросе.
    • vdb_hybrid_fusion_type — тип слияния (relative_score — по нормированным скорам, по умолчанию; ranked — по рангам (RRF))
    • vdb_rerank_enabled — включение переранжирования. Применяется, если обратное не указано пользователем в запросе (по умолчанию: true).

    Параметры индексирования BM25 и HNSW (опционально, применяются только при создании новой коллекции):

    • vdb_bm25_b — нормализация по длине документа (0..1, по умолчанию: 0.75)
    • vdb_bm25_k1 — насыщение от частоты терма (по умолчанию: 1.2)
    • vdb_hnsw_ef — ef на поиске; -1 = динамический ef (баланс recall/скорость, по умолчанию: -1)
    • vdb_hnsw_ef_construction — ef при построении индекса (качество графа vs время индексации, по умолчанию: 128)

  2. Запустите развертывание Ansible:

    ansible-playbook -i inventory/inventory.yaml deploy.yaml

  3. Проверьте работу:

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