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

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

Метод	Тип	Описание	Входные параметры	Ответ	Примечание
/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 - отображаются группы, до которых не хватает всего одной метки, с указанием процента заполненности и сортировкой по убыванию этого процента.
/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 создание новой модели из 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/test/{id}	POST	Предназначен для тестирования модели заранее подготовленным текстовым файлом со строками вида: КЛАСС<TAB>ФРАЗА Метод асинхронный. Окончание работы проверяется через метод /smc/info/{id}.	id - идентификатор модели csv-file - файл для тестирования confidence - уровень доверия, от 0 до 1. Порог, ниже которого класс считается неизвестным. при значении 0 происходит автоматический расчет среднего уровня доверия, которые можно потом получить методом /smc/info/{id}	{ error: INT, message: DESCRIPTION }