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

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

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

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

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

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

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

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

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

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

Ответ сервиса представляет собой JSON-документ в кодировке UTF-8 или двоичный файл. Содержимое документа зависит от результата выполнения запроса. При наличии ошибки в качестве ответа вернется переменная error=1 и описание в переменной message. Для удобства проверки методов по ссылке http://АДРЕС:6183 будет отображен интерфейс swagger со всеми методами с возможностью их проверки. Модель может содержать постобработчик. Это стандартный файл на языке Python, который выполняет произвольные действия с результатом работы модели. Обязательным условием является наличие функции handler, которая должна возвращать данные такого же вида, как и метод GET /smc/classify/{id}.

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

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

  returns classes

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

Метод	Тип	Описание	Входные параметры	Ответ
/smc/	GET	Вывод списка моделей	-	{ models: [model1,...,modelN] }
/smc/classify/{id}	GET	Классификация текстовой фразы	id - идентификатор модели text - текст, подлежащий классификации multiclass - опция запроса нескольких классов при их наличии, если multiclass=1	Если multiclass=0 ответ будет в виде массива с одним классом, иначе - список массивов. Ниже пример такого списка. [ { class: Appointment, calculated: Appointment, confidence: 0.9993352, start: 0, length: 2 }, {...} ] start - позиция слова начала фрагмента, определяющего класс length - количество слов во фрагменте, определяющим класс confidence - вероятность правильного определения класса calculated - поле, содержащее измененное постобработчиком (при его наличии) значение класса.
/smc/confusion/{id}/{type}	GET	Получение изображения матрицы ошибок	id - идентификатор модели type - тип данных для построения матрицы, train или test	Возвращает PNG изображение с матрицей ошибок
/smc/data/{id}	GET	Получение архива модели	id - идентификатор модели	ZIP-файл с моделью, либо { error: 1, message: DESCRIPTION }
/smc/data/{id}	POST	Добавление модели. Окончание работы проверяется через метод /smc/info/{id}. Модель может быть добавлена следующими способами: файл архива модели переименование существующей модели если указана переменная from-existing-model. В данном случае происходит переименование модели на сервере from-existing-model -> id создание новой модели из обучающего корпуса, текстового файла со строками КЛАСС<TAB>ФРАЗА в переменной csv-file	id - идентификатор модели zip-model - zip-архив с файлами модели from-existing-model - название модели, которое должно быть переименовано в id csv-file - текстовый файл для обучения модели tokenizer - способ оцифровки фразы. entities или fragments. В первом случае упор делается на взаимосвязи сущностей, во втором на N-граммы normalization - уровень нормализации для устранения количественного перекоса в данных каждого класса, 0 - автоматическое определение, 1-9 - ручной режим. При увеличении значения происходит синтез данных для каждого класса. По умолчанию 1 model-size - размер структуры модели. Чем больше данных, теб больше нужна модель. 0 - автоматический режим определения структуры модели. 1-5 - ручной режим. По умолчанию 3. entity-cross-limit - от 0 до 1. Предельный коэффициент возможного наличия сущности в многих классах, выше которого сущность считается мусорной. По умолчанию 1, т.е. допуск всех найденных сущностей. entity-rare-limit - от 0 до 1. Минимальный порог повторяемости сущности в классе, ниже которого сущность считается мусорной. По умолчанию 0, т.е. допуск всех найденных сущностей.	{ error: INT, message: DESCRIPTION }
/smc/data/{id}	DELETE	Удаление модели	id - идентификатор модели	{ error: INT, message: DESCRIPTION }
/smc/errors/{id}	GET	Получение файла с ошибками модели. В случае, если производилось тестирование модели, то файл содержит ошибки тестирования. Если не производилось - ошибки после обучения.	id - идентификатор модели	текстовый файл со строками вида: ИСТИНА<TAB>ОПРЕДЕЛЕНО<TAB>ФРАЗА
/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/test/{id}	POST	Предназначен для тестирования модели заранее подготовленным текстовым файлом со строками вида: КЛАСС<TAB>ФРАЗА Метод асинхронный. Окончание работы проверяется через метод /smc/info/{id}.	id - идентификатор модели csv-file - файл для тестирования confidence - уровень доверия, от 0 до 1. Порог, ниже которого класс считается неизвестным. при значении 0 происходит автоматический расчет среднего уровня доверия, которые можно потом получить методом /smc/info/{id}	{ error: INT, message: DESCRIPTION }
/smc/handler/{id}	GET	Получение файла-постобработчика	id - идентификатор модели	Файл handler.py
/smc/handler/{id}	POST	Отправка файла-постобработчика в указанную модель. Становится активным сразу после успешной отправки.	id - идентификатор модели handler - файл, содержащий программный код python постобработчика	{ error: INT, message: DESCRIPTION }
/smc/handler/{id}	DELETE	Удаление постобработчика	id - идентификатор модели	{ error: INT, message: DESCRIPTION }