Действия

UPS. Описание API

Материал из Флора AI

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


/auth: методы авторизации
Метод Описание Входные параметры Ответ Пояснения
POST

/auth/access

Предназначен для получения токенов доступа username - логин

password - пароль

{ 
 "x-access-token": "XXXXXXXXXXXXXXXXXXXX",
 "x-refresh-token": "XXXXXXXXXXXXXXXXXXXX"


}

Токен доступа определяет какие из методов будут доступны конкретному пользователю. Формируется на основании роли. Дополнительный входной параметр во всех методах, кроме перечисленных в разделе "nopassword" конфигурационного файла
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 только один параметр - наименование
POST/auth/datasets Предназначен для получения списка наборов данных - [

{"id": "XXXXXXXXXXXXXXXXXX",

"name": "XXX"},

{"id": "0",

"name": "По умолчанию"}

]

-
/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

/add/{servicetype}/{model}

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

Доступно для следующих сервисов: smc, see, spr.

  • servicetype - тип сервиса
  • model - название модели
 {

"error":0,

"message":"success"

}

-
POST

/install/{servicetype}/{model}

Предназначен для установки импортированной или обученной модели на рабочих серверах.

Доступно для следующих сервисов: smc, see, spr.

  • servicetype - тип сервиса
  • model - название модели
 {

"error":0,

"message":"success"

}

-
POST

/apply/{servicetype}/{model}

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

Доступно для следующих сервисов: smc, see, spr.

  • servicetype - тип сервиса
  • model - название модели
 {

"error":0,

"message":"success"

}

-
POST

/restore/{servicetype}/{model}

Откат модели. Делает текущую рабочую модель черновиком (future), рабочие серверы после выполнения данного метода продолжают уже с возвращенной моделью. Схематично действия над modeltype в результате выполнения данного метода можно представить так:
  • current -> future
  • previous -> current
  • null -> previous
  • servicetype - тип сервиса
  • model - название модели
 {"error":0,

"message":"success"

}

-
DELETE

/delete/{servicetype}/{model}

Полностью удаляет модель из системы и со всех управляемых серверов.

Доступно для следующих сервисов: smc, see, spr.

  • servicetype - тип сервиса
  • model - название модели
 {

"error":0,

"message":"success"

}

-
GET

/errors/{servicetype}/{model}/{modeltype}

Запрос на получение списка ошибок модели после тестирования. Если тестирования не было, то содержит ошибки проверки на обучающем корпусе. Доступен для сервисов see и smc
  • servicetype - тип сервиса
  • model - название модели
  • modeltype - тип модели
 [ [true, predicted, phrase],

... ]

содержит список вложенных списков. В каждом три значения: правильное значение, предсказанное моделью значение и начальные данные (фраза)
GET

/export/{servicetype}/{model}/{modeltype}

метод экспортирует модель,  модель скачивается в виде zip-архива
  • servicetype - тип сервиса
  • model - название модели
  • modeltype - тип модели
 файл model.zip, где model - название модели -
POST

/import/{servicetype}/{model}

Импортирует модель в черновик (modeltype=future)
  • servicetype - тип сервиса
  • model - название модели
  • zip-model - zip с файлами модели
 {

"error":0,

"message":"success"

}

-
GET

/info/{servicetype}/{model}

Получение информации о каждом типе (modeltype) указанной модели.
  • servicetype - тип сервиса
  • model - название модели
 {

  "previous": null,

  "current":  {

    "status": "trained",

    ...

  },

  "future": {

    "status": "trained",

    ...

  }

}

Итоговый массив содержит переменные типа modeltype, в каждой из который содержится информация о модели, более подробно о которой можно прочитать в руководствах пользователя smc и see.
GET

/info/{servicetype}

Получение информации о всех моделях указанного сервиса. Аналогичен методу GET /info/{servicetype}/{model}, но выводит информацию обо всех моделях.
  • servicetype - тип сервиса
 {

  "model1": {

    "previous": null,

    "current": null,

    "future": {

      "status": "empty",

      ...

    }

  },

  ...

}

-
GET

/log/{servicetype}/{model}/{modeltype}

Выводит лог обучения и тестирования модели. Доступно для следующих сервисов: smc, see.
  • servicetype - тип сервиса
  • model - название модели
  • modeltype - тип модели
 [

  "training",

  "preparing data",

  "tokenizing",

  ...

]

-
GET

/handler/{servicetype}/{model}

Получение файла-постобработчика из модели типа future.
  • servicetype - тип сервиса
  • model - название модели
 Файл handler.py более подробно об обработчике см. руководства пользователя smc и see.
POST

/handler/{servicetype}/{model}

Отправка файла-постобработчика в указанную модель типа future. Становится активным сразу после успешной отправки.
  • servicetype - тип сервиса
  • model - название модели
  • handler - файл, содержащий программный код python постобработчика
 {"error":0,

"message":"success"

}

более подробно об обработчике см. руководства пользователя smc и see.
DELETE

/handler/{servicetype}/{model}

Удаление постобработчика из модели типа future.
  • servicetype - тип сервиса
  • model - название модели
 {"error":0,

"message":"success"

}

более подробно об обработчике см. руководства пользователя smc и see.


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

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

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

/list/{servicetype}

Возвращает список всех корпусов данных для указанного типа сервиса
  • servicetype - тип сервиса
 [

 "корпус1",

 "корпус2",

  ...

]

Список с названиями всех имеющихся корпусов
GET/get/{servicetype} Возвращает JSON с данными корпуса
  • servicetype - тип сервиса
  • name - название корпуса
 [

  [

  "generalPayments",

    "соцвыплата"

  ],

  ...

]

Список вложенных списков со значениями "Класс" и "Фраза"
GET/export/{servicetype} Возвращает текстовый файл с данными, содержащий строки вида КЛАСС<TAB>ФРАЗА
  • servicetype - тип сервиса
  • name - название корпуса
 Файл name.txt -
DELETE/delete/{servicetype} Удаляет корпус с данными
  • servicetype - тип сервиса
  • name - название корпуса
 {

  "error": 0,

  "message": "success"

}

-
POST/put/{servicetype} Перезаписывает корпус отправленным массивом данных
  • servicetype - тип сервиса
  • name - название корпуса
  • json - строка формата json с данными. Аналогична выводу метода GET /get/{servicetype}
 {

  "error": 0,

  "message": "success"

}

-
POST/rename/{servicetype} Переименование корпуса
  • servicetype - тип сервиса
  • srcname - текущее имя
  • dstname - новое имя
 {

  "error": 0,

  "message": "success"

}

-
POST/copy/{servicetype} метод api для копирования корпуса данных
  • servicetype - тип сервиса
  • srcname - текущее имя
  • dstname - новое имя
 {

  "error": 0,

  "message": "success"

}

-
POST/import/{servicetype} Метод для импорта корпуса данных. Возможен как из текстового файла со строками вида КЛАСС<TAB>ФРАЗА (доступно для smc и see), так и из логов работы системы (только для smc). Если на вход поступил файл csv, происходит импорт из файла, в противном случае из логов.
  • servicetype - тип сервиса
  • name - название корпуса
  • csv - файл данных
  • startDate - дата начала выборки, YYYY-MM-DD
  • stopDate - дата окончания выборки, YYYY-MM-DD
  • model - имя модели, из логов которой будет произведен импорт
  • limit - числовое ограничение строк импорта
 {

  "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 - идентификатор модели
  • 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

/classify/{model}

метод для классификации текстовой фразы
  • model - идентификатор модели
  • text - текст, подлежащий классификации
  • multiclass - опция запроса нескольких классов при их наличии, если multiclass=1
 [

{ class:Appointment,

calculated:Appointment,

confidence:0.99,

start:0,

length:2

}, ...

]

Если multiclass=0 ответ будет в виде массива с одним классом, иначе - список массивов.
  • start - позиция слова начала фрагмента, определяющего класс
  • length - количество слов во фрагменте, определяющим класс
  • confidence - вероятность правильного определения класса
  • calculated - поле, содержащее измененное постобработчиком (при его наличии) значение класса.
POST

/train/{model}

Запуск обучения модели future
  • model - идентификатор модели
  • corpus - название корпуса с данными
  • 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": 0,

  "message": "success"

}

Метод асинхронный, статус обучения можно запросить методом GET

/info/{servicetype}/{model}

POST

/stop/{model}

Остановка обучения модели smc
  • model - идентификатор модели
 {  "error": 0,

  "message": "success"

}

-
POST

/test/{model}

Запуск тестирования модели smc
  • model - идентификатор модели
  • corpus - название корпуса с данными
  • confidence - уровень доверия, от 0 до 1. Порог, ниже которого класс считается неизвестным. При значении 0 происходит автоматический расчет среднего уровня доверия, которые можно потом получить методом GET /info/{servicetype}/{model}
 {  "error": 0,

  "message": "success"

}

Метод асинхронный, статус тестирования можно запросить методом GET

/info/{servicetype}/{model}

GET

/smc/groups/{model}

Получение группы по набору меток
  • classes - набор меток, разделитель - запятая
  • model - идентификатор модели
 Результат в виде json.

{ 

 "groups": [
   {
     "group": "Группа 1",
     "intersection": 3,
     "classes": [
       "метка1_о",
       "метка2_о",
       "метка3_о"
     ]
   },
   {
     "group": "Группа 2",
     "intersection": 2,
     "classes": [
       "метка1_о",
       "метка5_о"
     ]
   }
 ],
 "nearest": [
   {
     "group": "Группа до которой не хватило 1 метки",
     "percent": 0.75,
     "need": "недостающая метка_о"
   }
 ]

}

Поиск групп по ранее полученным меткам. Ищет группы по набору меток. Результат - группы (если найдены) и ближайшие группы с указанием недостающих меток.

Позволяет сохранять контекст в виде меток и дозапрашивать группы с учетом контекста. /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

/embedding/{model}

Получение оцифрованного представления говорящего
  • model - идентификатор модели.
  • wav - файл для анализа
 { error: 0, embedding: [ 0.019493144005537033, -0.08348844200372696, ... ] } -
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"

 }

}

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

/tts/dictionary/put

Предназначен для загрузки пользовательского словаря в виде json списка [ [ "привет", "прив+ет" ] ] {

"error": 0,

"message": "success",

"answers": {

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

}

}

Пользовательский словарь будет переписан, не дополнен!
/qas: методы работы с сервисом qas
Метод Описание Входные параметры Ответ Пояснения
POST

/qas/doc

Предназначен для загрузки текстового документа text title - заголовок документа

text category - категория документа

файл документа

{

"error": 0,

"message": "success",

"id": "ebe2bc57551c2d17f892987d1f62306d"

}

Добавляет документ в базу. После добавления необходимо выполнить инициализацию (/qas/reinit)
GET

/qas/doc/ask

Предназначен для получения ответа из найденных фрагментов text for search - текст запроса

text category - категория (раздел) знаний

{

"error": 0,

"text": "Здесь будет текст ответа"

}

-
GET

/qas/doc/search

Предназначен для поиска фрагментов содержащих ответ text for search - текст запроса


text category - категория (раздел) знаний

{

  "error": 0,

  "text": "

  Фрагмент 1:Здесь будет текст найденного фрагмента

  Фрагмент 2:Здесь будет текст найденного фрагмента",

  "fragments": [

    {

      "id": "3a386b0a9e0e19efb0870685e1d0b484",

      "title": "Заголовок документа",

      "category": "Категория документа",

      "text": "Здесь будет текст найденного фрагмента"

    },

    {

      "id": "44fd73ea1ac63f32cf18d79c854dbfe2",

      "title": "Заголовок документа",

      "category": "Категория документа",

      "text": "Здесь будет текст найденного фрагмента"

    }

  ]

}

-
GET

/qas/doc/{id}

Предназначен для выгрузки текста документа id - идентификатор документа {

  "error": 0,

  "text": "Здесь будет полный текст документа"

}

DELETE

/qas/doc/{id}

Предназначен для удаления документа id - идентификатор документа {"error": 0,"message": "success"} -
GET

/qas/list

Предназначен для получение списка имеющихся документов - {

  "error": 0,

  "docs": [

    {

      "id": "d4999cdee5ad1faf2cb3066ea1b5e96b",

      "title": "PVE. Установка сервисного пакета окружения",

      "category": "Техническая поддержка"

    },

    {

      "id": "759042575b965745b9d2af869bca1740",

      "title": "UPS. Руководство администратора",

      "category": "Техническая поддержка"

    }

  ]

}

GET

/qas/reinit

Предназначен для инициализации базы имеющихся документов - {"error": 0,"message": "success"} При инициализации генерируется база данных векторов по текстам документов.
/transcription: методы работы со стенографией
Метод Описание Входные параметры Ответ Пояснения
GET

/transcription/audio/{id}

Предназначен для получения аудиофайла по id стенограммы taskID - идентификатор стенограммы wav файл сохраненной стенограммы Идентификатор нужной стенограммы можно получить методом

"GET /transcription/list"

POST

/transcription/create

Предназначен для создания стенограммы из завершенного задания в очереди распознавания taskID - идентификатор задания из очереди { 
"error": 0,

"message": "success",

"id": "74721a3b-9055-4650-9afb-de4d103cafc7"

}

В ответ придет id созданной стенограммы
DELETE

/transcription/delete/{id}

Предназначен для удаления стенограммы id - идентификатор стенограммы {"error": 0,"message": "success"}
GET

/transcription/get/{id}

Предназначен для получения стенограммы id - идентификатор стенограммы стенограмма в json формате Используется для отображения стенограммы в веб интерфейсе
GET

/transcription/list

Предназначен для получения списка сохраненных стенограмм - [

{

"id": "926e8d25-4275-4a78-906b-a1109cdacbea",

"name": "название",

"model": "big",

"created": "2024-03-29 12:37:42",

"modified": "2024-04-24 16:09:09",

"user": "0",

"dataset": "0"

}

]

-
POST

/transcription/save/{id}

Предназначен для сохранения стенограмы стенограмма в json формате

id стенограммы

- Используется для сохранения изменений по нажатию кнопки "сохранить"
GET

/transcription/waveform/{id}

Служебный метод для отображения аудио в графическом виде, содержит пики сигнала id - идентификатор стенограммы { 
 <<"error": 0,
 "waveform": [
   0.016,
  ..........
  ..........
   0.015,
   0.01
 ]

}

-
Источник — https://wiki.connect2ai.net/index.php?title=UPS._Описание_API&oldid=1053