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

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

Сервис предназначен для поиска ответа на заданный вопрос. Входным значением для сервиса являются данные в текстовом формате. В ответ на входящий запрос сервис возвращает данные в формате 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/qas/ask	Метод генерирует ответ на поставленный вопрос на основе информации из документов в базе. Ответ на вопрос генерируется на основе информации, содержащейся в одном или нескольких документах. Документы должны быть в текстовом формате. Ответ возвращается в формате JSON, его можно скачать. Если метод не смог найти ответ, возвращается код ошибки и сообщение.
text — текст вопроса, на основе которого будут искаться фрагменты. category — id категории документа. Если не указать категорию, метод вернет ответ на основе всех документов в базе данных. channel — id канала creative — флаг креативности возможные варианты "yes" "no" useCache — использовать кешированные ответы возможные варианты: - "no" не использовать - "all" использовать все - "checked" использовать только проверенные useGPT - использовать генеративную сеть для поиска ответов в документах. возможные варианты "yes" "no" addAlias - добавлять похожие вопросы к синонимам, не создавая отдельного вопроса. возможные варианты "yes" "no"		{ "error": 0, "text": "Здесь будет текст ответа" }
POST/qas/autocache	Добавление вопросно-ответной пары в кэш. В случае указания id, answer будет принудительно добавлен в вопрос, с указанным id. Если же указан question, то система сначала попытается найти похожий вопрос и добавить ответ в него, если же вопрос не будет найден, то система создаст новый с указанной формулировкой. При установке флага emptyQuestion будет добавлен только вопрос (без ответа). Флаг addAlias отвечает за добавление/не добавление кандидата в формулировки существующего вопроса в случае, если в базе уже найден вопрос, сооветствующий указанному в question.
question - текст вопроса category - категория channel - канал answer - ответ emptyQuestion - yes или no, флаг добавления вопроса без указания ответа addAlias - yes или no, флаг добавления кандидата в формулировки существующего вопроса id - код существующего вопроса		{"error": 0, "message": "success"}
GET/qas/cachemaker/start	Генерация ответов на вопросы в кэше.
category категория для которой генерируются ответы mode - режим генерации ответов, возможные значения: paraphrase - генерирует вариации ответов перефразированием уже проверенных ответов, если таковые имеются на вопросе generate - генерирует кэш через разные ответы на каждый вопрос по документации option - variants - количество ответов, от 1 до 9		{"error": 0, "message": "success"}
GET/qas/cachemaker/status	Состояние генерации ответов на вопросы в кэше. статусы: started, stopped, если были ошибки поле ответа error будет содержать код ошибки
Входные параметры отсутствуют		{  "error": "",   "status": "started",   "progress": 33.33 }
GET/qas/cachemaker/stop	Остановить генерацию ответов на вопросы в кэше.
Входные параметры отсутствуют		{"error": 0, "message": "success"}
POST/qas/chat	Поиск ответа за пределами документов. На стадии разработки, не используется.
text - текст вопроса		Пример ответа на вопрос "как пройти в библиотеку" {"error": 0, "text": "1. Проверить время работы библиотеки (обычно от 9 до 20)\n2. Проверить местоположение библиотеки на карте или с помощью сервиса Google Maps\n3. Убедиться, что у вас есть необходимые документы для входа (паспорт, карта члена библиотеки и т.д.)\n4. Посетить библиотеку по адресу: [адрес библиотеки]\n5. Проверить правила поведения в библиотеке перед входом" }
GET/qas/chat	Поиск ответа за пределами документов. Аналогичен методу "POST/qas/chat". Не поддерживает большие тексты.На стадии разработки, не используется.
text - текст вопроса		Аналогично методу "POST/qas/chat".
GET/qas/questionlist/answers	Отображает лог массовой обработки вопросов
Входные параметры отсутствуют		на выходе : массив из объектов {   error: number;   question: string;   answer: string;   confidence: number | null; }
POST/qas/questionlist/start	Старт массовой обработки вопросов
Входные параметры отсутствуют		{error: 0 | 1, message: string}
GET/qas/questionlist/status	Статус массовой обработки вопросов
Входные параметры отсутствуют		{     error: string;      status: 'started' | 'stopped';      progress: number; }
GET/qas/questionlist/stop	Остановка массовой обработки вопросов
Входные параметры отсутствуют		{error: 0 | 1, message: string}
GET/qas/questionmaker/start	Запуск генерации вопросов для кэша. По каждому документу генерируются по 5 вопросов на фрагмент. Количество фрагментов зависят от размера документа и настройки размера контекста из конфигурационного файла. Если вопрос сильно похож на существующий, новый не создается, а добавляется к существующему в aliases.
category — категория, для которой выполнится генерация вопросов.		{error: 0 | 1, message: string}
GET/qas/questionmaker/status	Проверка состояния генерации. Статусы: started, stopped. Если были ошибки поле ответа error будет содержать код ошибки
Входные параметры отсутствуют		{  "error": "",   "status": "stopped",   "progress": 0 }
GET/qas/questionmaker/stop	Прервать генерацию.
Входные параметры отсутствуют		{error: 0 | 1, message: string}
GET/qas/search	Поиск фрагментов содержащих ответ
text — текст запроса category — категория (раздел) знаний		{  "error": 0,   "text": "   Фрагмент 1:Здесь будет текст найденного фрагмента   Фрагмент 2:Здесь будет текст найденного фрагмента",   "fragments": [     {      "id": "3a386b0a9e0e19efb0870685e1d0b484",       "title": "Заголовок документа",       "category": "Категория документа",       "text": "Здесь будет текст найденного фрагмента"    },     {      "id": "44fd73ea1ac63f32cf18d79c854dbfe2",       "title": "Заголовок документа",       "category": "Категория документа",       "text": "Здесь будет текст найденного фрагмента"    }  ] }

Метод	Тип	Описание	Входные параметры	Ответ
Группа методов 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}