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": "Здесь будет текст найденного фрагмента"    }  ] }
POST	заголовок
Вход		выход
Группа методов channel
POST/qas/channel/add	Добавление канала. В ответе id созданного канала или сообщение об ошибке
name — наименование канала		{"error": 0, "message": "success", "id": "a46fb887-5d98-41e0-8299-bcc94f615e91"}
DELETE/qas/channel/delete/{id}	Удаление канала
id — идентификатор канала		{ "error": 0, "message": "success" }
GET/qas/channel/list	Получить список всех каналов
Входные параметры отсутствуют		{  "error": 0,   "channels": [     {      "id": "1",      "name": "voice"    },     {      "id": "56442779-e871-43fd-ae4d-caf4ab6d09b9",      "name": "канал++"    },     {      "id": "0",      "name": "default"    }   ] }
POST/qas/channel/modify/{id}	Изменить канал. У канала пока есть только наименование, поэтому метод только переименовывает канал
name — новое наименование канала id — идентификатор канала		{  "error": 0,   "message": "success" }
Группа методов category
POST/qas/category/add	обавить категорию с указанным именем. В ответе - id созданной категории или сообщение об ошибке:
name — наименование категории		{  "error": 0,   "message": "success",   "id": "ad895085-2e48-439a-831e-b5f699b6a54a" }
DELETE/qas/category/delete/{id}	Удалить категорию. В ответе или сообщении об успехе, или ошибке, если категория используется или не существует.
id - идентификатор категории		{   "error": 0,   "message": "success" }
GET/qas/category/list	Получить список категорий
Входные параметры отсутствуют		В ответе json с именами и id категорий
POST/qas/category/modify/{id}	Изменить категорию. У категории пока есть только наименование, поэтому метод только переименовывает категорию
id — идентификатор категории name — наименование категории		{  "error": 0,   "message": "success" }
Группа методов doc
POST/qas/doc/add	Загрузить текстовый документ. Добавляет документ в базу. В ответе - id созданного документа или сообщение об ошибке
title — заголовок документа category — категория документа text — файл документа		{"error": 0, "message": "success", "id": "ebe2bc57551c2d17f892987d1f62306d"}
DELETE/qas/doc/delete/{id}	Удаление документа
id — идентификатор документа		{"error": 0,"message": "success"}
GET/qas/doc/get/{id}	Выгрузка текста документа
id — идентификатор документа		{   "error": 0,   "text": "Здесь будет полный текст документа" }
GET/qas/doc/list	Получение списка имеющихся документов
Входные параметры отсутствуют		Пример: {  "error": 0,   "docs": [     {id": "d4999cdee5ad1faf2cb3066ea1b5e96b",       "title": "PVE. Установка сервисного пакета окружения",       "category": "Техническая поддержка" },     {"id": "759042575b965745b9d2af869bca1740",       "title": "UPS. Руководство администратора",       "category": "Техническая поддержка"}   ]}
POST/qas/doc/modify/{id}	Обновление документа. В случае успеха метод вернет статус выполнения операции (например, «success»), в случае неудачи — код ошибки.
data — json c изменяемыми параметрами документа {   title: string,   category: string,   text: string } параметр который не меняется может отсутствовать в json id — идентификатор документа.		{"error": INT, "message": DESCRIPTION}
Группа методов question
POST/qas/question/add	Добавление вопроса. В случае успеха метод вернет id вопроса, в случае неудачи - код ошибки.
question - текст вопроса category - id категории к которой относится вопрос answers - ответы в виде Json: [ { "checked": true, "channel": "0", "answer": "ответ" } ] aliases - вопросы к которым подходят ответы из блока answers в виде json: ["вопрос","еще вопрос"]		{   "error": 0,   "id": "527be9f0-f773-4a3e-bd0b-81b40a061d0d" }
POST/qas/question/append/{id}	Добавляет алиасы/кандидаты к другому вопросу
aliases - JSON list с синонимами candidates JSON list с кандидатами id - идентификатор вопроса к которому добавить синонимы и(или) кандидаты		{error: 0 | 1, message: string}
POST/qas/question/approve/{destination_id}	Перемещает кандидаты в формулировки другого вопроса
candidates - json массив c текстами кандидатов destination_id - идентификатор вопроса		{error: 0 | 1, message: string}
POST/qas/question/delete/list	Удаление списка вопросов или ответов.
questions - json строка с перечнем id type - выбор, удалять вопросы или ответы (questions, answers)		{"error": INT, "message": DESCRIPTION}
DELETE/qas/question/delete/{id}	Удаление вопроса
id — идентификатор вопроса		{"error": INT, "message": DESCRIPTION}
GET/qas/question/get/{id}	Получение вопроса вместе с ответами и синонимами вопроса
id — идентификатор вопроса		{  "error": 0,   "answers": [     {   "checked": true,       "channel": "0",       "answer": "ответ"    }  ],   "aliases": [     "вопрос",     "синоним вопроса",     "еще синоним вопроса"  ] }
GET/qas/question/list	Получение списка вопросов.
Входные параметры отсутствуют		{  "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"    }   ] }
POST/qas/question/modify/{id}	Модификация вопроса. Позволяет заменить как все параметры так и отдельные
data - json c измененными параметрами, пример полного: {   "answers": [     {       "checked": true,       "channel": "0",       "answer": "новый ответ"     }   ], "question":"новый вопрос", "category": "a3801cc0-f8e5-4f3b-bb10-e42148cd772b",   "aliases": [     "новый вопрос",     "синоним",     "еще синоним"   ] } id — идентификатор вопроса		В случае успеха метод вернет статус выполнения операции (например, «success»), в случае неудачи — код ошибки. {"error": INT, "message": DESCRIPTION}