Аналитическая мультиагентная система «InsightFinder» — это мультиагентная система автоматического анализа данных (AutoEDA) на базе LangChain, разработанная для выявления ключевых факторов, различающих две группы по бинарной целевой переменной (например, "ушедшие клиенты" vs "лояльные клиенты").
Проект использует набор специализированных аналитических инструментов, управляемых LLM-агентами, для генерации подробного аналитического отчёта без необходимости написания кода пользователем.
Разработать прототип мультиагентной системы на Python, которая автоматически проводит исследовательский анализ данных (EDA) для табличного датасета с бинарной целевой переменной и генерирует человекочитаемый аналитический отчёт в формате Markdown (и HTML).
Пример отчета можно посмотреть в report/output (используемая модель: qwen2.5-32b-instruct).
pandas, numpy, scikit-learn, scipy, matplotlib, seaborn, langchain, openai, gradio, docker
insightfinder/
│
├── agents/
│ ├── analyst_agent.py # Агент, выбирающий необходимые для анализа инструменты
│ ├── executor_agent.py # Агент, запускающий инструменты
│ ├── summarizer_agent.py # Агент, генерирующий финальный отчёт
│ └── tools_wrapper.py # Обёртки для инструментов как LangChain Tools
│
├── core/
│ ├── data_loader.py # Загрузка и предварительная обработка данных
│ ├── orchestrator.py # Оркестратор всего процесса анализа
│ ├── utils.py # Вспомогательные функции
│ ├── logger.py # Настройка логирования
│ └── pipeline.py # Запуск оркестратора
│
├── logs/ # Папка с логами работы приложения
│ ├── orchestrator.log
│ ├── summarizer.log
│ └── ...(другие логи)
│
├── report/
│ ├── output/
│ │ ├── insightfinder_report_YYYYMMDD_HHMMSS.md # Финальный отчет (пример)
│ │ └── images/ # Папка для графиков из отчета
│ │ ├── desc_*.png
│ │ ├── corr_*.png
│ │ └── ...(другие изображения)
│ ├── to_html.py # Преобразование отчета markdown в HTML
│ └── generate_report.py # Сохранение отчёта в файл
│
├── tests/
│ ├── test_tools.py # Тесты для инструментов
│ ├── test_edge_cases.py # Тесты на граничные случаи
│ └── ...(другие тесты)
│
├── ui/
│ ├── web_app.py # Веб интерфейс (резерв, Streamlit)
│ └── gradio_app.py # Веб интерфейс (основной, Gradio)
│
├── tools/
│ ├── __init__.py
│ ├── primary_feature_finder.py # Поиск главного признака (Decision Tree глубины 1)
│ ├── correlation_analysis.py # Анализ корреляций (Point-Biserial)
│ ├── descriptive_stats_comparator.py # Сравнение описательных статистик между группами
│ ├── categorical_feature_analysis.py # Анализ категориальных признаков (Хи-квадрат)
│ ├── full_model_importance.py # Важность признаков (Random Forest)
│ ├── distribution_visualizer.py # Создание графиков распределений (boxplot, hist)
│ ├── outlier_detector.py # Обнаружение выбросов (IQR, Z-score)
│ ├── interaction_analyzer.py # Анализ взаимодействий признаков
│ └── insight_driven_visualizer.py # Создание целенаправленных графиков на основе инсайтов
│
├── tmp/ # Временные файлы (отчеты, архивы, загрузки)
├── .env # Файл с переменными окружения (API ключи)
├── .dockerignore # Файл для игнорирования файлов при сборке Docker-образа
├── Dockerfile # Файл для сборки Docker-образа
├── docker-compose.yml # Конфигурация для запуска через Docker Compose
├── .gitignore # Файл для игнорирования файлов в Git
├── main.py # Точка входа в приложение
├── debug_tools.py # Скрипт для отладки инструментов
├── requirements.txt # Зависимости проекта
└── README.md # Описание проекта
Docker обеспечивает изолированную, воспроизводимую среду для запуска приложения.
Убедитесь, что Docker установлен и запущен на вашем компьютере.
В корневой директории проекта (insightfinder) выполните:
docker build -t insightfinder .Запустите контейнер через терминал, пробросив порт 8502 (порт Gradio по умолчанию) и, опционально, подключив локальные директории для сохранения логов и отчётов командой:
# Запуск с сохранением логов и отчётов на хосте
docker run -p 8502:8502 \
-v $(pwd)/logs:/app/logs \
-v $(pwd)/report/output:/app/report/output \
insightfinder
# На Windows PowerShell для монтирования директорий используйте:
# docker run -p 8502:8502 -v ${PWD}/logs:/app/logs -v ${PWD}/report/output:/app/report/output insightfinderПримечание: При первом запуске папки
logsиreport/outputбудут созданы автоматически. Монтирование позволяет сохранять логи и отчёты на вашем компьютере даже после остановки контейнера.
Альтернативно можно использовать docker-compose. Это удобнее, так как все настройки вынесены в один файл.
Выполните в корневой директории:
docker-compose up --buildПриложение будет доступно по адресу: http://localhost:8502
Чтобы остановить приложение:
docker-compose downПреимущество:
Логи (logs) и отчёты (report/output) автоматически сохраняются на вашем компьютере.
Откройте браузер и перейдите по адресу: http://localhost:8502
Создайте виртуальное окружение и установите зависимости:
python -m venv venv
source venv/bin/activate # На Windows: venv\Scripts\activate
pip install -r requirements.txtpython main.pyПримечание: При локальном запуске директории
logs,tmp,report/output/imagesсоздаются автоматически. Логи будут записываться в папкуlogsвнутри проекта.
Чтобы приложение работало, ему нужен доступ к API вашей LLM. Есть два простых способа это сделать:
Просто запустите приложение. В интерфейсе Gradio будут поля для ввода API ключа, URL эндпоинта и названия модели. Приложение использует эти настройки для подключения.
Создайте в корневой директории проекта файл с названием .env и добавьте туда свои переменные:
OPENAI_API_KEY=ваш_api_ключ
OPENAI_BASE_URL=https://openai-hub.neuraldeep.tech # или ваш приватный эндпоинт
OPENAI_MODEL=qwen2.5-32b-instruct
Примечание: Проект использует
ChatOpenAIизlangchain_openai. Убедитесь, что ваша модель (например,qwen2.5-32b-instruct) доступна по указанномуbase_url. Если у вас нет доступа к LLM по API, обращайтесь в TG к @Zhdanov_Alexey
После запуска откроется страница в браузере (http://localhost:8502), где можно:
- Настроить API: Ввести API ключ, URL и модель.
- Загрузить CSV-файл: Выбрать файл для анализа.
- Задать вопрос: Сформулировать вопрос, на который система должна ответить, анализируя данные (например, "Какие факторы влияют на отток клиентов?"). Этот вопрос также используется для автоматического определения целевой переменной.
- Запустить анализ: Нажать кнопку "🚀 Запустить анализ".
- Просмотреть отчёт: После завершения анализа будет отображен интерактивный HTML-отчёт.
- Задать вопрос по отчёту: Ввести уточняющий вопрос по уже сгенерированному отчёту и получить краткий ответ от LLM.
- Скачать результаты:
- Отчёт в формате
.md. - Отчёт в формате
.html. - Графики из отчета в архиве
.zip. - Логи работы приложения в архиве
.zip.
- Отчёт в формате
- Интерфейс (
ui/gradio_app.py) получает данные от пользователя. - Оркестратор (
core/orchestrator.py) запускает процесс анализа. - Аналитик (
agents/analyst_agent.py) — LLM, которая решает, какой инструмент запустить следующим. - Исполнитель (
agents/executor_agent.py) запускает выбранный инструмент. - Инструменты (
tools/) выполняют статистический анализ:PrimaryFeatureFinder: находит главный признак (Decision Tree глубины 1).CorrelationAnalysis: считает корреляции с бинарной целью.DescriptiveStatsComparator: сравнивает статистики между группами.CategoricalFeatureAnalysis: проверяет категориальные признаки на значимость.FullModelImportance: оценивает важность признаков через Random Forest.DistributionVisualizer: создает графики распределений (boxplot, hist).OutlierDetector: ищет выбросы среди фичей.InteractionAnalyzer: анализирует взаимодействия признаков.InsightDrivenVisualizer: создает целенаправленные графики на основе полученных ранее инсайтов.
- Сумматор (
agents/summarizer_agent.py) собирает все результаты и генерирует финальный отчёт. - Интерфейс отображает отчёт и предоставляет возможность задать вопрос по нему и скачать результаты.
- Python 3.10+
- Доступ к LLM API (например, OpenAI, или приватный эндпоинт)
- Библиотеки из
requirements.txt
Отчёт включает:
- Анализ ключевых выводов (краткое резюме основных инсайтов)
- Главный признак и его характеристики
- Топ корреляций
- Сравнение статистик между группами
- Значимые категориальные признаки
- Важность признаков по модели
- Анализ распределений и их визуализация
- Выбросы и аномалии
- Анализ взаимодействий признаков
- Инсайт-ориентированные визуализации
- Заключение и рекомендации
Запустить тесты:
python -m pytest tests/MIT