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

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

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

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

Simple Entity Extractor (SEE) - сервис извлечения именованных сущностей.

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

Именованная сущность — слово или словосочетание, выделяющее определенный предмет или явление из ряда однотипных предметов или явлений. Например, это названия городов, стран, валют, имен.

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

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

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

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

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

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

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

  returns entities

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

GET/see/	Вывод списка моделей
Входные параметры отсутствуют		{ models: [model1,...,modelN] }
GET/see/confusion/{id}/{type}	Получение изображения матрицы ошибок
id - идентификатор модели type - тип данных для построения матрицы, только train.		Возвращает PNG изображение с матрицей ошибок
DELETE/see/data/{id}	Удаление модели
id - идентификатор модели		{ error: INT, message: DESCRIPTION }
GET/see/data/{id}	Получение архива модели
text		text
POST/see/data/{id}	Добавление модели. Метод асинхронный. Окончание работы проверяется через метод /see/info/{id}. Модель может быть добавлена следующими способами: - файл архива модели - переименование существующей модели если указана переменная from-existing-model. В данном случае происходит переименование модели на сервере from-existing-model -> id - создание новой модели из обучающего корпуса, текстового файла со строками СУЩНОСТЬ<TAB>ФРАЗА в переменной csv
id - идентификатор модели zip-model - zip-архив с файлами модели from-existing-model - название модели, которое должно быть переименовано в id csv-file - текстовый файл для обучения модели noise - уровень шума для генерации синтезированных данных для обучения модели, от 1 до 5, по умолчанию 2.		{ error: INT, message: DESCRIPTION }
GET/see/entities/{id}	Поиск сущностей. Вернется массив со всеми моделями, в которых были найдены сущности.(модели для поиска указываются в поле id) Каждая переменная с названием модели будет содержать список всех найденных сущностей.
id - идентификатор[ы] модели. Может быть указано несколько через запятую, тогда запрос будет обработан всеми указанными моделями text - текст для анализа similarity - порог похожести найденной сущности на эталонные, %. По умолчанию 70.		{ID-модели: [ {position: 0, confidence: 1, text: текст сущности, calculated: vaktsinatsiya }, {...} ]} position - позиция слова начала фрагмента, определяющего сущность confidence - вероятность правильного определения сущности calculated - поле, содержащее значение сущности либо код сущности, использованный при обучении модели
GET/see/errors/{id}	Получение файла с ошибками модели. В случае, если производилось тестирование модели, то файл содержит ошибки тестирования. Если не производилось - ошибки после обучения.
id - идентификатор модели		текстовый файл со строками вида: ИСТИНА<TAB>ОПРЕДЕЛЕНО<TAB>ФРАЗА
DELETE/see/handler/{id}	Удаление постобработчика
id - идентификатор модели		{ error: INT, message: DESCRIPTION }
GET/see/handler/{id}	Получение файла-постобработчика
id - идентификатор модели		Файл handler.py
POST/see/handler/{id}	Отправка файла-постобработчика в указанную модель. Становится активным сразу после успешной отправки.
id - идентификатор модели		{ error: INT, message: DESCRIPTION }
GET/see/info/{id}	Получение информации о модели. В результате выполнения будет возвращен массив с данными о модели. Матрица ошибок отдельно содержат классы, определяющие столбцы и строки матрицы, их количество может быть меньше, т.к. в матрицы попадают только те классы, по которым были ошибки.
id - идентификатор модели		id - идентификатор status - статус classes - список сущностей в модели entityMaxWords - максимальная длина сущности в корпусе обучения sequenceLength - максимальная длина последовательности при обучении noiseLevel - уровень шума использованный при обучении модели trainCorpusName - название файла, использованного при обучении trainAccuracy - точность обучения и тестирования testCorpusLength - размер тестового корпуса trainCorpusLength - размер обучающего корпуса trainConfusionMatrix - матрица ошибок обучения testConfusionMatrix - матрица ошибок тестирования
GET/see/log/{id}	Лог всех действий во время обучения/тестирования модели.
id - идентификатор модели		Лог содержится в переменной log в виде списка. {   <<"log": [     "training",     "macroEpoch: 1, microEpoch: 1 loss: 1.23790...",     ...   ] }

Метод	Тип	Описание	Входные параметры	Ответ
/see/	GET	Вывод списка моделей	-	{ models: [model1,...,modelN] }
/see/confusion/{id}/{type}	GET	Получение изображения матрицы ошибок	id - идентификатор модели type - тип данных для построения матрицы, только train.	Возвращает PNG изображение с матрицей ошибок
/see/data/{id}	DELETE	Удаление модели	id - идентификатор модели	{ error: INT, message: DESCRIPTION }
/see/data/{id}	POST	Добавление модели. Метод асинхронный. Окончание работы проверяется через метод /see/info/{id}. Модель может быть добавлена следующими способами: файл архива модели переименование существующей модели если указана переменная from-existing-model. В данном случае происходит переименование модели на сервере from-existing-model -> id создание новой модели из обучающего корпуса, текстового файла со строками СУЩНОСТЬ<TAB>ФРАЗА в переменной csv	id - идентификатор модели zip-model - zip-архив с файлами модели from-existing-model - название модели, которое должно быть переименовано в id csv-file - текстовый файл для обучения модели noise - уровень шума для генерации синтезированных данных для обучения модели, от 1 до 5, по умолчанию 2.	{ error: INT, message: DESCRIPTION }
/see/data/{id}	GET	Получение архива модели	id - идентификатор модели	ZIP-файл с моделью, либо { error: 1, message: DESCRIPTION }
/see/entities/{id}	GET	Поиск сущностей	id - идентификатор[ы] модели. Может быть указано несколько через запятую, тогда запрос будет обработан всеми указанными моделями text - текст для анализа similarity - порог похожести найденной сущности на эталонные, %. По умолчанию 70.	Вернется массив со всеми моделями, в которых были найдены сущности.(модели для поиска указываются в поле id) Каждая переменная с названием модели будет содержать список всех найденных сущностей. {ID-модели: [ { position: 0, confidence: 1, text: текст сущности, calculated: vaktsinatsiya }, {...} ] } position - позиция слова начала фрагмента, определяющего сущность confidence - вероятность правильного определения сущности calculated - поле, содержащее значение сущности либо код сущности, использованный при обучении модели
/see/errors/{id}	GET	Получение файла с ошибками модели. В случае, если производилось тестирование модели, то файл содержит ошибки тестирования. Если не производилось - ошибки после обучения.	id - идентификатор модели	текстовый файл со строками вида: ИСТИНА<TAB>ОПРЕДЕЛЕНО<TAB>ФРАЗА
/see/handler/{id}	DELETE	Удаление постобработчика	id - идентификатор модели	{ error: INT, message: DESCRIPTION }
/see/handler/{id}	POST	Отправка файла-постобработчика в указанную модель. Становится активным сразу после успешной отправки.	id - идентификатор модели handler - файл, содержащий программный код python постобработчика	{ error: INT, message: DESCRIPTION }
/see/handler/{id}	GET	Получение файла-постобработчика	id - идентификатор модели	Файл handler.py
/see/info/{id}	GET	Получение информации о модели.	id - идентификатор модели	В результате выполнения будет возвращен массив с данными о модели. Матрица ошибок отдельно содержат классы, определяющие столбцы и строки матрицы, их количество может быть меньше, т.к. в матрицы попадают только те классы, по которым были ошибки. id - идентификатор status - статус classes - список сущностей в модели entityMaxWords - максимальная длина сущности в корпусе обучения sequenceLength - максимальная длина последовательности при обучении noiseLevel - уровень шума использованный при обучении модели trainCorpusName - название файла, использованного при обучении trainAccuracy - точность обучения и тестирования testCorpusLength - размер тестового корпуса trainCorpusLength - размер обучающего корпуса trainConfusionMatrix - матрица ошибок обучения testConfusionMatrix - матрица ошибок тестирования
/see/log/{id}	GET	Лог всех действий во время обучения/тестирования модели.	id - идентификатор модели	Лог содержится в переменной log в виде списка. { <<"log": [ "training", "macroEpoch: 1, microEpoch: 1 loss: 1.23790...", ... ] }