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" model - имя модели GPT, если кроме default используются другие модели template - ID шаблона запроса к LLM, необязательный параметр addAlias — добавлять похожие вопросы к синонимам, не создавая отдельного вопроса. возможные варианты "yes" "no"		{ "error": 0, "text": "Здесь будет текст ответа" }
POST/qas/autocache	Добавление вопросно-ответной пары в кэш. В случае указания id answer будет принудительно добавлен в вопрос с указанным id. Если же указан question, то система сначала попытается найти похожий вопрос и добавить ответ в него, если же вопрос не будет найден, то система создаст новый с указанной формулировкой. При установке флага emptyQuestion будет добавлен только вопрос (без ответа).
question — текст вопроса category — категория channel — канал answer — ответ emptyQuestion — yes или no, флаг добавления вопроса без указания ответа id — код существующего вопроса		{"error": 0, "message": "success"}
GET/qas/cachemaker/start	Генерация ответов на вопросы в кэше.
category - категория для которой генерируются ответы mode - режим генерации ответов, возможные значения:- paraphrase - генерирует вариации ответов перефразированием уже проверенных ответов, если таковые имеются на вопросе- generate - генерирует кэш через разные ответы на каждый вопрос по документации option - {all | empty} обработать все вопросы или только не содержащие ответов category - если указан код категории, то генерация только для этой категории variants - количество ответов, от 1 до 9 replace - заменить ответы на сгенерированные maxDocs - максимальное количество документов одной категории для формирования контекста при генерации ответа на вопрос model - какую модель использовать для генерации, если кроме default используются другие модели template - ID шаблона запроса к LLM, необязательный параметр		{"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	Произвольный запрос в LLM.
text - текст вопроса history - история вопросов, будет склеена с text при запросе model - какую модель использовать для ответа, если кроме default используются другие модели useInternalTemplate - использовать ли шаблон запроса. no - не использовать, либо код шаблона запроса к LLM. Необязательный параметр. Если не указан, используется шаблон по умолчанию. params - необязательный параметр. JSON с произвольными параметрами запроса к LLM. Описание параметров см. в руководстве администратора.		Пример ответа на вопрос "как пройти в библиотеку" {"error": 0, "text": "1. Проверить время работы библиотеки (обычно от 9 до 20)\n2. Проверить местоположение библиотеки на карте или с помощью сервиса Google Maps\n3. Убедиться, что у вас есть необходимые документы для входа (паспорт, карта члена библиотеки и т.д.)\n4. Посетить библиотеку по адресу: [адрес библиотеки]\n5. Проверить правила поведения в библиотеке перед входом" }
GET/qas/chat	Поиск ответа за пределами документов. Аналогичен методу "POST/qas/chat". Не поддерживает большие тексты.На стадии разработки, не используется.
text - текст вопроса history - история вопросов, будет склеена с text при запросе model - какую модель использовать для ответа, если кроме default используются другие модели useInternalTemplate - использовать ли шаблон запроса. no - не использовать, либо код шаблона запроса к LLM. Необязательный параметр. Если не указан, используется шаблон по умолчанию. params - необязательный параметр. JSON с произвольными параметрами запроса к LLM. Описание параметров см. в руководстве администратора.		Аналогично методу "POST/qas/chat".
POST/qas/cleandoc	Очистка документа от лишней информации
text - текст документа model - какую модель использовать для ответа, если кроме default используются другие модели template - ID шаблона запроса к LLM, необязательный параметр		{"error": 0, "message": "success", "text": "измененный текст"}
POST/qas/paraphrase	Генерация фраз-синонимов для предложения.
text - предложение model - какую модель использовать для ответа, если кроме default используются другие модели template - ID шаблона запроса к LLM, необязательный параметр		{"error": 0, "message": "success", "texts": [ "перефразированный текст 1", ... ]}
GET/qas/gpt/list	Получение списка доступных(установленных) GPT моделей
Входные параметры отсутствуют		{  "error": 0,  "message": "success",   "models": ["default" ]}
GET/qas/questionlist/answers	Отображает лог массовой обработки вопросов
Входные параметры отсутствуют		на выходе : массив из объектов {   error: number;   question: string;   answer: string;   confidence: number | null; }
POST/qas/questionlist/start	Старт массовой обработки вопросов
questions - файл с вопросами format - в json или в text файл с вопросами category — id категории документа. Если не указать категорию, метод вернет ответ на основе всех документов в базе данных. Допускается указание нескольких категорий через разделитель "|". channel — id канала creative — флаг креативности возможные варианты "yes" "no" useCache — использовать кешированные ответы возможные варианты: — "no" не использовать - "all" использовать все - "checked" использовать только проверенные useGPT — использовать генеративную сеть для поиска ответов в документах. возможные варианты "yes" "no" model - имя модели GPT, если кроме default используются другие модели addAlias — добавлять похожие вопросы к синонимам, не создавая отдельного вопроса. возможные варианты "yes" "no" threshold - порог достоверности при обработке		{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 — категория, для которой выполнится генерация вопросов. doc - для какого документа генерировать model - какую модель использовать для генерации, если кроме default используются другие модели		{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/qas/summarize	Построение протокола или краткого содержания совещания
text - текст совещания options — словарь с разделами протокола, где ключ — название раздела, значение - краткая инструкция к формированию раздела. model - какую GPT модель использовать для построения протокола, если кроме default используются другие модели file — файл с текстом (utf8 только текстовый формат)		{  "error": 0,   "message": "success",   "summary": "здесь текст протокола" }
Группа методов 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}
POST/qas/doc/replace	Замена подстроки в текстах категории Будут заменены все найденные вхождения
search - искомая подстрока, будет заменена replace - текст замены category - в какой категории искать		{"error": INT, "message": DESCRIPTION,"replacements":INT}
POST/qas/doc/modifyphrases	Массовая замена текста в указанных фразах.
phrases - JSON массив с изменяемым фразами следующего вида: [ { 'doc_id': 'ad895085-2e48-439a-831e-b5f699b6a54a', 'phrase_id': 5, 'text': 'новый текст' } ]		{"error": 0,"message": "success"}
Группа методов 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	Получение списка вопросов.
question — фильтр вопросов answer — фильтр ответов		{  "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}
POST/qas/question/replace	Поиск и замена подстроки. Будут заменены все найденные вхождения
search - искомая подстрока, будет заменена replace - текст замены category - в какой категории искать		{"error": INT, "message": DESCRIPTION,"replacements":INT}
POST/qas/question/modifyanswers	Массовая замена текста в указанных ответах.
phrases - JSON массив с изменяемым ответами следующего вида: [ { 'question_id': 'ad895085-2e48-439a-831e-b5f699b6a54a', 'answer_id': 5, 'text': 'новый текст' } ]		{"error": 0,"message": "success"}
Группа методов summarization_template
POST/qas/summarization_template/add	Добавление шаблона протокола. В случае успеха метод вернет id шаблона, в случае неудачи — код ошибки.
name — название шаблона options — json словарь с именами разделов и их описанием		{  "error": 0,  "id": "527be9f0-f773-4a3e-bd0b-81b40a061d0d"}
DELETE/qas/summarization_template/delete/{id}	Удаление шаблона.
id — идентификатор шаблона		{"error": INT, "message": DESCRIPTION}
GET/qas/summarization_template/get/{id}	Получение json с шаблоном.
id — идентификатор шаблона		На выходе словарь, основные элементы: data — словарь с шаблоном, остальные элементы этого уровня служебные. В data: id, name (идентификатор и наименование).И options — словарь с разделами шаблона.
GET/qas/summarization_template/list	Получение всех шаблонов.
Входные параметры отсутствуют		На выходе словарь, основной элемент — templates, содержит список шаблонов (каждый шаблон как в выдаче метода GET /qas/summarization_template/get/{id}).
POST/qas/summarization_template/modify/{id}	Изменение шаблона.
data — словарь как в выдаче метода GET/qas/summarization_template/get/{id} id — идентификатор шаблона		{"error": INT, "message": DESCRIPTION}
Группа методов prompt
POST/qas/prompt/add	Добавление шаблона запроса к LLM. В случае успеха метод вернет id вопроса, в случае неудачи — код ошибки.
type — тип шаблона - chat - произвольный чат, - ask - запрос к документам, - cleandoc - очистка документа, форматирование либо другое преобразование, - similars_generator - генерация синонимичных которотких фраз, - paraphrase - перефразировка текста, - summarize - суммаризация текста (формирование краткой выдержки из текста), - question_generator - генерация вопросов по тексту, - replace - замена информации в тексте name — название шаблона prompt — текст шаблона postprompt - текст шаблона постобработки результатов (нужен только для summarize)		{   "error": 0,   "id": "527be9f0-f773-4a3e-bd0b-81b40a061d0d" }
DELETE/qas/prompt/delete/{id}	Удаление шаблона.
id — идентификатор вопроса		{"error": INT, "message": DESCRIPTION}
GET/qas/prompt/get/{id}	Получение шаблона.
id — идентификатор вопроса		{  "error": 0,   "prompt": {     "id": "cleandoc",     "type": "cleandoc",     "isDefault": false,     "name": "Чистка документа",     "prompt": "Удали сноски, колонтитуры и мусорную информацию из текста ниже. Не удаляй ничего лишнего. Не добавляй ничего, только информация из текста. Выведи только конечный результат без отчета о результате.\n###Текст:\n{context}\n\n###Конечный результат:",     "postprompt": "",     "_modified": 1751475766.7460272,     "_created": 1751475766.7460272,     "_modified_date": "2025-07-02",     "_created_date": "2025-07-02"   } }
GET/qas/prompt/list	Получение списка шаблонов.
		{  "error": 0,   "prompts": [     {       "id": "chat",       "type": "chat",       "isDefault": false,       "name": "Чат",       "prompt": "Ты спокойный вежливый консультант.[\n\n###История переписки:\n{history}]\n\n###Вопрос: {question}\n###Ответ:",       "postprompt": "",       "_modified": 1751475766.7460272,       "_created": 1751475766.7460272,       "_modified_date": "2025-07-02",       "_created_date": "2025-07-02"     }   ] }
POST/qas/prompt/modify/{id}	Модификация шаблона. Позволяет заменить как все параметры, так и отдельные.
data — json c измененными параметрами: { "name": "новое имя" } id — идентификатор вопроса		В случае успеха метод вернет статус выполнения операции (например, «success»), в случае неудачи — код ошибки. {"error": INT, "message": DESCRIPTION}