ssezmar
a0e026b641
first commit
|
hace 1 mes | |
|---|---|---|
| README.md | hace 1 mes |
README.md
Руководство пользователя LLM Kanban
Аннотация
Настоящий документ является руководством пользователя информационной системы LLM Kanban — веб-приложения для управления задачами, выполняемыми большими языковыми моделями (LLM), по принципу канбан-доски.
Документ предназначен для операторов, ревьюеров и администраторов системы, использующих её для постановки задач LLM-агентам, контроля их выполнения, ревью результатов и учёта стоимости вычислений.
В руководстве описаны область применения, условия эксплуатации, порядок установки и запуска клиентской части, основные пользовательские операции, типовые аварийные ситуации и способы их устранения.
Содержание
- Руководство пользователя LLM Kanban
- Содержание
- 1 Введение
- 2 Назначение и условия применения
- 3 Подготовка к работе
- 4 Описание операций
- 4.1 Авторизация пользователя
- 4.2 Просмотр канбан-доски
- 4.3 Создание задачи
- 4.4 Назначение LLM-агента
- 4.5 Запуск задачи на выполнение
- 4.6 Перемещение задачи между колонками
- 4.7 Ревью результата
- 4.8 Просмотр истории выполнения
- 4.9 Управление LLM-агентами
- 4.10 Управление пользователями
- 4.11 Просмотр учёта стоимости
- 4.12 Выход из системы
- 5 Аварийные ситуации
- 6 Рекомендации по освоению
- 7 Термины и сокращения
- 8 Контакты
- Лист регистрации изменений
1 Введение
1.1 Область применения
Система LLM Kanban применяется в организациях, использующих большие языковые модели (LLM) от внешних провайдеров (Anthropic, OpenAI, Google) для автоматизации интеллектуальной обработки текстовых задач: подготовки документов, анализа данных, генерации кода, перевода, реферирования и других подобных операций.
Система обеспечивает:
- централизованную постановку задач LLM-агентам;
- визуальное отслеживание состояния задач на канбан-доске;
- управление учётными записями LLM-провайдеров;
- ревью полученных результатов с возможностью повторного запуска;
- ведение журнала аудита всех действий пользователей;
- учёт стоимости выполненных запросов.
Типичные сценарии использования:
- постановка оператором задачи на генерацию текста, переводимая агентом Claude или GPT-5;
- ревью полученного ответа специалистом-ревьюером;
- администрирование набора подключённых моделей и их тарифов;
- анализ совокупных расходов на LLM за отчётный период.
1.2 Краткое описание возможностей
Система LLM Kanban предоставляет следующие возможности:
- создание, редактирование и удаление задач;
- визуальное представление задач в виде канбан-доски с колонками
Backlog,In Prompt,Processing,Review,Done,Failed; - перемещение задач между колонками методом drag-and-drop;
- выбор LLM-агента из списка подключённых;
- автоматическая постановка задачи в очередь выполнения через брокер Redis;
- получение и сохранение ответа LLM-провайдера;
- ревью и утверждение или отклонение результата;
- автоматический возврат задачи в
Backlogпри отклонении; - ведение журнала аудита (
audit_log) с фиксацией каждого изменения; - учёт стоимости каждого запроса в журнале
cost_ledger; - управление пользователями и их ролями (доступно администратору);
- управление LLM-агентами: добавление, отключение, изменение тарифа (доступно администратору);
- разграничение доступа к данным средствами Row Level Security (RLS) PostgreSQL.
1.3 Уровень подготовки пользователя
Пользователь должен обладать:
- базовыми навыками работы с персональным компьютером;
- базовыми навыками работы с веб-браузером;
- общим пониманием принципов работы канбан-методологии;
- общим пониманием принципов работы LLM (формулирование промптов, ограничения по числу токенов).
Для администраторов дополнительно требуется:
- понимание разграничения ролей в информационных системах;
- знание принципов учёта стоимости вычислений на основе токенов.
1.4 Перечень эксплуатационной документации
При эксплуатации системы рекомендуется использовать документы, перечисленные в таблице 1.
Таблица 1 – Перечень эксплуатационной документации
| Документ | Назначение |
|---|---|
| Руководство пользователя | Полное описание работы с системой LLM Kanban (настоящий документ) |
| Руководство администратора | Описание установки и конфигурирования серверной части |
| Руководство программиста | Описание GraphQL-схемы API и интеграции внешних сервисов |
| Описание архитектуры | Описание программно-аппаратной архитектуры по ГОСТ Р 57100-2025 |
2 Назначение и условия применения
2.1 Назначение системы
Система LLM Kanban предназначена для автоматизации процессов оркестрации задач, выполняемых большими языковыми моделями, и для контроля их выполнения по принципу канбан-доски.
Основные задачи системы:
- централизованная постановка и хранение задач LLM;
- автоматический подбор и вызов LLM-агента по заданным критериям;
- визуальный контроль состояния задач;
- ревью и утверждение результатов уполномоченным сотрудником;
- ведение полного журнала аудита;
- учёт стоимости в разрезе пользователя, агента, отчётного периода.
2.2 Условия применения
Система предназначена для работы в режиме многопользовательского доступа через локальную сеть или сеть Интернет. Серверная часть размещается в защищённой подсети и доступна клиентам по протоколу HTTPS.
Для работы с системой пользователю необходимо:
- наличие учётной записи в системе с присвоенной ролью;
- стабильное подключение к сети с пропускной способностью не ниже 1 Мбит/с;
- современный веб-браузер, поддерживающий стандарт ECMAScript 2022 и протокол WebSocket.
2.3 Минимальные требования
Минимальные требования к рабочему месту пользователя приведены в таблице 2.
Таблица 2 – Минимальные требования к рабочему месту пользователя
| Компонент | Требования |
|---|---|
| Операционная система | Windows 10, macOS 12, Ubuntu 22.04 и выше |
| Оперативная память | От 4 ГБ |
| Свободное место на диске | От 200 МБ |
| Браузер | Chrome 120+, Firefox 120+, Edge 120+, Safari 17+ |
| Разрешение экрана | От 1366×768 пикселей |
| Подключение к сети | От 1 Мбит/с |
Минимальные требования к серверной части приведены в руководстве администратора.
3 Подготовка к работе
3.1 Состав и содержание дистрибутива
Клиентская часть системы является веб-приложением и не требует установки на рабочее место пользователя. Доступ осуществляется через веб-браузер по адресу, предоставленному администратором (например, https://llm-kanban.example.org).
Серверная часть распространяется в виде Docker-контейнеров и устанавливается администратором согласно руководству администратора.
3.2 Запуск программы
Для запуска клиентской части пользователю необходимо:
- Открыть веб-браузер.
- В адресной строке ввести URL системы, предоставленный администратором.
- Дождаться загрузки экрана авторизации.
После загрузки на экране отображается форма входа, как показано на рисунке 1.
Рисунок 1 – Экран авторизации
3.3 Проверка работоспособности
Для проверки корректной работы системы необходимо последовательно выполнить операции, приведённые в таблице 3.
Таблица 3 – Проверка работоспособности
| № | Действие | Ожидаемый результат |
|---|---|---|
| 1 | Открыть URL системы | Отображается экран авторизации |
| 2 | Ввести корректные учётные данные и нажать «Войти» | Выполняется переход на канбан-доску |
| 3 | Открыть колонку Backlog |
Список задач загружается без ошибок |
| 4 | Открыть раздел «Агенты» | Отображается список подключённых LLM-агентов |
| 5 | Выйти из системы | Выполняется возврат на экран авторизации |
Если на любом из шагов возникла ошибка, следует обратиться к разделу 5 Аварийные ситуации.
4 Описание операций
4.1 Авторизация пользователя
При обращении к системе отображается экран авторизации.
Для входа в систему необходимо:
- Ввести адрес электронной почты в поле «Email».
- Ввести пароль в поле «Пароль».
- Нажать кнопку «Войти».
При успешной авторизации выполняется следующее:
- система генерирует JWT-токен доступа сроком действия 1 час;
- токен сохраняется в защищённом хранилище браузера;
- одновременно создаётся сессия в Redis с ключом вида
session:{token}и временем жизни 3600 секунд; - выполняется переход на канбан-доску;
- в журнал
audit_logзаписывается событие входа.
Если данные введены неверно, отображается сообщение:
Неверный email или пароль
При повторном открытии системы в том же браузере вход выполняется автоматически, пока действителен сохранённый токен.
Внешний вид экрана авторизации представлен на рисунке 1.
Рисунок 1 – Экран авторизации
4.2 Просмотр канбан-доски
После авторизации пользователь попадает на главный экран — канбан-доску.
Доска содержит шесть колонок:
а) Backlog — новые и отклонённые задачи, ожидающие назначения;
б) In Prompt — задачи с назначенным агентом, ожидающие запуска;
в) Processing — задачи, обрабатываемые LLM-агентом в настоящий момент;
г) Review — задачи с полученным ответом, ожидающие ревью;
д) Done — задачи, ревью которых завершено успешно;
е) Failed — задачи, выполнение которых завершилось ошибкой.
Каждая задача представлена карточкой с краткой информацией:
- идентификатор задачи;
- заголовок промпта (первые 80 символов);
- приоритет (
low,medium,high); - имя назначенного агента (если назначен);
- автор задачи.
Состав отображаемых задач зависит от роли пользователя и определяется политикой Row Level Security:
- оператор видит только свои задачи;
- ревьюер дополнительно видит задачи в статусе
Review; - администратор видит все задачи.
Общий вид канбан-доски представлен на рисунке 2.
Рисунок 2 – Главный экран. Канбан-доска
4.3 Создание задачи
Для создания новой задачи необходимо нажать кнопку «Создать задачу» в верхней части канбан-доски. После нажатия открывается форма создания задачи.
Пользователь должен заполнить поля, перечисленные в таблице 4.
Таблица 4 – Поля формы создания задачи
| Поле | Обязательность | Описание |
|---|---|---|
| Промпт | Обязательное | Текст задачи для LLM-агента, до 16 000 символов |
| Приоритет | Обязательное | Одно из значений: low, medium, high |
| Агент | Необязательное | LLM-агент из списка подключённых |
| Контекстные файлы | Необязательное | Прикрепляемые файлы формата PDF, TXT, MD общим объёмом до 10 МБ |
После заполнения формы необходимо нажать кнопку «Сохранить». Для отмены операции используется кнопка «Отмена».
При успешном сохранении выполняется следующее:
- в таблицу
tasksPostgreSQL вставляется новая запись со статусомbacklog; - в журнал
audit_logзаписывается событие создания; - прикреплённые файлы сохраняются в MongoDB-коллекции
task_artifacts; - карточка задачи появляется в колонке
Backlog.
Если агент при создании не выбран, задача остаётся в Backlog до его назначения. Если агент выбран, задача автоматически переводится в колонку In Prompt.
4.4 Назначение LLM-агента
Для назначения агента задаче в колонке Backlog необходимо:
- Открыть карточку задачи нажатием на неё.
- В поле «Агент» выбрать одно из значений выпадающего списка.
- Нажать кнопку «Сохранить».
При выборе агента отображается информация:
- название модели;
- лимит токенов на запрос;
- стоимость 1000 входных и 1000 выходных токенов;
- провайдер (Anthropic, OpenAI или Google).
После сохранения задача автоматически перемещается в колонку In Prompt.
4.5 Запуск задачи на выполнение
Для запуска задачи на выполнение LLM-агентом необходимо:
- Открыть карточку задачи в колонке
In Prompt. - Нажать кнопку «Запустить».
После нажатия выполняется следующая последовательность действий:
- Карточка задачи перемещается в колонку
Processing. - В очередь Redis
queue:llm-callsдобавляется команда на вызов LLM-провайдера. - Worker-процесс извлекает команду из очереди и обращается к API провайдера.
- По завершении запроса ответ сохраняется в
task_artifactsMongoDB. - В журнал
cost_ledgerзаписывается стоимость, рассчитанная по числу входных и выходных токенов. - Карточка автоматически перемещается в колонку
Review.
В случае ошибки выполнения карточка перемещается в колонку Failed, а в журнал audit_log записывается причина отказа.
Прогресс выполнения отображается в реальном времени средствами GraphQL Subscriptions через канал events:tasks.
4.6 Перемещение задачи между колонками
Перемещение задач между колонками выполняется методом drag-and-drop. Допустимые переходы между статусами определяются конечным автоматом, представленным на рисунке 3.
Рисунок 3 – Диаграмма состояний задачи
Допустимые ручные переходы приведены в таблице 5.
Таблица 5 – Допустимые ручные переходы между колонками
| Из колонки | В колонку | Условие | Доступно роли |
|---|---|---|---|
| Backlog | In Prompt | Назначен агент | Оператор, Администратор |
| In Prompt | Backlog | — | Оператор, Администратор |
| Review | Done | Ответ утверждён | Ревьюер, Администратор |
| Review | Backlog | Ответ отклонён | Ревьюер, Администратор |
| Failed | Backlog | Повторная попытка | Оператор, Администратор |
Прочие переходы выполняются автоматически и через интерфейс drag-and-drop недоступны.
4.7 Ревью результата
Задачи в колонке Review доступны для проверки пользователям с ролью «ревьюер» или «администратор».
Для проведения ревью необходимо:
- Открыть карточку задачи в колонке
Review. - Ознакомиться с исходным промптом, контекстными файлами и ответом LLM-агента.
- Нажать кнопку «Утвердить» или «Отклонить».
При нажатии «Утвердить»:
- статус задачи изменяется на
done; - карточка перемещается в колонку
Done; - в журнал
audit_logзаписывается событие утверждения.
При нажатии «Отклонить»:
- открывается диалоговое окно с полем «Причина отклонения»;
- после ввода причины и подтверждения статус задачи изменяется на
backlog; - карточка перемещается в колонку
Backlog; - значение поля
retry_countзадачи увеличивается на единицу; - в журнал
audit_logзаписывается событие отклонения с указанной причиной.
4.8 Просмотр истории выполнения
Для просмотра истории действий по задаче необходимо:
- Открыть карточку задачи.
- Перейти на вкладку «История».
На вкладке отображается хронологический список событий из коллекции task_events MongoDB. Для каждого события указаны:
- дата и время;
- тип события (
created,assigned,started,completed,approved,rejected,failed); - автор события;
- дополнительные данные в формате JSON.
История доступна для просмотра в рамках прав, определённых политикой RLS.
4.9 Управление LLM-агентами
Раздел «Агенты» доступен только пользователям с ролью «администратор».
В разделе отображается список подключённых LLM-агентов. Для каждого агента указаны:
- провайдер;
- название модели;
- лимит токенов;
- стоимость 1000 входных и 1000 выходных токенов;
- статус активности.
Доступные операции:
а) Добавление агента — нажатием кнопки «Добавить агент» открывается форма ввода параметров нового агента, включая API-ключ. Ключ сохраняется в зашифрованном виде в поле encrypted_api_key;
б) Редактирование агента — нажатием на строку агента открывается форма редактирования параметров;
в) Отключение агента — переключателем «Активен» агент переводится в неактивное состояние. Неактивные агенты недоступны для выбора при создании задач, но связанные с ними записи cost_ledger сохраняются;
г) Удаление агента — недоступно из соображений целостности учётных данных. Используется отключение.
4.10 Управление пользователями
Раздел «Пользователи» доступен только пользователям с ролью «администратор».
В разделе отображается список зарегистрированных пользователей. Для каждого указаны:
- идентификатор;
- email;
- ФИО;
- роль (
operator,reviewer,admin); - статус активности.
Доступные операции:
а) Добавление пользователя — заполнение формы с указанием email, ФИО, роли и начального пароля. Пароль сохраняется в виде хеша Argon2;
б) Изменение роли — выбор нового значения роли из выпадающего списка;
в) Блокировка пользователя — переключение поля is_active в значение «ложь». Заблокированный пользователь не может авторизоваться, но его задачи и записи audit_log сохраняются;
г) Сброс пароля — генерация нового временного пароля, отображаемого администратору один раз.
4.11 Просмотр учёта стоимости
Раздел «Учёт стоимости» доступен пользователям с ролью «ревьюер» или «администратор».
В разделе отображается таблица записей cost_ledger. Для каждой записи указаны:
- идентификатор задачи;
- агент;
- число входных и выходных токенов;
- стоимость в условных единицах;
- отчётный период.
Доступные операции:
а) фильтрация по агенту, пользователю, периоду;
б) группировка по агенту, пользователю или периоду с подсчётом суммы;
в) экспорт результатов в формат CSV.
4.12 Выход из системы
Для выхода из системы необходимо:
- Нажать на имя пользователя в правом верхнем углу.
- В открывшемся меню выбрать пункт «Выйти».
При выходе выполняется следующее:
- JWT-токен удаляется из хранилища браузера;
- ключ
session:{token}удаляется из Redis; - в журнал
audit_logзаписывается событие выхода; - выполняется переход на экран авторизации.
5 Аварийные ситуации
Типовые аварийные ситуации и рекомендации по их устранению приведены в таблице 6.
Таблица 6 – Аварийные ситуации
| Сообщение или симптом | Возможная причина | Рекомендация |
|---|---|---|
| «Неверный email или пароль» | Опечатка во вводе либо учётная запись заблокирована | Проверить раскладку клавиатуры, обратиться к администратору |
| «Срок действия сессии истёк» | Истёк срок действия JWT-токена (1 ч) | Повторно выполнить вход в систему |
| «Доступ запрещён» | У роли нет прав на запрошенное действие | Обратиться к администратору для уточнения прав |
| «Превышен лимит запросов» | Превышен лимит rate-limit для пользователя или агента | Подождать восстановления квоты согласно политике (60/120/300 запросов в минуту) |
| «Ошибка обращения к LLM-провайдеру» | Внешний API недоступен или ключ недействителен | Сообщить администратору; задача переводится в Failed |
| «Задача превысила лимит токенов» | Размер промпта или ожидаемого ответа превышает token_limit агента |
Уменьшить размер промпта или выбрать агента с большим лимитом |
| Канбан-доска не загружается | Отсутствует подключение к серверу | Проверить соединение с сетью; обновить страницу |
| Карточка не перемещается между колонками | Запрещённый переход согласно конечному автомату | См. таблицу 5 |
| Файл не загружается | Превышен размер 10 МБ либо неподдерживаемый формат | Использовать форматы PDF, TXT, MD; уменьшить размер |
При возникновении нештатной ситуации, не описанной в таблице 6, необходимо обратиться в службу технической поддержки (см. раздел 8 Контакты).
6 Рекомендации по освоению
Для эффективного освоения системы LLM Kanban рекомендуется:
- начать работу с тестовых задач с агентом наименьшей стоимости;
- формулировать промпты максимально конкретно, указывая желаемый формат ответа;
- использовать поле «Приоритет» для упорядочивания работы команды;
- регулярно отклонять некорректные результаты для повышения качества возможных доработок промпта;
- использовать раздел «Учёт стоимости» для контроля расходов;
- администраторам — отключать неиспользуемые агенты, чтобы не загромождать выпадающий список выбора;
- обращать внимание на значение
retry_count: его рост может означать, что промпт сформулирован неудачно.
7 Термины и сокращения
Перечень применяемых терминов и сокращений приведён в таблице 7.
Таблица 7 – Термины и сокращения
| Термин | Значение |
|---|---|
| LLM | Large Language Model — большая языковая модель |
| API | Application Programming Interface — программный интерфейс приложения |
| JWT | JSON Web Token — стандарт защищённой передачи утверждений |
| RLS | Row Level Security — построчное разграничение доступа в PostgreSQL |
| CRUD | Create, Read, Update, Delete — операции создания, чтения, изменения и удаления |
| Worker | Серверный процесс, обрабатывающий очередь задач |
| Промпт | Текстовое задание, передаваемое LLM-агенту на вход |
| Токен | Минимальная единица обработки текста LLM, используемая для тарификации |
| Канбан | Метод визуального управления задачами с использованием доски и карточек |
| Drag-and-drop | Способ перемещения объекта интерфейса путём захвата мышью |
| Ревью | Проверка результата выполнения задачи уполномоченным пользователем |
| Backlog | Колонка канбан-доски с задачами, ожидающими назначения |
8 Контакты
Служба технической поддержки системы:
- электронная почта:
support@llm-kanban.example.org; - Telegram:
@llm_kanban_support; - репозиторий проекта:
https://gogs.itiscaf.ru/romanov_da/llm-kanban.
Часы работы службы поддержки: с 09:00 до 18:00 по московскому времени, в рабочие дни.
Лист регистрации изменений
| № | Дата | Раздел | Изменение | Автор |
|---|---|---|---|---|
| 1 | 22.05.2026 | Все разделы | Создание документа | Романов Д. А. |