QAS. Руководство администратора

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

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

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

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

Системные требования

Для нормальной работы сервиса без GPU необходимо не менее 8 CPU (минимальные требования для использования метода ask) >= 2.20 GHz с поддержкой инструкций AVX2 или новее:

• Intel Haswell
• Intel Broadwell
• Intel Skylake
• Intel Kaby Lake
• Intel Coffee Lake
• Intel Comet Lake
• Intel Rocket Lake
• Intel Alder Lake
• AMD Excavator
• AMD Zen (AMD Ryzen)
• AMD Zen 2 (AMD Ryzen)
• AMD Zen 3 (AMD Ryzen)

Работа на CPU при использовании метода ask крайне не рекомендуется. Оперативной памяти необходимо не менее 16Gb для работы без GPU.

Установка/обновление сервиса

Дистрибутив распространяется в виде установочных пакетов для окружения и сервиса. Загрузите установочные пакеты на сервер и выполните команды для вашей системы в каталоге с пакетом.

Перед установкой непосредственно сервиса необходимо установить сервисный пакет окружения.

• Установка/обновление QAS осуществляется скриптом chmod +x ./qas-<версия>-<релиз>.sh && ./qas-<версия>-<релиз>.sh -i с правами администратора. Список всех ключей инсталлятора можно посмотреть, запустив инсталлятор ./qas-<версия>-<релиз>.sh без ключей.
• Загрузить последнюю версию продукта curl -s "https://repo.connect2ai.net/api/qas/new" --user '[user]:[pass]' 2>&1 | bash или в интерактивном режиме bash -c "$(curl -s https://repo.connect2ai.net/api/qas --user '[user]:[pass]' 2>&1)".
• Обновить QAS /opt/qas/inupdate в интерактивном режиме. Или запустить с ключом:
  • /opt/qas/inupdate -b – обновить до последней beta версии;
  • /opt/qas/inupdate -r – обновить до последней release версии;
  • /opt/qas/inupdate -n – обновить до последней версии (неважно beta или release).
• Установить модели /opt/qas/inmodel в интерактивном режиме.
• Проверить актуальную версию продукта curl -s "https://repo.connect2ai.net/api/qas/version.
• Посмотреть лог изменений curl -s "https://repo.connect2ai.net/api/qas/changelog" --user '[user]:[pass]'.
• Полное описание всех команд API репозитория можно найти по ссылке https://repo.connect2ai.net/api. [user]:[pass] – это тот же логин и пароль, что и от Nextcloud.
• В папке с продуктом можно добавить 2 файла конфигурации (допускается один общий файл на все продукты в папке с окружением /opt/pve/):
  • echo -n "[user]:[pass]" > /opt/qas/.userapi (это файл авторизации в API, нужен для обновления и загрузки моделей)
  • echo -n "http://example.com:3128 [user] [password]" > /opt/qas/.proxy (это файл конфигурации proxy, необходим для обновления и загрузки моделей, при отсутствующем прямом подключении к интернету)

При обновлении следующий список файлов и папок сохраняется: .userapi, .proxy, logs, nnets, config.json, cache, pretrained, pve, data. Сервис не требует остановки и возвращается в актуальное состояние после обновления.

Не забудьте запустить сервис и включить в автозапуск в системе:

sudo systemctl enable qas.service && sudo systemctl start qas.service

Удостоверьтесь, что сервис стартовал:

systemctl status qas.service

Разрешите доступ к порту 6187 на нужном интерфейсе по протоколу tcp.

Лицензия

Сервис не функционирует без действующей лицензии. Информация о лицензии хранится в файле:

/opt/qas/license.json

Файл лицензии должен соответствовать следующему формату:

{"service": "qas", "expire": "2045-01-01", "licenses": , "key": ""}

Для получения лицензии необходимо:

1. Запустить сервис systemctl start qas и извлечь UUID, указанный в файле /opt/qas/logs/log.txt

2. Передать полученный UUID руководителю проекта для оформления лицензии.

Установка моделей

В составе QAS используются модели векторизации, и генеративные модели LLM.

Модели векторизации располагаются в папках:

• /opt/qas/pretrained/embeddings/questions - для работы с кэшем вопросов
• /opt/qas/pretrained/embeddings/docs - для работы с документами
• /opt/qas/pretrained/embeddings/rerank - для реранжирования документов

Расположение моделей LLM: /opt/qas/pretrained/gpt/<имя_модели>/. Например , встроенная модель LLM: /opt/qas/pretrained/gpt/default/. Модели после установки QAS должны быть добавлены системным администратором.

QAS допускает использование дополнительных моделей LLM. Каждая из таких моделей должна быть в отдельной папке каталога /opt/qas/pretrained/gpt/<имя_модели>/. Если модель формата GGUF, то достаточно поместить ее в свою папку в /opt/qas/pretrained/gpt/. В остальных случаях (в том числе и если необходимо обращаться к стороннему api) в папке модели должен быть файл handler.py с функцией handler(prompt='тут текст',params={параметры запроса, см. в руководстве пользователя в метода добавления шаблона запроса}), которая возвращает сгенерированный текст.

Работа в составе кластера

Для высоконагруженных систем сервис можно расположить на нескольких нодах (виртуальных машинах). В этом случае, чтобы не потерять документы и изменения, полученные на одной из нод, выделяется один основной сервис и вспомогательные сервисы:

• База файловая, в папке data.
• lsync настроен через конфиг QAS для репликации базы на все указанные серверы в списке cluster.nodes: [], указываем все слейв-сервера.
• На всех слейвах прописан в конфиге master, чтобы все операции добавления и изменения данных при автокешировании они производили через мастер. Параметр в конфиге questions.master, на мастере значение «http://127.0.0.1:6187».
• Векторная база на каждом сервере своя, она следит за своей папкой data и обновляет в оперативке по этой папке данные у себя.
• UPS при изменении данных работает только с мастером QAS, а при запросе данных — со всеми серверами cluster, распределяя нагрузку.
• В конфигурации UPS: в servers.qas.trainer указываем мастер-сервер, в servers.qas.cluster перечисляем все сервера кластера QAS, в том числе и мастер.

Конфигурирование параметров сервиса

Настройка параметров сервиса qas производится в файле /opt/qas/config.json.

Описание параметров приведено в таблице.

Параметр	По умолчанию	Назначение
reloader.period	60	Период обновления векторов базы вопросов и документов.
gpt.instances	1	Количество экземпляров встроенной нейросети
gpt.gpu_layers	12	Количество слоёв gpt нейросети, загружаемых в память видеокарты. Остальные слои загрузятся в оперативную память. Чтобы загрузить всю модель в ГПУ использовать значение "-1"
gpt.context	32768	Размер контекста встроенной нейросети.
logs.path	logs/	Папка для хранения логов. Примеры абсолютного пути: "/var/log/qas/".
logs.backups	10	Количество файлов ротации.
logs.maxSize	5242880	Максимальный размер файла в байтах, триггер для ротации.
cache.size	2560000	Максимальный размер кэша векторов
cache.update	3600	Период сохранения кэша на диск (секунды)
fragments.context	16384	Максимальная длина текста, которая будет подана в генератор для поиска ответа на вопрос.
fragments.threshold	0.5	Уровень достоверности при векторном поиске фрагментов в загруженных документах.
fragments.limit	1	Максимальное количество фрагментов, которые должны быть найдены в документах в порядке убывания доверия.
fragments.alpha	0.5	Параметр alpha — весовой коэффициент в формуле итоговой релевантности фрагмента, которая объединяет результаты двух моделей: векторизации и реранжирования. Настройка параметра: - Высокие значения (близкие к 1.0): Система в большей степени доверяет результатам модели векторизации. - Низкие значения (близкие к 0.0): Система больше полагается на более точную, но ресурсоемкую модель реранжирования.
fragments.filters	[ "^\\d+\\.$", "^[^\\S\n]*[(\\{\\[«\"]?\\d+\\.[^\\S\\\n]*$", "^[{}\\[\\]]$", "^[a-z]{2,3}\\.?$", "^(?:https?|ftp|www|com|org|net|io|co|edu|gov|html)$" ]	Список регулярных выражений, который используются как фильтр мусора для векторизации. Все что вызывает положительно срабатывание не будет векторизовано.
questions.master	"http://127.0.0.1:6187"	Адрес мастер-сервера для работы в кластере. Необходим, чтобы добавленные вопросы распространились на серверы кластера.
questions.threshold	0.9	Минимальный уровень достоверности ответа для попадания в кеш.
cluster.logfile	logs/sync.log	Расположение лог-файла синхронизации (актуально для мастер-сервера).
cluster.logfile	logs/sync.status	Расположение файла статуса lsyncd (актуально для мастер-сервера)
cluster.nodes	[ ]	Ноды кластера, на которые с мастер-сервера будут распространяться изменения.

Сбор данных об ошибках

Логи сервиса по умолчанию находятся в файле /opt/qas/logs/log.txt

Удаление

Для удаления выполните команду: /opt/qas/uninstall. Команда деинсталлирует сервис и удалит рабочий каталог, включая все установленные модели.