Редактировать README.md
This commit is contained in:
Markov Andrey
270
README.md
270
README.md
@@ -117,176 +117,121 @@
|
|||||||
|
|
||||||
### 6.2. Структура каталогов проекта
|
### 6.2. Структура каталогов проекта
|
||||||
|
|
||||||
|
Проект организован по принципу разделения ответственности: RAG-сервер и боты-клиенты имеют свои независимые каталоги. Тесты вынесены в корень проекта.
|
||||||
|
|
||||||
```
|
```
|
||||||
/usr/local/etc/fckbot/
|
/usr/local/etc/fckbot/ # КОРЕНЬ ПРОЕКТА
|
||||||
│
|
│
|
||||||
├── core/ # ОБЩИЙ КОД (серверы, клиенты, утилиты)
|
├── rag/ # RAG-СЕРВЕР (HTTP-ядро)
|
||||||
│ ├── __init__.py
|
│ ├── .env.example # Шаблон переменных окружения (пароли, ключи API)
|
||||||
│ ├── rag_server.py # HTTP-сервер RAG-ядра (FastAPI + Uvicorn)
|
│ ├── create_qdrant_collection.py # Скрипт создания коллекции в Qdrant
|
||||||
│ ├── rag_orchestrator.py # Оркестратор RAG-пайплайна
|
│ ├── LICENSE # Лицензия ISC
|
||||||
│ ├── rag_api.py # Локальный API-интерфейс (для ботов)
|
│ ├── rag_api.py # Локальный API-интерфейс (facade) для вызова RAG-логики без HTTP
|
||||||
│ ├── rag_client.py # HTTP-клиент для ботов (связь с RAG-сервером)
|
│ ├── rag.conf # Конфиг RAG-сервера (YAML): БД, Qdrant, GigaChat, чанкинг, RAG, HTTP-сервер
|
||||||
│ ├── bot.py # Точка входа для запуска XMPP-бота
|
│ ├── rag_orchestrator.py # Оркестратор RAG-пайплайна: координация всех этапов обработки запроса
|
||||||
│ ├── core.conf # Общий конфиг (YAML)
|
│ ├── rag_server.py # HTTP-сервер на FastAPI + Uvicorn (точка входа RAG-ядра)
|
||||||
│ ├── requirements.txt # Зависимости Python
|
│ ├── README.md # Документация RAG-сервера
|
||||||
│ ├── .env.example # Шаблон переменных окружения
|
│ ├── requirements.txt # Список зависимостей Python для всего проекта
|
||||||
│ ├── create_qdrant_collection.py # Скрипт создания коллекции в Qdrant
|
│ ├── schema.sql # Схема PostgreSQL (единая БД для всех ботов)
|
||||||
│ ├── schema.sql # Схема PostgreSQL
|
│ ├── functions/ # Чистые функции (без состояния)
|
||||||
│ ├── LICENSE
|
│ │ ├── check_consistency.py # Проверка логических/числовых/терминологических противоречий между фрагментами
|
||||||
│ └── README.md
|
│ │ ├── 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/ # СЕРВИСЫ – долгоживущие компоненты
|
├── bots/ # ОБЩИЙ КОД БОТОВ-КЛИЕНТОВ
|
||||||
│ ├── __init__.py
|
│ ├── bot.py # Точка входа для запуска XMPP-бота (принимает --profile-dir)
|
||||||
│ ├── postgres_service.py # Пул соединений с PostgreSQL
|
│ ├── rag_client.py # HTTP-клиент для связи с RAG-сервером (асинхронный, с повторными попытками)
|
||||||
│ ├── qdrant_service.py # Векторная БД (создание, поиск, удаление)
|
│ ├── commands/ # Команды ботов (XMPP-интерфейс)
|
||||||
│ ├── embedding_service.py # Эмбеддинги GigaChat (кэширование)
|
│ │ ├── base.py # Базовый класс Command (алиасы, права доступа, кэширование)
|
||||||
│ ├── kb_service.py # База знаний (индексация, поиск, управление)
|
│ │ ├── create.py # !create – генерация документа по шаблону
|
||||||
│ ├── file_service.py # Извлечение текста из файлов
|
│ │ ├── expert.py # !summary, !metrics – экспертные функции
|
||||||
│ ├── giga_client.py # Клиент GigaChat (chat, upload_file)
|
│ │ ├── global_remove.py # !global_remove – удаление глобального документа (админ)
|
||||||
│ └── reranker_service.py # Кросс-энкодер для переранжирования (локально)
|
│ │ ├── 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/ # НЕЗАВИСИМЫЕ ФУНКЦИИ
|
├── template_bot_profile/ # ШАБЛОН ПРОФИЛЯ (для создания новых ботов)
|
||||||
│ ├── __init__.py
|
│ ├── bot.conf.sample # Пример конфига бота-клиента (копируется в bot.conf)
|
||||||
│ ├── intent_classify.py # Классификация намерений
|
│ ├── data/ # Пустой каталог для постоянных копий файлов
|
||||||
│ ├── expand_query.py # Расширение запроса (синонимы, аббревиатуры)
|
│ ├── prompts/ # Пример промптов (копируются в профиль)
|
||||||
│ ├── extract_metrics.py # Извлечение KPI в JSON
|
│ │ ├── consistency_check.txt # Проверка противоречий между фрагментами
|
||||||
│ ├── summarize_document.py # Суммаризация документа (до 30%)
|
│ │ ├── expand.txt # Расширение запроса (синонимы, аббревиатуры)
|
||||||
│ ├── check_consistency.py # Проверка логических противоречий
|
│ │ ├── generate_document.txt # Генерация документа по шаблону
|
||||||
│ ├── check_spelling.py # Проверка орфографии и пунктуации
|
│ │ ├── intent_classify.txt # Классификация намерений
|
||||||
│ ├── critique_answer.py # Самокритика ответа
|
│ │ ├── metrics_extract.txt # Извлечение KPI в JSON
|
||||||
│ ├── rerank_context.py # Переранжирование контекста (кросс-энкодер)
|
│ │ ├── quality_criteria.txt # Дополнительные критерии качества ответа
|
||||||
│ ├── file_processor.py # Отправка файлов, хирургическая замена
|
│ │ ├── self_critique.txt # Самокритика ответа
|
||||||
│ └── generate_document.py # Генерация по шаблону (заполнение плейсхолдеров)
|
│ │ ├── smart_summary.txt # Суммаризация документа
|
||||||
|
│ │ ├── spellcheck.txt # Проверка орфографии и пунктуации
|
||||||
|
│ │ ├── synthesis.txt # Шаблон синтеза ответа
|
||||||
|
│ │ └── system.txt # Системный промпт (роль, стиль, правила)
|
||||||
|
│ └── temp/ # Пустой каталог для временных файлов
|
||||||
│
|
│
|
||||||
├── core/handlers/ # ОБРАБОТЧИКИ XMPP СОБЫТИЙ
|
├── tests/ # ЮНИТ-ТЕСТЫ (общие для всего проекта)
|
||||||
│ ├── __init__.py
|
│ ├── conftest.py # Фикстуры и моки для pytest
|
||||||
│ ├── metrics_handler.py # Счетчики (сообщения, файлы, AI-запросы, ошибки)
|
│ ├── test_check_spelling.py # Тесты проверки орфографии
|
||||||
│ ├── message_handler.py # Маршрутизация входящих сообщений (использует RAGClient)
|
│ ├── test_consistency.py # Тесты проверки противоречий
|
||||||
│ ├── file_handler.py # Скачивание файлов и постановка в очередь
|
│ ├── test_critique.py # Тесты самокритики
|
||||||
│ ├── room_handler.py # MUC комнаты (приглашения, вход, переподключение)
|
│ ├── test_expand_query.py # Тесты расширения запроса
|
||||||
│ ├── subscription_handler.py # Подписки (roster subscription)
|
│ ├── test_extract_metrics.py # Тесты извлечения метрик
|
||||||
│ └── health_handler.py # Очистка файлов, healthcheck БД/Qdrant
|
│ ├── test_intent_classify.py # Тесты классификации намерений
|
||||||
|
│ └── test_summarize.py # Тесты суммаризации
|
||||||
│
|
│
|
||||||
├── core/workers/ # ФОНОВЫЕ АСИНХРОННЫЕ ВОРКЕРЫ
|
├── venv/ # ВИРТУАЛЬНОЕ ОКРУЖЕНИЕ Python
|
||||||
│ ├── __init__.py
|
│ ├── bin/ # Исполняемые файлы (python, pip, activate)
|
||||||
│ └── indexing_worker.py # Индексация файлов и URL (через HTTP в RAG-сервер)
|
│ ├── lib/ # Установленные библиотеки
|
||||||
│
|
|
||||||
├── 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/ # Установленные библиотеки
|
|
||||||
│ └── ...
|
│ └── ...
|
||||||
│
|
│
|
||||||
└── .env # ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ
|
└── .env # ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ
|
||||||
├── XMPP_PASSWORD=...
|
├── XMPP_PASSWORD=... # Пароль для XMPP-аккаунта бота
|
||||||
├── DB_PASSWORD=...
|
├── DB_PASSWORD=... # Пароль для PostgreSQL
|
||||||
├── GIGACHAT_API_KEY=...
|
├── GIGACHAT_API_KEY=... # API-ключ GigaChat
|
||||||
└── SALUTE_SPEECH_AUTH=...
|
└── SALUTE_SPEECH_AUTH=... # Авторизация для SaluteSpeech (голосовые сообщения)
|
||||||
```
|
```
|
||||||
|
|
||||||
|
**Важные примечания:**
|
||||||
|
|
||||||
|
- Реальные профили ботов (например, `metabot/`, `korobot/`, `persobot/`) создаются администратором вручную путем копирования `template_bot_profile/` и размещаются **вне репозитория** (например, в `/usr/local/etc/fckbot/profiles/`).
|
||||||
|
- Все юнит-тесты находятся в корневом каталоге `tests/`, что упрощает их запуск и поддержку.
|
||||||
|
- Конфигурационные файлы (`rag.conf`, `bot.conf`) и переменные окружения (`.env`) не хранятся в репозитории и создаются отдельно.
|
||||||
|
|
||||||
### 6.3. Взаимодействие компонентов
|
### 6.3. Взаимодействие компонентов
|
||||||
|
|
||||||
```
|
```
|
||||||
@@ -321,7 +266,7 @@
|
|||||||
|
|
||||||
### 6.4. Тестирование
|
### 6.4. Тестирование
|
||||||
|
|
||||||
Проект покрыт unit-тестами с использованием `pytest` и `pytest-asyncio`. Тесты находятся в директории `core/tests/` и проверяют критически важные функции:
|
Проект покрыт unit-тестами с использованием `pytest` и `pytest-asyncio`. Тесты находятся в корневом каталоге `tests/` и проверяют критически важные функции:
|
||||||
|
|
||||||
- классификацию намерений (`test_intent_classify.py`),
|
- классификацию намерений (`test_intent_classify.py`),
|
||||||
- расширение запроса (`test_expand_query.py`),
|
- расширение запроса (`test_expand_query.py`),
|
||||||
@@ -333,7 +278,8 @@
|
|||||||
|
|
||||||
**Запуск всех тестов:**
|
**Запуск всех тестов:**
|
||||||
|
|
||||||
```bash
|
```
|
||||||
|
cd /usr/local/etc/fckbot
|
||||||
source venv/bin/activate
|
source venv/bin/activate
|
||||||
pytest tests/ -v
|
pytest tests/ -v
|
||||||
```
|
```
|
||||||
|
|||||||
Reference in New Issue
Block a user