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

Программный комплекс «RAGu MAX» — корпоративная платформа оркестрации ИИ-агентов

Правообладатель: ООО «Ресетлаб» Версия ПО: 1.0.0

Настоящее руководство описывает функции роли администратор: управление пользователями и ролями, настройка языковых моделей, реестр инструментов и навыки платформы. Установка и первичная настройка описаны в «Инструкции по установке», базовые функции портала — в «Руководстве пользователя», работа с приложениями внешней платформы — в «Руководстве контрибьютора».

1. Роль и область доступа

Роль admin назначается учётной записи в сервере ключей (Keycloak), realm ragu. Роль включает все возможности contributor — вкладка «Ассистенты» доступна администратору без дополнительных назначений (см. «Руководство контрибьютора»).

Роль Назначение Вкладки в «Настройках»
user Обычный пользователь портала «Профиль», «Пароли»
contributor Публикация приложений, подключения к внешней платформе + «Ассистенты»
admin Полный доступ: конфигурация LLM, инструменты и навыки платформы + «Ассистенты», «LLM платформы», «Инструменты»

Особенности:

  • роли проверяются и на стороне интерфейса (видимость вкладок), и на стороне API (запросы без роли отклоняются с кодом 403);
  • группы Keycloak (finance, engineering, …) используются для разграничения доступа к приложениям с ограниченной видимостью и к LLM-эндпоинтам (п. 3.2).

2. Управление пользователями и ролями

Учётные записи, роли и группы ведутся в административной консоли Keycloak (http://<RAGU_HOST>/admin, учётные данные — KEYCLOAK_ADMIN / KEYCLOAK_ADMIN_PASSWORD из .env).

Назначение роли:

Консоль Keycloak -> realm ragu -> Пользователи -> пользователь -> Role mapping -> Assign role

  1. Консоль → realm ragu → Users → выберите пользователя.
  2. Вкладка Role mapping → Assign role.

Назначенные роли пользователя

Назначенные роли пользователя
  1. Выберите contributor и/или admin → Assign.

Диалог назначения роли

Диалог назначения роли

Пользователю достаточно перезайти на портал (или дождаться обновления сессии), чтобы новые вкладки появились в «Настройках».

Создание пользователей, групп и назначение членства описаны в «Инструкции по установке» (п. 5.4).

Предупреждение

Демонстрационные учётные записи (contribuser — роль contributor, adminuser — роли admin, contributor) перед вводом в эксплуатацию удалите или смените им пароли.

3. Вкладка «LLM платформы»

Вкладка управляет конфигурациями языковых моделей портала и содержит подвкладки «Конфигурации LLM» и «Настройки LLM по умолчанию». Стартовая конфигурация задаётся переменной окружения RAGU_DEFAULT_LLM_CONFIGS при установке; далее модели управляются из интерфейса и хранятся в базе данных.

3.1. Конфигурации LLM

Аватар пользователя -> Настройки -> LLM платформы -> Конфигурации LLM -> Добавить конфигурацию

Конфигурации LLM

Конфигурации LLM

Таблица подключений к OpenAI-совместимым эндпоинтам. Колонки: Иконка (favicon, подхватывается при проверке), Название, Модель, Базовый URL, Активен, По умолчанию (маркер ⚠ — конфигурация входит в платформенные настройки по умолчанию и уже доступна всем пользователям).

Добавление конфигурации:

  1. Нажмите «Добавить конфигурацию».

  2. Заполните поля:

    Поле Описание
    Название Отображаемое имя (например, OpenAI GPT-4o) — показывается в списке выбора модели
    API ключ Ключ доступа к эндпоинту; при редактировании оставьте пустым, чтобы сохранить текущий
    Базовый URL Адрес OpenAI-совместимого API
    Ссылка на документацию Опционально — документация провайдера
    Модель Идентификатор модели
    Макс. токенов Лимит токенов ответа
    Макс. повторных попыток Число повторов при сбое вызова
    Активен Конфигурация доступна для выбора и маршрутизации
    Порядок сортировки Позиция в списке выбора модели

  3. «Сохранить».

Добавление конфигурации LLM

Добавление конфигурации LLM

Действия со строкой конфигурации:

Действие Результат
Тест Проверка соединения — показывает задержку и подхватывает favicon эндпоинта
Доступ Групповой доступ к LLM (гранты группам Keycloak; для конфигурации «по умолчанию» влияет только на приоритет отказоустойчивости, т.к. она уже доступна всем)
Изменить Правка параметров
Удалить Удаление конфигурации

Доступные пользователю модели складываются из платформенных конфигураций по умолчанию и грантов для его групп Keycloak.

3.2. Настройки LLM по умолчанию

Аватар пользователя -> Настройки -> LLM платформы -> Настройки LLM по умолчанию

Настройки LLM по умолчанию

Настройки LLM по умолчанию

Задаёт цепочку моделей платформы и системные лимиты:

  • Список конфигураций — каждая строка связывает конфигурацию LLM с ролью и приоритетом:

    Роль Назначение
    Супервизор Модель планирования и оркестрации шагов
    Извлечение контекста Модель извлечения контекста/памяти
    По умолчанию Модель диалогов

    Приоритет определяет порядок отказоустойчивости: при недоступности модели с меньшим приоритетом вызов переходит к следующей в списке. Строки добавляются кнопкой «Добавить конфигурацию» и удаляются кнопкой корзины.

  • Макс. раундов базы знаний — ограничение итераций поиска по базам знаний за один запрос;

  • Глубина истории (сообщений) — число последних сообщений диалога, передаваемых модели в контексте.

Применение — кнопка «Сохранить настройки».

4. Вкладка «Инструменты»

Вкладка управляет инструментами платформы и навыками. Содержит подвкладки «Инструменты» (реестр MCP-инструментов) и «Навыки» (WASM/microVM-навыки).

4.1. Реестр инструментов

Аватар пользователя -> Настройки -> Инструменты -> Инструменты -> Добавить инструмент

Реестр инструментов

Реестр инструментов

Таблица инструментов с фильтром по источнику и поиском по названию. Источники:

Источник Значение
native Встроенные инструменты платформы (например, web_search — DuckDuckGo)
wasm WASM-навык (привязан к записи на подвкладке «Навыки»)
microvm Навык в микроконтейнере (OCI-образ)
remote_mcp Удалённый MCP-сервер
ragflow_app Приложение внешней платформы, опубликованное как инструмент (тумблер MCP у контрибьютора)

Колонки: Тег, Имя инструмента (invoke_name), Источник, MCP режим, Активен (тумблер включения без открытия формы), Адрес, Учётные данные, Действия.

Добавление инструмента — кнопка «Добавить инструмент»:

Поле Описание
Тег Отображаемое имя (@тег для упоминания)
Имя инструмента Уникальное invoke-имя; при редактировании не изменяется
Источник native / wasm / microvm / remote_mcp; для native заблокирован — определяется реализацией
MCP режим auto — инструмент доступен модели автоматически; mentions — только по явному упоминанию
Persistence упоминаний Только для режима mentions: single_turn — действует на один запрос; conversation — на весь диалог
Навык Для wasm/microvm — привязка к навыку из подвкладки «Навыки»
Адрес Для remote_mcp — URL MCP-сервера
Секретная ссылка Для remote_mcp — токен доступа; при редактировании оставьте пустым, чтобы сохранить
Запись Инструмент может изменять данные (write-capable)
Всегда виден Инструмент всегда включён в контекст модели, альтернативно - выключен из контекста при отсутствии файлов
Порядок сортировки Позиция в списке

Добавление инструмента

Добавление инструмента

Для remote_mcp доступна кнопка «Тест» — проверка соединения возвращает число обнаруженных на сервере инструментов.

Предупреждение

У remote_mcp-инструментов отображается значок ⚠: удалённый сервер получает аргументы запроса пользователя в исходном виде — подключайте только доверенные серверы.

СоветВеб-поиск

Встроенный web_search работает через DuckDuckGo без API-ключа. Для Tavily добавьте remote_mcp-инструмент с адресом https://mcp.tavily.com/mcp/ — все его инструменты появятся автоматически.

4.2. Навыки

Аватар пользователя -> Настройки -> Инструменты -> Навыки -> Добавить навык

Подвкладка «Навыки»

Подвкладка «Навыки»

Подвкладка «Навыки» — создание и управление WASM- и microVM-навыками. После создания навык регистрируется как инструмент на подвкладке «Инструменты» (источник wasm/microvm → поле «Навык»).

Создание навыка — кнопка «Добавить навык»:

Поле Описание
Название, Описание, Тег Имя навыка, краткое назначение, @тег для упоминания
Видимость, Маршрутизация по запросу Область видимости (Публичный/Ограниченный) и участие в автоматическом выборе по смыслу запроса
Движок выполнения MicroVM — исполнение в микроконтейнере; WASM — исполнение скомпилированного кода
Язык Только WASM: Python или JavaScript
Исходный код Только WASM: код навыка в редакторе с подсветкой
Образ инструмента (OCI) Только MicroVM: ссылка на OCI-образ; список доступных образов подгружается автоматически
Инструкции (SKILL.md) Инструкции навыка для модели. Кнопка «Получить из образа» (MicroVM) запускает временную песочницу и извлекает SKILL.md и схемы из образа
Входная / Выходная схема (JSON) JSON Schema аргументов и результата навыка
Таймаут (мс) Лимит времени исполнения
Сеть разрешена Доступ навыка к сети во время исполнения

Добавление навыка

Добавление навыка

Действия со строкой навыка:

Действие Результат
Изменить Правка полей навыка
Перекомпилировать Только WASM: загрузка нового исходного кода; предыдущая версия сохраняется, журнал компиляции доступен для просмотра
Версии Только WASM: список скомпилированных версий (номер, дата, хэш исходника); кнопка «Сделать активной» переключает активную версию; строка разворачивается в журнал компиляции
Удалить Удаление навыка

Навыки отображаются в каталоге «Приложения» (тип «Скилл»), вызываются через @-упоминание и доступны модели как инструменты — см. «Руководство пользователя», п. 4.4.

Приложение А. Матрица доступа

Функция user contributor admin
Диалоги, файлы, каталог, профиль ✓ ✓ ✓
Подключения к внешней платформе — ✓ ✓
Регистрация и публикация приложений — ✓ ✓
Групповой доступ к приложениям — ✓ ✓
Назначение ролей (Keycloak) — — ✓
Конфигурации LLM и настройки по умолчанию — — ✓
Групповой доступ к LLM — — ✓
Реестр инструментов (MCP) — — ✓
Навыки WASM / microVM — — ✓