Просмотр кода страницы SEE. Руководство пользователя


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


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

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

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

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


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

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

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

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

<code>def handler(entities=[],text=""):</code>

<code>  returns entities</code>

На вход подается результат работы модели, а также начальный текст.
{| class="wikitable"
|+
!Метод
!Тип
!Описание
!Входные параметры
!Ответ
|-
|/see/
|GET
|Вывод списка моделей
| -
|<code>{ models: [model1,...,modelN] }</code>
|-
|/see/confusion/{id}/{type}
|GET
|Получение изображения матрицы ошибок
|'''id''' - идентификатор модели
'''type''' - тип данных для построения матрицы, только train.
|Возвращает PNG изображение с матрицей ошибок
|-
|/see/data/{id}
|DELETE
|Удаление модели
|'''id''' - идентификатор модели
|<code>{ error: INT, message: DESCRIPTION }</code>
|-
|/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.
|<code>{ error: INT, message: DESCRIPTION }</code>
|-
|/see/data/{id}
|GET
|Получение архива модели
|'''id''' - идентификатор модели
|<code>ZIP-файл с моделью, либо { error: 1, message: DESCRIPTION }</code>
|-
|/see/entities/{id}
|GET
|Поиск сущностей
|
* '''id''' - идентификатор[ы] модели. Может быть указано несколько через запятую, тогда запрос будет обработан всеми указанными моделями
* '''text''' - текст для анализа
* '''similarity''' - порог похожести найденной сущности на эталонные, %. По умолчанию 70.
|Вернется массив со всеми моделями, в которых были найдены сущности.(модели для поиска указываются в поле id) Каждая переменная с названием модели будет содержать список всех найденных сущностей.
<code>{</code><code>ID-модели: [</code>

<code>{</code>

<code>position: 0,</code>

<code>confidence: 1,</code>

<code>text: текст сущности,</code>

<code>calculated: vaktsinatsiya</code>

<code>}, {...}</code>

<code>]</code>

<code>}</code>

'''position''' - позиция слова начала фрагмента, определяющего сущность

'''confidence''' - вероятность правильного определения сущности

'''calculated''' - поле, содержащее значение сущности либо код сущности, использованный при обучении модели
|-
|/see/errors/{id}
|GET
|Получение файла с ошибками модели. В случае, если производилось тестирование модели, то файл содержит ошибки тестирования. Если не производилось - ошибки после обучения.
|'''id''' - идентификатор модели
|текстовый файл со строками вида:
ИСТИНА<TAB>ОПРЕДЕЛЕНО<TAB>ФРАЗА
|-
|/see/handler/{id}
|DELETE
|Удаление постобработчика
|'''id''' - идентификатор модели
|<code>{ error: INT, message: DESCRIPTION }</code>
|-
|/see/handler/{id}
|POST
|Отправка файла-постобработчика в указанную модель. Становится активным сразу после успешной отправки.
|
* '''id''' - идентификатор модели
* '''handler''' - файл, содержащий программный код python постобработчика
|<code>{ error: INT, message: DESCRIPTION }</code>
|-
|/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 в виде списка.
<code>{</code>
   <<"log": [
     "training",
     "macroEpoch: 1, microEpoch: 1 loss: 1.23790...",

     <code>...</code>

   <code>]</code>
<code>}</code>
|}