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

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

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

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

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

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

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

Метод	Тип	Описание	Входные параметры	Ответ
/qas/ask	GET	Метод генерирует ответ на поставленный вопрос на основе информации из документов в базе	text - текст вопроса, на основе которого будут искаться фрагменты. category - Категория документа. Если не указать категорию, метод вернет ответ на основе всех документов в базе данных.	Ответ на вопрос генерируется на основе информации, содержащейся в одном или нескольких документах. Документы должны быть в текстовом формате. Ответ возвращается в формате JSON, его можно скачать. Если метод не смог найти ответ, возвращается код ошибки и сообщение. { "error": INT, "answer": "ответ на вопрос"}
/qas/autocache	POST	Принимает правки кеша с другого сервера	question - текст вопроса category - категория channel - канал answer - ответ
/qas/chat	GET	Поиск ответа за пределами документов. На стадии разработки, не используется.	text - текст вопроса	Пример ответа на вопрос "как пройти в библиотеку" { "error": 0, "text": "1. Проверить время работы библиотеки (обычно от 9 до 20)\n2. Проверить местоположение библиотеки на карте или с помощью сервиса Google Maps\n3. Убедиться, что у вас есть необходимые документы для входа (паспорт, карта члена библиотеки и т.д.)\n4. Посетить библиотеку по адресу: [адрес библиотеки]\n5. Проверить правила поведения в библиотеке перед входом" }
/qas/search	GET	Поиск фрагмента (фрагментов) в документах, предварительно загруженных в БД, указанной категории по заданному вопросу	text - текст вопроса, на основе которого будут искаться фрагменты. category - категория документа. Если не указать категорию, метод будет искать ближайшие фрагменты во всех документах в базе данных.	На выходе 2 фрагмента из документа указанной категории. Поиск нужного фрагмента осуществляется с помощью векторизации: выбирается ближайшее предложение по вектору из текста, добавляются по 5 фраз до и после фразы-вопроса — это и является результатом работы метода в формате JSON, его так же можно скачать. В случае ошибки возвращается информация об ошибке.
/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" }
				{ "error": 0, "channels": [ { "id": "1", "name": "voice" }, { "id": "56442779-e871-43fd-ae4d-caf4ab6d09b9", "name": "канал++" }, { "id": "2", "name": "web" }, { "id": "3", "name": "telegram" }, { "id": "4", "name": "vkontakte" }, { "id": "0", "name": "default" } ] }
/qas/doc	POST	Метод используется для добавления нового документа в базу данных. Загружаемый файл должен быть в формате txt, в кодировке Unicode UTF-8	title - заголовок файла. category - категория документа. text - поле для загрузки файла.	Успешное выполнение метода возвращает сообщение об успешном добавлении файла и присвоенном ему идентификатору. Пример ответа: {"error": 0, "message": "success", "id": "92da6b1968616db4e8d3981c62e0f71f"}
/qas/doc/{id}	GET	Метод возвращает текст документа из базы данных по его идентификатору	id - идентификатор документа.	На выходе полный текст документа, соответствующий указанному идентификатору. При успешном выполнении метода выдается тест документа в формате JSON. В случае отсутствия документа с указанным идентификатором появится сообщение об ошибке: { "error": 1, "message": "text not found"}
/qas/doc/{id}	DELETE	Метод предназначен для удаления документа из базы по его id	id - идентификатор документа.	В случае успеха метод вернет статус выполнения операции (например, “success”), в случае неудачи - код ошибки. {"error": INT, "message": DESCRIPTION}
/qas/list/	GET	Метод возвращает список всех доступных документов с их уникальными идентификаторами и категорией	-	Возвращает список объектов, где каждый объект содержит следующие поля: id - идентификатор документа; title - заголовок файла; category - категория документа. Пример ответа: [ { "id": "Идентификатор документа", "title": "Название документа", "category": "Категория документа" }, { "id": "Идентификатор документа", "title": "Название документа", "category": "Категория документа"  }, ...... ]
/qas/reinit	GET	Метод для обновления базы данных	-	На выходе метод вернет объект с сообщением об успешном выполнении. {"error": INT, "message": DESCRIPTION} В случае ошибки метод вернет объект с кодом ошибки и сообщением об ошибке.

Важные заметки

• При изменении параметров векторизации - необходимо выполнить переинициализацию БД.