DeepTutor: Персональный учебный ассистент на базе ИИ

Быстрый старт · Основные модули · Часто задаваемые вопросы

🇬🇧 English · 🇨🇳 中文 · 🇯🇵 日本語 · 🇪🇸 Español · 🇫🇷 Français · 🇸🇦 العربية · 🇮🇳 हिन्दी · 🇵🇹 Português

📚 Q&A по знаниям из массивов документов • 🎨 Интерактивная визуализация обучения
🎯 Укрепление знаний • 🔍 Глубокие исследования и генерация идей

📰 Новости

[2026.1.1] С Новым годом! Присоединяйтесь к нашему Discord-сообществу, WeChat-сообществу или Discussions — формируйте будущее DeepTutor! 💬

[2025.12.30] Посетите наш официальный сайт для получения дополнительной информации!

[2025.12.29] DeepTutor уже в сети! ✨

📦 Релизы

[2026.1.23] Релиз v0.6.0 - Сохранение сеансов интерфейса, полная поддержка китайского языка, обновления развертывания Docker и исправления незначительных ошибок -- Спасибо всем за обратную связь!

История релизов

[2026.1.18] Релиз v0.5.2 - Улучшение конвейера RAG с поддержкой Docling и улучшение рабочих процессов CI/CD с исправлением нескольких незначительных ошибок -- Спасибо всем за отзывы!

[2026.1.15] Релиз v0.5.0 - Унифицированные службы LLM и встраивания, выбор конвейера RAG и значительные улучшения модулей Home, History, QuestionGen и Settings -- Спасибо всем участникам!

[2026.1.9] Релиз v0.4.1 с полной переработкой системы провайдера LLM, улучшением надежности генерации вопросов и очисткой кодовой базы - Спасибо всем участникам!

[2026.1.9] Релиз v0.4.0 с новой структурой кода, поддержкой нескольких llm и встраиваний - Спасибо всем участникам!

[2026.1.5] v0.3.0 - Унифицированная архитектура PromptManager, автоматизация CI/CD и предварительно собранные образы Docker на GHCR

[2026.1.2] v0.2.0 - Развертывание Docker, обновление до Next.js 16 и React 19, исправления безопасности WebSocket и критических уязвимостей

Ключевые особенности DeepTutor

📚 Q&A по знаниям из массивов документов

• Интеллектуальная база знаний: Загружайте учебники, научные статьи, технические руководства и документы, специфичные для области. Создавайте исчерпывающий репозиторий знаний на основе ИИ для мгновенного доступа.
• Решение проблем с несколькими агентами: Двухконтурная архитектура рассуждений с RAG, веб-поиском и выполнением кода — предоставление пошаговых решений с точными цитатами.

🎨 Интерактивная визуализация обучения

• Упрощение знаний и объяснения: Преобразование сложных концепций, знаний и алгоритмов в понятные визуальные пособия, подробные пошаговые разборы и увлекательные интерактивные демонстрации.
• Персонализованный Q&A: Контекстно-зависимые разговоры, адаптирующиеся к вашему прогрессу в обучении, с интерактивными страницами и отслеживанием знаний на основе сеансов.

🎯 Укрепление знаний с помощью генератора практических задач

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

🔍 Глубокие исследования и генерация идей

• Комплексные исследования и обзор литературы: Проведение глубокого изучения тем с систематическим анализом. Выявление закономерностей, соединение связанных концепций в разных дисциплинах и синтез существующих исследовательских находок.
• Открытие новых идей: Генерация структурированных учебных материалов и выявление пробелов в знаниях. Определение перспективных новых направлений исследований посредством интеллектуального синтеза знаний между доменами.

📚 Q&A по знаниям из массивов документов

_{Многоагентное решение проблем с точными цитатами}

🎨 Интерактивная визуализация обучения

_{Пошаговые визуальные объяснения с персональными Q&A}

🎯 Укрепление знаний

Пользовательские вопросы _{Генерация практических вопросов с автоматической проверкой}

Имитационные вопросы _{Клонирование стиля экзамена для подлинной практики}

🔍 Глубокие исследования и генерация идей

Глубокие исследования _{Расширение знаний из учебника с помощью RAG, веб- и поиска по статьям}

Автоматизированная генерация идей _{Систематический мозговой штурм и синтез концепций с двухфазным рабочим процессом}

Интерактивная генерация идей _{Совместное написание текстов на основе RAG и веб-поиска с генерацией подкастов}

🏗️ Все-в-одном система знаний

Персональная база знаний _{Создание и организация собственного репозитория знаний}

Персональный блокнот _{Ваша контекстная память для учебных сессий}

_{🌙 Используйте DeepTutor в темном режиме!}

🏛️ Фреймворк DeepTutor

💬 Слой пользовательского интерфейса

• Интуитивное взаимодействие: Простой двунаправленный поток запросов-ответов для интуитивного взаимодействия.
• Структурированный вывод: Генерация структурированных ответов, организующих сложную информацию в действия.

🤖 Модули интеллектуальных агентов

• Решение проблем и оценка: Пошаговое решение проблем и генерация настраиваемых оценок.
• Исследование и обучение: Глубокие исследования для изучения тем и руководство обучением с визуализацией.
• Генерация идей: Автоматизированное и интерактивное развитие концепций с инсайтами из нескольких источников.

🔧 Слой интеграции инструментов

• Поиск информации: Гибридное извлечение RAG, поиск в реальном времени и базы данных научных статей.
• Обработка и анализ: Выполнение кода Python, поиск элементов запроса и анализ документов в формате PDF.

🧠 Основа знаний и памяти

• Граф знаний: Сопоставление сущностей и отношений для семантических связей и открытия знаний.
• Векторное хранилище: Поиск на основе встраивания для интеллектуального поиска контента.
• Система памяти: Управление состоянием сеанса и отслеживание цитат для контекстной непрерывности.

📋 Будущие задачи

🌟 Поставьте звезду, чтобы следить за нашими будущими обновлениями!

Поддержка многоязычности
Сообщество DeepTutor
Поддержка видео- и аудиофайлов
Настройка атомарного конвейера RAG
Пошаговое редактирование базы знаний
Персонализированное рабочее пространство
Визуализация базы данных
Онлайн-демонстрация

🚀 Быстрый старт

Шаг 1: Предварительная настройка

① Клонирование репозитория

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor

② Настройка переменных окружения

cp .env.example .env
# Отредактируйте файл .env с вашими API ключами

📋 Справочник переменных окружения

Переменная	Обязательно	Описание
`LLM_MODEL`	Да	Имя модели (например: `gpt-4o`)
`LLM_API_VERSION`	Нет	Версия API для Azure OpenAI (например: `2024-02-15-preview`)
`LLM_API_KEY`	Да	Ваш API ключ LLM
`LLM_HOST`	Да	URL конечной точки API
`EMBEDDING_MODEL`	Да	Имя модели встраивания
`EMBEDDING_API_VERSION`	Нет	Версия API для Azure OpenAI Embeddings
`EMBEDDING_API_KEY`	Да	API ключ встраивания
`EMBEDDING_HOST`	Да	Конечная точка API встраивания
`BACKEND_PORT`	Нет	Порт backend (по умолчанию: `8001`)
`FRONTEND_PORT`	Нет	Порт frontend (по умолчанию: `3782`)
`NEXT_PUBLIC_API_BASE`	Нет	URL API для фронтенда — установите для удаленного/LAN-доступа (например: `http://192.168.1.100:8001`)
`TTS_*`	Нет	Настройки синтеза речи
`SEARCH_PROVIDER`	Нет	Провайдер поиска (варианты: `perplexity`, `tavily`, `serper`, `jina`, `exa`, `baidu`, по умолчанию: `perplexity`)
`SEARCH_API_KEY`	Нет	Единый API-ключ для поиска

💡 Удаленный доступ: если вы заходите с другого устройства (например: 192.168.31.66:3782), добавьте в .env:
NEXT_PUBLIC_API_BASE=http://192.168.31.66:8001

③ Настроить Порты и LLM (Опционально)

Порты: Настройте в .env → BACKEND_PORT / FRONTEND_PORT (по умолчанию: 8001/3782)
LLM: Отредактируйте config/agents.yaml → temperature / max_tokens для каждого модуля
См. Документацию по конфигурации для подробностей

④ Попробовать демо базы знаний (Опционально)

📚 Доступные демо

Исследовательские Статьи — 5 статей из нашей лаборатории (AI-Researcher, LightRAG, и т.д.)
Учебник по Науке о Данных — 8 глав, 296 страниц (Ссылка на Книгу)

Скачать с Google Drive
Распаковать в каталог data/

Демо БЗ используют text-embedding-3-large с dimensions = 3072

⑤ Создать собственную базу знаний (После Запуска)

Перейдите на http://localhost:3782/knowledge
Нажмите "New Knowledge Base" → Введите имя → Загрузите файлы PDF/TXT/MD
Следите за прогрессом в терминале

Шаг 2: Выберите метод установки

🐳 Вариант A: Установка через Docker

Установка Python/Node.js не требуется

Требования: Docker & Docker Compose

Быстрый старт — Сборка из исходного кода:

docker compose up                  # Сборка и запуск (~11 мин при первом запуске на mac mini M4)
docker compose build --no-cache    # Очистка кэша и пересборка после обновления репозитория

Или использовать предварительно собранный образ (быстрее):

# Работает на всех платформах — Docker автоматически определяет архитектуру
docker run -d --name deeptutor \
  -p 8001:8001 -p 3782:3782 \
  --env-file .env \
  -v $(pwd)/data:/app/data \
  -v $(pwd)/config:/app/config:ro \
  ghcr.io/hkuds/deeptutor:latest

# Windows PowerShell: используйте ${PWD} вместо $(pwd)

Общие команды:

docker compose up -d      # Запуск
docker compose down       # Остановка
docker compose logs -f    # Просмотр логов
docker compose up --build # Пересборка после изменений

📋 Дополнительные параметры Docker (предварительно собранные образы, облачная установка, пользовательские порты)

Теги предварительно собранных образов:

Тег	Архитектуры	Описание
`:latest`	AMD64 + ARM64	Последний стабильный выпуск (автоопределение архитектуры)
`:v0.5.x`	AMD64 + ARM64	Конкретная версия (автоопределение архитектуры)
`:v0.5.x-amd64`	Только AMD64	Явный образ AMD64
`:v0.5.x-arm64`	Только ARM64	Явный образ ARM64

💡 Тег :latest является мультиархитектурным образом — Docker автоматически загружает правильную версию для вашей системы (Intel/AMD или Apple Silicon/ARM)

Облачная установка — Необходимо установить внешний URL-адрес API:

docker run -d --name deeptutor \
  -p 8001:8001 -p 3782:3782 \
  -e NEXT_PUBLIC_API_BASE_EXTERNAL=https://your-server.com:8001 \
  --env-file .env \
  -v $(pwd)/data:/app/data \
  ghcr.io/hkuds/deeptutor:latest

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

docker run -d --name deeptutor \
  -p 9001:9001 -p 3000:3000 \
  -e BACKEND_PORT=9001 \
  -e FRONTEND_PORT=3000 \
  -e NEXT_PUBLIC_API_BASE_EXTERNAL=https://your-server.com:9001 \
  --env-file .env \
  -v $(pwd)/data:/app/data \
  ghcr.io/hkuds/deeptutor:latest

💻 Вариант B: Ручная установка

Для разработки или сред без Docker

Требования: Python 3.10+, Node.js 18+

1. Настройка окружения:

# Использование conda (Рекомендуется)
conda create -n deeptutor python=3.10 && conda activate deeptutor

# Или использование venv
python -m venv venv && source venv/bin/activate  # Windows: venv\Scripts\activate

2. Установка зависимостей:

# Установка в один клик (Рекомендуется)
python scripts/install_all.py
# Или: bash scripts/install_all.sh

# Или ручная установка
pip install -r requirements.txt
npm install --prefix web

3. Запуск:

python scripts/start_web.py    # Запуск интерфейса и бэкенда
# Или: python scripts/start.py  # Только CLI
# Остановка: Ctrl+C

🔧 Запуск интерфейса и бэкенда отдельно

Бэкенд (FastAPI):

python src/api/run_server.py
# Или: uvicorn src.api.main:app --host 0.0.0.0 --port 8001 --reload

Интерфейс (Next.js):

cd web && npm install && npm run dev -- -p 3782

Примечание: Создайте web/.env.local:

NEXT_PUBLIC_API_BASE=http://localhost:8001

Сервис	Порт по умолчанию
Бэкенд	`8001`
Интерфейс	`3782`

URLs Доступа

Сервис	URL	Описание
Frontend	http://localhost:3782	Основной веб-интерфейс
Документация API	http://localhost:8001/docs	Интерактивная документация API

📂 Хранение данных

Все пользовательские данные и системные данные хранятся в каталоге data/:

data/
├── knowledge_bases/              # Хранилище базы знаний
└── user/                         # Данные пользовательской активности
    ├── solve/                    # Результаты решения проблем и артефакты
    ├── question/                 # Сгенерированные вопросы
    ├── research/                 # Отчеты об исследованиях и кэш
    ├── co-writer/                # Интерактивные документы IdeaGen и аудиофайлы
    ├── notebook/                 # Записи блокнотов и метаданные
    ├── guide/                    # Сеансы руководства обучением
    ├── logs/                     # Системные логи
    └── run_code_workspace/       # Рабочее пространство выполнения кода

Результаты автоматически сохраняются во время всех действий. Каталоги создаются автоматически по мере необходимости.

📦 Основные модули

🧠 Умный решатель

Диаграмма архитектуры

Интеллектуальная система решения проблем на основе двухконтурной архитектуры Анализ + Решение, поддерживающая многорежимные рассуждения и динамическое извлечение знаний.

Основные особенности

Feature	Description
Двухконтурная архитектура	Контур анализа: InvestigateAgent → NoteAgent Контур решения: PlanAgent → ManagerAgent → SolveAgent → CheckAgent → Format
Совместная работа нескольких агентов	Специализированные агенты: InvestigateAgent, NoteAgent, PlanAgent, ManagerAgent, SolveAgent, CheckAgent
Потоковая передача в реальном времени	Передача через WebSocket с отображением процесса рассуждения в реальном времени
Интеграция инструментов	RAG (наивный/гибридный), веб-поиск, элемент запроса, выполнение кода
Постоянная память	Файлы памяти на основе JSON для сохранения контекста
Управление цитированием	Структурированные цитаты с отслеживанием ссылок

Использование

Перейдите на http://localhost:{frontend_port}/solver
Выберите базу знаний
Введите свой вопрос, нажмите "Solve"
Наблюдайте за процессом рассуждения в реальном времени и окончательный ответ

Python API

import asyncio
from src.agents.solve import MainSolver

async def main():
    solver = MainSolver(kb_name="ai_textbook")
    result = await solver.solve(
        question="Calculate the linear convolution of x=[1,2,3] and h=[4,5]",
        mode="auto"
    )
    print(result['formatted_solution'])

asyncio.run(main())

Местоположение вывода

data/user/solve/solve_YYYYMMDD_HHMMSS/
├── investigate_memory.json    # Память контура анализа
├── solve_chain.json           # Шаги контура решения и записи инструментов
├── citation_memory.json       # Управление цитированием
├── final_answer.md            # Окончательное решение (Markdown)
├── performance_report.json    # Мониторинг производительности
└── artifacts/                 # Вывод выполнения кода

📝 Генератор вопросов

Диаграмма архитектуры

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

Основные особенности

Feature	Description
Пользовательский режим	Фоновые знания → Планирование вопросов → Генерация → Однократная проверка Анализирует релевантность вопросов без логики отклонения
Режим имитации	Загрузка PDF → Парсинг MinerU → Извлечение вопросов → Имитация стиля Генерирует вопросы на основе структуры эталонного экзамена
Движок ReAct	QuestionGenerationAgent с автономным принятием решений (think → act → observe)
Анализ проверки	Однократный анализ релевантности с `kb_coverage` и `extension_points`
Типы вопросов	Multiple choice, fill-in-the-blank, calculation, written response, etc.
Пакетная генерация	Parallel processing with progress tracking
Complete Persistence	All intermediate files saved (background knowledge, plan, individual results)
Timestamped Output	Mimic mode creates batch folders: `mimic_YYYYMMDD_HHMMSS_{pdf_name}/`

Использование

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

Перейдите на http://localhost:{frontend_port}/question
Заполните требования (topic, difficulty, question type, count)
Нажмите "Generate Questions"
Просмотрите сгенерированные вопросы с отчетами о проверке

Режим имитации:

Перейдите на http://localhost:{frontend_port}/question
Переключитесь на вкладку "Mimic Exam"
Загрузите PDF или укажите каталог разобранного экзамена
Дождитесь разбора → извлечения → генерации
Просмотрите сгенерированные вопросы рядом с оригинальными ссылками

Python API

Пользовательский режим - Полный конвейер:

import asyncio
from src.agents.question import AgentCoordinator

async def main():
    coordinator = AgentCoordinator(
        kb_name="ai_textbook",
        output_dir="data/user/question"
    )

    # Генерация нескольких вопросов из текстового требования
    result = await coordinator.generate_questions_custom(
        requirement_text="Generate 3 medium-difficulty questions about deep learning basics",
        difficulty="medium",
        question_type="choice",
        count=3
    )

    print(f"✅ Generated {result['completed']}/{result['requested']} questions")
    for q in result['results']:
        print(f"- Relevance: {q['validation']['relevance']}")

asyncio.run(main())

Режим имитации - Загрузка PDF:

from src.agents.question.tools.exam_mimic import mimic_exam_questions

result = await mimic_exam_questions(
    pdf_path="exams/midterm.pdf",
    kb_name="calculus",
    output_dir="data/user/question/mimic_papers",
    max_questions=5
)

print(f"✅ Generated {result['successful_generations']} questions")
print(f"Output: {result['output_file']}")

Местоположение вывода

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

data/user/question/custom_YYYYMMDD_HHMMSS/
├── background_knowledge.json      # Результаты извлечения RAG
├── question_plan.json              # Планирование вопросов
├── question_1_result.json          # Индивидуальные результаты вопросов
├── question_2_result.json
└── ...

Режим имитации:

data/user/question/mimic_papers/
└── mimic_YYYYMMDD_HHMMSS_{pdf_name}/
    ├── {pdf_name}.pdf                              # Оригинальный PDF
    ├── auto/{pdf_name}.md                          # Разобранный markdown MinerU
    ├── {pdf_name}_YYYYMMDD_HHMMSS_questions.json  # Извлеченные вопросы
    └── {pdf_name}_YYYYMMDD_HHMMSS_generated_questions.json  # Сгенерированные вопросы

🎓 Руководство по обучению

Диаграмма архитектуры

Персонализированная система обучения на основе содержимого блокнота, автоматически генерирующая прогрессивные учебные пути через интерактивные страницы и умный Q&A.

Основные особенности

Feature	Description
Многоагентная архитектура	LocateAgent: Определяет 3-5 прогрессивных точек знаний InteractiveAgent: Преобразует в визуальные HTML-страницы ChatAgent: Обеспечивает контекстный Q&A SummaryAgent: Генерирует сводки обучения
Умное определение знаний	Автоматический анализ содержимого блокнота
Интерактивные страницы	Генерация HTML-страниц с исправлением ошибок
Умный Q&A	Ответы с учетом контекста с объяснениями
Отслеживание прогресса	Статус в реальном времени с сохранением сеанса
Поддержка нескольких блокнотов	Выбор записей из нескольких блокнотов

Рабочий процесс использования

Выбор блокнота(ов) — Выберите один или несколько блокнотов (cross-notebook selection supported)
Генерация учебного плана — LocateAgent определяет 3-5 основных точек знаний
Начало обучения — InteractiveAgent генерирует визуализацию HTML
Интерактивное обучение — Задавайте вопросы, нажмите "Next" для продолжения
Завершение обучения — SummaryAgent генерирует сводку обучения

Местоположение вывода

data/user/guide/
└── session_{session_id}.json    # Полное состояние сеанса, точки знаний, история чата

✏️ Интерактивная генерация идей (Co-Writer)

Диаграмма архитектуры

Интеллектуальный редактор Markdown, поддерживающий написание с помощью ИИ, автоматическую аннотацию и озвучивание текста.

Основные особенности

Feature	Description
Rich Text Editing	Full Markdown syntax support with live preview
EditAgent	Rewrite: Custom instructions with optional RAG/web context Shorten: Compress while preserving key information Expand: Add details and context
Auto-Annotation	Automatic key content identification and marking
NarratorAgent	Script generation, TTS audio, multiple voices (Cherry, Stella, Annie, Cally, Eva, Bella)
Context Enhancement	Optional RAG or web search for additional context
Multi-Format Export	Markdown, PDF, etc.

Использование

Перейдите на http://localhost:{frontend_port}/co_writer
Введите или вставьте текст в редактор
Используйте функции ИИ: Rewrite, Shorten, Expand, Auto Mark, Narrate
Экспорт в Markdown или PDF

Местоположение вывода

data/user/co-writer/
├── audio/                    # Аудиофайлы TTS
│   └── {operation_id}.mp3
├── tool_calls/               # История вызовов инструментов
│   └── {operation_id}_{tool_type}.json
└── history.json              # История редактирования

🔬 Глубокие исследования

Диаграмма архитектуры

DR-in-KG (Глубокие исследования в графе знаний) — Систематическая система глубоких исследований на основе архитектуры Динамическая очередь тем, позволяющая совместную работу нескольких агентов в три фазы: Планирование → Исследование → Отчетность.

Основные особенности

Особенность	Описание
Трехфазная архитектура	Фаза 1 (Планирование): RephraseAgent (оптимизация темы) + DecomposeAgent (декомпозиция подтем) Фаза 2 (Исследование): ManagerAgent (планирование очереди) + ResearchAgent (принятие решений об исследованиях) + NoteAgent (сжатие информации) Фаза 3 (Отчетность): Дедупликация → Генерация структуры из трех уровней → Написание отчета с цитатами
Динамическая очередь тем	Основная система планирования с управлением состоянием TopicBlock: `PENDING → RESEARCHING → COMPLETED/FAILED`. Поддерживает динамическое обнаружение тем во время исследования
Режимы выполнения	Последовательный режим: Последовательная обработка тем Параллельный режим: Одновременная обработка нескольких тем с `AsyncCitationManagerWrapper` для потокобезопасных операций
Интеграция нескольких инструментов	RAG (гибридный/наивный), Поиск по запросу (поиск сущностей), Поиск статей, Веб-поиск, Выполнение кода — динамически выбирается ResearchAgent
Единая система цитирования	Централизованный CitationManager как единый источник истины для генерации ID цитирования, сопоставления ref_number и дедупликации
Предустановленные конфигурации	quick: Быстрое исследование (1-2 подтемы, 1-2 итерации) medium/standard: Сбалансированная глубина (5 подтем, 4 итерации) deep: Тщательное исследование (8 подтем, 7 итераций) auto: Агент самостоятельно решает глубину

Архитектура системы цитирования

Система цитирования следует централизованному дизайну с CitationManager как единым источником истины:

┌─────────────────────────────────────────────────────────────────┐
│                      CitationManager                            │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  │
│  │  Генерация ID   │  │  Карта ref_number│  │   Дедупликация  │  │
│  │  PLAN-XX        │  │  citation_id →  │  │   (только статьи)│  │
│  │  CIT-X-XX       │  │  ref_number     │  │                 │  │
│  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘  │
└───────────┼────────────────────┼────────────────────┼───────────┘
            │                    │                    │
     ┌──────┴──────┐      ┌──────┴──────┐      ┌──────┴──────┐
     │DecomposeAgent│      │ReportingAgent│      │ Раздел     │
     │ ResearchAgent│      │ (inline [N]) │      │ Ссылок     │
     │  NoteAgent   │      └─────────────┘      └────────────┘
     └─────────────┘

Компонент	Описание
Формат ID	PLAN-XX (запросы RAG на этапе планирования) + CIT-X-XX (этап исследований, X=номер блока)
Сопоставление ref_number	Последовательные номера, начинающиеся с 1, созданные из отсортированных ID цитирования, с дедупликацией статей
Встроенные цитаты	Простой формат `[N]` в выводе LLM, пост-обработка в кликабельные ссылки `[[N]](#ref-N)`
Таблица цитирования	Четкая таблица ссылок, предоставленная LLM: `Цитировать как [1] → (RAG) предпросмотр запроса...`
Пост-обработка	Автоматическое преобразование формата + проверка для удаления недействительных ссылок на цитаты
Параллельная безопасность	Потокобезопасные асинхронные методы (`get_next_citation_id_async`, `add_citation_async`) для параллельного выполнения

Архитектура параллельного выполнения

Когда включено execution_mode: "parallel", несколько блоков тем исследуются одновременно:

┌─────────────────────────────────────────────────────────────────────────┐
│                    Параллельное выполнение исследований                │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   DynamicTopicQueue                    AsyncCitationManagerWrapper      │
│   ┌─────────────────┐                  ┌─────────────────────────┐      │
│   │ Тема 1 (PENDING)│ ──┐             │  Потокобезопасная       │      │
│   │ Тема 2 (PENDING)│ ──┼──→ asyncio  │  обертка для            │      │
│   │ Тема 3 (PENDING)│ ──┤   Semaphore │                         │      │
│   │ Тема 4 (PENDING)│ ──┤   (max=5)   │  • get_next_citation_   │      │
│   │ Тема 5 (PENDING)│ ──┘             │    id_async()           │      │
│   └─────────────────┘                  │  • add_citation_async() │      │
│            │                           └───────────┬─────────────┘      │
│            ▼                                       │                    │
│   ┌─────────────────────────────────────────────────────────────┐      │
│   │              Задачи параллельных ResearchAgent               │      │
│   │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐        │      │
│   │  │ Задача 1│  │ Задача 2│  │ Задача 3│  │ Задача 4│  ...   │      │
│   │  │(Тема 1) │  │(Тема 2) │  │(Тема 3) │  │(Тема 4) │        │      │
│   │  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘        │      │
│   │       │            │            │            │              │      │
│   │       └────────────┴────────────┴────────────┘              │      │
│   │                         │                                    │      │
│   │                         ▼                                    │      │
│   │              AsyncManagerAgentWrapper                        │      │
│   │              (Обновления очереди, безопасные для потоков)    │      │
│   └─────────────────────────────────────────────────────────────┘      │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Компонент	Описание
`asyncio.Semaphore`	Ограничивает количество одновременных задач до `max_parallel_topics` (по умолчанию: 5)
`AsyncCitationManagerWrapper`	Оборачивает CitationManager с `asyncio.Lock()` для потокобезопасной генерации ID
`AsyncManagerAgentWrapper`	Обеспечивает атомарность обновлений состояния очереди в параллельных задачах
Отслеживание прогресса в реальном времени	Отображение всех активных задач исследования с индикаторами состояния

Обязанности агентов

Агент	Фаза	Обязанности
RephraseAgent	Планирование	Оптимизация входной темы пользователя, поддержка многораундового взаимодействия пользователя для уточнения
DecomposeAgent	Планирование	Декомпозиция темы на подтемы с контекстом RAG, получение ID цитирования из CitationManager
ManagerAgent	Исследование	Управление состоянием очереди, планирование задач, динамическое добавление тем
ResearchAgent	Исследование	Проверка достаточности знаний, планирование запросов, выбор инструментов, запрос ID цитирования перед каждым вызовом инструмента
NoteAgent	Исследование	Сжатие необработанных выходных данных инструментов в сводки, создание ToolTraces с заранее назначенными ID цитирования
ReportingAgent	Отчетность	Построение карты цитирования, генерация структуры из трех уровней, написание разделов отчета с таблицами цитирования, пост-обработка цитирований

Конвейер генерации отчетов

1. Построить карту цитирования →  CitationManager.build_ref_number_map()
2. Генерация структуры →  Трехуровневые заголовки (H1 → H2 → H3)
3. Написание разделов →  LLM использует [N] цитирования с предоставленной таблицей цитирования
4. Пост-обработка →  Преобразование [N] → [[N]](#ref-N), проверка ссылок
5. Генерация списка литературы →  Стилизованные академические записи с раскрывающимися деталями источника

Использование

Посетите http://localhost:{frontend_port}/research
Введите тему исследования
Выберите режим исследования (quick/medium/deep/auto)
Наблюдайте за прогрессом в реальном времени с параллельным/последовательным выполнением
Просмотрите структурированный отчет с кликабельными встроенными цитатами
Экспортируйте в Markdown или PDF (с правильным разделением страниц и поддержкой диаграмм Mermaid)

CLI

# Режим быстрого (быстрое исследование)
python src/agents/research/main.py --topic "Основы глубокого обучения" --preset quick

# Режим среднего (сбалансированный)
python src/agents/research/main.py --topic "Архитектура Transformer" --preset medium

# Режим глубокого (тщательное исследование)
python src/agents/research/main.py --topic "Графовые нейронные сети" --preset deep

# Режим авто (агент решает глубину)
python src/agents/research/main.py --topic "Обучение с подкреплением" --preset auto

Python API

import asyncio
from src.agents.research import ResearchPipeline
from src.core.core import get_llm_config, load_config_with_main

async def main():
    # Загрузка конфигурации (main.yaml объединяется с любыми модульными переопределениями)
    config = load_config_with_main("research_config.yaml")
    llm_config = get_llm_config()

    # Создание конвейера (параметры агента загружаются из agents.yaml автоматически)
    pipeline = ResearchPipeline(
        config=config,
        api_key=llm_config["api_key"],
        base_url=llm_config["base_url"],
        kb_name="ai_textbook"  # Необязательно: переопределить базу знаний
    )

    # Запуск исследования
    result = await pipeline.run(topic="Механизмы внимания в глубоком обучении")
    print(f"Отчет сохранен в: {result['final_report_path']}")

asyncio.run(main())

Местоположение вывода

data/user/research/
├── reports/                          # Окончательные отчеты о исследованиях
│   ├── research_YYYYMMDD_HHMMSS.md   # Markdown-отчет с кликабельными цитатами [[N]](#ref-N)
│   └── research_*_metadata.json      # Метаданные и статистика исследований
└── cache/                            # Кэш процесса исследования
    └── research_YYYYMMDD_HHMMSS/
        ├── queue.json                # Состояние DynamicTopicQueue (TopicBlocks + ToolTraces)
        ├── citations.json            # Реестр цитирования с ID-счетчиками и сопоставлением ref_number
        │                             #   - citations: {citation_id: citation_info}
        │                             #   - counters: {plan_counter, block_counters}
        ├── step1_planning.json       # Результаты фазы планирования (подтемы + PLAN-XX цитаты)
        ├── planning_progress.json    # События прогресса планирования
        ├── researching_progress.json # События прогресса исследования
        ├── reporting_progress.json   # События прогресса отчетности
        ├── outline.json              # Трехуровневая структура отчета
        └── token_cost_summary.json   # Статистика использования токенов

Структура файла цитирования (citations.json):

{
  "research_id": "research_20241209_120000",
  "citations": {
    "PLAN-01": {"citation_id": "PLAN-01", "tool_type": "rag_hybrid", "query": "...", "summary": "..."},
    "CIT-1-01": {"citation_id": "CIT-1-01", "tool_type": "paper_search", "papers": [...], ...}
  },
  "counters": {
    "plan_counter": 2,
    "block_counters": {"1": 3, "2": 2}
  }
}

Параметры конфигурации

Key configuration in config/main.yaml (research section) and config/agents.yaml:

# config/agents.yaml - Параметры LLM агента
research:
  temperature: 0.5
  max_tokens: 12000

# config/main.yaml - Настройки исследования
research:
  # Режим выполнения
  researching:
    execution_mode: "parallel"    # "series" или "parallel"
    max_parallel_topics: 5        # Максимальное количество одновременных тем
    max_iterations: 5             # Максимальное количество итераций на тему

  # Переключатели инструментов
    enable_rag_hybrid: true       # Извлечение гибридного RAG
    enable_rag_naive: true        # Базовое извлечение RAG
    enable_paper_search: true     # Поиск научных статей
    enable_web_search: true       # Веб-поиск (также контролируется через tools.web_search.enabled)
    enable_run_code: true         # Выполнение кода

  # Ограничения очереди
  queue:
    max_length: 5                 # Максимальное количество тем в очереди

  # Отчетность
  reporting:
    enable_inline_citations: true # Включить кликабельные [N] цитаты в отчете

  # Предустановки: quick, medium, deep, auto

# Глобальные переключатели инструментов в разделе инструментов
tools:
  web_search:
    enabled: true                 # Глобальный переключатель веб-поиска (более высокий приоритет)

💡 Автоматическая генерация идей

Диаграмма архитектуры

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

Основные особенности

Feature	Description
MaterialOrganizerAgent	Извлекает точки знаний из записей блокнота
Multi-Stage Filtering	Loose Filter → Explore Ideas (5+ per point) → Strict Filter → Generate Markdown
Idea Exploration	Innovative thinking from multiple dimensions
Structured Output	Organized markdown with knowledge points and ideas
Progress Callbacks	Real-time updates for each stage

Использование

Посетите http://localhost:{frontend_port}/ideagen
Выберите блокнот с записями
При необходимости укажите мысли/предпочтения пользователя
Нажмите "Generate Ideas"
Просмотрите сгенерированные исследовательские идеи, организованные по точкам знаний

Python API

import asyncio
from src.agents.ideagen import IdeaGenerationWorkflow, MaterialOrganizerAgent
from src.core.core import get_llm_config

async def main():
    llm_config = get_llm_config()

    # Шаг 1: Извлечение точек знаний из материалов
    organizer = MaterialOrganizerAgent(
        api_key=llm_config["api_key"],
        base_url=llm_config["base_url"]
    )
    knowledge_points = await organizer.extract_knowledge_points(
        "Ваш учебный материал или содержимое блокнота здесь"
    )

    # Шаг 2: Генерация исследовательских идей
    workflow = IdeaGenerationWorkflow(
        api_key=llm_config["api_key"],
        base_url=llm_config["base_url"]
    )
    result = await workflow.process(knowledge_points)
    print(result)  # Идеи исследований в формате Markdown

asyncio.run(main())

📊 Панель управления + Управление базой знаний

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

Ключевые особенности

Особенность	Описание
Статистика активности	Недавние записи решения/генерации/исследования
Обзор базы знаний	Список БЗ, статистика, инкрементальные обновления
Статистика блокнотов	Количество блокнотов, распределение записей
Быстрые действия	Доступ к модулям в один клик

Использование

Веб-интерфейс: Посетите http://localhost:{frontend_port} для просмотра обзора системы
Создать KB: Нажмите "New Knowledge Base", загрузите документы PDF/Markdown
Просмотреть активность: Проверьте последние учебные мероприятия на панели мониторинга

📓 Блокнот

Унифицированное управление учебными записями, соединяющее выводы из всех модулей для создания персонализированной базы знаний обучения.

Основные особенности

Особенность	Описание
Управление несколькими блокнотами	Создание, редактирование, удаление блокнотов
Единое хранилище записей	Интеграция записей решения/генерации/исследования/интерактивной генерации идей
Теги категоризации	Автоматическая категоризация по типу, базе знаний
Пользовательское оформление	Персонализация цвета, значков

Использование

Посетите http://localhost:{frontend_port}/notebook
Создайте новый блокнот (установите имя, описание, цвет, значок)
После выполнения задач в других модулях нажмите "Add to Notebook"
Просмотрите и управляйте всеми записями на странице блокнота

📖 Документация модуля

Конфигурация	Каталог данных	API Backend	Основные утилиты
База знаний	Инструменты	Веб-интерфейс	Модуль решения
Модуль вопросов	Модуль исследования	Модуль интерактивной генерации идей	Модуль руководства
Модуль автоматической генерации идей

❓ Часто задаваемые вопросы

Не удается запустить backend?

Контрольный список

Подтвердите версию Python >= 3.10
Подтвердите установку всех зависимостей: pip install -r requirements.txt
Проверьте, используется ли порт 8001
Проверьте конфигурацию файла .env

Решения

Изменить порт: Установите BACKEND_PORT=9001 в файле .env
Проверить логи: Просмотрите сообщения об ошибках в терминале

Порт занят после Ctrl+C?

Проблема

После нажатия Ctrl+C во время выполнения задачи (например, глубокое исследование) при повторном запуске появляется ошибка "порт уже используется".

Причина

Ctrl+C иногда завершает только процесс frontend, в то время как backend продолжает работать в фоновом режиме.

Решение

# macOS/Linux: Найти и убить процесс
lsof -i :8001
kill -9 <PID>

# Windows: Найти и убить процесс
netstat -ano | findstr :8001
taskkill /PID <PID> /F

Затем перезапустите сервис с помощью python scripts/start_web.py.

Ошибка npm: command not found?

Проблема

Запуск scripts/start_web.py показывает npm: command not found или статус выхода 127.

Контрольный список

Проверьте, установлен ли npm: npm --version
Проверьте, установлен ли Node.js: node --version
Подтвердите активацию среды conda (если используется conda)

Решения

# Вариант A: Использование Conda (рекомендуется)
conda install -c conda-forge nodejs

# Вариант B: Использование официального установщика
# Загрузка с https://nodejs.org/

# Вариант C: Использование nvm
nvm install 18
nvm use 18

Проверка установки

node --version  # Должно показывать v18.x.x или выше
npm --version   # Должно показывать номер версии

Проблемы с длинными именами файлов при установке в Windows?

Проблема

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

Причина

Windows имеет ограничение по умолчанию на длину пути (260 символов), которое может быть превышено из-за вложенной структуры каталогов и зависимостей DeepTutor.

Решение

Включите поддержку длинных путей в системе, выполнив следующую команду в командной строке от имени администратора:

reg add "HKLM\SYSTEM\CurrentControlSet\Control\FileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /f

После выполнения этой команды перезапустите терминал, чтобы изменения вступили в силу.

Frontend не может подключиться к backend?

Контрольный список

Подтвердите, что backend запущен (посетите http://localhost:8001/docs)
Проверьте консоль браузера на наличие сообщений об ошибках

Решение

Создайте .env.local в каталоге web:

NEXT_PUBLIC_API_BASE=http://localhost:8001

Docker: Frontend не может подключиться при облачном развертывании?

Проблема

При развертывании на облачном сервере интерфейс показывает ошибки подключения, такие как "Не удалось получить данные" или "NEXT_PUBLIC_API_BASE не настроен".

Причина

Стандартный URL API - localhost:8001, который указывает на локальную машину пользователя в браузере, а не на ваш сервер.

Решение

Установите переменную окружения NEXT_PUBLIC_API_BASE_EXTERNAL на публичный URL вашего сервера:

# Использование docker run
docker run -d --name deeptutor \
  -e NEXT_PUBLIC_API_BASE_EXTERNAL=https://your-server.com:8001 \
  ... другие параметры ...
  ghcr.io/hkuds/deeptutor:latest

# Или в файле .env
NEXT_PUBLIC_API_BASE_EXTERNAL=https://your-server.com:8001

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

# Если используется порт бэкенда 9001
-e BACKEND_PORT=9001 \
-e NEXT_PUBLIC_API_BASE_EXTERNAL=https://your-server.com:9001

Docker: Как использовать пользовательские порты?

Решение

Установите как переменные окружения портов, так и сопоставления портов:

docker run -d --name deeptutor \
  -p 9001:9001 -p 4000:4000 \
  -e BACKEND_PORT=9001 \
  -e FRONTEND_PORT=4000 \
  -e NEXT_PUBLIC_API_BASE_EXTERNAL=http://localhost:9001 \
  ... другие переменные окружения ...
  ghcr.io/hkuds/deeptutor:latest

Важно: Сопоставление портов -p должно соответствовать значениям BACKEND_PORT/FRONTEND_PORT.

Соединение WebSocket не удается?

Контрольный список

Подтвердите, что backend запущен
Проверьте настройки брандмауэра
Подтвердите правильность URL-адреса WebSocket

Решение

Проверьте логи backend
Подтвердите формат URL: ws://localhost:8001/api/v1/...

На странице настроек отображается "Ошибка загрузки данных" при использовании HTTPS обратного прокси?

Проблема

При развертывании за HTTPS обратным прокси (например, nginx), на странице настроек отображается "Ошибка загрузки данных", и инструменты разработчика браузера показывают, что HTTPS-запросы перенаправляются на HTTP (307 редирект).

Причина

Эта проблема была исправлена в версии v0.5.0+. Если вы используете более старую версию, проблема была вызвана автоматическими перенаправлениями с завершающей косой чертой от FastAPI, которые генерировали HTTP URL-адреса вместо сохранения исходного протокола HTTPS.

Решение (для v0.5.0+)

Обновитесь до последней версии. Исправление отключает автоматические перенаправления с косой чертой, чтобы предотвратить понижение протокола.

Рекомендуемая конфигурация nginx

При использовании nginx в качестве HTTPS обратного прокси используйте следующую конфигурацию:

# Фронтенд
location / {
    proxy_pass http://localhost:3782;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

# API бэкенда
location /api/ {
    proxy_pass http://localhost:8001;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;  # Важно: сохраняет исходный протокол
}

# Поддержка WebSocket
location /api/v1/ {
    proxy_pass http://localhost:8001;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Переменная окружения

Установите в .env:

NEXT_PUBLIC_API_BASE=https://your-domain.com:port

См.: GitHub Issue #112

Где хранятся выходные данные модуля?

Модуль	Путь вывода
Решение	`data/user/solve/solve_YYYYMMDD_HHMMSS/`
Вопросы	`data/user/question/question_YYYYMMDD_HHMMSS/`
Исследование	`data/user/research/reports/`
Интерактивная генерация идей	`data/user/co-writer/`
Блокнот	`data/user/notebook/`
Руководство	`data/user/guide/session_{session_id}.json`
Логи	`data/user/logs/`

Как добавить новую базу знаний?

Веб-интерфейс

Посетите http://localhost:{frontend_port}/knowledge
Нажмите "New Knowledge Base"
Введите имя базы знаний
Загрузите документы PDF/TXT/MD
Система будет обрабатывать документы в фоновом режиме

CLI

python -m src.knowledge.start_kb init <kb_name> --docs <pdf_path>

Как постепенно добавлять документы в существующую БЗ?

CLI (рекомендуется)

python -m src.knowledge.add_documents <kb_name> --docs <new_document.pdf>

Преимущества

Обрабатывает только новые документы, экономит время и стоимость API
Автоматически объединяет с существующим графом знаний
Сохраняет все существующие данные

Ошибка uvloop.Loop при извлечении пронумерованных элементов?

Проблема

При инициализации базы знаний вы можете столкнуться с этой ошибкой:

ValueError: Can't patch loop of type <class 'uvloop.Loop'>

Это происходит потому, что Uvicorn по умолчанию использует цикл событий uvloop, который несовместим с nest_asyncio.

Решение

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

# Вариант 1: Использование shell-скрипта (рекомендуется)
./scripts/extract_numbered_items.sh <kb_name>

# Вариант 2: Прямая команда Python
python src/knowledge/extract_numbered_items.py --kb <kb_name> --base-dir ./data/knowledge_bases

Это извлечет нумерованные элементы (Определения, Теоремы, Уравнения и т.д.) из вашей базы знаний без повторной инициализации.

⭐ История звезд

🤝 Участие в разработке

Мы надеемся, что DeepTutor сможет стать подарком для сообщества. 🎁

🔗 Связанные проекты

⚡ LightRAG	🎨 RAG-Anything	💻 DeepCode	🔬 AI-Researcher
Простой и быстрый RAG	Мультимодальный RAG	Помощник по коду на ИИ	Автоматизация исследований

Лаборатория интеллектуальных данных @ HKU

⭐ Поставьте звезду · 🐛 Сообщить об ошибке · 💬 Обсуждения

Этот проект распространяется под лицензией AGPL-3.0.

Спасибо, что посетили ✨ DeepTutor!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DeepTutor: Персональный учебный ассистент на базе ИИ

📰 Новости

📦 Релизы

Ключевые особенности DeepTutor

📚 Q&A по знаниям из массивов документов

🎨 Интерактивная визуализация обучения

🎯 Укрепление знаний с помощью генератора практических задач

🔍 Глубокие исследования и генерация идей

📚 Q&A по знаниям из массивов документов

🎨 Интерактивная визуализация обучения

🎯 Укрепление знаний

🔍 Глубокие исследования и генерация идей

🏗️ Все-в-одном система знаний

🏛️ Фреймворк DeepTutor

💬 Слой пользовательского интерфейса

🤖 Модули интеллектуальных агентов

🔧 Слой интеграции инструментов

🧠 Основа знаний и памяти

📋 Будущие задачи

🚀 Быстрый старт

Шаг 1: Предварительная настройка

Шаг 2: Выберите метод установки

🐳 Вариант A: Установка через Docker

💻 Вариант B: Ручная установка

URLs Доступа

📂 Хранение данных

📦 Основные модули

📖 Документация модуля

❓ Часто задаваемые вопросы

⭐ История звезд

🤝 Участие в разработке

🔗 Связанные проекты

FilesExpand file tree

README_RU.md

Latest commit

History

README_RU.md

File metadata and controls

DeepTutor: Персональный учебный ассистент на базе ИИ

📰 Новости

📦 Релизы

Ключевые особенности DeepTutor

📚 Q&A по знаниям из массивов документов

🎨 Интерактивная визуализация обучения

🎯 Укрепление знаний с помощью генератора практических задач

🔍 Глубокие исследования и генерация идей

📚 Q&A по знаниям из массивов документов

🎨 Интерактивная визуализация обучения

🎯 Укрепление знаний

🔍 Глубокие исследования и генерация идей

🏗️ Все-в-одном система знаний

🏛️ Фреймворк DeepTutor

💬 Слой пользовательского интерфейса

🤖 Модули интеллектуальных агентов

🔧 Слой интеграции инструментов

🧠 Основа знаний и памяти

📋 Будущие задачи

🚀 Быстрый старт

Шаг 1: Предварительная настройка

Шаг 2: Выберите метод установки

🐳 Вариант A: Установка через Docker

💻 Вариант B: Ручная установка

URLs Доступа

📂 Хранение данных

📦 Основные модули

📖 Документация модуля

❓ Часто задаваемые вопросы

⭐ История звезд

🤝 Участие в разработке

🔗 Связанные проекты