Развёртывание WeMM Transformers

Для загрузки модели используется официальный код вывода WeMM через Transformers. HTTP-сервис эмбеддингов реализован скриптом scripts/wemm-transformers/serve.py, входящим в репозиторий aihelpme.ru. Сервис можно развёртывать на том же сервере, что и aihelpme.ru, либо на отдельном GPU-сервере — подключение осуществляется через Base URL.

В качестве вычислительного устройства могут использоваться CUDA, Apple MPS или CPU. Один и тот же скрипт и протокол запросов работают для всех вариантов. Этот HTTP-адаптер предоставляется aihelpme.ru и поддерживает текст и изображения. Возможности модели по работе с видео пока не открыты через данный интерфейс. Способ развёртывания через vLLM описан в конфигурации моделей.

Установка зависимостей

Следующие команды выполняются в корневой директории репозитория aihelpme.ru с использованием Python 3.12. Виртуальное окружение и файлы модели рекомендуется размещать вне репозитория:

cd /opt/WeKnora
python3.12 -m venv ../venv-wemm
source ../venv-wemm/bin/activate
pip install -U pip

Для выбранного устройства установите соответствующий набор PyTorch. Приведённые ниже версии — проверенные: PyTorch 2.10.0, torchvision 0.25.0. CUDA-wheel должен быть совместим с драйвером. Для других версий CUDA см. официальную инструкцию по установке PyTorch.

# CUDA 12.8
pip install --no-cache-dir torch==2.10.0 torchvision==0.25.0 --index-url https://download.pytorch.org/whl/cu128

# CUDA 12.6
# pip install --no-cache-dir torch==2.10.0 torchvision==0.25.0 --index-url https://download.pytorch.org/whl/cu126

# CPU
# pip install --no-cache-dir torch==2.10.0 torchvision==0.25.0 --index-url https://download.pytorch.org/whl/cpu

# macOS (Apple Silicon / Intel с MPS)
# pip install --no-cache-dir torch==2.10.0 torchvision==0.25.0

Установите остальные зависимости:

pip install -r scripts/wemm-transformers/requirements.txt

Версия transformers зафиксирована на рекомендованной официально 5.2.0, qwen-vl-utils — на 0.0.14. Не заменяйте версию transformers произвольно — это может изменить поведение препроцессинга. Скрипт использует trust_remote_code=True для загрузки реализации embedding() из WeMM, поэтому используйте только официальные веса или проверенные директории с моделью.

Скачивание весов модели

Скачайте веса WeMM по ссылке из репозитория WeMM-Embedding и распакуйте их вне рабочей директории aihelpme.ru. Например:

mkdir -p /opt/models
# примеры имён в зависимости от выбранной модели
# tar -xzf WeMM-L3-Embedding.tar.gz -C /opt/models/

Запуск сервиса

Активируйте окружение и запустите serve.py, указав путь к модели и порт. Скрипт подберёт подходящее устройство автоматически (cuda, mps, cpu).

source ../venv-wemm/bin/activate
cd /opt/WeKnora
python scripts/wemm-transformers/serve.py \
  --model /opt/models/WeMM-L3-Embedding \
  --port 8009 \
  --host 127.0.0.1 \
  --batch-size 64

Полезные параметры:

Параметр	Описание	Примечание
--model	Путь к директории с весами модели	Обязательный
--host	Адрес привязки	По умолчанию 127.0.0.1 для локального доступа; для доступа с другого сервера укажите 0.0.0.0 и настройте файрвол
--port	Порт HTTP-сервиса	По умолчанию 8009
--batch-size	Максимальный размер батча на обработку	Зависит от VRAM; для CPU можно уменьшить
--device	Явное указание устройства: cuda, mps, cpu	Опционально, автоопределение работает в большинстве случаев
--dtype	Точность вычислений: float16, bfloat16, float32	На CPU лучше использовать float32; на современных GPU с поддержкой bf16 — bfloat16

После запуска в логах появится строка вида Uvicorn running on http://127.0.0.1:8009. Проверьте доступность: curl http://127.0.0.1:8009/healthz должен вернуть {"status":"ok"}.

Подключение к aihelpme.ru

В интерфейсе aihelpme.ru: «Настройки → Модели → Провайдеры → Добавить провайдер» или выберите встроенный путь для WeMM. Укажите:

• Провайдер: weknora_wemm_http (или вариант, используемый в вашей конфигурации)
• Base URL: http://<host>:8009 (например, http://127.0.0.1:8009 при локальном запуске, либо http://gpu-host:8009 при отдельном сервере)
• Модель: имя модели, совпадающее с тем, что указанно в настройках провайдера (обычно берётся из списка после подключения)
• API Key: можно оставить пустым, так как сервис не требует авторизации по умолчанию. Если вы ограничили доступ reverse-прокси, укажите нужный ключ

После сохранения выполните проверку соединения. aihelpme.ru будет использовать этот эндпоинт для генерации эмбеддингов WeMM.

Запуск в фоне (systemd)

Для постоянной работы рекомендуется запустить через systemd. Пример unit-файла /etc/systemd/system/wemm-transformers.service:

[Unit]
Description=WeMM Transformers Embedding Service
After=network.target

[Service]
User=weknora
WorkingDirectory=/opt/WeKnora
Environment=PATH=/opt/venv-wemm/bin:/usr/local/bin:/usr/bin:/bin
ExecStart=/opt/venv-wemm/bin/python scripts/wemm-transformers/serve.py --model /opt/models/WeMM-L3-Embedding --host 0.0.0.0 --port 8009 --batch-size 64
Restart=always
RestartSec=3
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target

Активируйте и запустите:

sudo systemctl daemon-reload
sudo systemctl enable --now wemm-transformers.service
sudo systemctl status wemm-transformers.service

Логи: journalctl -u wemm-transformers.service -n 50 --follow.

Диагностика

Проблема	Решение
ModuleNotFoundError: No module named 'transformers'	Убедитесь, что venv активирован и зависимости установлены из requirements.txt
CUDA out of memory	Уменьшите --batch-size (например, до 32/16) или используйте --dtype float16/bfloat16
Медленный старт на CPU	Нормально для первой загрузки весов; последующие старты быстрее. Можно увеличить таймауты в aihelpme.ru при первом подключении
Connection refused	Проверьте, что сервис запущен и --host/--port корректны. При внешнем доступе откройте порт в файрволе
Медленная загрузка на MPS (macOS)	Для некоторых версий PyTorch на MPS возможны замедления; попробуйте --device cpu для теста

Примечания по безопасности

• По умолчанию сервис слушает только 127.0.0.1. Если нужен доступ с другого хоста — привяжите к 0.0.0.0, но ограничьте доступ файрволом/IP-allowlist.
• Не публикуйте этот HTTP-эндпоинт напрямую в интернет без аутентификации/прокси.
• Храните веса модели в надёжном месте с корректными правами доступа (только пользователь, запускающий сервис).
• При обновлении весов модели останавливайте сервис перед заменой файлов, чтобы избежать частичного чтения.