Просмотр кода страницы 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''' =====
[https://cloud.connect2ai.net/index.php/apps/files/?dir=/smc&fileid=560 Дистрибутив] распространяется в виде установочных пакетов для окружения и сервиса. Загрузите установочные пакеты на сервер и выполните команды для вашей системы в каталоге с пакетом.

Перед установкой непосредственно сервиса необходимо [[PVE. Установка сервисного пакета окружения|установить сервисный пакет окружения]].

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

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

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

<code>sudo systemctl enable smc.service && sudo systemctl start smc.service</code>

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

<code>systemctl status smc.service</code>

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



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

<code>/opt/smc/license.json</code>

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

<code>{"service": "smc", "expire": "2045-01-01", "licenses": , "key": ""}</code>

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

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

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



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

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

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

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

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

| -
|}

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


===== '''Установка моделей классификации''' =====
Модель классификации — это модель, обученная на определенном наборе данных (корпусе) и предназначенная непосредственно для классификации. Установка модели возможна запросом с помощью методов API. Методы описаны в [https://wiki.connect2ai.net/index.php/SMC._%D0%A0%D1%83%D0%BA%D0%BE%D0%B2%D0%BE%D0%B4%D1%81%D1%82%D0%B2%D0%BE_%D0%BF%D0%BE%D0%BB%D1%8C%D0%B7%D0%BE%D0%B2%D0%B0%D1%82%D0%B5%D0%BB%D1%8F руководстве пользователя]. Также модель может быть установлена копированием содержимого каталога /opt/smc/nnets/<имя модели> с одного сервера smc на другой. Внимание! При этом способе UPS, в конфигурационном файле которого указан новый smc, не увидит скопированную модель.  


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

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

Описание параметров приведено в таблице
{| class="wikitable"
|+
!Параметр
!По умолчанию
!Назначение
|-
|logs.path
|logs/
|Дерриктория для хранения логов. Примеры абсолютного пути: "/var/log/smc/"
|-
|logs.backups
|10
|Количество файлов ротации.
|-
|logs.maxSize
|5242880
|Максимальный размер файла в байтах, триггер для ротации.
|-
|noise.enabled
|true
|Детекция мусора при классификации (фраз, которые не относятся ни к одному классу)
|-
|noise.threshold
|0.7
|Порог отсева
|-
|gpu.productionModels
|true
| rowspan="8" |Флаг загрузки модели в GPU. productionModels подразумевает все рабочие модели классификации, которые создаются в системе. Остальные модели — сервисные: embeddingModel — языковая, punctuationModel — пунктуация, emotionsModel — анализ эмоций, compressorModel — модель сжатия фраз, toxicityModel — модель анализа фразы на токсичность. Можно отдельно по названию сервисной модели включать/выключать ее загрузку в GPU. Рабочие модели можно включить в память GPU только все вместе.
|-
|gpu.embeddingModel
|true
|-
|gpu.punctuationModel
|true
|-
|gpu.emotionsModel
|true
|-
|gpu.compressorModel
|true
|-
|gpu.emotionsModel
|true
|-
|gpu.toxicityModel
|true
|-
|gpu.correctionModel
|true
|}



===== '''Работа сервиса через реверс-прокси''' =====
Сервис предполагает передачу больших объемов данных через HTTP. Рекомендуем соответствующим образом настроить конфигурацию сайта в реверс-прокси. Например, в nginx дополнительные параметры:
   client_max_body_size 0;
   proxy_read_timeout 3h;
   large_client_header_buffers 8 256k;



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


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


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

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