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 канала useCache — использовать кешированные ответы возможные варианты: — "no" не использовать - "all" использовать все - "checked" использовать только проверенные useGPT — использовать генеративную сеть для поиска ответов в документах. возможные варианты "yes" "no" model - имя модели GPT, если кроме default используются другие модели template - ID шаблона запроса к LLM, необязательный параметр addAlias — добавлять похожие вопросы к синонимам, не создавая отдельного вопроса. возможные варианты "yes" "no" maxDocs — максимальное количество документов одной категории для формирования контекста при генерации ответа на вопрос, по умолчанию 1 similarityArea — определяет допустимую разницу между максимальной и минимальной релевантностью фрагментов при фильтрации результатов		{ "error": 0, "text": "Здесь будет текст ответа" }
POST/qas/autocache	Добавление вопросно-ответной пары в кэш. В случае указания id answer будет принудительно добавлен в вопрос с указанным id. Если же указан question, то система сначала попытается найти похожий вопрос и добавить ответ в него, если же вопрос не будет найден, то система создаст новый с указанной формулировкой. При установке флага emptyQuestion будет добавлен только вопрос (без ответа).
question — текст вопроса category — категория channel — канал answer — ответ emptyQuestion — yes или no, флаг добавления вопроса без указания ответа checked — yes или no, флаг добавления вопроса как «проверенного» id — код существующего вопроса		{"error": 0, "message": "success"}
GET/qas/cachemaker/start	Генерация ответов на вопросы в кэше.
category — категория для которой генерируются ответы, если указан код категории, то генерация только для этой категории mode — режим генерации ответов, возможные значения:- paraphrase - генерирует вариации ответов перефразированием уже проверенных ответов, если таковые имеются на вопросе- generate — генерирует кэш через разные ответы на каждый вопрос по документации option — {all | empty} обработать все вопросы или только не содержащие ответов variants — количество ответов, от 1 до 9 replace — заменить ответы на сгенерированные maxDocs — максимальное количество документов одной категории для формирования контекста при генерации ответа на вопрос, по умолчанию 1 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. Проверить правила поведения в библиотеке перед входом" }
POST/qas/cleandoc/start	Очистка документа от лишней информации
text - текст документа model - какую модель использовать для ответа, если кроме default используются другие модели template - ID шаблона запроса к LLM, необязательный параметр doc_id - необязательный параметр, ID документа user_id - ID пользователя		{"error": 0, "message": "success"}
GET/qas/cleandoc/stop	Остановка очистки документа для конкретного пользователя
user_id - ID пользователя		{"error": 0, "message": "success"}
GET/qas/cleandoc/status	Статус очистки документа для конкретного пользователя
user_id - ID пользователя		{ "error": 0, "status": stopped | started, "progress": 33.3, "message": string, "place": number, #место в очереди "queue": True | False #состояния - в очереди или в процессе очистки }
GET/qas/cleandoc/result	Результат очистки документа для конкретного пользователя
doc_id - необязательный параметр, ID документа user_id - ID пользователя		{"error": 0,"status": "stopped","text": "очищенный текст","doc_id": "ID документа"}
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 канала useCache — использовать кешированные ответы возможные варианты: — "no" не использовать - "all" использовать все - "checked" использовать только проверенные useGPT — использовать генеративную сеть для поиска ответов в документах. возможные варианты "yes" "no" model - имя модели GPT, если кроме default используются другие модели template - ID шаблона запроса к LLM, необязательный параметр maxDocs - максимальное количество документов одной категории для формирования контекста при генерации ответа на вопрос, по умолчанию 1 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}
POST/qas/mismatchsearcher/start	Старт поиска несоответствий
category — id категории документа. Если не указать категорию, метод вернет ответ на основе всех документов в базе данных. Допускается указание нескольких категорий через разделитель "|". model - имя модели GPT, если кроме default используются другие модели template - ID шаблона запроса к LLM для анализа на несоответствия, необязательный параметр asktemplate - ID шаблона запроса к LLM для генерации ответов по документу, необязательный параметр answers - тип вопросов, по которым осуществляется поиск несоответствий, необязательный параметр, по умолчанию «all»		{error: 0 | 1, message: string}
GET/qas/mismatchsearcher/status	Статус поиска несоответствий
Входные параметры отсутствуют		{     error: string;      status: 'started' | 'stopped';      progress: number; }
GET/qas/mismatchsearcher/stop	Остановка поиска несоответствий
Входные параметры отсутствуют		{error: 0 | 1, message: string}
GET/qas/mismatchsearcher/mismatches	Статус получения результатов
Входные параметры отсутствуют		{"error": 0,"message": "success","mismatches": [{ "question_id": "ID вопроса", "question": "вопрос", "category": "ID категории", "answer_id": "ID ответа", "answer": "ответ на вопрос {question}", "description": "результат поиска", "error" : string, "context": "фрагмент документа", "generatedText" : "Результат генерации" }, ... ] }
GET/qas/questionmaker/start	Запуск генерации вопросов
category - ID категории, по которой будет происходить генерация вопросов doc - ID документа, по которому будет происходить генерация вопросов generateAnswers - флаг для генерации ответов вместе с вопросами [yse|no], по умолчанию «no» model - имя модели GPT, если кроме default используются другие модели template - ID шаблона запроса к LLM для анализа генерации вопросов, необязательный параметр		{ "error": 0, "message": "success" }
GET/qas/questionmaker/status	Статус генерации вопросов
Входные параметры отсутствуют		{ "error": string, "status": 'started' | 'stopped', "progress": 33.3 }
GET/qas/questionmaker/stop	Прервать генерацию.
Входные параметры отсутствуют		{error: 0 | 1, message: string}
GET/qas/search	Поиск фрагментов содержащих ответ
text — текст запроса category — категория (раздел) знаний. Допускается указание нескольких категорий через разделитель "|". maxDocs - максимальное количество документов одной категории для формирования контекста при поиске ответа на вопрос, по умолчанию 1 similarityArea - определяет допустимую разницу между максимальной и минимальной релевантностью фрагментов при фильтрации результатов		{  "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 — файл с текстом (текст, csv, pdf или текстовые офисные документы) template - ID шаблона запроса к LLM, необязательный параметр		{  "error": 0,   "message": "success",   "summary": "здесь текст протокола" }
POST/qas/replace	корректировка информации в тексте при помощи LLM
text - текст oldinfo — старая информация newinfo — новая информация model - какую модель использовать для генерации, если кроме default используются другие модели template - ID шаблона запроса к LLM, необязательный параметр		{  "error": 0,   "message": "success",   "text": "итоговый текст" }
POST/qas/replacementlist	список всех фраз в документах и ответов в вопросах, подлежащих правке. Векторно ищет все фрагменты по указанному тексту.
text - текст category — категория, в которой производится векторный поиск threshold — порог похожести, необязательный параметр, если не указан, берется из конфигурационного файла (fragments -> threshold) answers - тип вопросов, по которым осуществляется поиск для внесения правок, необязательный параметр, по умолчанию «all»		{"error": 0, "message": "success", "docs": [], "answers": [] }
Группа методов 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 — фильтр вопросов category — фильтр категорий answer — фильтр ответов created — фильтр по дате создания, оставляет вопросы, созданные не ранее указанной даты createdBefore — фильтр по дате создания, оставляет вопросы, созданные не позже указанной даты modified — фильтр по дате изменения, оставляет вопросы, изменённые в точности в указанную дату onlyNew - фильтр, оставляющий только новые (необработанные) вопросы		{  "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	Массовая замена текста в указанных ответах.
answers - 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 - замена информации в тексте, mismatch - поиск несоответствий name — название шаблона prompt — текст шаблона postprompt - текст шаблона постобработки результатов (нужен только для summarize) params - параметры запроса к LLM"max_tokens": 4096, "top_k": 30, "top_p": 0.5, "temperature": 0.5, "repeat_penalty": 1.3		{   "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}