База знаний на Rio и n8n — учебный пример МТУСИ

Это тестовый учебный пример работы с Codex в рамках курса МТУСИ.

Приложение позволяет загружать Markdown-документы в базу знаний и задавать по ним вопросы. Ответы помощника отображаются с Markdown-форматированием. Проект предназначен для обучения и экспериментов; готовность к промышленной эксплуатации здесь не заявляется.

Как это устроено

Браузер → сервер Rio → webhook n8n.

Rio отвечает за интерфейс, загрузку файлов и отображение ответов. Workflow n8n обрабатывают документы и вопросы. Адреса webhook читаются на сервере из .env и не передаются в браузер.

Что понадобится

Для локального backend подготовлен Docker Compose для n8n с шаблонными настройками и отдельной инструкцией запуска.

• Python 3.12 (на этой версии проверялся проект).
• PowerShell для выполнения приведённых ниже команд в Windows.
• Работающий n8n с опубликованными workflow для вопросов и загрузки документов, настроенными внешними сервисами и их учётными данными.
• Два полных URL webhook: для вопроса и для загрузки. Без них интерфейс откроется, но отправка работать не будет.

Зависимости Rio, HTTPX и python-dotenv устанавливаются командами ниже. Отдельно устанавливать их не нужно.

Первый запуск

1. Перейдите в папку приложения

Откройте PowerShell в корне проекта и выполните:

cd .\rio_frontend

В этой папке должны находиться app.py, pyproject.toml и rio.toml. Все последующие команды выполняются из неё.

2. Создайте окружение и установите зависимости

python --version
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[test]"

Первую установку выполняйте с доступом к интернету. Активировать виртуальное окружение не требуется: команды явно используют Python из .venv.

3. Заполните настройки

Создайте .env из шаблона, если он ещё не существует, и откройте его:

if (-not (Test-Path .env)) { Copy-Item .env.example .env }
notepad .env

Укажите свои адреса вместо примеров и сохраните файл:

N8N_CHAT_WEBHOOK_URL=https://your-n8n-host/webhook/126bdb74-0630-415d-a8f7-6f699eac1a2c
N8N_UPLOAD_WEBHOOK_URL=https://your-n8n-host/webhook/993d3a50-19a7-4c64-9d36-67c0ced130dd

N8N_CHAT_TIMEOUT_SECONDS=60
N8N_UPLOAD_TIMEOUT_SECONDS=120
N8N_MAX_FILE_BYTES=10485760

Копируйте полные Production URL из соответствующих узлов Webhook вашего n8n: пути в примере относятся к исходным workflow проекта. Test URL действуют только во время ожидания тестового события в n8n.

Параметр	Назначение	По умолчанию
N8N_CHAT_WEBHOOK_URL	Webhook вопросов	Не задан
N8N_UPLOAD_WEBHOOK_URL	Webhook загрузки документов	Не задан
N8N_CHAT_TIMEOUT_SECONDS	Ожидание ответа, секунды	60
N8N_UPLOAD_TIMEOUT_SECONDS	Ожидание загрузки одного файла, секунды	120
N8N_MAX_FILE_BYTES	Максимальный размер каждого файла, байты	10485760 — 10 МиБ

Таймауты и лимит должны быть положительными. .env исключён из Git; для передачи шаблона используется .env.example. Произвольные дополнительные ключи не добавляют функций приложению.

4. Запустите приложение

.\.venv\Scripts\python.exe -m rio run --port 8765 --release

Откройте в браузере http://127.0.0.1:8765. Оставьте терминал открытым, пока пользуетесь приложением.

Параметр --release отключает правую панель разработчика Rio. Для остановки сервера нажмите Ctrl+C в терминале.

Повторный запуск и изменение настроек

При следующем запуске создавать окружение и устанавливать зависимости заново не нужно. Откройте PowerShell в папке rio_frontend и выполните:

.\.venv\Scripts\python.exe -m rio run --port 8765 --release

После изменения .env остановите сервер через Ctrl+C, запустите его снова и обновите страницу браузера. Файл настроек ищется рядом с config.py, независимо от текущего каталога.

Переменные окружения имеют приоритет над .env. Если ранее задавали $env:N8N_... в терминале, откройте новый терминал перед запуском. Если переменные сохранены в настройках Windows, исправьте или удалите их там.

Как пользоваться

1. Укажите название базы знаний, например my-store. Оно используется и для загрузки, и для последующих вопросов.
2. Выберите или перетащите один или несколько непустых файлов .md.
3. Нажмите «Добавить в базу». Файлы отправляются по очереди; интерфейс показывает прогресс. При ошибке другие файлы продолжают отправляться, а неотправленные остаются для ручного повтора. При ошибке чтения файл нужно выбрать заново.
4. Задайте вопрос по содержимому документов и нажмите «Отправить».
5. Прочитайте ответ: заголовки, списки, ссылки и код отображаются с форматированием, длинные блоки кода можно прокручивать горизонтально.

Успешная отправка файла означает приём запроса, а не подтверждённое завершение индексации. Проверьте результат вопросом по его содержимому. После таймаута проверьте исполнение в n8n перед повтором: сервер мог успеть обработать файл. Автоматических повторов нет.

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

Если что-то не работает

Ситуация	Что проверить
«Не задан корректный полный URL webhook»	Заполните нужный URL в rio_frontend/.env, сохраните файл и перезапустите сервер. Проверьте приоритет переменных окружения.
Ошибка HTTP или webhook недоступен	Проверьте полный URL, публикацию workflow, доступность n8n и журнал его выполнений.
Истекло время ожидания	Проверьте выполнение workflow; при необходимости увеличьте соответствующий таймаут в .env и перезапустите приложение.
Справа видна панель Tree / Pages / Theme	Остановите сервер и запустите с --release, затем обновите страницу.
Порт 8765 занят	Остановите предыдущий сервер или укажите другой порт, например --port 8767, и откройте этот же порт в браузере.
Команда python не найдена	Установите Python 3.12 и откройте новый терминал. Если доступна команда py, используйте py -3.12 -m venv .venv.

Проверки для разработки

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

.\.venv\Scripts\python.exe -m pytest -q -p no:cacheprovider

Для отдельной сквозной проверки с настроенными webhook:

.\.venv\Scripts\python.exe live_smoke.py

Этот сценарий изменяет данные n8n: создаёт отдельную тестовую коллекцию, загружает небольшой документ и проверяет ответ по контрольной метке. Он не входит в обычный запуск тестов.

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

Рекомендуемые плагины для n8n

Для расширения учебных workflow рекомендуем рассмотреть следующие community nodes. Это дополнительные пакеты для n8n, а не зависимости Python или Rio; устанавливать все сразу для запуска интерфейса не требуется. Совместимость конкретных версий пакетов с вашим n8n нужно проверять отдельно.

Пакет	Для чего использовать
n8n-nodes-yandex-disk	Интеграция с Яндекс Диском; доступные операции смотрите в README пакета.
n8n-nodes-universal-reranker	Повторное ранжирование найденных фрагментов по релевантности вопросу через поддерживаемый reranker-сервис.
n8n-nodes-semantic-splitter-with-context	Смысловое разбиение документов на фрагменты с добавлением контекста перед индексацией.
n8n-nodes-query-retriever-rerank	Поиск документов с различными стратегиями запросов и повторным ранжированием результатов.
n8n-nodes-qdrant	Работа с API Qdrant: коллекциями, точками, векторами, поиском и метаданными.
n8n-nodes-openai-langfuse	Вызовы OpenAI-совместимых чат-моделей с отправкой трассировок запросов и ответов в Langfuse.
@langfuse/n8n-nodes-langfuse	Получение промптов из Langfuse Prompt Management для использования в workflow.

Два пакета Langfuse решают разные задачи: получение промптов и трассировку вызовов модели. Установка узла Prompt Management сама по себе не включает трассировку всего workflow. Подробнее — в описании интеграции n8n от Langfuse.

Как установить

В собственной установке n8n с доступным разделом Community Nodes:

1. Откройте Settings → Community Nodes → Install.
2. Введите точное имя нужного npm-пакета из таблицы, например n8n-nodes-qdrant. Для пакета Langfuse сохраните префикс @langfuse/.
3. Ознакомьтесь с уведомлением n8n об установке стороннего кода и подтвердите установку.
4. Добавьте установленный узел в workflow и настройте его credentials: адрес сервиса и необходимые ключи.
5. Проверьте узел на небольшом учебном примере перед включением в основной workflow.

Пакеты устанавливаются в n8n, не через pip и не в окружение Rio. Они не заменяют узлы существующих workflow автоматически. Для воспроизводимости записывайте проверенные версии n8n и установленных пакетов. Ключи сервисов храните в credentials n8n, а не в README.

Структура приложения

Файл	Назначение
app.py	Точка входа и тема Rio
components.py	Чат, очередь файлов и состояния интерфейса
n8n_client.py	HTTP-запросы к webhook и обработка ошибок
config.py	Чтение и проверка настроек
.env.example	Шаблон настроек
rio.toml	Конфигурация запуска Rio
tests/	Автоматические проверки

Контракт вопросов: JSON с полями message, collection_name, session_id; ответ — текст, который может содержать Markdown. Контракт загрузки: один файл в multipart-поле file и поле collection_name на каждый HTTP-запрос.

Локальная векторная база Qdrant

Шаблон Qdrant и инструкция запуска содержат настройки без личных данных и описывают подключение к n8n. Запуск контейнера сам по себе не меняет узлы хранения в workflow.