SMC. Руководство пользователя

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

Сервис Short  Message Classifier предназначен для классификации текстовых фрагментов (фраз естественной речи). Принимает на вход текстовую строку и возвращает структурированные данные в формате JSON.

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

Short  Message Classifier (SMC) - сервис классификации текстовых фрагментов.

Модель — предварительно обученная специализированная нейронная сеть классификации коротких фраз.

Swagger UI – интерактивная  веб-консоль с кратким описанием методов АPI и возможностью выполнять запросы к сервису SMC.

Описание методов API SMC

Запросы осуществляются по протоколу HTTP 1.1 на адрес сервера с доступным сервисом SMC. По умолчанию используется порт 6181/tcp.

Авторизация запросов не требуется. HTTP-запросы должны содержать заголовок "accept: application/json"

Ответ сервиса представляет собой JSON-документ в кодировке UTF-8 или двоичный файл. Содержимое документа зависит от результата выполнения запроса. При наличии ошибки в качестве ответа вернется переменная error=1 и описание в переменной message. Для удобства проверки методов по ссылке http://АДРЕС:6181 будет отображен интерфейс swagger со всеми методами с возможностью их проверки.

Постобработка

Модель может содержать постобработчик. Это стандартный файл на языке Python, который выполняет произвольные действия с результатом работы модели. Обязательным условием является наличие функции handler, которая должна возвращать данные такого же вида, как и метод GET /smc/classify/{id}.

Пример пустой функции:

def handler(classes=[],text=""):

  returns classes

На вход подается результат работы модели, а также начальный текст.

GET/smc/	Вывод списка моделей
GET/smc/automark/list	Список заданий на автоматическую разметку корпуса
GET/smc/automark/result/{id}	Получить результат задания на автоматическую разметку корпуса
POST/smc/automark/start	Начать автоматическую разметку корпуса
GET/smc/automark/status/{id}	Получить статус задания на автоматическую разметку корпуса
GET/smc/automark/stop/{id}	Прервать задание на автоматическую разметку корпуса
GET/smc/classify/{id}	Классификация текстовой фразы
GET/smc/compress	Убирает из фразы слова не влияющие на ее смысл.
GET/smc/confusion/{id}/{type}	Получение изображения матрицы ошибок
GET/smc/correct	Коррекция правописания. Изменяет неправильно написанные слова меняя их на наиболее близкие правильные (из знакомых модели).
GET/smc/data/{id}	Получение архива модели
DELETE/smc/data/{id}	Удаление модели
POST/smc/data/{id}	Добавление модели.
GET/smc/emotion	Анализ эмоций.
GET/smc/errors/{id}	Получение файла с ошибками модели.
GET/smc/groups/{id}	Поиск групп по ранее полученным меткам.
POST/smc/groups/{id}	Добавляет к модели группы
GET/smc/handler/{id}	Получает постобработчик модели
DELETE/smc/handler/{id}	Удаляет постобработчик модели
POST/smc/handler/{id}	Устанавливает постобработчик модели
GET/smc/info/{id}	Получение информации о модели.
GET/smc/log/{id}	Лог всех действий во время обучения/тестирования модели.
GET/smc/normalize	Обратная нормализация текста
GET/smc/punctuate	Расстановка знаков препинания
POST/smc/search	Поиск фразы в тексте
POST/smc/test/{id}	Тестирование модели. Тестируется заранее подготовленным текстовым файлом со строками вида: КЛАСС<TAB>ФРАЗА Метод асинхронный. Окончание работы проверяется через метод /smc/info/{id}.
GET/smc/toxicity	Определение токсичности высказывания

Метод	Тип	Описание	Входные параметры	Ответ	Примечание
/smc/	GET	Вывод списка моделей	-	{ models: [model1,...,modelN] }	Выводит только пользовательские модели, сервисные модели, корпуса, наборы меток - не выводит.
/smc/automark/list	GET	Список заданий на автоматическую разметку корпуса	-	{   "error": 0,   "message": "success",   "tasks": [     {       "id": "id-1",       "taskname": "name1",       "status": "finished"     },     {       "id": "id-nnnn",       "taskname": "name2",       "status": "finished"     }   ] }	Метод для использования сервисом ups
/smc/automark/result/{id}	GET	Получить результат задания на автоматическую разметку корпуса	id - идентификатор задания	{   "error": 0,   "message": "success",   "started": "2024-10-09 18:05:51",   "finished": "2024-10-09 18:05:51",   "corpus": [[ [], [ ["тэг"],"фраза 1"]],     [ [], [["тэг"],"фраза 2"]] ] }	Метод для использования сервисом ups
/smc/automark/start	POST	Начать автоматическую разметку корпуса	taskname - произвольное имя задания corpus - json строка с размечаемым корпусом[ [ [класс1,... классН], текст ], [ [класс1,... классН], текст ] ] marks - json строка с набором меток [    [ метка, [синоним, синоним2 ... синоним Н], порог ], [ метка, [синоним, синоним2 ... синоним Н], порог ], ] appendMarks - "yes" - дополнить разметку "no" -заменить разметку	{   "error": 0,   "message": "success",   "id": "уникальный id задания" }	Метод для использования сервисом ups.
/smc/automark/status/{id}	GET	Получить статус задания на автоматическую разметку корпуса	id - идентификатор задания	{   "error": "",   "status": "finished",   "started": "2024-10-09 13:49:46",   "finished": "2024-10-09 13:49:46",   "progress": 0 }	Метод для использования сервисом ups.
GET /smc/automark/stop/{id}	GET /smc/automark/stop/{id}	Прервать задание на автоматическую разметку корпуса	id - идентификатор задания	{   "error": 0,   "message": "success" }	Метод для использования сервисом ups.
/smc/classify/{id}	GET	Классификация текстовой фразы	id - идентификатор модели text - текст, подлежащий классификации confidenceThreshold, % - минимальный порог доверия.	{   "classes": [     {       "class": "название класса",       "confidence": 1     },     {       "class": "название класса 2",       "confidence": 1     }   ],   "groups": [     {       "group": "название группы 1",       "intersection": 2,       "classes": [         "название класса",         "название класса 2"       ]     }   ],   "nearest": [     {       "group": "название группы 2",       "percent": 0.6666666666666666,       "need": "название класса которого не хватило 1"     },     {       "group": ""название группы 3",       "percent": 0.6666666666666666,       "need": "название класса которого не хватило 2"     }   ] }	classes - список , для каждого класса которого отображается название класса, к которому был отнесен текст, и вероятность его принадлежности к этому классу. groups - название группы и число совпавших классов. Если метки совпадают с несколькими группами, они отображаются в порядке убывания числа совпавших классов (т.е. чем полнее группа, тем выше ее позиция в списке). nearest - отображаются группы, до которых не хватает всего одной метки, с указанием процента заполненности и сортировкой по убыванию этого процента. В случает если модель была создана из меток в ответе groups и nearesn будут пустыми, а ответ будет построен без учета confidenceThreshold из запроса.
/smc/compress	GET	Убирает из фразы слова не влияющие на ее смысл.	text - текст для сжатия threshold - уровень компрессии от 1 до 100. Чем меньше число тем меньше слов будет в итоговой фразе	{   "text": "сжатый текст" }
/smc/confusion/{id}/{type}	GET	Получение изображения матрицы ошибок	id - идентификатор модели type - тип данных для построения матрицы, train или test	Возвращает PNG изображение с матрицей ошибок
/smc/correct	GET	Коррекция правописания. Изменяет неправильно написанные слова меняя их на наиболее близкие правильные (из знакомых модели).	text - текст для коррекции	{   "text": "корректный текст" }	Если модель коррекции не смогла предложить правильное написание текста, метод вернет текст неизменным.
/smc/data/{id}	GET	Получение архива модели	id - идентификатор модели	ZIP-файл с моделью, либо { error: 1, message: DESCRIPTION }
/smc/data/{id}	DELETE	Удаление модели	id - идентификатор модели	{ error: INT, message: DESCRIPTION }
/smc/data/{id}	POST	Добавление модели.	id - идентификатор модели zip-model - zip-архив с файлами модели from-existing-model - название модели, которое должно быть переименовано в id csv-file - текстовый файл для обучения модели или json файл с метками isMarks - если "1" то вместо csv файла корпуса метод ожидает json файл с метками	{ error: INT, message: DESCRIPTION }	Окончание работы проверяется через метод /smc/info/{id}. Модель может быть добавлена следующими способами: файл архива модели переименование существующей модели если указана переменная from-existing-model. В данном случае происходит переименование модели на сервере from-existing-model -> id создание новой модели из обучающего корпуса, текстового файла со строками классов: класс,класс2,..классN<TAB>ФРАЗА<TAB><data> и строками групп: класс,класс2,..классN<TAB>группа<TAB><group> в переменной csv-file При обучении файл корпуса копируется в папку /opt/smc/cache создание новой модели из json файла с метками, формат файла: {"id": "уникальный идентификатор", "name": "имя набора", "data": [ ["метка1",["синоним1", "еще несколько синонимов через запятую"],порог достоверности], ["еще метка",["синоним", "еще несколько синонимов через запятую"],порог достоверности] ]} модель созданная из меток при этом не обучается, созданный файл модели используется для расчетов векторов "на лету" и выдачи результатов на основании сравнения векторов текста и синонимов из файла с метками
/smc/emotion	GET	Анализ эмоций.	text - фраза для анализа эмоций	{ "emotion": "positive", "score": 0.9601 }
/smc/errors/{id}	GET	Получение файла с ошибками модели.	id - идентификатор модели	текстовый файл со строками вида: ИСТИНА<TAB>ОПРЕДЕЛЕНО<TAB>ФРАЗА	В случае, если производилось тестирование модели, то файл содержит ошибки тестирования. Если не производилось - ошибки после обучения.
/smc/groups/{id}	GET	Поиск групп по ранее полученным меткам.	id - идентификатор модели	Результат в виде json. { "groups": [ { "group": "Группа 1", "intersection": 3, "classes": [ "метка1_о", "метка2_о", "метка3_о" ] }, { "group": "Группа 2", "intersection": 2, "classes": [ "метка1_о", "метка5_о" ] } ], "nearest": [ { "group": "Группа до которой не хватило 1 метки", "percent": 0.75, "need": "недостающая метка_о" } ] }	Ищет группы по набору меток. Результат - группы (если найдены) и ближайшие группы с указанием недостающих меток. Позволяет сохранять контекст в виде меток и дозапрашивать группы с учетом контекста.
/smc/groups/{id}	POST	Добавляет к модели группы	id - наименование модели csv-file - файл с группами	{   "error": 0,   "message": "string" }
/smc/handler/{id}	GET	Получает постобработчик модели	id - наименование модели	Файл программы обработчика на python
/smc/handler/{id}	DELETE	Удаляет постобработчик модели	id - наименование модели	{   "error": 0,   "message": "string" }
/smc/handler/{id}	POST	Устанавливает постобработчик модели	id - наименование модели handler - файл постобработчика	{   "error": 0,   "message": "string" }
/smc/info/{id}	GET	Получение информации о модели.	id - идентификатор модели	В результате выполнения будет возвращен массив с данными о модели. Матрица ошибок отдельно содержат классы, определяющие столбцы и строки матрицы, их количество может быть меньше, т.к. в матрицы попадают только те классы, по которым были ошибки. id - идентификатор status - статус classes - список классов в модели confidenceLevel - средний уровень достоверности определения класса, рассчитывается при тестировании sequenceLength - максимальная длина последовательности при обучении normalization, nerCrossLimit, nerRareLimit, modelSize - параметры, использованные при обучении модели trainCorpusName, testCorpusName - названия файлов, использованных при обучении и тестировании trainAccuracy, testAccuracy - точность обучения и тестирования initCorpusLength - начальный размер корпуса обучения trainCorpusLength - размер корпуса после нормализации и синтеза данных testCorpusLength - размер тестового корпуса trainConfusionMatrix - матрица ошибок обучения testConfusionMatrix - матрица ошибок тестирования
/smc/log/{id}	GET	Лог всех действий во время обучения/тестирования модели.	id - идентификатор модели	Лог содержится в переменной log в виде списка. { "log": [ "training", "normalization: 5, model size: 2", "training", "preparing data", "tokenizing", "data loaded", "training entities", "Warmup, corpus length 24965", ... ] }
/smc/normalize	GET	Обратная нормализация текста	text - текст для обработки	{"text": "<строка после обратной нормализации>"}	Пример: двадцать пятого апреля в пятом часу -> 25 апреля в 5-м часу
/smc/punctuate	GET	Расстановка знаков препинания	text - текст для преобразования	{   "text": "string" }
/smc/search	POST	Поиск фразы в тексте	phrase text	{   "error": 0,   "message": "success",   "similarity": 1,   "fragment": "найденная фраза" }
/smc/test/{id}	POST	Предназначен для тестирования модели заранее подготовленным текстовым файлом со строками вида: КЛАСС<TAB>ФРАЗА Метод асинхронный. Окончание работы проверяется через метод /smc/info/{id}.	id - идентификатор модели csv-file - файл для тестирования confidence - уровень доверия, от 0 до 1. Порог, ниже которого класс считается неизвестным. при значении 0 происходит автоматический расчет среднего уровня доверия, которые можно потом получить методом /smc/info/{id}	{ error: INT, message: DESCRIPTION }
/smc/toxicity	GET	Определение токсичности высказывания	text - текстовая строка с высказыванием	{   "insult": 0.13,   "obscenity": 0,   "threat": 0,   "politeness": 0.53 }	Высказывание анализируется по 4 параметрам, по каждому выдается вероятность от 0 до 1: "оскорбление": 0.13, "непристойность": 0, "угроза": 0, "вежливость": 0.53