SMC. Руководство администратора

Общее описание

Сервис предназначен для анализа и классификации текстовой информации. Входным значением для сервиса являются данные в текстовом формате. В ответ на входящий запрос сервис возвращает данные в формате JSON.

Термины и определения

Simple Message Classifier (SMC) – сервис анализа и классификации.

Системные требования для SMC

Для работы smc рекомендуется использовать видеокарту NVIDIA, поддерживающую технологию CUDA и имеющую в составе ядра CUDA.

В случае отсутствия видеокарты для нормальной работы сервиса необходимо обеспечить не менее 8 потоков CPU >= 2.20GHz с поддержкой инструкций AVX2 или новее. В конфигурации 8 потоков Intel(R) Xeon(R) Gold 6148 2.40GHz 6Гб ОЗУ фраза из 10 слов классифицируется 0.2с, соответственно за секунду может быть распознано до 5 фраз, отправленных на распознавание последовательно или одновременно. Увеличение количества ядер/потоков дает прирост производительности, но не прямо пропорциональный.

Оперативной памяти необходимо не менее 4Gb.

Для обучения моделей рекомендуется использовать видеокарту. Обучение модели на корпусе размером 7500 строк занимает на ВМ с 16 ядрами, 16Гб ОЗУ и видеокартой А16 (одном из 4-х ее ядер) около 20 минут. Недостаточная мощность CPU может увеличить время обучения за счет подготовки данных.

Установка/обновление сервиса SMC

Дистрибутив распространяется в виде установочных пакетов для окружения и сервиса. Загрузите установочные пакеты на сервер и выполните команды для вашей системы в каталоге с пакетом.

Перед установкой непосредственно сервиса необходимо установить сервисный пакет окружения.

• Установка/обновление SMC осуществляется скриптом chmod +x ./smc-<версия>-<релиз>.sh && ./smc-<версия>-<релиз>.sh -i с правами администратора. Список всех ключей инсталлятора можно посмотреть, запустив инсталлятор ./smc-<версия>-<релиз>.sh без ключей.
• Загрузить последнюю версию продукта curl -s "https://repo.connect2ai.net/api/smc/new" --user '[user]:[pass]' 2>&1 | bash или в интерактивном режиме bash -c "$(curl -s https://repo.connect2ai.net/api/smc --user '[user]:[pass]' 2>&1)".
• Обновить SMC/opt/smc/inupdate в интерактивном режиме. Или запустить с ключом:
  • /opt/smc/inupdate -b – обновить до последней beta версии;
  • /opt/smc/inupdate -r – обновить до последней release версии;
  • /opt/smc/inupdate -n – обновить до последней версии (неважно beta или release).
• Установить модели /opt/smc/inmodel в интерактивном режиме.
• Проверить актуальную версию продукта curl -s "https://repo.connect2ai.net/api/smc/version.
• Посмотреть лог изменений curl -s "https://repo.connect2ai.net/api/smc/changelog" --user '[user]:[pass]'.
• Полное описание всех команд API репозитория можно найти по ссылке https://repo.connect2ai.net/api. [user]:[pass] – это тот же логин и пароль, что и от Nextcloud.
• В папке с продуктом можно добавить 2 файла конфигурации (допускается один общий файл на все продукты в папке с окружением /opt/pve/):
  • echo -n "[user]:[pass]" > /opt/smc/.userapi (это файл авторизации в API, нужен для обновления и загрузки моделей)
  • echo -n "http://example.com:3128 [user] [password]" > /opt/smc/.proxy (это файл конфигурации proxy, необходим для обновления и загрузки моделей, при отсутствующем прямом подключении к интернету)

При обновлении следующий список файлов и папок сохраняется: .userapi, .proxy, logs, nnets, config.json, cache, pretrained, pve, data. Сервис не требует остановки и возвращается в актуальное состояние после обновления.

Не забудьте запустить сервис и включить в автозапуск в системе:

sudo systemctl enable smc.service && sudo systemctl start smc.service

Удостоверьтесь, что сервис стартовал:

systemctl status smc.service

Разрешите доступ к порту 6181 на нужном интерфейсе по протоколу tcp.

Лицензия

Сервис не функционирует без действующей лицензии. Информация о лицензии хранится в файле:

/opt/smc/license.json

Файл лицензии должен соответствовать следующему формату:

{"service": "smc", "expire": "2045-01-01", "licenses": , "key": ""}

Для получения лицензии необходимо:

1. Запустить сервис systemctl start smc и извлечь UUID, указанный в файле /opt/smc/logs/log.txt

2. Передать полученный UUID руководителю проекта для оформления лицензии.

Установка сервисных моделей SMC

Установка сервисных моделей возможна только копированием файла(файлов) модели в каталог с названием модели. Названия моделей предопределены и соответствуют их назначению (compressor,  correction,  embeddings,  emotions,  normalization,  punctuation, toxicity). Установка сервисных моделей невозможна через API, в отличие от моделей классификации.

Модели располагаются в каталоге /opt/smc/pretrained/. Для установки модели необходимо создать каталог /opt/smc/pretrained/<название модели>/ и распаковать в неё архив модели, после чего перезагрузить сервис командой systemctl restart smc.

Проверить корректность работы модели пунктуации можно запросом к API с отправкой текста на распознавание:

curl -H "accept: application/json" -X GET "http://АДРЕС_СЕРВЕРА:6181/smc/punctuate?text=<текст>"

Список всех моделей представлен в таблице:

Модель	Описание	Пример запроса к модели	Пример ответа от модели
embeddings	Языковая, отвечает за вычисление векторов при обучении модели.	Проверить работу напрямую запросом к API не получится, метод не предусмотрен.	-
compressor	Модель сжатия фраз. Убирает из фразы слова, не влияющие на ее смысл.	Проверить работу можно через API запросом: curl -s  -G -X GET "http://АДРЕС_СЕРВЕРА:6181/smc/compress?threshold=30" --data-urlencode "text=как можно было бы получить выплату мне бы"  -H "accept: application/json"|jq	{ "text": "получить выплату мне бы" }
emotions	Анализ эмоций.	Проверить работу можно через API запросом: curl -s  -G -X GET "http://АДРЕС_СЕРВЕРА:6181/smc/emotion" --data-urlencode "text=спасибо все хорошо" -H "accept: application/json"|jq	{ "emotion": "positive", "score": 0.9601 }
punctuation	Пунктуация.	Проверить работу можно через API запросом: curl -s  -G -X GET "http://АДРЕС_СЕРВЕРА:6181/smc/punctuate?" --data-urlencode "text=я пришел как мне получить услугу" -H "accept: application/json"|jq	{ "text": "Я пришел. Как мне получить услугу?" }
normalization	Обратная нормализация, заменяет числа прописью на цифры. Внимание! У модели есть дополнительные требования к модулям Python в файле requirements.txt!	Проверить работу можно через API запросом: curl -s  -G -X GET "http://АДРЕС_СЕРВЕРА:6181/smc/normalize?" --data-urlencode "text=запишите меня к тринадцати" -H "accept: application/json"|jq	{"text": "запишите меня к 13-ти"}
correction	Коррекция правописания. Изменяет неправильно написанные слова, меняя их на наиболее близкие правильные (из знакомых модели).	Проверить работу можно через API запросом: curl -s  -G -X GET "http://АДРЕС_СЕРВЕРА:6181/smc/correct?" --data-urlencode "text=халодная вода" -H "accept: application/json"|jq	{"text": "холодная вода"}
toxicity	Анализ текста на невежливость, угрозы, брань.	Проверить работу можно через API запросом: curl -s  -G -X GET "http://АДРЕС_СЕРВЕРА:6181/smc/toxicity?" --data-urlencode "text=нехороший человек" -H "accept: application/json"|jq Подробнее см в руководстве пользователя.	-

ВНИМАНИЕ! Модели punctuation, embeddings, correction обязательны для установки, остальные - в зависимости от сценария использования.

Установка моделей классификации

Модель классификации — это модель, обученная на определенном наборе данных (корпусе) и предназначенная непосредственно для классификации. Установка модели возможна запросом с помощью методов API. Методы описаны в руководстве пользователя. Также модель может быть установлена копированием содержимого каталога /opt/smc/nnets/<имя модели> с одного сервера smc на другой. Внимание! При этом способе UPS, в конфигурационном файле которого указан новый smc, не увидит скопированную модель.

Конфигурирование параметров сервиса

Настройка параметров сервиса smc производится в файле /opt/smc/config.json

Описание параметров приведено в таблице

Параметр	По умолчанию	Назначение
logs.path	logs/	Директория для хранения логов. Примеры абсолютного пути: "/var/log/smc/"
logs.backups	10	Количество файлов ротации.
logs.maxSize	5242880	Максимальный размер файла в байтах, триггер для ротации.
noise.enabled	true	Детекция мусора при классификации (фраз, которые не относятся ни к одному классу)
noise.threshold	0.7	Порог отсева
cache.size.embedding	262144	Максимальный размер кэша векторов (количество записей)
cache.size.classify	32768	Максимальный размер кэша запросов классификации (количество записей)
cache.size.correction	32768	Максимальный размер кэша запросов коррекции (количество записей)
cache.size.punctuation	32768	Максимальный размер кэша запросов пунктуации (количество записей)
cache.size.similar	32768	Максимальный размер кэша запросов похожести фраз (количество записей)
cache.update	3600	Период сохранения кэша на диск (секунды)
devices.productionModel	cuda:0	Вычислительное устройство (cpu/cuda:N, где N — номер графического ускорителя), в ОЗУ которого осуществляется загрузка моделей. productionModel подразумевает все рабочие модели классификации, которые создаются в системе. Остальные модели — сервисные: embeddingModel — языковая, punctuationModel — пунктуация, emotionsModel — анализ эмоций, compressorModel — модель сжатия фраз, toxicityModel — модель анализа фразы на токсичность. Можно отдельно по названию сервисной модели включать/выключать ее загрузку в GPU. Рабочие модели можно включить в память GPU только все вместе.
devices.normalizationModel	cuda:0
devices.embeddingModel	cuda:0
devices.punctuationModel	cuda:0
devices.emotionsModel	cuda:0
devices.compressorModel	cuda:0
devices.emotionsModel	cuda:0
devices.toxicityModel	cuda:0
devices.correctionModel	cuda:0
cluster.logfile	logs/sync.log	Файл логов синхронизации есть только на главном сервере кластера
cluster.statusFile	logs/sync.status	Статус задачи синхронизации есть только на главном сервере кластера
cluster.nodes	[]	Перечень подчиненных нод для синхронизации изменений заполняется только на главном сервере кластера

Работа сервиса через реверс-прокси

Сервис предполагает передачу больших объемов данных через HTTP. Рекомендуем соответствующим образом настроить конфигурацию сайта в реверс-прокси. Например, в nginx дополнительные параметры:

  client_max_body_size 0;
  proxy_read_timeout 3h;
  large_client_header_buffers 8 256k;

Работа в составе кластера

Для высоконагруженных систем сервис можно расположить на нескольких нодах (виртуальных машинах). В этом случае, чтобы не потерять документы и изменения, полученные на одной из нод, выделяется один основной сервис и вспомогательные сервисы.

• База файловая, в папке data.
• lsync настроен через конфиг SMC для репликации базы на все указанные серверы в списке cluster.nodes: [], указываем все слейв-сервера.
• На всех слейвах список cluster.nodes: [] оставляем пустым.
• Векторная база на каждом сервере своя, она следит за своей папкой data и обновляет в оперативке по этой папке данные у себя.
• UPS при изменении данных работает только с мастером SMC, а при запросе данных — со всеми серверами cluster, распределяя нагрузку.
• В конфигурации UPS: в servers.smc.cluster.trainer указываем мастер-сервер, в servers.smc.cluster перечисляем все сервера кластера SMC, в том числе и мастер.

Сбор данных об ошибках

Логи сервиса по умолчанию находятся в файле /opt/smc/logs/log.txt

Удаление

Для удаления выполните команду: /opt/smc/uninstall. Команда деинсталлирует сервис и удалит рабочий каталог, включая все установленные модели.

Практические рекомендации

Сервис SMC в работе использует большую языковую модель, которая формирует многомерное семантическое пространство. Смысл фразы для ее классификации вычисляется на основании вектора фразы в этом пространстве. Для производительности таких вычислений рекомендуется использовать GPU с 16 Гб видеопамяти. В случае отсутствия видеокарт рекомендуется использовать не менее 3 серверов по 8 ядер и 16 Гб оперативной памяти. При этом желательно в строке запуска gunicorn в файле сервиса добавить параметр «-w 2». Это приведет к загрузке в память 2-х экземпляров приложения и моделей и позволит при высокой нагрузке полностью загрузить процессорные ядра.

В папке /opt/smc/cache/ находится кэш векторов фраз, которые были созданы моделью векторизации. При работе сервиса при наличии вектора в кэше, он берется из него, а не создается моделью заново. Причем остается в ОЗУ тоже, что значительно увеличивает производительность сервиса, однако при прохождении через сервис большого количества различных фраз может привести к потреблению нескольких гигабайт памяти. Необходимо либо увеличить количество ОЗУ, либо просто перезагружать сервис в нерабочее время. Папку cache при желании можно периодически чистить, но в данном случае кэш будет постепенно заполняться заново с использованием GPU.