QAS. Руководство пользователя: различия между версиями

Версия от 11:15, 24 октября 2024

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

Сервис предназначен для поиска ответа на заданный вопрос. Входным значением для сервиса являются данные в текстовом формате. В ответ на входящий запрос сервис возвращает данные в формате JSON.

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

Question Answering System (QAS) – сервис ответов на вопросы.

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

Сервис QAS доступен по протоколу HTTP 1.1 через порт 6187/tcp. Авторизация не требуется, но все запросы должны содержать заголовок "accept: application/json". Ответ сервиса возвращается в формате JSON. Если произошла ошибка, возвращается переменная «error=1» и описание ошибки в переменной «message». Для удобства тестирования и использования методов сервиса, по адресу http://АДРЕС:6187 доступен интерфейс Swagger, который позволяет просматривать и тестировать все доступные методы из таблицы ниже.

*Описание методов API*
Группа методов qas
GET	заголовок
Вход		выход
POST	заголовок
Вход		выход
GET	заголовок
Вход		выход
GET	заголовок
Вход		выход
GET	заголовок
Вход		выход
POST	заголовок
Вход		выход
GET	заголовок
Вход		выход
GET	заголовок
Вход		выход
POST	заголовок
Вход		выход
GET	заголовок
Вход		выход
GET	заголовок
Вход		выход
GET	заголовок
Вход		выход
GET	заголовок
Вход		выход
GET	заголовок
Вход		выход
GET	заголовок
Вход		выход

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

Группа методов qas

/qas/ask

GET

Метод генерирует ответ на поставленный вопрос на основе информации из документов в базе

text - текст вопроса, на основе которого будут искаться фрагменты.
category - id категории документа. Если не указать категорию, метод вернет ответ на основе всех документов в базе данных.
channel - id канала
creative - флаг креативности возможные варианты "yes" "no"
useCache - использовать кешированные ответы

возможные варианты:

- "no" не использовать

- "all" использовать все

- "checked" использовать только проверенные

useGPT - использовать генеративную сеть для поиска ответов в документах

возможные варианты "yes" "no"

addAlias - добавлять кандидата в формулировки вопроса для последующего утверждения и использования при поиске, yes или no.

Ответ на вопрос генерируется на основе информации, содержащейся в одном или нескольких документах. Документы должны быть в текстовом формате. Ответ возвращается в формате JSON, его можно скачать. Если метод не смог найти ответ, возвращается код ошибки и сообщение.

{

"error": INT,

"answer": "ответ на вопрос"

}

/qas/autocache

POST

Метод добавления вопросно-ответной пары в кэш

question - текст вопроса
category - категория
channel - канал
answer - ответ
emptyQuestion - yes или no, флаг добавления вопроса без указания ответа
addAlias - yes или no, флаг добавления кандидата в формулировки существующего вопроса
id - код существующего вопроса

В случае указания id, answer будет принудительно добавлен в вопрос, с указанным id. Если же указан question, то система сначала попытается найти похожий вопрос и добавить ответ в него, если же вопрос не будет найден, то система создаст новый с указанной формулировкой. При установке флага emptyQuestion будет добавлен только вопрос (без ответа). Флаг addAlias отвечает за добавление/не добавление кандидата в формулировки существующего вопроса в случае, если в базе уже найден вопрос, сооветствующий указанному в question.

/qas/cachemaker/start

GET

Генерация ответов на вопросы в кэше.

category категория для которой генерируются ответы

mode - режим генерации ответов, возможные значения:

paraphrase - генерирует вариации ответов перефразированием уже проверенных ответов, если таковые имеются на вопросе

generate - генерирует кэш через разные ответы на каждый вопрос по документации

variants - количество ответов, от 1 до 9

{"error": 0, "message": "success"}

/qas/cachemaker/status

GET

Состояние генерации ответов на вопросы в кэше.

статусы: started, stopped, если были ошибки поле ответа

error будет содержать код ошибки

-

{

"error": "",

"status": "started",

"progress": 33.33

}

/qas/cachemaker/stop GET Остановить генерацию ответов на вопросы в кэше. - {"error": 0, "message": "success"}

/qas/chat

GET

Поиск ответа за пределами документов. На стадии разработки, не используется.

text - текст вопроса

Пример ответа на вопрос "как пройти в библиотеку"

{

"error": 0,

"text": "1. Проверить время работы библиотеки (обычно от 9 до 20)\n2. Проверить местоположение библиотеки на карте или с помощью сервиса Google Maps\n3. Убедиться, что у вас есть необходимые документы для входа (паспорт, карта члена библиотеки и т.д.)\n4. Посетить библиотеку по адресу: [адрес библиотеки]\n5. Проверить правила поведения в библиотеке перед входом"

}

/qas/questionmaker/start

GET

Запуск генерации вопросов для кэша. По каждому документу генерируются по 5 вопросов на фрагмент. Количество фрагментов зависят от размера документа и настройки размера контекста из конфигурационного файла. Если вопрос сильно похож на существующий - новый не создается, а добавляется к существующему в aliases

category - id категории для которой генерируются вопросы

{ "error": 0, "message": "success" }

/qas/questionmaker/status

GET

Проверка состояния генерации - started, stopped, если были ошибки поле ответа error будет содержать код ошибки

-

{

"error": "",

"status": "stopped",

"progress": 0

}

/qas/questionmaker/stop GET Прервать генерацию. {"error": 0, "message": "success"}

/qas/search

GET

Поиск фрагмента (фрагментов) в документах, предварительно загруженных в БД, указанной категории по заданному вопросу

text - текст вопроса, на основе которого будут искаться фрагменты.
category - категория документа. Если не указать категорию, метод будет искать ближайшие фрагменты во всех документах в базе данных.

На выходе 2 фрагмента из документа указанной категории. Поиск нужного фрагмента осуществляется с помощью векторизации: выбирается ближайшее предложение по вектору из текста, добавляются по 5 фраз до и после фразы-вопроса — это и является результатом работы метода в формате JSON, его так же можно скачать. В случае ошибки возвращается информация об ошибке.

Группа методов qas/channel (channel operations)

/qas/channel/add

POST

Добавление канала

name - наименование канала

{

"error": 0,

"message": "success",

"id": "a46fb887-5d98-41e0-8299-bcc94f615e91"

}

/qas/channel/delete/{id}

DELETE

Удаление канала

id - идентификатор канала

{

"error": 0, "message": "success" }

/qas/channel/list

GET

Получить список всех каналов

{

"error": 0,

"channels": [

{

"id": "1",

"name": "voice"

},

{

"id": "56442779-e871-43fd-ae4d-caf4ab6d09b9",

"name": "канал++"

},

{

"id": "0",

"name": "default"

}

]

}

/qas/channel/modify/{id}

POST

Изменить канал. У канала пока есть только наименование, поэтому метод только переименовывает канал

name - новое наименование канала
id - идентификатор канала

{

"error": 0,

"message": "success"

}

Группа методов qas/category (category operations)

/qas/category/add

POST

Добавить категорию с указанным именем

name - наименование категории

В ответе - id созданной категории или сообщение об ошибке:

{

"error": 0,

"message": "success",

"id": "ad895085-2e48-439a-831e-b5f699b6a54a"

}

/qas/category/delete/{id}

DELETE

Удалить категорию

id - идентификатор категории

В ответе или сообщение об успехе или ошибке если категория используется или не существует

{

"error": 0,

"message": "success"

}

/qas/category/list GET Получить список категорий - В ответе json с именами и id категорий

/qas/category/modify/{id}

POST

Изменить категорию. У категории пока есть только наименование, поэтому метод только переименовывает категорию

id - идентификатор категории
name - наименование категории

{

"error": 0,

"message": "success"

}

Группа методов qas/doc (document operations)

/qas/doc/add

POST

Метод используется для добавления нового документа в базу данных. Загружаемый файл должен быть в формате txt, в кодировке Unicode UTF-8

title - заголовок файла.
category - категория документа.
text - поле для загрузки файла.

Успешное выполнение метода возвращает сообщение об успешном добавлении файла и присвоенном ему идентификатору.

Пример ответа: {"error": 0, "message": "success", "id": "92da6b1968616db4e8d3981c62e0f71f"}

/qas/doc/delete/{id}

DELETE

Метод предназначен для удаления документа из базы по его id

id - идентификатор документа.

В случае успеха метод вернет статус выполнения операции (например, “success”), в случае неудачи - код ошибки.

{"error": INT, "message": DESCRIPTION}

/qas/doc/get/{id}

GET

Метод возвращает текст документа из базы данных по его идентификатору

id - идентификатор документа.

На выходе полный текст документа, соответствующий указанному идентификатору. При успешном выполнении метода выдается тест документа в формате JSON. В случае отсутствия документа с указанным идентификатором появится сообщение об ошибке:

{ "error": 1, "message": "text not found"}

/qas/doc/list

GET

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

-

Возвращает список объектов, где каждый объект содержит следующие поля:

id - идентификатор документа;
title - заголовок файла;
category - категория документа.

Пример ответа:

[
  {
    "id": "Идентификатор документа",
    "title": "Название документа",
    "category": "Категория документа"
  },
  {
    "id": "Идентификатор документа",
    "title": "Название документа",
    "category": "Категория документа"

},

......

]

/qas/doc/modify/{id}

POST

Метод для обновления документа

data - json c изменяемыми параметрами документа{

title: string,

category: string,

text: string

}

параметр который не меняется может отсутствовать в json

id - идентификатор документа.

В случае успеха метод вернет статус выполнения операции (например, “success”), в случае неудачи - код ошибки.

{"error": INT, "message": DESCRIPTION}

Группа методов qas/question (question cache operations)

/qas/question/add

POST

Метод для добавления вопроса

question - текст вопроса
category - id категории к которой относится вопрос
answers - ответы в виде Json:

[ { "checked": true, "channel": "0", "answer": "ответ" } ]

aliases - вопросы к которым подходят ответы из блока answers в виде json:

["вопрос","еще вопрос"]

В случае успеха метод вернет id вопроса, в случае неудачи - код ошибки.

{

"error": 0,

"id": "527be9f0-f773-4a3e-bd0b-81b40a061d0d"

}

/qas/question/delete/{id}

DELETE

Метод для удаления вопроса

id - идентификатор вопроса

В случае успеха метод вернет статус выполнения операции (например, “success”), в случае неудачи - код ошибки.

{"error": INT, "message": DESCRIPTION}

/qas/question/get/{id}

GET

Метод для получения вопроса вместе с ответами и синонимами вопроса

id - идентификатор вопроса

{

"error": 0,

"answers": [

{

"checked": true,

"channel": "0",

"answer": "ответ"

}

],

"aliases": [

"вопрос",

"синоним вопроса",

"еще синоним вопроса"

]

}

/qas/question/list

GET

Метод для получения списка вопросов.

-

{

"error": 0,

"questions": [

{

"id": "77b42c9b-2075-4a5f-b6d9-a284bba7cf43",

"question": "вопрос",

"category": "9580b3b7-34cb-4d0e-ba75-d17313ead16d"

},

{

"id": "d1836e5e-010e-4f3a-b306-813c3acb7efb",

"question": "n-й второй вопрос",

"category": "7d8a3415-cb09-4dad-a169-478ba15ade47"

}

]

}

/qas/question/modify/{id}

POST

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

data - json c измененными параметрами, пример полного:

{ "answers": [

{

"checked": true,

"channel": "0",

"answer": "новый ответ"

}

],

"question":"новый вопрос",

"category": "a3801cc0-f8e5-4f3b-bb10-e42148cd772b",

"aliases": [

"новый вопрос",

"синоним",

"еще синоним"

]

}

id - идентификатор вопроса

В случае успеха метод вернет статус выполнения операции (например, “success”), в случае неудачи - код ошибки. `{"error": INT, "message": DESCRIPTION}`

@@ Строка 11: / Строка 11: @@
 ==== '''Описание методов API''' ====
 Сервис QAS доступен по протоколу HTTP 1.1 через порт 6187/tcp. Авторизация не требуется, но все запросы должны содержать заголовок <code>"accept: application/json"</code>. Ответ сервиса возвращается в формате JSON. Если произошла ошибка, возвращается переменная «error=1» и описание ошибки в переменной «message». Для удобства тестирования и использования методов сервиса, по адресу <nowiki>http://АДРЕС:6187</nowiki> доступен интерфейс Swagger, который позволяет просматривать и тестировать все доступные методы из таблицы ниже.
+{| class="wikitable" style="width: 110%"
+|+''Описание методов API''
+|-
+! colspan="4" |Группа методов qas
+|-
+! style="color:blue;width: 15%" |'''GET'''
+! colspan="3" style="width: 85%" |заголовок
+|-
+| colspan="2" style="width: 50%" |<small>Вход</small>
+| colspan="2" style="width: 50%" |<small>выход</small>
+|-
+! style="color:green;width: 15%" |'''POST'''
+! colspan="3" style="width: 85%" |заголовок
+|-
+| colspan="2" style="width: 50%" |<small>Вход</small>
+| colspan="2" style="width: 50%" |<small>выход</small>
+|-
+! style="color:blue;width: 15%" |'''GET'''
+! colspan="3" style="width: 85%" |заголовок
+|-
+| colspan="2" style="width: 50%" |<small>Вход</small>
+| colspan="2" style="width: 50%" |<small>выход</small>
+|-
+! style="color:blue;width: 15%" |'''GET'''
+! colspan="3" style="width: 85%" |заголовок
+|-
+| colspan="2" style="width: 50%" |<small>Вход</small>
+| colspan="2" style="width: 50%" |<small>выход</small>
+|-
+! style="color:blue;width: 15%" |'''GET'''
+! colspan="3" style="width: 85%" |заголовок
+|-
+| colspan="2" style="width: 50%" |<small>Вход</small>
+| colspan="2" style="width: 50%" |<small>выход</small>
+|-
+! style="color:green;width: 15%" |'''POST'''
+! colspan="3" style="width: 85%" |заголовок
+|-
+| colspan="2" style="width: 50%" |<small>Вход</small>
+| colspan="2" style="width: 50%" |<small>выход</small>
+|-
+! style="color:blue;width: 15%" |'''GET'''
+! colspan="3" style="width: 85%" |заголовок
+|-
+| colspan="2" style="width: 50%" |<small>Вход</small>
+| colspan="2" style="width: 50%" |<small>выход</small>
+|-
+! style="color:blue;width: 15%" |'''GET'''
+! colspan="3" style="width: 85%" |заголовок
+|-
+| colspan="2" style="width: 50%" |<small>Вход</small>
+| colspan="2" style="width: 50%" |<small>выход</small>
+|-
+! style="color:green;width: 15%" |'''POST'''
+! colspan="3" style="width: 85%" |заголовок
+|-
+| colspan="2" style="width: 50%" |<small>Вход</small>
+| colspan="2" style="width: 50%" |<small>выход</small>
+|-
+! style="color:blue;width: 15%" |'''GET'''
+! colspan="3" style="width: 85%" |заголовок
+|-
+| colspan="2" style="width: 50%" |<small>Вход</small>
+| colspan="2" style="width: 50%" |<small>выход</small>
+|-
+! style="color:blue;width: 15%" |'''GET'''
+! colspan="3" style="width: 85%" |заголовок
+|-
+| colspan="2" style="width: 50%" |<small>Вход</small>
+| colspan="2" style="width: 50%" |<small>выход</small>
+|-
+! style="color:blue;width: 15%" |'''GET'''
+! colspan="3" style="width: 85%" |заголовок
+|-
+| colspan="2" style="width: 50%" |<small>Вход</small>
+| colspan="2" style="width: 50%" |<small>выход</small>
+|-
+! style="color:blue;width: 15%" |'''GET'''
+! colspan="3" style="width: 85%" |заголовок
+|-
+| colspan="2" style="width: 50%" |<small>Вход</small>
+| colspan="2" style="width: 50%" |<small>выход</small>
+|-
+! style="color:blue;width: 15%" |'''GET'''
+! colspan="3" style="width: 85%" |заголовок
+|-
+| colspan="2" style="width: 50%" |<small>Вход</small>
+| colspan="2" style="width: 50%" |<small>выход</small>
+|-
+! style="color:blue;width: 15%" |'''GET'''
+! colspan="3" style="width: 85%" |заголовок
+|-
+| colspan="2" style="width: 50%" |<small>Вход</small>
+| colspan="2" style="width: 50%" |<small>выход</small>
+|}
 {| class="wikitable"

QAS. Руководство пользователя: различия между версиями

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

Версия от 11:15, 24 октября 2024

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

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

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