UPS. Описание API: различия между версиями

Версия от 10:55, 21 июня 2024

Описание часто используемых параметров


Параметр	Тип	Описание
servicetype	запрос	Тип сервиса. Возможные значения: spr, smc, see, sbs, tts
servertype	запрос	Тип группы серверов. Возможные значения: trainer (серверы обучения), cluster (рабочие серверы)
model	запрос	Название модели
modeltype	запрос	Тип модели. Возможные значения: future - планируемая/черновик, current - текущая/рабочая, previous - архивная.
error	ответ	Флаг ошибки
message	ответ	Информационное сообщение

"/external modules" методы внешних модулей

В этом разделе будут методы соответствующим образом оформленных внешних модулей

/auth: методы авторизации

Метод	Описание	Входные параметры	Ответ	Пояснения
POST /auth/access	Предназначен для получения токенов доступа	username - логин password - пароль	{ "x-access-token": "XXXXXXXXXXXXXXXXXXXX", "x-refresh-token": "XXXXXXXXXXXXXXXXXXXX" }	Токен доступа определяет какие из методов будут доступны конкретному пользователю. Формируется на основании роли. Дополнительный входной параметр во всех методах, кроме перечисленных в разделе "nopassword" конфигурационного файла. Время действия токена определяется параметром auth.accessLifeTime конфигурационного файла.
POST/auth/dataset/add	Предназначен для добавления dataset (набора данных)	{ "name": "test2" }	{ "error": 0, "message": "success", "dataset_id": "XXXXXXXXXXXXX" }	dataset (набор данных) используется для ограничения доступа к данным. В ответе метод вернет id созданного набора данных
DELETE/auth/dataset/delete/{id}	Предназначен для удаления dataset (набора данных)	id - идентификатор набора данных	{ "error": 0, "message": "success" }	-
POST/auth/dataset/modify/{id}	Предназначен для переименования dataset (набора данных)	id - идентификатор набора данныхdata - JSON c новыми параметрами	{ "error": 0, "message": "success" }	Метод меняет все параметры набора данных, но на данный момент времени у набора данных кроме id только один параметр - наименование
GET/auth/datasets	Предназначен для получения списка наборов данных	-	[ {"id": "XXXXXXXXXXXXXXXXXX", "name": "XXX"}, {"id": "0", "name": "По умолчанию"} ]	-
GET/auth/refresh	Предназначен для обновления токенов доступа	x-refresh-token - токен обновления доступа	{ "x-access-token": "XXXXXXXXXXXXXXXXXXXX", "x-refresh-token": "XXXXXXXXXXXXXXXXXXXX" }	Время в течение которого можно обновить доступ регулируется параметром auth.refreshLifeTime конфигурационного файла. Служебный метод, используется в основном в вэбинтерфейсе чтобы не запрашивать лишний раз пароль
GET/auth/rights	Предназначен для получения списка прав доступа	-	<<{ "РОЛЬ": [ "GET:/......" ], "nopassword": [ "GET:/.......", ............... <<............... "POST:/......." ] }	Служебный метод - по токену получает название роли и все права доступа этой роли а также общедоступные методы
POST/auth/role/add	Предназначен для создания роли	data - JSON с параметрами роли: { "name": "проверка создания", "rights": [ "набор прав через запятую" ] }	{ "error": 0, "message": "success", "role_id": "a7e68bb83169f864c2fc868401b5250c" }	Служебный метод - используется вебинтерфейсом при создании роли
DELETE/auth/role/delete/{id}	Предназначен для удаления роли	id роли	{"error": 0,"message": "success"}	-
POST/auth/role/modify/{id}	Предназначен для изменения роли	id ролиdata - JSON с параметрами роли	{"error": 0,"message": "success"}	параметры как при создании роли. роль будет переписана
GET/auth/roles	Предназначен для получения списка ролей	-	[ { "id": "XXXXXXXXXXX", "name": "имя роли", "rights": [ "набор прав через запятую" ] }, ............ ]	-
POST /auth/user/add	Предназначен для создания нового пользователя	{ "username": "login_name", "fullname": "Отображаемое Имя","password": "XXXXX","role": "role_id", "dataset": "default dataset id", "datasets": [ "dataset id", ................. ] }	{ "error": 0, "message": "success", "user_id": "XXXXXXXXXXXXXXXX" }	-
DELETE /auth/user/delete/{id}	Предназначен для удаления пользователя	user_id
GET /auth/user/get/{id}	Предназначен для получения параметров пользователя	user_id	{ "id": "XXXXXXXXXX", "username": "loginname", "fullname": "Full Name", "role": "0", "dataset": "0", "datasets": [ "0", "2dc34d3454243522e5407d3a170815a2"] }	-
GET /auth/user/info	Предназначен для получения параметров пользователя по его токену доступа	x-access-token	{"id": "XXXXXXXXXX", "username": "loginname", "fullname": "Full Name", "role": "0", "dataset": "0", "datasets": [ "0", "2dc34d3454243522e5407d3a170815a2"] }, "rights": [ .......... ]	-
GET /auth/user/list	Предназначен для получения списка пользователей с их параметрами	-	тоже самое что и в методе GET /auth/user/info, только для всех пользователей	-
POST /auth/user/modify/{id}	Предназначен для изменения параметров пользователя	data - параметры пользователя как при создании id - идентификатор пользователя	{ "error": 0, "message": "success" }	-
POST /auth/user/password	Предназначен для смены пароля пользователя по его токену доступа	password	{ "error": 0,"message": "success" }	-
GET /auth/version	Предназначен для получения верчии UPS	-	{ "version": "4.049 beta" }	-

/lang: методы мультиязычности

Метод	Описание	Входные параметры	Ответ	Пояснения
GET /	Предназначен для вывода информации о переводе элементов интерфейса на текущий язык	-	`{` `"see":"Сущности",` `"smc":"Классификатор",` `...` `}`	-

/server: получение информации о серверах

Метод	Описание	Входные параметры	Ответ	Пояснения
GET /get/addresses/{servicetype}	Предназначен для вывода информации о сервера, обслуживающих данный сервис, а также настроеных параметров обращения к данным серверам	servicetype - тип сервиса	`{` `"trainer": "http://127.0.0.1:6181",` `"cluster": [` `"http://127.0.0.1:6181"` `],` `"timers": {` `"connect": 0.5,` `"read": 1,` `"failed": 600,` `"install": 60,` `"info": 3` `},` `"counter": 0,` `"current": 0,` `"fail": {` `"http://127.0.0.1:6181":1686295678` `}` `}`	trainer - сервер обучения cluster - рабочие серверы connect - время на подключение read - время на ответ failed - время пребывание в сбойных install - время на установку модели info - время на получение информации о модели counter - счетчик запросов current - индекс последнего опрошенного cluster-сервера fail - массив сбойных серверов со временем постановки в сбой
GET /get/models/{servicetype}/{servertype}	Предназначен для вывода информации о моделях указанного сервиса на каждом сервере указанного типа	servicetype - тип сервиса servertype - тип серверов	`{` `"http://127.0.0.1:6181": [` `"model1",` `...` `"modelN"` `],` `...` `}`	Вывод представляет собой массив url серверов, для каждого из которых указан список моделей

/model: методы работы с моделями

Метод	Описание	Входные параметры	Ответ	Пояснения
POST /model/add/{servicetype}/{model}	Предназначен для создания пустой модели в указанном сервисе. Доступно для следующих сервисов: smc, see, spr.	servicetype - тип сервиса model - название модели	`{` `"error":0,` `"message":"success"` `}`	-
POST /model/apply/{servicetype}/{model}	Предназначен для применения установленной на рабочих серверах модели. После применения модель становится доступна для штатного режима работы. Доступно для следующих сервисов: smc, see, spr.	servicetype - тип сервиса model - название модели	`{` `"error":0,` `"message":"success"` `}`	-
DELETE /model/delete/{servicetype}/{model}	Полностью удаляет модель из системы и со всех управляемых серверов. Доступно для следующих сервисов: smc, see, spr.	servicetype - тип сервиса model - название модели	`{` `"error":0,` `"message":"success"` `}`	-
GET /model/errors/{servicetype}/{model}/{modeltype}	Запрос на получение списка ошибок модели после тестирования. Если тестирования не было, то содержит ошибки проверки на обучающем корпусе. Доступен для сервисов see и smc	servicetype - тип сервиса model - название модели modeltype - тип модели	`[` `[true, predicted, phrase],` `...` `]`	содержит список вложенных списков. В каждом три значения: правильное значение, предсказанное моделью значение и начальные данные (фраза)
GET /model/export/{servicetype}/{model}/{modeltype}	метод экспортирует модель, модель скачивается в виде zip-архива	servicetype - тип сервиса model - название модели modeltype - тип модели	файл model.zip, где model - название модели	-
POST /model/handler/{servicetype}/{model}	Отправка файла-постобработчика в указанную модель типа future. Становится активным сразу после успешной отправки.	servicetype - тип сервиса model - название модели handler - файл, содержащий программный код python постобработчика	`{"error":0,` `"message":"success"` `}`	более подробно об обработчике см. руководства пользователя smc и see.
DELETE /model/handler/{servicetype}/{model}	Удаление постобработчика из модели типа future.	servicetype - тип сервиса model - название модели	`{"error":0,` `"message":"success"` `}`	более подробно об обработчике см. руководства пользователя smc и see.
GET /model/handler/{servicetype}/{model}	Получение файла-постобработчика из модели типа future.	servicetype - тип сервиса model - название модели	Файл handler.py	более подробно об обработчике см. руководства пользователя smc и see.
POST /model/handler/{servicetype}/{model}/{modeltype}	Отправка файла-постобработчика в указанную модель указанного типа. Становится активным сразу после успешной отправки.	modeltype - тип модели servicetype - тип сервиса model - название модели handler - файл, содержащий программный код python постобработчика	`{` `"error":0,` `"message":"success"` `}`	-
DELETE /model/handler/{servicetype}/{model}/{modeltype}	Удаление постобработчика в указанной модели указанного типа.	servicetype - тип сервиса model - название модели modeltype - тип модели	`{` `"error":0,` `"message":"success"` `}`
GET /model/handler/{servicetype}/{model}/{modeltype}	Получение файла-постобработчика из указанной модели указанного типа.	servicetype - тип сервиса model - название модели modeltype - тип модели	Файл handler.py
POST /model/import/{servicetype}/{model}	Импортирует модель в черновик (modeltype=future)	servicetype - тип сервиса model - название модели zip-model - zip с файлами модели	`{` `"error":0,` `"message":"success"` `}`	-
GET /model/info/{servicetype}	Получение информации о всех моделях указанного сервиса. Аналогичен методу GET /info/{servicetype}/{model}, но выводит информацию обо всех моделях.	servicetype - тип сервиса	`{` `"model1": {` `"previous": null,` `"current": null,` `"future": {` `"status": "empty",` `...` `}` `},` `...` `}`	-
GET /model/info/{servicetype}/{model}	Получение информации о каждом типе (modeltype) указанной модели.	servicetype - тип сервиса model - название модели	`{` `"previous": null,` `"current": {` `"status": "trained",` `...` `},` `"future": {` `"status": "trained",` `...` `}` `}`	Итоговый массив содержит переменные типа modeltype, в каждой из который содержится информация о модели, более подробно о которой можно прочитать в руководствах пользователя smc и see.
POST /model/install/{servicetype}/{model}	Предназначен для установки импортированной или обученной модели на рабочих серверах. Доступно для следующих сервисов: smc, see, spr.	servicetype - тип сервиса model - название модели	`{` `"error":0,` `"message":"success"` `}`
GET /model/log/{servicetype}/{model}/{modeltype}	Выводит лог обучения и тестирования модели. Доступно для следующих сервисов: smc, see.	servicetype - тип сервиса model - название модели modeltype - тип модели	`[` `"training",` `"preparing data",` `"tokenizing",` `...` `]`	-
POST /model/restore/{servicetype}/{model}	Откат модели. Делает текущую рабочую модель черновиком (future), рабочие серверы после выполнения данного метода продолжают уже с возвращенной моделью. Схематично действия над modeltype в результате выполнения данного метода можно представить так: current -> future previous -> current null -> previous	servicetype - тип сервиса model - название модели	`{"error":0,` `"message":"success"` `}`	-

/corpus: работа с данными для обучения моделей

Методы данного класса предназначены только для сервисов smc и see

Метод	Описание	Входные параметры	Ответ	Пояснения
POST /corpus/copy/{servicetype}	метод api для копирования корпуса данных	servicetype - тип сервиса srcname - текущее имя dstname - новое имя	`{` `"error": 0,` `"message": "success"` `}`	-
DELETE /corpus/delete/{servicetype}	Удаляет корпус с данными	servicetype - тип сервиса name - название корпуса	`{` `"error": 0,` `"message": "success"` `}`	-
GET /corpus/export/{servicetype}	Возвращает текстовый файл с данными, содержащий строки вида КЛАСС<TAB>ФРАЗА	servicetype - тип сервиса name - название корпуса	Файл name.txt	-
GET /corpus/get/{servicetype}	Возвращает JSON с данными корпуса	servicetype - тип сервиса name - название корпуса	`[` `[` `"generalPayments",` `"соцвыплата"` `],` `...` `]`	Список вложенных списков со значениями "Класс" и "Фраза"
POST /corpus/import/{servicetype}	Метод для импорта корпуса данных. Возможен как из текстового файла со строками вида КЛАСС<TAB>ФРАЗА (доступно для smc и see), так и из логов работы системы (только для smc). Если на вход поступил файл csv, происходит импорт из файла, в противном случае из логов.	servicetype - тип сервиса name - название корпуса csv - файл данных startDate - дата начала выборки, YYYY-MM-DD stopDate - дата окончания выборки, YYYY-MM-DD model - имя модели, из логов которой будет произведен импорт limit - числовое ограничение строк импорта	`{` `"error": 0,` `"message": "success"` `}`	-
GET /corpus/list/{servicetype}	Возвращает список всех корпусов данных для указанного типа сервиса	servicetype - тип сервиса	`[` `"корпус1",` `"корпус2",` `...` `]`	Список с названиями всех имеющихся корпусов
POST /corpus/put/{servicetype}	Перезаписывает корпус отправленным массивом данных	servicetype - тип сервиса name - название корпуса json - строка формата json с данными. Аналогична выводу метода GET /get/{servicetype}	`{` `"error": 0,` `"message": "success"` `}`	-
POST /corpus/rename/{servicetype}	Переименование корпуса	servicetype - тип сервиса srcname - текущее имя dstname - новое имя	`{` `"error": 0,` `"message": "success"` `}`	-

/spr: работа с сервисом SPR

Метод	Описание	Входные параметры	Ответ	Пояснения
GET/spr/audio/{taskID}	Метод для получения аудиофайла отложенного задания	taskID - идентификатор задания в очереди	Wav файл
GET/spr/queue	Метод для получения очереди отложенных заданий		{ "id задания": { "created": "ХХХХ-ХХ-ХХ ХХ:ХХ:ХХ", "status": "waiting", "filename": "wav" } Статусы ready - готово waiting - ожидание failed - сбой
DELETE/spr/queue/{taskID}	Метод для удаления задания из очереди	taskID - идентификатор задания в очереди	{ "error": 0, "message": "success" }
GET/spr/result/{taskID}	Метод для получения результатов распознавания отложенного задания	taskID - идентификатор задания в очереди	Вывод аналогичен выводу метода stt + добавлено поле status, которое содержит информацию о статусе отложенной задачи: ready - готово waiting - ожидание not found - не найдена failed - сбой
POST /stt/{model}	Метод для отправки файла на распознавание речи. Моно-файлы до 30 секунд распознаются без разбивки на фрагменты. Многоканальные файлы и файлы длиннее 30 секунд предварительно разбиваются на фрагменты по отсутствию речи. Настройка данных параметров описана в руководстве администратора SPR. В случае отправки переменной speakers=1, дополнительно производится поиск говорящих и получение метаданных по каждому говорящему.	model - идентификатор модели denoise - уровень шумоподавления wav - файл для распознавания speakers - опция разделения по говорящим	`{` `"model":"name",` `"text":"текст без разбивки",` `"speakers":[` `{` `"gender":"MALE",` `"age":"20-29",` `"emotion":"BORE",` `"id":"Ivan"` `}, ...` `]` `"splitted":[` `{` `"start":"00:00:02",` `"stop":"00:00:10",` `"channel":0,` `"duration":"00:00:08",` `"start_ms":2255,` `"stop_ms":10995,` `"duration_ms":8740,` `"speaker":0,` `"confidence":0.95,` `"text":"текст"` `}, ...` `]` `}`	Более подробное описание доступно в пользователя SPR.
GET/spr/waveform/{taskID}	Служебный метод для отображения аудио в графическом виде, содержит пики сигнала	taskID - идентификатор задания	{ <"error": 0, "waveform": [ 0.016, .......... .......... 0.015, 0.01 ] }

/smc: работа с сервисом SMC

Метод	Описание	Входные параметры	Ответ	Пояснения
GET /smc/classify/{model}	метод для классификации текстовой фразы	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 - отображаются группы, до которых не хватает всего одной метки, с указанием процента заполненности и сортировкой по убыванию этого процента.
GET /smc/compress	Убирает из фразы слова не влияющие на ее смысл.	text - текст для сжатия threshold - уровень компрессии от 1 до 100. Чем меньше число тем меньше слов будет в итоговой фразе	{ "text": "сжатый текст" }
GET /smc/correct	Коррекция правописания. Изменяет неправильно написанные слова меняя их на наиболее близкие правильные (из знакомых модели).	text - текст для коррекции
GET /smc/emotion	Анализ эмоций.	text - фраза для анализа эмоций	{ "emotion": "positive", "score": 0.9601 }
POST /smc/groups/{model}	Добавляет к модели группы	id - наименование модели corpus - наименование корпуса- источника групп	{ "error": 0, "message": "string" }
GET /smc/groups/{model}	Поиск групп по ранее полученным меткам.	classes - набор меток через запятую model - имя модели	{ "groups": [ { "group": "Группа 1", "intersection": 3, "classes": [ "метка1_о", "метка2_о", "метка3_о" ] }, { "group": "Группа 2", "intersection": 2, "classes": [ "метка1_о", "метка5_о" ] } ], "nearest": [ { "group": "Группа до которой не хватило 1 метки", "percent": 0.75, "need": "недостающая метка_о" } ] }	Ищет группы по набору меток. Результат - группы (если найдены) и ближайшие группы с указанием недостающих меток. Позволяет сохранять контекст в виде меток и дозапрашивать группы с учетом контекста.
GET /smc/normalize	Обратная нормализация текста	text - текст для обработки	{"text": "<строка после обратной нормализации>"}	Пример: двадцать пятого апреля в пятом часу - 25 апреля в 5-м часу
GET /smc/punctuate	Расстановка знаков препинания	text - текст для преобразования	{ "text": "string" }
POST /smc/stop/{model}	Остановка обучения модели.	model - имя модели	{ "error": 0, "message": "string" }	Удаляет тестовую версию модели с сервера обучения, тем самым прерывает обучение
POST /smc/test/{model}	Запуск тестирования модели smc	model - идентификатор модели corpus - название корпуса с данными	`{ "error": 0,` `"message": "success"` `}`	Метод асинхронный, статус тестирования можно запросить методом GET /info/{servicetype}/{model}
POST /smc/train/{model}	Запуск обучения модели future	model - идентификатор модели corpus - название корпуса с данными	`{ "error": 0,` `"message": "success"` `}`	Метод асинхронный, статус обучения можно запросить методом GET /info/{servicetype}/{model}

/see: работа с сервисом SEE

Метод	Описание	Входные параметры	Ответ	Пояснения
GET /entities/{model}	метод для поиска сущностей	model - идентификатор[ы] модели. Может быть указано несколько через запятую, тогда запрос будет обработан всеми указанными моделями text - текст similarity - порог похожести найденной сущности на эталонные, %. По умолчанию 70.	`{ID-модели: [{` `position: 0,` `confidence: 1,` `text: текст сущности,` `calculated: vaktsinatsiya` `}, {...}` `]` `}`	Вернется массив со всеми моделями, в которых были найдены сущности. Каждая переменная с названием модели будет содержать список всех найденных сущностей. position - позиция слова начала фрагмента, определяющего сущность confidence - вероятность правильного определения сущности calculated - поле, содержащее измененное постобработчиком (при его наличии) значение сущности либо код сущности, использованный при обучении модели
POST /train/{model}	Запуск обучения модели future	model - идентификатор модели corpus - название корпуса с данными noise - уровень шума для генерации синтезированных данных для обучения модели, от 1 до 5, по умолчанию 2	`{` `"error": 0,` `"message": "success"` `}`	Метод асинхронный, статус обучения можно запросить методом GET /info/{servicetype}/{model}
POST /stop/{model}	Остановка обучения модели	model - идентификатор модели	`{` `"error": 0,` `"message": "success"` `}`	-

/sbs: работа с сервисом SBS

Метод	Описание	Входные параметры	Ответ	Пояснения
POST /analyze/{model}	Получение аналитических метаданных из голосового фрагмента	model - идентификатор модели. wav - файл для анализа	`{ age: { class: 20-29, confidence: 0.99 }, emotion: { class: SADNESS, confidence: 0.99 }, gender: { class: FEMALE, confidence: 0.99 } }`	Более подробные сведения находятся в руководстве пользователя SBS.
POST /search/{model}	Поиск говорящего по базе слепков	model - идентификатор модели. wav - файл для анализа	`{ error: 0, speaker: Ivan, confidence: 0.79 }`	-
DELETE /speaker/{model}/{speaker_id}	Удаление слепка из базы	model - идентификатор модели. speaker_id - идентификатор говорящего	`{ "error": 0,` `"message": "success"` `}`	-
GET /speakers/{model}	Получение списка всех слепков в модели	model - идентификатор модели.	`[ "Kiryl","Artem", "vladimir", "Sergey", "vladimir2", "Alla" ]`	-
POST /verify/{model}/{speaker_id}	Сравнение оцифрованного представления wav-файла cо слепком в базе	model - идентификатор модели. speaker_id - идентификатор говорящего	`{"error": 0,` `"confidence": 0.78` `}`	-

/tts: методы работы с сервисом tts

Метод Описание Входные параметры Ответ Пояснения

GET

/tts/dictionary/export

Предназначен для экспорта пользовательского словаря в виде строк

-

привет прив+ет

-

GET

/tts/dictionary/get

Предназначен для экспорта пользовательского словаря в виде json

-

[ [ "привет", "прив+ет" ] ]

-

POST

/tts/dictionary/import

Предназначен для загрузки пользовательского словаря в виде строк из файла .csv

csv файл с разделителем - "табуляция"

{

"error": 0,

"message": "success",

"answers": {

"http://127.0.0.1:6186": "{\"error\": 0, \"message\": \"success\"}\n"

}

Пользовательский словарь будет переписан, не дополнен!