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