XSYSTECH KB

Appearance

Руководство по работе с агентами ПК Director в CLI-режиме ​

  1. Введение

  2. Установка и настройка

  3. Режимы работы

  4. Интерактивное меню

  5. CLI режим

  6. Настройки и конфигурация

  7. Работа с логами

  8. Примеры использования

Введение ​

xrmd_agent_manager.py - это многофункциональный инструмент для работы с агентами в системе ПК Director. Утилита обеспечивает комплексное взаимодействие с API, позволяя управлять агентами, сеансами и проводить автоматизированный анализ логов с использованием возможностей искусственного интеллекта.

Основные возможности ​

  • ✅ Просмотр агентов - полный список всех доступных агентов с детальной информацией
  • ✅ Создание и удаление сеанса с агентом - управление жизненным циклом сеансов
  • ✅ Ведение диалогов с агентами - интерактивное общение с поддержкой потоковой передачи ответов
  • ✅ Просмотр списка сеансов агента - мониторинг активных сеансов
  • ✅ Пакетный анализатор логов - автоматизированная обработка и интеллектуальный анализ системных логов
  • ✅ CLI интерфейс - полноценная автоматизация через командную строку
  • ✅ Предустановленные промпты - готовые шаблоны для частых задач с возможностью настройки
  • ✅ Потоковая передача - получение ответов в реальном времени
  • ✅ Гибкие настройки - широкие возможности конфигурации всех аспектов работы
  • ✅ Многопоточность - эффективная обработка больших объемов данных
  • ✅ Сохранение результатов - структурированное хранение данных в SQLite базе
  • ✅ Статистика и метрики - детальный анализ эффективности обработки логов

Требования к ПО: ​

  • ОС: Red OS 8.0
  • Права: root/sudo доступ для установки зависимостей и первоначальной настройки
  • Python: версия > 3.10 - < 3.13, рекомендуемая 3.11
  • Обязательные модули Python:
    • ragflow_sdk - для взаимодействия с RAGFlow API
    • sqlite3 - для хранения результатов анализа (обычно включен в стандартную библиотеку)
    • argparse - для работы с аргументами командной строки (обычно включен в стандартную библиотеку)
  • Системные требования:
    • CPU: многоядерный процессор для эффективной многопоточной обработки
  • Сетевые требования:
    • Доступ к серверу с развернутым ПК Director

Архитектура системы ​

Утилита построена на основе модульной архитектуры и состоит из следующих ключевых компонентов:

  1. Ядро (Core) - базовый модуль для взаимодействия по API

    • Управление подключением
    • Аутентификация
    • Обработка запросов

  2. Интерфейсы - компоненты для взаимодействия с пользователем

    • Консольное меню (TUI)
    • Интерфейс командной строки (CLI)
    • Обработчики пользовательского ввода

  3. Обработчики данных

    • Анализатор логов
    • Менеджер сеансов
    • Обработчик ответов агентов

  4. Хранилище данных

    • SQLite база для результатов
    • Файловая система для хранения логов
    • Кэширование ответов

  5. Утилиты

    • Логирование действий
    • Обработка ошибок
    • Многопоточность

Взаимодействие между компонентами происходит через четко определенные интерфейсы, что обеспечивает высокую модульность и расширяемость системы.

Установка и настройка ​

Путь к файлу xrmd_agent_manager.py после развертывания ПК Director в системе - /opt/xrm-director/utils

Первоначальная настройка ​

  1. Настройка подключения: добавить API и IP сервера в файл xrmd_agent_manager.py
python
API_KEY = "ragflow-ZjNTQxMjc0ZTE2ZTExZWZiYzQ3MDI0Mm"
BASE_URL = "http://{IP адрес сервера с развернутым ПК Director}:9380"
  1. Настройка путей (автоматически):
    • Логи: logs_to_agent.txt
    • База данных: log_results.db
    • Все файлы создаются в папке со скриптом
  2. Проверка подключения:
bash
python xrmd_agent_manager.py --list-agents

При успешном подключении Вы получите ответ с доступными агентами, см. пример ниже:

python xrmd_agent_manager.py --list-agents
Доступные агенты:
--------------------------------------------------
1. ID: 4988d880356c11f0815e0242ac120006
   Название: api_llm_agent
--------------------------------------------------

Режимы работы ​

1. Интерактивный режим (по умолчанию) ​

Запуск:

bash
sudo python xrmd_agent_manager.py

2. CLI режим ​

Запуск с параметрами:

bash
python xrmd_agent_manager.py --send "ERROR 2024-07-12 11:15:26,987 config get 148 FATAL: no pg_hba.conf entry for host \"10.1.97.70\", user \"udsdbadm\", database \"udsdb\", SSL on" --agent-title "api_llm_agent"

Интерактивное меню ​

Главное меню ​

========== Менеджер по работе с агентами ПК Director ==========

1. Посмотреть всех агентов
2. Создать сеанс с агентом
3. Поговорить с агентом
4. Список сеансов агента
5. Удалить сеансы агента
6. Удалить все сеансы у всех агентов
7. Анализатор логов
0. Выход

📖 Описание пунктов главного меню ​

1. Посмотреть всех агентов ​

Назначение: Отображение всех доступных агентов в системе

Что делает:

  • Подключается к серверу
  • Получает список всех агентов
  • Показывает ID и название каждого агента
  • Использует пагинацию для больших списков

Пример вывода:

Доступные агенты:
--------------------------------------------------
1. ID: 4988d880356c11f0815e0242ac120006
   Название: api_llm_agent
--------------------------------------------------
2. ID: b416715a34f711f0a6d20242ac120006
   Название: support_agent
--------------------------------------------------

2. Создать сеанс с агентом ​

Назначение: Создание нового сеанса для общения с выбранным агентом

Что делает:

  • Показывает список доступных агентов
  • Позволяет выбрать агента по номеру
  • Создает новый сеанс с выбранным агентом
  • Сохраняет сеанс как текущий для дальнейшей работы

3. Поговорить с агентом ​

Назначение: Ведение диалога с агентом в активном сеансе

Специальные команды в чате:

  • exit, quit, выход - выход из чата
  • menu, меню, /menu, /меню - возврат в главное меню
  • /help - показать доступные предустановленные промпты
  • /log_analyzer - использовать промпт для анализа логов

Пример диалога:

===== Вы =====
> ERROR 2024-07-12 11:15:26,987 config get 148 FATAL: no pg_hba.conf entry for host "10.1.97.70", user "udsdbadm", database "udsdb", SSL on

===== Агент =====
{"similarity_percent": 95, "match": 1}

4. Список сеансов агента ​

Назначение: Просмотр всех активных сеансов выбранного агента

Что делает:

  • Позволяет выбрать агента
  • Показывает все сеансы этого агента
  • Отображает ID сеансов

5. Удалить сеансы агента ​

Назначение: Удаление выбранных сеансов конкретного агента

Что делает:

  • Показывает список сеансов агента
  • Позволяет выбрать сеансы для удаления
  • Опция удаления всех сеансов агента

6. Удалить все сеансы у всех агентов ​

Назначение: Массовое удаление всех сеансов (функция очистки)

⚠️ ВНИМАНИЕ: Эта операция необратима!

7. Анализатор логов ​

Назначение: Автоматический анализ системных логов с помощью ИИ

Подменю "Анализатор логов" ​

1. Запустить обработку логов
2. Остановить обработку логов
3. Приостановить обработку
4. Возобновить обработку
5. Показать статистику обработки
6. Настройки анализатора
0. Вернуться в главное меню

Описание функций анализатора логов: ​

1. Запустить обработку логов ​
  • Выбор агента для анализа (рекомендуется api_llm_agent)
  • Создание нового сеанса с агентом
  • Выбор шаблона промпта для анализа
  • Загрузка логов из файла logs_to_agent.txt
  • Автоматическая обработка логов пакетами
2. Остановить обработку логов ​
  • Полная остановка процесса обработки
  • Сохранение текущих результатов в базу данных
3. Приостановить обработку ​
  • Временная приостановка без потери данных
  • Возможность возобновления с того же места
4. Возобновить обработку ​
  • Продолжение обработки с места остановки
5. Показать статистику обработки ​
  • Общее количество обработанных логов
  • Статистика по типам (ERROR, INFO, WARNING)
  • Время обработки
  • Успешность анализа
6. Настройки анализатора ​

Переход в подменю настроек

Подменю "Настройки анализатора" ​

1. Файл логов: [текущий путь]
2. База данных: [текущий путь]
3. Задержка между обработками: [текущее значение] сек.
4. Редактировать промпты
0. Вернуться в меню анализатора

Описание настроек: ​

1. Файл логов ​
  • Изменение пути к файлу с логами
  • По умолчанию: logs_to_agent.txt в папке скрипта
2. База данных ​
  • Изменение пути к базе данных результатов
  • По умолчанию: log_results.db в папке скрипта
3. Задержка между обработками ​
  • Настройка интервала между запросами к агенту
  • Предотвращает перегрузку сервера
4. Редактировать промпты ​

Переход в подменю редактирования промптов

Подменю "Редактирование промптов" ​

1. log_prompt_1 - Полный промпт для анализа логов
2. log_prompt_2 - Простой промпт ввода
3. log_analyzer - Базовый промпт
4. Добавить новый промпт
0. Вернуться в настройки

Предустановленные промпты: ​

log_prompt_1 ​
You are a log analyzer. Strictly compare the incoming log line for similarity with two knowledge bases: {{kb_uds_error}} - error examples (ERROR) and {{kb_uds_info}} - normal operation logs (INFO). Log line for analysis: '{}'. Respond ONLY with the required JSON.
log_prompt_2 ​
Input text:: '{}'
log_analyzer ​
'{}'

Меню выбора промптов при обработке логов ​

1. log_prompt_1
2. log_prompt_2
3. log_analyzer
4. Ввести свой промпт
5. Не использовать промпты (отправлять логи как есть)

CLI режим ​

CLI (Command Line Interface) режим предоставляет возможность использовать все основные функции утилиты напрямую из командной строки. Это позволяет автоматизировать работу с агентами, интегрировать утилиту в скрипты и создавать сложные сценарии обработки данных.

Основные команды ​

CLI-интерфейс утилиты разделен на несколько логических групп команд для работы с разными аспектами системы. Каждая команда имеет набор специфических параметров и опций.

Справка ​

Получение полной справки по всем доступным командам и параметрам:

bash
python xrmd_agent_manager.py --help

Результат выполнения:

usage: xrmd_agent_manager.py [-h] [--list-agents] [--create-session]
                       [--send MESSAGE] [--agent-id ID] [--agent-title TITLE]
                       [--session-id ID] [--new-session] [--no-references]
                       [--no-streaming]

Менеджер по работе с агентами ПК Director

optional arguments:
  -h, --help            show this help message and exit
  --list-agents         Показать список всех доступных агентов
  --create-session      Создать новый сеанс с агентом
  --send MESSAGE        Отправить сообщение агенту
  --agent-id ID         ID агента для работы
  --agent-title TITLE   Название агента для поиска (частичное совпадение)
  --session-id ID       ID существующего сеанса
  --new-session         Принудительно создать новый сеанс
  --no-references       Не показывать источники информации в ответах
  --no-streaming        Отключить потоковую передачу ответов
...

Работа с агентами ​

Получение списка агентов:

bash
python xrmd_agent_manager.py --list-agents

Пример вывода:

Доступные агенты:
-------------------------------------------------
ID: 4988d880356c11f0815e0242ac120006
Название: api_llm_agent
-------------------------------------------------
ID: b416715a34f711f0a6d20242ac120006
Название: support_agent
-------------------------------------------------
ID: c7e3915a34f711f0a6d20242ac120006
Название: security_agent
-------------------------------------------------

Фильтрация списка агентов: Хотя в текущей версии утилиты нет прямых параметров для фильтрации списка агентов, вы можете использовать стандартные инструменты командной строки:

bash
python xrmd_agent_manager.py --list-agents | grep -i "security"

Работа с сеансами ​

Создание сеанса по названию агента:

bash
python xrmd_agent_manager.py --create-session --agent-title "api_llm_agent"

Создание сеанса по ID агента (более точный метод):

bash
python xrmd_agent_manager.py --create-session --agent-id "4988d880356c11f0815e0242ac120006"

Результат создания сеанса:

Создан новый сеанс с агентом 'api_llm_agent'
ID агента: 4988d880356c11f0815e0242ac120006
ID сеанса: 7a92d456-3edc-4fb1-b8d7-a62c98f3e10c

Примечание: ID сеанса следует сохранить, если вы планируете использовать его для последующих запросов. Особенно это актуально при интеграции в скрипты.

Отправка сообщения ​

Простая отправка (с автоматическим созданием сеанса):

bash
python xrmd_agent_manager.py --send "ERROR 2024-07-12 11:15:26,987 config get 148 FATAL: no pg_hba.conf entry for host \"10.1.97.70\", user \"udsdbadm\", database \"udsdb\", SSL on" --agent-title "api_llm_agent"

С созданием нового сеанса (даже если сеансы уже существуют):

bash
python xrmd_agent_manager.py --send "ERROR 2024-07-12 11:15:26,987 config get 148 FATAL: no pg_hba.conf entry for host \"10.1.97.70\", user \"udsdbadm\", database \"udsdb\", SSL on" --agent-title "api_llm_agent" --new-session

Отправка в существующий сеанс (для продолжения диалога):

bash
python xrmd_agent_manager.py --send "Что означает эта ошибка?" --session-id "7a92d456-3edc-4fb1-b8d7-a62c98f3e10c"

Без отображения источников (более компактный вывод):

bash
python xrmd_agent_manager.py --send "ERROR 2024-07-12 11:15:26,987 config get 148 FATAL: no pg_hba.conf entry for host \"10.1.97.70\", user \"udsdbadm\", database \"udsdb\", SSL on" --agent-title "api_llm_agent" --no-references

Без потоковой передачи (ответ придет только после полного завершения):

bash
python xrmd_agent_manager.py --send "ERROR 2024-07-12 11:15:26,987 config get 148 FATAL: no pg_hba.conf entry for host \"10.1.97.70\", user \"udsdbadm\", database \"udsdb\", SSL on" --agent-title "api_llm_agent" --no-streaming

Дополнительные параметры ​

CLI режим поддерживает различные комбинации параметров для более гибкого контроля:

Комплексный пример с несколькими параметрами:

bash
python xrmd_agent_manager.py --send "ERROR 2024-07-12 11:15:26,987 config get 148 FATAL: no pg_hba.conf entry for host \"10.1.97.70\", user \"udsdbadm\", database \"udsdb\", SSL on" --agent-id "4988d880356c11f0815e0242ac120006" --new-session --no-references --no-streaming

Работа с текстовыми файлами: Для отправки содержимого файла как сообщения:

bash
python xrmd_agent_manager.py --send "$(cat error.log)" --agent-title "api_llm_agent"

Перенаправление вывода:

bash
python xrmd_agent_manager.py --send "ERROR 2024-07-12 11:15:26,987..." --agent-title "api_llm_agent" --no-references > result.txt

Параметры CLI ​

Полная таблица всех доступных параметров CLI с детальным описанием:

ПараметрТипОбязательныйОписание
--helpфлагнетПоказать подробную справку по всем командам
--list-agentsфлагнетПолучить список всех доступных агентов
--create-sessionфлагнетСоздать новый сеанс с выбранным агентом
--sendстроканетОтправить указанное сообщение агенту
--agent-idстроканет*ID агента для работы (имеет приоритет над agent-title)
--agent-titleстроканет*Название агента для поиска (поддерживает частичное совпадение)
--session-idстроканетID существующего сеанса для продолжения диалога
--new-sessionфлагнетПринудительно создать новый сеанс, даже если существуют активные
--no-referencesфлагнетНе показывать источники информации в ответах агента
--no-streamingфлагнетОтключить потоковую передачу ответов (выдать только итоговый результат)

Примечание: *Один из параметров --agent-id или --agent-title обязателен при использовании --create-session или --send без указания --session-id.

Настройки и конфигурация ​

Утилита предлагает широкие возможности настройки под конкретные задачи пользователя. Все настройки сосредоточены в начале файла xrmd_agent_manager.py и сгруппированы по функциональным разделам.

Основные настройки ​

Базовые настройки утилиты, необходимые для соединения по API и определения поведения системы:

python
# Параметры подключения
API_KEY = "ragflow-ZjNTQxMjc0ZTE2ZTExZWZiYzQ3MDI0Mm"
BASE_URL = "http://{IP адрес сервера с развернутым ПК Director}:9380"

# Настройки чата с агентом
ENABLE_STREAMING = True           # Потоковая передача
SHOW_REFERENCES = True            # Показ источников
MAX_RESPONSE_LENGTH = 0           # Лимит длины ответа (0 = без лимита)
USER_PROMPT_PREFIX = "===== Вы =====\n> "
ASSISTANT_PREFIX = "===== Агент ====="

# Настройки анализатора логов
LOG_BATCH_SIZE = 10               # Размер пакета логов
LOG_PROCESSING_DELAY = 0.5        # Задержка между запросами

Параметры подключения ​

Конфигурация подключения по API является критически важной для работы утилиты:

  • API_KEY: Персональный ключ доступа. Уникальный для каждой установки ПК Director.

    • Формат: строка, начинающаяся с префикса "ragflow-"
    • Пример: "ragflow-ZjNTQxMjc0ZTE2ZTExZWZiYzQ3MDI0Mm"
    • ⚠️ Важно: храните API ключ в безопасном месте и не передавайте третьим лицам!

  • BASE_URL: URL-адрес ФЗсервера.

    • Формат: полный URL с протоколом (http/https) и портом (если не стандартный)
    • Пример: "http://127.0.0.1:9380" для локальной установки

Настройки чата с агентом ​

Определяют поведение и внешний вид интерфейса чата при общении с агентами:

  • ENABLE_STREAMING: Включение/выключение потоковой передачи ответов от агента.

    • Значения: True - включено (по умолчанию), False - выключено
    • Преимущества включения: получение ответов в реальном времени, видимость процесса генерации
    • Преимущества выключения: меньше нагрузка на сеть, итоговый ответ приходит целиком

  • SHOW_REFERENCES: Показывать или скрывать источники информации, использованные агентом.

    • Значения: True - показывать (по умолчанию), False - скрывать
    • Преимущества включения: прозрачность формирования ответа, возможность проверки источников
    • Преимущества выключения: более компактный вывод, подходит для интеграции с другими системами

  • MAX_RESPONSE_LENGTH: Ограничение максимальной длины ответа агента.

    • Значения: 0 - без ограничений (по умолчанию), любое положительное число - максимальное количество символов
    • Когда использовать ограничения: при работе с консолями с ограниченным буфером, для получения кратких ответов

  • USER_PROMPT_PREFIX: Префикс для отображения пользовательского ввода в чате.

    • По умолчанию: "===== Вы =====\n> "
    • Можно изменить для более компактного отображения, например: "Пользователь: "

  • ASSISTANT_PREFIX: Префикс для отображения ответов агента.

    • По умолчанию: "===== Агент ====="
    • Можно изменить для брендирования или более компактного отображения

Настройки анализатора логов ​

Параметры, влияющие на процесс автоматического анализа логов:

  • LOG_FILE_PATH: Путь к файлу с логами для анализа.

    • По умолчанию: os.path.join(SCRIPT_DIR, "logs_to_agent.txt")
    • Рекомендуется использовать абсолютные пути для надежности
    • Можно изменить через интерфейс меню (пункт 7.6.1)

  • LOG_DB_PATH: Путь к файлу базы данных SQLite для хранения результатов анализа.

    • По умолчанию: os.path.join(SCRIPT_DIR, "log_results.db")
    • Рекомендуется разместить на разделе с достаточным свободным местом
    • Можно изменить через интерфейс меню (пункт 7.6.2)

  • LOG_BATCH_SIZE: Количество строк логов для обработки за один запрос к агенту.

    • По умолчанию: 10
    • Оптимальное значение зависит от:
      • Сложности логов (для сложных логов уменьшите)
      • Производительности сервера (для мощных серверов увеличьте)
      • Доступного объема памяти (для ограниченных ресурсов уменьшите)

  • LOG_PROCESSING_DELAY: Задержка между запросами к агенту при обработке логов (в секундах).

    • По умолчанию: 0.5 (500 миллисекунд)
    • Увеличьте при большой нагрузке на сервер или при достижении лимитов API
    • Уменьшите для более быстрой обработки, если ресурсы сервера позволяют

Предустановленные промпты ​

Шаблоны запросов для различных сценариев использования агентов:

python
PREDEFINED_PROMPTS = {
    "log_prompt_1": "You are a log analyzer. Strictly compare the incoming log line for similarity with two knowledge bases: {{kb_uds_error}} - error examples (ERROR) and {{kb_uds_info}} - normal operation logs (INFO). Log line for analysis: '{}'. Respond ONLY with the required JSON.",
    "log_prompt_2": "Input text:: '{}'",
    "log_analyzer": "'{}'",
}

Подробное объяснение предустановленных промптов:

  1. log_prompt_1:

    • Назначение: Полный промпт для продвинутого анализа логов с использованием баз знаний
    • Особенности:
      • Обращение к конкретным базам знаний ( и )
      • Строгое требование выдачи ответа в формате JSON
      • Классификация логов на ERROR и INFO
    • Когда использовать: Для точного анализа логов с определением типа и степени соответствия

  2. log_prompt_2:

    • Назначение: Простой шаблон для передачи текста агенту
    • Особенности: Минимальное форматирование, просто указывает агенту входной текст
    • Когда использовать: Для быстрой отправки текста без сложных инструкций

  3. log_analyzer:

    • Назначение: Базовый промпт для прямой передачи лога агенту
    • Особенности: Наиболее простая форма, передает лог как есть
    • Когда использовать: Когда агент уже настроен на анализ логов и не требует дополнительных инструкций

Конфигурационные параметры ​

Помимо основных настроек, в начале файла определены дополнительные параметры конфигурации, влияющие на внешний вид и поведение системы:

python
# Системные конфигурационные параметры
CONFIG = {
    # Параметры подключения к серверу
    'API_KEY': API_KEY,
    'BASE_URL': BASE_URL,
    
    # Параметры пагинации
    'DEFAULT_PAGE': 1,
    'DEFAULT_PAGE_SIZE': 30,
    
    # Параметры сортировки
    'DEFAULT_ORDER_BY': "update_time",
    'DEFAULT_DESC': True,
    
    # Настройки интерфейса
    'MENU_SEPARATOR': MENU_SEPARATOR,
    'EXIT_COMMANDS': EXIT_COMMANDS,
    'MENU_COMMANDS': MENU_COMMANDS,
    
    # Настройки чата
    'ENABLE_STREAMING': ENABLE_STREAMING,
    'SHOW_REFERENCES': SHOW_REFERENCES,
    'MAX_RESPONSE_LENGTH': MAX_RESPONSE_LENGTH,
    'USER_PROMPT_PREFIX': USER_PROMPT_PREFIX,
    'ASSISTANT_PREFIX': ASSISTANT_PREFIX,
    
    # Предустановленные промпты
    'PREDEFINED_PROMPTS': PREDEFINED_PROMPTS,
    'INPUT_LOG_LINE': "[INPUT_LOG_LINE]",
    
    # Сообщения
    'MESSAGES': {
        'welcome': "Менеджер по работе с агентами ПК Director",
        'goodbye': "До свидания!",
        'invalid_choice': "Неверный выбор. Попробуйте снова.",
        'press_enter': "Нажмите Enter для продолжения...",
        'no_agents': "Нет доступных агентов",
        'no_session': "Сначала создайте сеанс!",
        'no_sessions_available': "Нет доступных сеансов для этого агента. Создайте новый сеанс.",
        'session_error': "Сессия была сброшена из-за ошибки. Пожалуйста, создайте новую сессию.",
        'chat_welcome': "Здравствуйте! Задайте свой вопрос агенту?",
        'chat_exit_help': "Для выхода введите 'exit', 'quit' или 'выход'. Для возврата в главное меню введите 'menu' или 'меню'.",
        'all_sessions_deleted': "Все сеансы у всех агентов удалены",
        'select_session': "Выберите существующий сеанс или создайте новый",
        'back_to_menu': "Возврат в главное меню..."
    }
}

Параметры пагинации и сортировки:

  • DEFAULT_PAGE: Номер страницы по умолчанию при получении списков (агентов, сеансов)
  • DEFAULT_PAGE_SIZE: Количество элементов на странице
  • DEFAULT_ORDER_BY: Поле для сортировки (обычно "update_time")
  • DEFAULT_DESC: Направление сортировки (True - по убыванию, False - по возрастанию)

Настройки интерфейса:

  • MENU_SEPARATOR: Разделитель в меню (по умолчанию "-" * 50)
  • EXIT_COMMANDS: Список команд для выхода (['exit', 'quit', 'выход'])
  • MENU_COMMANDS: Список команд для возврата в меню (['menu', 'меню', '/menu', '/меню'])

Сообщения интерфейса: Словарь MESSAGES содержит все текстовые сообщения, используемые в интерфейсе. Изменение этих сообщений позволяет настроить интерфейс под конкретные нужды, включая локализацию на другие языки.

Расширение функциональности ​

При необходимости вы можете расширить функциональность утилиты, модифицируя код или добавляя новые настройки:

  1. Добавление новых промптов:

    python
    PREDEFINED_PROMPTS["my_new_prompt"] = "Новый шаблон промпта: '{}'"

  2. Настройка форматирования вывода:

    python
    # Измените префиксы для более компактного отображения
USER_PROMPT_PREFIX = "👤 "
ASSISTANT_PREFIX = "🤖 "

  3. Настройка параметров базы данных:

    python
    # Добавьте в начало файла после импорта модулей
DB_PRAGMAS = {
    "journal_mode": "WAL",      # Режим журналирования
    "synchronous": "NORMAL",    # Режим синхронизации
    "cache_size": 5000          # Размер кэша (в страницах)
}
# Затем используйте эти настройки при инициализации базы данных

Работа с логами ​

Анализатор логов - одна из ключевых функций утилиты, позволяющая автоматизировать процесс обработки и интерпретации системных логов с использованием искусственного интеллекта. Эта функциональность особенно полезна при мониторинге сложных систем и быстром выявлении потенциальных проблем.

Структура базы данных ​

Для хранения результатов анализа логов используется база данных SQLite, что обеспечивает надежность хранения и простоту доступа к данным. Скрипт автоматически создает базу log_results.db со следующей структурой:

  1. log_analysis - таблица для хранения детальных результатов анализа каждой строки лога:

    sql
    CREATE TABLE IF NOT EXISTS log_analysis (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    agent_name TEXT NOT NULL,           -- Название агента, выполнившего анализ
    log_text TEXT NOT NULL,             -- Исходный текст строки лога
    response TEXT NOT NULL,             -- Полный ответ агента
    json_answer TEXT,                   -- Извлеченный JSON из ответа (если есть)
    processing_time REAL NOT NULL,      -- Время обработки в секундах
    timestamp DATETIME DEFAULT CURRENT_TIMESTAMP  -- Временная метка анализа
)

  2. log_stats - таблица для хранения сводной статистики по сеансам обработки логов:

    sql
    CREATE TABLE IF NOT EXISTS log_stats (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    start_time DATETIME NOT NULL,       -- Время начала сеанса
    end_time DATETIME,                  -- Время завершения сеанса
    total_logs INTEGER NOT NULL,        -- Общее количество логов для обработки
    processed_logs INTEGER NOT NULL,    -- Обработано логов
    successful_logs INTEGER NOT NULL,   -- Успешно обработано
    failed_logs INTEGER NOT NULL,       -- Количество ошибок обработки
    average_time REAL,                  -- Среднее время обработки (сек)
    status TEXT NOT NULL                -- Статус сеанса (running, completed, stopped, paused)
)

Примечание по безопасности:

  • База данных SQLite не требует установки отдельного сервера
  • Для обеспечения целостности данных используются внешние ключи и транзакции
  • При повреждении базы данных система автоматически пытается восстановить её структуру
  • Рекомендуется периодически создавать резервные копии базы данных для предотвращения потери результатов анализа

Поддерживаемые форматы логов ​

Анализатор поддерживает работу с различными форматами логов. Благодаря использованию технологий искусственного интеллекта, система может эффективно интерпретировать множество форматов без необходимости предварительной настройки парсеров:

  1. Стандартные системные логы:

    Jul 12 11:15:26 server kernel: CPU: 1 PID: 1234 Comm: process Tainted: G        W  4.15.0-54

  2. Логи приложений PostgreSQL:

    2024-07-12 11:15:26,987 [1234] ERROR: no pg_hba.conf entry for host "10.1.97.70", user "udsdbadm"

  3. Логи в формате systemd:

    июл 12 11:15:26 hostname service[1234]: Connection to database failed: timeout

  4. Структурированные JSON логи:

    {"timestamp": "2024-07-12T11:15:26.987Z", "level": "ERROR", "message": "Connection failed", "host": "10.1.97.70"}

  5. Логи веб-серверов (Apache, Nginx):

    10.15.20.25 - - [12/Jul/2024:11:15:26 +0300] "GET /api/status HTTP/1.1" 500 1234 "-" "Mozilla/5.0"

  6. Пользовательские форматы:

    • Любые текстовые логи, даже без стандартной структуры, могут быть проанализированы
    • Система использует контекстное понимание для интерпретации даже нестандартных форматов

Процесс анализа ​

Процесс анализа логов состоит из нескольких последовательных этапов:

  1. Загрузка логов:

    • Чтение строк из файла logs_to_agent.txt (или другого указанного пути)
    • Фильтрация пустых строк
    • Формирование очереди для обработки

  2. Подготовка к анализу:

    • Выбор агента для анализа (рекомендуется api_llm_agent)
    • Создание нового сеанса с выбранным агентом
    • Выбор подходящего шаблона промпта
    • Создание записи в таблице статистики для отслеживания процесса

  3. Пакетная обработка:

    • Строки логов обрабатываются пакетами по LOG_BATCH_SIZE строк
    • Для каждой строки формируется специальный промпт для агента
    • Строки отправляются на анализ с интервалом LOG_PROCESSING_DELAY секунд

  4. Интеллектуальный анализ:

    • Агент анализирует строку лога, используя свои знания и контекст
    • Для каждой строки генерируется ответ, идеально в структурированном JSON формате
    • Измеряется время обработки каждой строки для сбора статистики

  5. Сохранение результатов:

    • Ответ агента сохраняется в таблицу log_analysis
    • Если ответ содержит JSON, он извлекается и сохраняется отдельно для удобства дальнейшего использования
    • Статистика обработки (успешная/неуспешная) обновляется в таблице log_stats

  6. Мониторинг процесса:

    • Текущий статус обработки отображается в реальном времени
    • Пользователь может приостановить, возобновить или полностью остановить процесс
    • По завершении обработки формируется итоговая статистика

Типы промптов для анализа ​

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

  1. Полный аналитический промпт (log_prompt_1):

    You are a log analyzer. Strictly compare the incoming log line for similarity 
with two knowledge bases: {{kb_uds_error}} - error examples (ERROR) and 
{{kb_uds_info}} - normal operation logs (INFO). 
Log line for analysis: 'ERROR 2024-07-12 11:15:26,987 config get 148 FATAL: no pg_hba.conf entry'. 
Respond ONLY with the required JSON.
    • Особенности: Максимально точный анализ с использованием баз знаний
    • Ожидаемый результат: Структурированный JSON с детальной информацией о типе лога и его классификации
    • Пример ответа:
      json
      {"similarity_percent": 95, "match": 1, "log_type": "ERROR", "category": "PostgreSQL auth failure"}

  2. Простой промпт (log_prompt_2):

    Input text:: 'ERROR 2024-07-12 11:15:26,987 config get 148 FATAL: no pg_hba.conf entry'
    • Особенности: Минимальное форматирование, универсальный промпт
    • Пример ответа: Может варьироваться от текстового описания до JSON-объекта

  3. Базовый промпт (log_analyzer):

    'ERROR 2024-07-12 11:15:26,987 config get 148 FATAL: no pg_hba.conf entry'
    • Особенности: Прямая передача текста лога агенту
    • Пример ответа: Может варьироваться в зависимости от обучения агента

  4. Пользовательский промпт:

    • Возможность создания собственных промптов через меню "Редактирование промптов"
    • Полная свобода в формировании запросов к агенту с использованием плейсхолдера {} для вставки текста лога

Интерпретация результатов ​

После анализа логов результаты могут быть представлены в различных форматах:

  1. JSON-ответы: Наиболее удобный формат для автоматизированной обработки. Типичный JSON может содержать:

    • similarity_percent: Процент соответствия известным шаблонам (0-100%)
    • match: Тип совпадения (0 - не совпадает, 1 - ошибка, 2 - информационное сообщение)
    • log_type: Классификация лога (ERROR, INFO, WARNING)
    • category: Категория сообщения
    • severity: Уровень критичности (1-5, где 5 - максимальная критичность)
    • description: Текстовое описание проблемы
    • recommendation: Рекомендации по устранению (если применимо)

  2. Текстовые ответы: В случае, если агент не вернул структурированный JSON, результат будет содержать текстовый анализ:

    • Описание проблемы
    • Возможные причины
    • Рекомендации по устранению

Оптимизация процесса анализа ​

Для повышения эффективности работы анализатора логов:

  1. Выбор подходящего агента:

    • Для общего анализа логов рекомендуется использовать api_llm_agent
    • Для специфических задач могут быть использованы специализированные агенты

  2. Настройка размера пакета:

    • Увеличьте LOG_BATCH_SIZE для ускорения обработки, если сервер достаточно мощный
    • Уменьшите размер пакета при обработке сложных логов или при ограниченных ресурсах

  3. Управление задержкой:

    • Настройте LOG_PROCESSING_DELAY в зависимости от нагрузки на сервер
    • Минимальная рекомендуемая задержка - 0.1 секунд для предотвращения перегрузки API

  4. Фильтрация логов:

    • Предварительно отфильтруйте логи по ключевым словам для обработки только важных сообщений
    • Пример: grep -i "error\|warning\|critical" system.log > logs_to_agent.txt

Пример файла логов ​

Для начала работы с анализатором создайте файл logs_to_agent.txt в папке скрипта со следующим содержимым:

text
ERROR 2024-07-12 11:15:26,987 config get 148 FATAL:  no pg_hba.conf entry for host "10.1.97.70", user "udsdbadm", database "udsdb", SSL on
INFO 2024-07-12 11:16:30,123 User login successful for admin
ERROR 2024-07-12 11:17:45,456 Timeout connecting to API
WARNING 2024-07-12 11:18:00,789 High memory usage detected
INFO 2024-07-12 11:20:15,234 Database backup completed successfully
ERROR 2024-07-12 11:25:32,678 Out of memory: Kill process 1234 (java) score 123
WARNING 2024-07-12 11:30:45,901 Disk usage above 85% on /var/log
INFO 2024-07-12 11:35:22,345 Service restarted successfully
ERROR 2024-07-12 11:40:18,765 Failed to connect to database: Connection refused

Этот набор логов представляет различные типы сообщений и ситуаций, что позволит оценить возможности анализатора и качество ответов агента.

Примеры использования ​

Пример 1: Анализ логов через интерфейс ​

  1. Запустить: python xrmd_agent_manager.py
  2. Выбрать пункт 7 (Анализатор логов)
  3. Выбрать пункт 1 (Запустить обработку логов)
  4. Выбрать агента api_llm_agent
  5. Выбрать промпт для анализа
  6. Дождаться завершения анализа
  7. Просмотреть результаты (пункт 5)

Ожидаемый результат:

json
{"similarity_percent": 95, "match": 1}

Пример 2: Быстрый анализ через CLI ​

bash
# Анализ конкретной ошибки
python xrmd_agent_manager.py --send "ERROR 2024-07-12 11:15:26,987 config get 148 FATAL: no pg_hba.conf entry for host \"10.1.97.70\", user \"udsdbadm\", database \"udsdb\", SSL on" --agent-title "api_llm_agent" --new-session

Ожидаемый ответ:

json
{"similarity_percent": 95, "match": 1}

Пример 3: Пакетная отправка вопросов ​

bash
python xrmd_agent_manager.py --send "ERROR 2024-07-12 11:15:26,987 config get 148 FATAL: no pg_hba.conf entry for host \"10.1.97.70\", user \"udsdbadm\", database \"udsdb\", SSL on" --agent-title "api_llm_agent" --new-session
python xrmd_agent_manager.py --send "INFO 2024-07-12 11:16:30,123 User login successful for admin" --agent-title "api_llm_agent" --new-session
python xrmd_agent_manager.py --send "WARNING 2024-07-12 11:18:00,789 High memory usage detected" --agent-title "api_llm_agent" --new-session

XSYSTECH.RU

Copyright © 2022-2026