From 66ebb623a766633d839fb5a19e4e364d132a6260 Mon Sep 17 00:00:00 2001 From: Markov Andrey Date: Tue, 30 Jun 2026 11:35:16 +0000 Subject: [PATCH] =?UTF-8?q?=D0=A0=D0=B5=D0=B4=D0=B0=D0=BA=D1=82=D0=B8?= =?UTF-8?q?=D1=80=D0=BE=D0=B2=D0=B0=D1=82=D1=8C=20README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 270 ++++++++++++++++++++++-------------------------------- 1 file changed, 108 insertions(+), 162 deletions(-) diff --git a/README.md b/README.md index 0b30fc2..d1a7316 100644 --- a/README.md +++ b/README.md @@ -117,176 +117,121 @@ ### 6.2. Структура каталогов проекта +Проект организован по принципу разделения ответственности: RAG-сервер и боты-клиенты имеют свои независимые каталоги. Тесты вынесены в корень проекта. + ``` -/usr/local/etc/fckbot/ +/usr/local/etc/fckbot/ # КОРЕНЬ ПРОЕКТА │ -├── core/ # ОБЩИЙ КОД (серверы, клиенты, утилиты) -│ ├── __init__.py -│ ├── rag_server.py # HTTP-сервер RAG-ядра (FastAPI + Uvicorn) -│ ├── rag_orchestrator.py # Оркестратор RAG-пайплайна -│ ├── rag_api.py # Локальный API-интерфейс (для ботов) -│ ├── rag_client.py # HTTP-клиент для ботов (связь с RAG-сервером) -│ ├── bot.py # Точка входа для запуска XMPP-бота -│ ├── core.conf # Общий конфиг (YAML) -│ ├── requirements.txt # Зависимости Python -│ ├── .env.example # Шаблон переменных окружения -│ ├── create_qdrant_collection.py # Скрипт создания коллекции в Qdrant -│ ├── schema.sql # Схема PostgreSQL -│ ├── LICENSE -│ └── README.md +├── rag/ # RAG-СЕРВЕР (HTTP-ядро) +│ ├── .env.example # Шаблон переменных окружения (пароли, ключи API) +│ ├── create_qdrant_collection.py # Скрипт создания коллекции в Qdrant +│ ├── LICENSE # Лицензия ISC +│ ├── rag_api.py # Локальный API-интерфейс (facade) для вызова RAG-логики без HTTP +│ ├── rag.conf # Конфиг RAG-сервера (YAML): БД, Qdrant, GigaChat, чанкинг, RAG, HTTP-сервер +│ ├── rag_orchestrator.py # Оркестратор RAG-пайплайна: координация всех этапов обработки запроса +│ ├── rag_server.py # HTTP-сервер на FastAPI + Uvicorn (точка входа RAG-ядра) +│ ├── README.md # Документация RAG-сервера +│ ├── requirements.txt # Список зависимостей Python для всего проекта +│ ├── schema.sql # Схема PostgreSQL (единая БД для всех ботов) +│ ├── functions/ # Чистые функции (без состояния) +│ │ ├── check_consistency.py # Проверка логических/числовых/терминологических противоречий между фрагментами +│ │ ├── check_spelling.py # Проверка орфографии и пунктуации с сохранением форматирования +│ │ ├── critique_answer.py # Самокритика ответа по 5 критериям +│ │ ├── expand_query.py # Расширение запроса (синонимы, аббревиатуры) +│ │ ├── extract_metrics.py # Извлечение числовых показателей (KPI) в JSON +│ │ ├── file_processor.py # Отправка файлов через HTTP Upload и обработка тегов [SURGICAL_REPLACE], [REWRITE], [FILE] +│ │ ├── generate_document.py # Генерация документа по шаблону (заполнение плейсхолдеров {{...}}) +│ │ ├── intent_classify.py # Классификация намерений пользователя (FACT, PROCEDURE, METRICS и др.) +│ │ ├── rerank_context.py # Переранжирование контекста через локальный кросс-энкодер +│ │ └── summarize_document.py # Суммаризация документа (краткий пересказ ≤30%) +│ ├── services/ # Сервисы (долгоживущие компоненты) +│ │ ├── embedding_service.py # Эмбеддинги GigaChat (одиночные/пакетные запросы с кэшированием) +│ │ ├── file_service.py # Извлечение текста из файлов (DOCX, PDF, XLSX, PPTX, изображения, аудио, архивы) +│ │ ├── giga_client.py # Клиент GigaChat (chat, upload_file) – без бизнес-логики +│ │ ├── kb_service.py # База знаний (индексация, поиск, управление доступом) +│ │ ├── postgres_service.py # Пул соединений с PostgreSQL (CRUD для документов, истории, комнат, шаблонов) +│ │ ├── qdrant_service.py # Векторная БД (создание коллекции, гибридный поиск, удаление) +│ │ └── reranker_service.py # Кросс-энкодер для переранжирования (локально, модель intfloat/multilingual-e5-reranker) +│ └── utils/ # Утилиты (без бизнес-логики) +│ ├── arg_parser.py # Парсинг аргументов командной строки (--flag value) +│ ├── config_loader.py # Загрузка rag.conf и bot.conf, слияние, чтение .env +│ ├── logger.py # Настройка логирования (уровни, вывод в файл и консоль) +│ ├── text_utils.py # Разбиение текста на чанки (tiktoken + razdel), подсчёт токенов +│ └── web_utils.py # Веб-скрапинг (fetch_any_url, crawl_url) │ -├── core/services/ # СЕРВИСЫ – долгоживущие компоненты -│ ├── __init__.py -│ ├── postgres_service.py # Пул соединений с PostgreSQL -│ ├── qdrant_service.py # Векторная БД (создание, поиск, удаление) -│ ├── embedding_service.py # Эмбеддинги GigaChat (кэширование) -│ ├── kb_service.py # База знаний (индексация, поиск, управление) -│ ├── file_service.py # Извлечение текста из файлов -│ ├── giga_client.py # Клиент GigaChat (chat, upload_file) -│ └── reranker_service.py # Кросс-энкодер для переранжирования (локально) +├── bots/ # ОБЩИЙ КОД БОТОВ-КЛИЕНТОВ +│ ├── bot.py # Точка входа для запуска XMPP-бота (принимает --profile-dir) +│ ├── rag_client.py # HTTP-клиент для связи с RAG-сервером (асинхронный, с повторными попытками) +│ ├── commands/ # Команды ботов (XMPP-интерфейс) +│ │ ├── base.py # Базовый класс Command (алиасы, права доступа, кэширование) +│ │ ├── create.py # !create – генерация документа по шаблону +│ │ ├── expert.py # !summary, !metrics – экспертные функции +│ │ ├── global_remove.py # !global_remove – удаление глобального документа (админ) +│ │ ├── help.py # !help – подробная справка по командам +│ │ ├── info.py # !info – краткая справка +│ │ ├── kb.py # !clear, !global_clear, !kb – управление базой знаний +│ │ ├── learn.py # !learn, !stop_learn, !global_learn – режим обучения +│ │ ├── other.py # !reset – сброс истории +│ │ ├── registry.py # Регистрация команд, алиасы, подсказки при опечатке +│ │ ├── stats.py # !stats, !status, !clean – администрирование +│ │ └── template.py # !template_save, !template_list, !template_delete – шаблоны +│ ├── handlers/ # Обработчики XMPP событий +│ │ ├── file_handler.py # Скачивание файлов и постановка в очередь индексации +│ │ ├── health_handler.py # Очистка временных файлов, healthcheck БД/Qdrant (для клиентов) +│ │ ├── message_handler.py # Маршрутизация входящих сообщений (команды, файлы, AI-запросы) – использует RAGClient +│ │ ├── metrics_handler.py # Счётчики (сообщения, файлы, AI-запросы, ошибки) +│ │ ├── room_handler.py # MUC комнаты (приглашения, вход, переподключение) +│ │ └── subscription_handler.py # Подписки (roster subscription) +│ ├── workers/ # Фоновые воркеры +│ │ └── indexing_worker.py # Индексация файлов и URL (отправляет на RAG-сервер через RAGClient) +│ └── xmpp/ # XMPP-клиент +│ └── client.py # Основной класс Bot (наследует slixmpp.ClientXMPP) │ -├── core/functions/ # НЕЗАВИСИМЫЕ ФУНКЦИИ -│ ├── __init__.py -│ ├── intent_classify.py # Классификация намерений -│ ├── expand_query.py # Расширение запроса (синонимы, аббревиатуры) -│ ├── extract_metrics.py # Извлечение KPI в JSON -│ ├── summarize_document.py # Суммаризация документа (до 30%) -│ ├── check_consistency.py # Проверка логических противоречий -│ ├── check_spelling.py # Проверка орфографии и пунктуации -│ ├── critique_answer.py # Самокритика ответа -│ ├── rerank_context.py # Переранжирование контекста (кросс-энкодер) -│ ├── file_processor.py # Отправка файлов, хирургическая замена -│ └── generate_document.py # Генерация по шаблону (заполнение плейсхолдеров) +├── template_bot_profile/ # ШАБЛОН ПРОФИЛЯ (для создания новых ботов) +│ ├── bot.conf.sample # Пример конфига бота-клиента (копируется в bot.conf) +│ ├── data/ # Пустой каталог для постоянных копий файлов +│ ├── prompts/ # Пример промптов (копируются в профиль) +│ │ ├── consistency_check.txt # Проверка противоречий между фрагментами +│ │ ├── expand.txt # Расширение запроса (синонимы, аббревиатуры) +│ │ ├── generate_document.txt # Генерация документа по шаблону +│ │ ├── intent_classify.txt # Классификация намерений +│ │ ├── metrics_extract.txt # Извлечение KPI в JSON +│ │ ├── quality_criteria.txt # Дополнительные критерии качества ответа +│ │ ├── self_critique.txt # Самокритика ответа +│ │ ├── smart_summary.txt # Суммаризация документа +│ │ ├── spellcheck.txt # Проверка орфографии и пунктуации +│ │ ├── synthesis.txt # Шаблон синтеза ответа +│ │ └── system.txt # Системный промпт (роль, стиль, правила) +│ └── temp/ # Пустой каталог для временных файлов │ -├── core/handlers/ # ОБРАБОТЧИКИ XMPP СОБЫТИЙ -│ ├── __init__.py -│ ├── metrics_handler.py # Счетчики (сообщения, файлы, AI-запросы, ошибки) -│ ├── message_handler.py # Маршрутизация входящих сообщений (использует RAGClient) -│ ├── file_handler.py # Скачивание файлов и постановка в очередь -│ ├── room_handler.py # MUC комнаты (приглашения, вход, переподключение) -│ ├── subscription_handler.py # Подписки (roster subscription) -│ └── health_handler.py # Очистка файлов, healthcheck БД/Qdrant +├── tests/ # ЮНИТ-ТЕСТЫ (общие для всего проекта) +│ ├── conftest.py # Фикстуры и моки для pytest +│ ├── test_check_spelling.py # Тесты проверки орфографии +│ ├── test_consistency.py # Тесты проверки противоречий +│ ├── test_critique.py # Тесты самокритики +│ ├── test_expand_query.py # Тесты расширения запроса +│ ├── test_extract_metrics.py # Тесты извлечения метрик +│ ├── test_intent_classify.py # Тесты классификации намерений +│ └── test_summarize.py # Тесты суммаризации │ -├── core/workers/ # ФОНОВЫЕ АСИНХРОННЫЕ ВОРКЕРЫ -│ ├── __init__.py -│ └── indexing_worker.py # Индексация файлов и URL (через HTTP в RAG-сервер) -│ -├── core/commands/ # КОМАНДЫ БОТА (XMPP-интерфейс) -│ ├── __init__.py -│ ├── registry.py # Регистрация команд, алиасы, подсказки -│ ├── base.py # Базовый класс Command -│ ├── info.py # !info — краткая справка -│ ├── help.py # !help — подробная справка -│ ├── learn.py # !learn, !stop_learn, !global_learn -│ ├── kb.py # !clear, !global_clear, !kb -│ ├── stats.py # !stats, !status, !clean -│ ├── expert.py # !summary, !metrics -│ ├── other.py # !reset -│ ├── template.py # !template_save, !template_list, !template_delete -│ ├── create.py # !create (генерация по шаблону) -│ └── global_remove.py # !global_remove – удаление глобального документа (админ) -│ -├── core/tests/ # ЮНИТ-ТЕСТЫ (pytest) -│ ├── __init__.py -│ ├── conftest.py # Фикстуры и моки -│ ├── test_intent_classify.py # Тесты классификации намерений -│ ├── test_expand_query.py # Тесты расширения запроса -│ ├── test_extract_metrics.py # Тесты извлечения метрик -│ ├── test_summarize.py # Тесты суммаризации -│ ├── test_consistency.py # Тесты проверки противоречий -│ ├── test_critique.py # Тесты самокритики -│ └── test_check_spelling.py # Тесты проверки орфографии -│ -├── core/utils/ # ВСПОМОГАТЕЛЬНЫЕ УТИЛИТЫ -│ ├── __init__.py -│ ├── config_loader.py # Загрузка core.conf + bot.conf, чтение .env -│ ├── logger.py # Настройка логирования -│ ├── layout_converter.py # Конвертер раскладки (русская ↔ английская) -│ ├── text_utils.py # Разбиение на чанки (tiktoken + razdel) -│ ├── web_utils.py # Веб-скрапинг (fetch_any_url, crawl_url) -│ └── arg_parser.py # Парсинг аргументов команд (--flag value) -│ -├── core/xmpp/ # XMPP-КЛИЕНТ (тонкий) -│ ├── __init__.py -│ └── client.py # Основной класс Bot (наследует slixmpp.ClientXMPP) -│ -├── metabot/ # ПРОФИЛЬ: МЕТОДОЛОГ -│ ├── bot.conf # Конфиг профиля (JID, БД, коллекция Qdrant, промпты) -│ ├── bot.conf.sample # Пример конфига -│ ├── schema.sql # Схема БД -│ ├── LICENSE # Лицензия -│ ├── README.md -│ ├── prompts/ # ПРОМПТЫ ДЛЯ МЕТОДОЛОГА -│ │ ├── system.txt # Роль, стиль, правила поведения (строгий RAG) -│ │ ├── synthesis.txt # Шаблон синтеза ответа (контекст + запрос → ответ) -│ │ ├── intent_classify.txt # Классификация намерений (FACT, PROCEDURE, METRICS и др.) -│ │ ├── expand.txt # Расширение запроса (синонимы, аббревиатуры) -│ │ ├── metrics_extract.txt # Извлечение KPI в JSON из текста -│ │ ├── smart_summary.txt # Суммаризация документа (до 30%) -│ │ ├── consistency_check.txt # Проверка логических/числовых противоречий -│ │ ├── self_critique.txt # Самокритика ответа (оценка по 5 критериям) -│ │ ├── spellcheck.txt # Проверка орфографии и пунктуации -│ │ ├── quality_criteria.txt # Дополнительные критерии качества ответа -│ │ └── generate_document.txt # Генерация документа по шаблону (заполнение плейсхолдеров) -│ ├── data/ # Постоянные копии файлов -│ └── temp/ # Временные файлы -│ -├── korobot/ # ПРОФИЛЬ: КОРОБОЧНЫЕ РЕШЕИЯ -│ ├── bot.conf -│ ├── bot.conf.sample -│ ├── korobot.rc.template -│ ├── schema.sql -│ ├── LICENSE -│ ├── README.md -│ ├── prompts/ # ПРОМПТЫ ДЛЯ КОРОБОЧНИКА (аналогичный набор) -│ │ ├── system.txt -│ │ ├── synthesis.txt -│ │ ├── intent_classify.txt -│ │ ├── expand.txt -│ │ ├── metrics_extract.txt -│ │ ├── smart_summary.txt -│ │ ├── consistency_check.txt -│ │ ├── self_critique.txt -│ │ ├── spellcheck.txt -│ │ ├── quality_criteria.txt -│ │ └── generate_document.txt -│ ├── data/ -│ └── temp/ -│ -├── persobot/ # ПРОФИЛЬ: ПЕРСОНАЛЬНЫЙ АССИСТЕНТ -│ ├── bot.conf -│ ├── bot.conf.sample -│ ├── persobot.rc.template -│ ├── schema.sql -│ ├── LICENSE -│ ├── README.md -│ ├── prompts/ # ПРОМПТЫ ДЛЯ ПЕРСОНАЛЬНОГО АССИСТЕНТА (аналогичный набор) -│ │ ├── system.txt -│ │ ├── synthesis.txt -│ │ ├── intent_classify.txt -│ │ ├── expand.txt -│ │ ├── metrics_extract.txt -│ │ ├── smart_summary.txt -│ │ ├── consistency_check.txt -│ │ ├── self_critique.txt -│ │ ├── spellcheck.txt -│ │ ├── quality_criteria.txt -│ │ └── generate_document.txt -│ ├── data/ -│ └── temp/ -│ -├── venv/ # ВИРТУАЛЬНОЕ ОКРУЖЕНИЕ Python -│ ├── bin/ # Исполняемые файлы (python, pip, activate) -│ ├── lib/ # Установленные библиотеки +├── venv/ # ВИРТУАЛЬНОЕ ОКРУЖЕНИЕ Python +│ ├── bin/ # Исполняемые файлы (python, pip, activate) +│ ├── lib/ # Установленные библиотеки │ └── ... │ -└── .env # ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ - ├── XMPP_PASSWORD=... - ├── DB_PASSWORD=... - ├── GIGACHAT_API_KEY=... - └── SALUTE_SPEECH_AUTH=... +└── .env # ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ + ├── XMPP_PASSWORD=... # Пароль для XMPP-аккаунта бота + ├── DB_PASSWORD=... # Пароль для PostgreSQL + ├── GIGACHAT_API_KEY=... # API-ключ GigaChat + └── SALUTE_SPEECH_AUTH=... # Авторизация для SaluteSpeech (голосовые сообщения) ``` +**Важные примечания:** + +- Реальные профили ботов (например, `metabot/`, `korobot/`, `persobot/`) создаются администратором вручную путем копирования `template_bot_profile/` и размещаются **вне репозитория** (например, в `/usr/local/etc/fckbot/profiles/`). +- Все юнит-тесты находятся в корневом каталоге `tests/`, что упрощает их запуск и поддержку. +- Конфигурационные файлы (`rag.conf`, `bot.conf`) и переменные окружения (`.env`) не хранятся в репозитории и создаются отдельно. + ### 6.3. Взаимодействие компонентов ``` @@ -321,7 +266,7 @@ ### 6.4. Тестирование -Проект покрыт unit-тестами с использованием `pytest` и `pytest-asyncio`. Тесты находятся в директории `core/tests/` и проверяют критически важные функции: +Проект покрыт unit-тестами с использованием `pytest` и `pytest-asyncio`. Тесты находятся в корневом каталоге `tests/` и проверяют критически важные функции: - классификацию намерений (`test_intent_classify.py`), - расширение запроса (`test_expand_query.py`), @@ -333,7 +278,8 @@ **Запуск всех тестов:** -```bash +``` +cd /usr/local/etc/fckbot source venv/bin/activate pytest tests/ -v ```