# I. Платформа «Эфцекабот»: полное описание ## 1. Рабочее название **Эфцекабот** — (_fckbot, производное от ФЦК БОТ_) корпоративная платформа для интеллектуальной обработки документов и диалогов, реализующая гибридный RAG (Retrieval-Augmented Generation) на базе GigaChat. Платформа включает единое RAG-ядро и несколько специализированных ботов-клиентов (методолог, коробочник, персональный ассистент), работающих в корпоративном мессенджере (XMPP). Ориентирована на поддержку бережливого производства, производительности труда, нормативной документации, ИИ-метрик, разработки лучших практик и коробочных решений, а также других функций. ## 2. Подход к построению **Архитектура**: платформа состоит из трех основных слоев: 1. **RAG-ядро (HTTP-сервис)** — центральный компонент, выполняющий все этапы обработки запросов: классификацию намерений, расширение запроса, гибридный поиск (dense + sparse) в Qdrant, переранжирование через локальный кросс-энкодер, синтез ответа через GigaChat, самокритику и перегенерацию. Ядро также управляет индексацией документов и хранением истории диалогов в PostgreSQL. RAG-ядро реализовано как отдельный HTTP-сервер (FastAPI + Uvicorn), что позволяет использовать его для любых клиентов (XMPP, Telegram, Mastodon, веб-интерфейс, системы аналитики). 2. **Тонкие XMPP-боты-клиенты** — каждый профиль (методолог, коробочник, персональный ассистент) представляет собой отдельный XMPP-клиент, который подключается к ejabberd, обрабатывает команды, принимает файлы и пересылает запросы пользователей в RAG-ядро по HTTP. Боты не содержат RAG-логики, не имеют локальной БД или Qdrant, а только загружают свои промпты и передают их в запросах. Это делает их легковесными и независимыми. 3. **Внешние системы хранения и API**: - **ejabberd** — XMPP-сервер (сообщения, MUC-комнаты, HTTP Upload). - **PostgreSQL** — централизованное хранилище метаданных документов, истории диалогов, прав доступа, списка комнат, шаблонов и оценок обратной связи. - **Qdrant** — векторная БД с двумя полями (dense, sparse) для гибридного поиска. Доступна только RAG-ядру. - **GigaChat API** — генерация текста и эмбеддингов. Вызовы осуществляются только из RAG-ядра, что позволяет централизованно управлять кэшированием и лимитами. **Философия**: - Каждый документ принадлежит контексту (личный, комнатный, глобальный). - Боты-клиенты не имеют собственных знаний – они только передают запросы в RAG-ядро, которое отвечает строго по загруженным материалам (строгий RAG). - Единая история диалога для каждого пользователя/комнаты хранится на сервере, что обеспечивает непрерывность контекста независимо от того, через какой интерфейс (XMPP, Telegram, веб) пользователь общается с системой. - Встроен интеллектуальный маршрутизатор запросов (классификация намерений), экспертная подсистема (метрики, суммаризация, проверка противоречий, хирургическая замена) и самокритика ответов – все это реализовано в RAG-ядре и доступно всем клиентам. **Сервисы распределены по jails FreeBSD/Linux**: - `rag-server` (Python 3.11/3.12) — HTTP-сервис RAG-ядра. - `metabot`, `korobot`, `persobot` — отдельные XMPP-клиенты (также на Python), которые общаются с RAG-ядром через HTTP. - `ejabberd`, `PostgreSQL`, `Qdrant` — внешние системы. ## 3. Уникальность решения 1. **Гибридный RAG (dense + sparse) с самокритикой и централизованным ядром** — не используется в корпоративных ботах массово. Коммерческие решения часто ограничиваются простым семантическим поиском без переранжирования и самокритики. Вынесение RAG-логики в отдельный HTTP-сервис позволяет легко масштабировать и подключать любые клиентские интерфейсы. 2. **Персональный ассистент как часть экосистемы** — типичные персональные ассистенты не имеют доступа к внутренней базе знаний и не умеют отвечать на сложные вопросы по документам. Эфцекабот объединяет общие и персональные функции в едином RAG-ядре, при этом каждый бот-профиль использует свои промпты, что позволяет гибко настраивать поведение под конкретные задачи. 3. **Единая чат-среда и единый RAG-бэкенд для всех коммуникаций** — не требуется переключаться между десятками каналов (чат-боты в Telegram, веб-формы, почта). Весь документооборот, командировки, экспертные вопросы — в одном интерфейсе (корпоративном мессенджере), а при необходимости те же функции доступны через Telegram, или веб-интерфейс благодаря универсальному HTTP API RAG-ядра. 4. **Полный контроль над данными** — все компоненты развернуты внутри компании. Никакие документы или переписка не покидают периметр. История и документы хранятся только на серверах компании. 5. **Открытая агентная архитектура** — можно подключить любого RPA, внешнее API, 1С, SAP, календарь, тревел-агрегатор без необходимости переписывать ядро бота — достаточно реализовать HTTP-клиент к RAG-ядру. Конкуренты, как правило, предлагают закрытые экосистемы. 6. **Автоматическая индексация файлов в комнатах** — файл, попавший в групповой чат, автоматически становится доступен всей команде через RAG-ядро. Даже у Slack и Teams нет такой функции «из коробки». ## 4. Преимущества и недостатки работы бота в чате #### Преимущества: - **Единое корпоративное окно** — пользователь не переключается между приложениями, получает экспертные ответы прямо в рабочем чате. - **Мгновенный обмен файлами** — встроен HTTP Upload, бот автоматически отправляет файлы в RAG-ядро для индексации (в т.ч. в групповых комнатах). - **Учет контекста беседы** — история диалога хранится централизованно в RAG-ядре, что обеспечивает единый контекст для всех клиентов (XMPP, Telegram, веб). - **Поддержка комнат (MUC)** — документы, загруженные в комнату, видны всем участникам, а переписка в комнате служит общим контекстом. - **Легковесные клиенты** — боты не содержат сложной RAG-логики, что упрощает их обновление и развертывание; все изменения в RAG вносятся в одном месте — RAG-ядре. - **Не требует установки уникального клиентского ПО** — достаточно любого XMPP-клиента (Fluux, Conversations, Gajim, Pidgin) или работать через web-интерфейс (который также может использовать RAG-ядро). - **Полный контроль данных** — развертывание внутри периметра, никаких облачных сервисов. - **Поддерживаемые форматы**: DOCX, PDF, XLSX, PPTX, TXT, CSV, JSON, изображения (OCR), аудио (SaluteSpeech), архивы ZIP/7z. - **Размер загружаемого файла**: до 1 Гб. #### Недостатки: - **Задержка** — добавлен сетевой вызов от бота к RAG-ядру (1–2 мс внутри сети) и несколько вызовов GigaChat (3–10 секунд). Однако благодаря кэшированию (классификация, расширение, эмбеддинги) и локальному кросс-энкодеру итоговое время ответа в большинстве случаев составляет 3–7 секунд, что приемлемо для экспертной системы. - **Сложность отладки** — распределенная система (RAG-ядро, боты-клиенты, ejabberd, PostgreSQL, Qdrant) усложняет трассировку ошибок, но централизованное логирование и единая точка входа (RAG-ядро) упрощают мониторинг. ## 5. Как чат-бот влияет на работу с GigaChat | Аспект | Влияние | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Скорость** | GigaChat – облачный API, задержка ~1–2 секунды на вызов. В текущей архитектуре все вызовы GigaChat происходят только из RAG-ядра (не из ботов). Пайплайн может делать 2–4 вызова на запрос (классификация, расширение, генерация, критика). Благодаря общему кэшированию (TTL 5 минут) для классификации и расширения, а также локальному кросс-энкодеру для переранжирования, количество вызовов GigaChat сокращено до минимума, что снижает итоговую задержку до 3–7 секунд. | | **Экономия токенов** | Переранжирование и гибридный поиск (sparse + dense) уменьшают объём контекста. История диалога обрезается точно по токенам (через tiktoken) на стороне RAG-ядра, что позволяет эффективнее использовать контекстное окно. Централизация также позволяет агрегировать кэши и общие эмбеддинги, снижая общие затраты на токены. | | **Качество ответа** | GigaChat хорошо понимает русский язык, отлично справляется с деловой и технической терминологией. Но без точного промпта и контекста возможны галлюцинации – самокритика и перегенерация, выполняемые в RAG-ядре, частично нивелируют это. Единые промпты для всех клиентов упрощают тонкую настройку качества. | | **Надежность** | GigaChat имеет лимиты и может выдавать ошибки. RAG-ядро делает несколько попыток при эмбеддингах и генерации, а при отказе API возвращает сообщение о недоступности. Централизация позволяет реализовать единые политики повторных попыток и fallback. | | **Гибридные векторы** | GigaChat генерирует только dense-эмбеддинги, sparse-векторы вычисляются через FastEmbed (`Qdrant/bm25`) локально на сервере RAG-ядра. Это разгружает GigaChat и не требует дополнительных API, а также позволяет использовать общий кэш эмбеддингов для всех клиентов. | ## 6. Архитектура проекта ### 6.1. Общая архитектура Платформа состоит из трех основных логических слоев: ``` ┌──────────────────────────────────────────────────────────────────────┐ │ ВНЕШНИЕ КЛИЕНТЫ (пользователи) │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ XMPP-боты │ │ Telegram │ │ Mastodon │ │ Веб-интерф. │ │ │ │ (тонкие) │ │ (клиент) │ │ (клиент) │ │ (клиент) │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ │ │ │ │ │ └────────────────┼────────────────┼────────────────┘ │ │ │ │ │ │ ▼ ▼ │ │ ┌────────────────────────────────────────────────────────────────┐ │ │ │ RAG-СЕРВЕР (HTTP API) │ │ │ │ POST /rag/query – выполнить RAG-запрос │ │ │ │ POST /rag/index – проиндексировать документ │ │ │ │ GET /health – проверить состояния │ │ │ └────────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌────────────────────────────────────────────────────────────────┐ │ │ │ ВНЕШНИЕ СИСТЕМЫ (данные и API) │ │ │ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │ │ │ │PostgreSQL │ │ Qdrant │ │ GigaChat │ │ Файлы │ │ │ │ │ │(история, │ │(векторный │ │ (генерация│ │ (DOCX, │ │ │ │ │ │ документы,│ │ поиск) │ │эмбеддинги)│ │ PDF и │ │ │ │ │ │ права) │ │ │ │ │ │ т.д.) │ │ │ │ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │ │ │ └────────────────────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────────────────┘ ``` **Ключевые компоненты:** - **RAG-сервер** — единая точка входа для всех RAG-запросов. Содержит всю бизнес-логику (поиск, генерацию, самокритику, индексацию). Запускается как отдельный HTTP-сервис. - **Тонкие клиенты** — боты-профили (XMPP, Telegram, Mastodon и т.д.), которые только передают запросы в RAG-сервер и не содержат RAG-логики. - **Внешние системы** — PostgreSQL, Qdrant, GigaChat API — доступны только RAG-серверу. ### 6.2. Структура каталогов проекта ``` /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 │ ├── 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 # Кросс-энкодер для переранжирования (локально) │ ├── 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 # Генерация по шаблону (заполнение плейсхолдеров) │ ├── 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 │ ├── 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/ # Установленные библиотеки │ └── ... │ └── .env # ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ ├── XMPP_PASSWORD=... ├── DB_PASSWORD=... ├── GIGACHAT_API_KEY=... └── SALUTE_SPEECH_AUTH=... ``` ### 6.3. Взаимодействие компонентов ``` ┌─────────────┐ HTTP ┌─────────────┐ SQL ┌─────────────┐ │ Пользова- │ ──────────────▶│ RAG- │ ──────────────▶│ PostgreSQL │ │ тель │ │ сервер │ │ (история, │ │ (XMPP) │ ◀──────────────│ (ядро) │ ◀──────────────│ документы) │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ XMPP │ HTTP (gRPC) │ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ ejabberd │ │ Qdrant │ │ GigaChat │ │ (чат-серв.) │ │ (векторная │ │ (API) │ └─────────────┘ │ БД) │ └─────────────┘ │ └─────────────┘ │ │ XMPP │ │ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ XMPP-бот │ │ FastEmbed │ │ Файлы │ │ (тонкий) │ │ (локальный │ │ (диск) │ │ клиент │ │ кросс-энк.) │ └─────────────┘ └─────────────┘ └─────────────┘ ``` **Поток данных:** 1. **Запрос пользователя** → XMPP-бот (ejabberd) → HTTP → RAG-сервер. 2. RAG-сервер получает историю из PostgreSQL, ищет в Qdrant, генерирует ответ через GigaChat, выполняет самокритику. 3. **Ответ** → HTTP → XMPP-бот → ejabberd → пользователь. 4. **Индексация файла** → XMPP-бот → файл → HTTP → RAG-сервер → Qdrant + PostgreSQL. ### 6.4. Тестирование Проект покрыт unit-тестами с использованием `pytest` и `pytest-asyncio`. Тесты находятся в директории `core/tests/` и проверяют критически важные функции: - классификацию намерений (`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`). **Запуск всех тестов:** ```bash source venv/bin/activate pytest tests/ -v ``` Для тестирования RAG-сервера отдельно можно использовать `curl` или Postman для отправки запросов на эндпоинты. ### 6.5. Конфигурационные параметры В `core.conf` и `bot.conf` доступны следующие параметры RAG-пайплайна: - **`max_context_tokens`** — лимит **токенов** для истории диалога (по умолчанию 3000). Используется точный подсчет через библиотеку `tiktoken`. Рекомендуемое значение: 2000–4000 токенов в зависимости от модели. - **`rerank.min_length`** — порог длины контекста (в символах) для запуска переранжирования (по умолчанию 5000). Если контекст короче, переранжирование не выполняется, что экономит ресурсы. - **`rag_server_url`** — URL RAG-сервера (используется ботами-клиентами). Пример: `"http://localhost:8080"`. - **`mention_keyword`** — ключевое слово, на которое бот реагирует в групповых чатах (в дополнение к упоминанию по JID и нику). Если параметр не указан, используется имя бота. Пример: `mention_keyword: "методолог"`. Эти параметры позволяют настраивать поведение без изменения кода. Переопределение параметров из `core.conf` в `bot.conf` дает гибкость для разных профилей. ### 6.6. Основные слои (что есть что) | Слой | Назначение | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **RAG-сервер** (`rag_server.py`) | HTTP-сервис, обрабатывающий все RAG-запросы. Содержит оркестратор (`RAGOrchestrator`), который выполняет классификацию, поиск, генерацию и самокритику. Запускается как отдельный процесс. Доступен по HTTP всем клиентам. | | **RAG-оркестратор** (`rag_orchestrator.py`) | Ядро RAG-логики. Координирует вызовы всех функций (классификация, расширение, поиск, переранжирование, генерация, критика). Не зависит от XMPP. | | **HTTP-клиент** (`rag_client.py`) | Используется ботами-клиентами для отправки запросов в RAG-сервер. Асинхронный, с повторными попытками. | | **Сервисы** (`services/`) | Долгоживущие компоненты, предоставляющие API для работы с внешними системами (PostgreSQL, Qdrant, GigaChat, файлы). Используются только RAG-сервером и оркестратором. Не содержат бизнес-логики. | | **Функции** (`functions/`) | Независимые чистые функции, каждая решает одну конкретную задачу: классификация, расширение, суммаризация, проверка противоречий, самокритика и т.д. Не имеют состояния, вызываются из оркестратора. | | **XMPP-боты-клиенты** (`xmpp/client.py`) | Тонкие клиенты, подключающиеся к ejabberd. Содержат только XMPP-логику, команды и загрузку промптов. Все RAG-запросы отправляют в RAG-сервер через `rag_client.py`. | | **Обработчики XMPP** (`handlers/`) | Реагируют на события XMPP (сообщения, приглашения, подписки). Маршрутизируют запросы: команды, файлы, AI-запросы (через RAG-клиент). | | **Воркеры** (`workers/`) | Фоновые асинхронные задачи: индексация файлов и URL (через HTTP-запросы в RAG-сервер). | | **Команды** (`commands/`) | Классы, реализующие команды бота (`!help`, `!learn`, `!summary`, `!metrics` и т.д.). Каждая команда — отдельный файл, наследуемый от `Command`. | | **Утилиты** (`utils/`) | Вспомогательные функции без бизнес-логики: загрузка конфигурации, логирование, конвертер раскладки, разбиение текста на чанки, веб-скрапинг, парсинг аргументов. | ## 7. Функции бота Ниже представлен полный перечень функций платформы Эфцекабот, доступных пользователям. Каждая функция описана максимально детально: указано, что она делает, в чем ее уникальность, какая от нее польза, а также приведены **все возможные сценарии использования** — от простых запросов до сложных рабочих процессов. ### Ранжирование по ценности | Место | Функция | Обоснование | | ----- | ------- | ----------- | | **🥇 1** | Генерация по шаблону | Основной инструмент для создания коробочных решений — автоматизирует производство документов | | **🥈 2** | Гибридный RAG | Без него бот не может отвечать по документам — фундамент системы | | **🥉 3** | Комнатные/глобальные БЗ | Обеспечивают коллективную работу над коробочными решениями | | **4** | Хирургическая замена | Ускоряет доработку документов, критично для подготовки финальных версий | | **5** | Проверка орфографии | Повышает качество исходящих документов | | **6** | Суммаризация | Ускоряет анализ больших объемов информации | | **7** | Самокритика | Повышает надежность ответов в критических областях | | **8** | Извлечение метрик | Автоматизирует сбор KPI | | **9** | Проверка противоречий | Исключает ошибки в документации | | **10** | Классификация намерений | Обеспечивает интеллектуальную маршрутизацию | | **11** | Цепочка рассуждений | Повышает точность расчетов и инструкций | | **12** | Полнотекстовый поиск | Гарантирует юридическую точность и поиск инструкций | | **13** | Расширение запроса | Улучшает полноту поиска | | **14** | Переранжирование | Экономит токены и повышает точность | | **15** | Автоиндексация | Упрощает коллективную работу | | **16** | Веб-скрапинг | Интегрирует внешние источники | | **17** | Голосовые сообщения | Удобство для мобильных пользователей | | **18** | Администрирование | Оперативный контроль без доступа к серверу | ## 7.1. Ключевые функции для создания документов (коробочных решений) ### 🥇 **1. Генерация коробочных решений по шаблону** **Что делает**: По команде `!create "Коробочное решение"` бот генерирует готовый коробочный документ на основе шаблона, заполняя все плейсхолдеры `{{...}}` данными из базы знаний комнаты. Шаблон содержит следующие разделы (соответствует файлу `Шаблон коробочного решения.docx`): 1. **Профиль коробочного решения** — параметры внедрения, ресурсы, сроки. 2. **Актуальность коробочного решения** — потенциал повышения производительности, задачи, ожидаемые результаты. 3. **Решаемая проблема** — типовой процесс (до улучшения), проблемные зоны, коренные причины. 4. **Решение** — целевой процесс (после улучшения), детальное описание решений, результаты внедрения. 5. **Алгоритм внедрения коробочного решения** — состав рабочей группы, последовательность этапов. 6. **Риски** — описание рисков и мер по их снижению. 7. **Термины, сокращения, определения** — глоссарий из документов комнаты. 8. **Сопроводительные документы** — перечень приложений, шаблонов, регламентов. 9. **Лучшие практики** — ссылки на реализованные аналогичные решения. **Уникальность**: Превращает бота из информатора в **инструмент производства готовых коробочных решений**. Достаточно один раз настроить шаблон, и бот будет генерировать документы на основе актуальных данных из базы знаний. Все, что требуется от пользователя — загрузить в комнату документы-источники (регламенты, отчеты, методики, ГОСТы, аналитические записки). **Польза**: Автоматизация подготовки коробочных решений, сокращение времени на создание документов с 1-2 недель до 10-30 минут, исключение ошибок ручного ввода, единообразие документов, возможность быстрого масштабирования на любые типы организаций. **Примеры использования (все возможные сценарии)**: #### 1.1. Сохранение шаблона коробочного решения Загружаете в чат DOCX-файл `Шаблон коробочного решения.docx` (содержит плейсхолдеры вида `{{DOC_CODE}}`, `{{TARGET_ORG_TYPES}}` и т.д.). Вводите: ``` !template_save "Коробочное решение v1.0" ``` Бот сохраняет шаблон в БД комнаты как `"Коробочное решение v1.0"`. Если шаблон с таким именем уже существует – он перезаписывается. #### 1.2. Просмотр всех шаблонов в комнате ``` !template_list ``` Бот выводит список: «Коробочное решение v1.0», «Коробочное решение v2.0», «Договор поставки» и т.д. #### 1.3. Генерация коробочного решения Вы вводите: ``` !create "Коробочное решение v1.0" ``` Бот выполняет следующие шаги: 1. **Извлекает шаблон** из БД комнаты. 2. **Находит все плейсхолдеры** в шаблоне (их около 70+): - Профиль: `{{DOC_CODE}}`, `{{TARGET_ORG_TYPES}}`, `{{TARGET_ORG_COUNT}}`, `{{FINANCIAL_RESOURCES}}`, `{{HUMAN_RESOURCES}}`, `{{IMPLEMENTATION_TERM_MIN}}`, `{{KPI_NAME}}`, `{{KPI_BEFORE}}`, `{{KPI_AFTER}}` и т.д. - Актуальность: `{{PROCESS_NAME}}`, `{{DATA_DATE}}`, `{{TOTAL_STAFF}}`, `{{TYPICAL_PROBLEM_DESCRIPTION}}`, `{{PREREQUISITE_1}}`, `{{TASK_1}}`, `{{RESULT_1}}` и т.д. - Решаемая проблема: `{{STAGE_1_NAME}}`, `{{STAGE_1_ACTORS}}`, `{{STAGE_1_PROBLEMS}}`, `{{ROOT_CAUSE_1}}` и т.д. - Решение: `{{TARGET_STAGE_1_DESC}}`, `{{IMPROVEMENT_1}}`, `{{SOLUTION_1_NAME}}`, `{{SOLUTION_1_DESCRIPTION}}`, `{{KPI_1_NAME}}` и т.д. - Алгоритм внедрения: `{{ROLE_1}}`, `{{ROLE_1_DUTIES}}`, `{{STAGE1_DURATION}}`, `{{STAGE1_ACTIONS}}` и т.д. - Риски: `{{RISK_1_NAME}}`, `{{RISK_1_DESCRIPTION}}`, `{{RISK_1_MITIGATION}}`. - Термины: `{{TERM_1}}`, `{{TERM_1_DEF}}`. - Сопроводительные документы: `{{APPENDIX_1_NAME}}`. - Лучшие практики: `{{BEST_PRACTICE_1_LINK}}`, `{{BEST_PRACTICE_1_DESC}}`. 3. **Для каждого плейсхолдера выполняет поиск** в базе знаний комнаты (личные + комнатные + глобальные документы). Поиск использует: - Семантический поиск (dense-эмбеддинги) — для общих запросов. - Полнотекстовый поиск (MatchText) — для точных цитат и номеров пунктов. - Расширение запроса (query expansion) — добавляет синонимы и аббревиатуры. - Переранжирование (кросс-энкодер) — отбирает только релевантные фрагменты. 4. **Формирует промпт для GigaChat** с инструкцией заполнить плейсхолдер на основе найденных фрагментов. Промпт содержит контекст из фрагментов документов и сам плейсхолдер. 5. **Генерирует значение для каждого плейсхолдера** — например, для `{{TYPICAL_PROBLEM_DESCRIPTION}}` GigaChat напишет: «В региональной системе наблюдается дефицит сотрудников с профильным образованием (только 30% из 100), нерегулярное планирование, отсутствие единой методики оценки компетенций». 6. **Заменяет плейсхолдеры в копии шаблона**, сохраняя все форматирование (жирный шрифт, курсив, цвета, таблицы, колонтитулы). Замена выполняется с учетом возможного разбиения текста на несколько `runs` в DOCX, что повышает точность. 7. **Отправляет готовый DOCX-файл в чат**. **Пример заполнения (фрагменты)**: ``` **{{DOC_CODE}}** → **КР-5S-2025-001** **{{TARGET_ORG_TYPES}}** → «Библиотеки, культурно-досуговые учреждения» **{{TARGET_ORG_COUNT}}** → «47» **{{FINANCIAL_RESOURCES}}** → «1 200» **{{HUMAN_RESOURCES}}** → «5» **{{IMPLEMENTATION_TERM_MIN}}** → «3» **{{KPI_NAME}}** → «Процент сотрудников с профильным образованием» **{{KPI_BEFORE}}** → «30%» **{{KPI_AFTER}}** → «85%» ``` #### 1.4. Обновление коробочного решения Если вы улучшили шаблон или изменили структуру, загружаете новую версию DOCX и повторяете: ``` !template_save "Коробочное решение v1.0" ``` Старый шаблон перезаписывается новым. Все последующие генерации будут использовать обновленный шаблон. #### 1.5. Удаление шаблона ``` !template_delete "Коробочное решение v1.0" ``` Шаблон удаляется из БД комнаты. #### 1.6. Кастомизация шаблона под конкретный проект Вы можете создать несколько версий шаблона для разных типов организаций или отраслей: ``` !template_save "Коробочное решение_Библиотеки" !template_save "Коробочное решение_Музеи" !template_save "Коробочное решение_Образование" ``` Затем генерировать нужную версию: ``` !create "Коробочное решение_Библиотеки" ``` #### 1.7. Использование общих знаний (если разрешено) Если для какого-то плейсхолдера не нашлось данных в БЗ (например, `{{BEST_PRACTICE_1_LINK}}`), бот может использовать свои общие знания для заполнения (если в конфиге `allow_public_knowledge: true`). Это полезно для лучших практик и терминов. #### 1.8. Многоязычность Если в документах есть информация на иностранном языке, бот переведет ее на язык шаблона (русский) и заполнит плейсхолдер. **Пример**: плейсхолдер `{{KPI_NAME}}` – бот найдет в английских документах «Overall Equipment Effectiveness» и переведет как «Общая эффективность оборудования» (или оставит аббревиатуру OEE, если так указано в документах). ### 🥈 **2. Гибридный RAG с самокритикой** **Что делает**: Это ядро системы, которое используется для поиска данных для каждого плейсхолдера шаблона. Бот выполняет: - Семантический поиск (dense-эмбеддинги от GigaChat). - Ключевой поиск (sparse-векторы BM25 от FastEmbed). - Объединение через Reciprocal Rank Fusion (RRF). - Генерацию ответа через GigaChat. - Проверку через самокритику (оценка по 5 критериям). - Перегенерацию при необходимости. **Уникальность**: Комбинация двух типов поиска + самокритика – это значительно повышает точность и доверие к ответам. Редкая функция для корпоративных ботов. **Польза**: Гарантирует, что ответ или каждое значение в коробочном решении основано на реальных документах, а не на выдумках LLM. Это критично для юридической и финансовой достоверности. Это фундамент, без которого остальные функции теряют смысл. **Примеры использования**: 1. **Фактологический вопрос (FACT)**: - «Какое тактовое время установлено на линии сборки?» - Бот ищет в документах (регламент линии, паспорт оборудования) и выдает точное значение с указанием источника: `Тактовое время на линии сборки составляет 120 секунд. [Источник: Регламент_линии_2025.docx]` 2. **Инструкция / процедура (PROCEDURE)**: - «Как рассчитать OEE для станка?» - Бот находит алгоритм расчета в методических документах и выдает пошаговое руководство (с цепочкой рассуждений). 3. **Сравнение показателей (COMPARISON)**: - «Сравни производительность труда до и после внедрения кайдзен» - Бот находит данные в отчетах (по периодам) и выдает сравнительный анализ с цифрами. 4. **Расчет по формуле (CALCULATION)**: - «Рассчитай ожидаемую выработку на следующую смену при загрузке 120%» - Бот использует формулу из документов, выполняет расчет (пошагово) и выдает результат. 5. **Поиск по юридически значимым пунктам**: - «Выведи пункт 3.2.1 из договора №123» - Бот переключается на точный подстроковый поиск (см. пункт 12) и выдает цитату. 6. **Общий вопрос (GENERAL)**: - «О чем этот документ?» - Бот дает краткое описание на основе содержания (если есть контекст). 7. **Приветствие (GREETING)**: - «Привет» – бот отвечает вежливо, без поиска. **Примеры использования для коробочных решений**: 1. **Поиск KPI по ключевым словам**: - Для плейсхолдера `{{KPI_NAME}}` бот ищет в документах упоминания показателей: «OEE», «процент брака», «выработка на человека». - Находит в отчетах: «Процент сотрудников с профильным образованием». - Возвращает точное название. 2. **Поиск числовых значений**: - Для `{{KPI_BEFORE}}` и `{{KPI_AFTER}}` бот находит в документах цифры: «в 2024 году – 30%», «целевой показатель – 85%». - Возвращает числа. 3. **Поиск корневых причин проблем**: - Для `{{ROOT_CAUSE_1}}` бот анализирует документы и выделяет ключевые проблемы: «дефицит кадров», «отсутствие регламентов», «нерегулярное планирование». 4. **Поиск постановки задач**: - Для `{{TASK_1}}` бот находит в стратегических документах перечень задач: «разработать стандарт», «обучить персонал», «внедрить систему мониторинга». ### 🥉 **3. Комнатные и глобальные базы знаний** **Что делает**: Документы могут быть трех типов: - **Личные** – видны только владельцу (загружаются в личном чате без флагов). - **Комнатные** – доступны всем участникам комнаты (автоматически при загрузке в групповой чат). - **Глобальные** – доступны всем пользователям (загружаются администратором с флагом `--global` в личном чате). Последний загруженный файл привязан к комнате, что предотвращает перезапись файлов разных пользователей в одной комнате. **Уникальность**: Позволяет естественно разграничивать доступ и организовывать коллективную работу. Редко встречается в RAG-ботах. **Польза**: Юридические документы для всех сотрудников (глобальные), конфиденциальные отчеты для отдела (комнатные), личные заметки – все в одном боте. Команда может совместно разрабатывать шаблоны и коробочные решения. **Примеры использования**: 1. **Личная БЗ**: - В личном чате с ботом загружаете файл (например, личный план работы). Бот индексирует его как личный – доступен только вам. 2. **Комнатная БЗ**: - В групповом чате загружаете файл (регламент отдела). Бот автоматически индексирует его в комнатную БЗ – доступен всем участникам комнаты. 3. **Глобальная БЗ**: - Администратор в личном чате вводит: `!learn --global` Затем отправляет файл (или ссылку). Бот индексирует документ как глобальный – доступен всем пользователям во всех контекстах. 4. **Просмотр доступных документов**: - `!kb` – в личном чате покажет список личных + глобальных документов. - `!kb` в комнате – покажет комнатные + глобальные документы. 5. **Очистка БЗ**: - `!clear` – в личном чате очищает личную БЗ. - `!clear` в комнате (только админ) – очищает комнатную БЗ. - `!global_clear` (админ, личный чат) – очищает глобальную БЗ. 6. **Удаление конкретного глобального документа** (админ): - `!global_remove "Название документа"` – удаляет документ из глобальной БЗ по точному названию. ## 7.2. Функции работы с документами ### **4. «Хирургическая» (точечная) замена текста в DOCX** **Что делает**: По запросу «замени старое слово на новое» бот выполняет **умную замену** с учетом грамматических форм (падежи, числа, роды) без потери форматирования. Поддерживает замену словоформ (например, «учеников» → «строителей»). Работает только с DOCX, использует морфологический анализатор `mawo-pymorphy3`. **Уникальность**: Очень редкая функция для RAG-систем; превращает бота из информатора в инструмент редактирования документов. **Польза**: Автоматизация рутинных правок в отчетах, договорах, планах. Снижение человеческих ошибок. Экономия времени на переделку документов. **Примеры использования (все возможные сценарии)**: 1. **Простая замена**: - Загружаете DOCX, затем вводите: `Замени ООО "Ромашка" на ООО "Тюльпан"` - Бот заменяет все вхождения во всех падежах (ООО "Ромашка", "Ромашке", "Ромашку" и т.д.) и возвращает исправленный файл. 2. **Замена с морфологией**: - `Замени учеников на строителей` - Бот заменит «ученик», «ученика», «ученикам», «учениками» и т.д. на соответствующие формы «строитель», «строителя», «строителям», «строителями» и т.д. 3. **Замена дат или чисел**: - `Замени 2024 на 2025` - Заменит все цифры 2024 (в том числе в тексте и таблицах) на 2025. 4. **Множественные замены** – можно загрузить файл и выполнить несколько команд подряд, бот будет применять их последовательно (каждая команда работает с последним измененным файлом). 5. **Замена в таблицах и колонтитулах** – замены выполняются во всех элементах документа, включая таблицы, сноски, колонтитулы и надписи. 6. **Сохранение форматирования** – замены выполняются без потери жирного шрифта, курсива, подчеркивания, цветов, размеров шрифта, выравнивания. 7. **Работа с архивами** – если загружен ZIP-архив, бот распаковывает его, выполняет замену во всех DOCX-файлах внутри и упаковывает обратно (если включена поддержка архивов). ### **5. Проверка орфографии** **Что делает**: Пользователь загружает DOCX, затем пишет «Проверь орфографию» или «Найди ошибки». Бот разбивает текст на чанки (учитывая токены), отправляет каждый чанк в GigaChat с промптом на исправление ошибок. Исправления применяются с сохранением форматирования. Возвращает исправленный файл и список изменений в виде «было → стало». **Уникальность**: Автоматическое исправление ошибок в готовых документах без ручной правки. Поддерживает сложные случаи русского языка (благодаря использованию `razdel` для разбиения на предложения). **Польза**: Экономия времени на вычитку, повышение грамотности исходящих документов. Незаменимо при подготовке коробочных решений и официальных документов. **Примеры использования**: 1. **Базовая проверка**: - Загружаете DOCX, пишете: `Проверь орфографию` - Бот возвращает исправленный файл и список всех исправлений: `было «пашол» → стало «пошел»` `было «молоко хлеб» → стало «молоко, хлеб»` 2. **Альтернативные команды**: - `Найди ошибки в документе` - `Исправь ошибки` - `Проверь грамматику` - Работают аналогично. 3. **Проверка с сохранением стиля** – бот исправляет только орфографические и пунктуационные ошибки, не меняет структуру предложений, не заменяет синонимы, не улучшает стилистику (это сделано намеренно, чтобы сохранить авторский стиль). 4. **Обработка ошибок парсинга** – если GigaChat не смог сформировать список изменений в требуемом формате (`[CHANGES]...[/CHANGES]`), бот покажет сырой ответ модели, чтобы исправления не потерялись, и предложит проверить вручную. 5. **Работа с большими документами** – текст разбивается на чанки (по токенам) и обрабатывается последовательно, что позволяет проверять документы любого размера. 6. **Только в личном чате** – проверка орфографии доступна только в личном чате с ботом (для безопасности и предотвращения спама в комнатах). ### **6. Суммаризация документа** **Что делает**: Создает краткий пересказ (≤30% от оригинала) с выделением целей, выводов и ключевых цифр. Использует промпт, который фокусируется на наиболее важных аспектах документа. **Уникальность**: Не просто сжатие, а интеллектуальное выделение самой важной информации на основе промпта (а не просто первые предложения). **Польза**: Быстрое ознакомление с объемными регламентами, отчетами, ГОСТами. Ускоряет анализ больших документов при разработке коробочных решений. **Примеры использования**: 1. **Суммаризация последнего загруженного файла**: - `!summary` - Бот выдает краткое изложение документа (не более 30% объема) с выделением цели, выводов и ключевых цифр. В конце обязательно указывается источник. 2. **Автоматическая суммаризация при намерении SUMMARY** – если пользователь спросит «Сделай суммаризацию документа», классификатор распознает это намерение и вызовет функцию автоматически (без команды `!summary`). 3. **Фокус на числовых показателях** – если в документе есть OEE, такт, выработка, проценты, они выделяются в отдельный раздел. 4. **Быстрое ознакомление** – можно использовать для регламентов, ГОСТов, длинных отчетов, чтобы понять суть за 1–2 минуты. 5. **Ограничение длины** – если документ длиннее `max_chars` (по умолчанию 8000 символов), он обрезается по границам предложений (с использованием `razdel`), чтобы суммаризация была по полному тексту. ## 7.3. Функции анализа и качества ### **7. Самокритика ответа с перегенерацией** **Что делает**: После генерации ответа другой экземпляр LLM оценивает его по пяти критериям: 1. Соответствие источнику – все ли факты подтверждаются контекстом. 2. Отсутствие галлюцинаций – нет ли информации, отсутствующей в контексте. 3. Соблюдение стиля и форматирования (нет LaTeX, есть источники, правильные списки). 4. Логическая связность – ответ не противоречит сам себе. 5. Запрет внешних знаний – не используются личные знания модели (если `allow_public_knowledge = false`). При неудовлетворительной оценке ответ перегенерируется один раз. Если и после перегенерации неудовлетворительно, выдается сообщение о неуверенности. **Уникальность**: Редкий механизм самоконтроля, повышающий доверие к боту. Работает как «человек проверяет себя». **Польза**: Снижает вероятность ошибочного ответа, особенно в критических областях (юриспруденция, финансы, медицина, нормативная документация). **Примеры использования**: 1. **Обычный запрос** – самокритика работает в фоновом режиме. Если ответ не проходит проверку, бот перегенерирует его один раз. Если и после перегенерации неудовлетворительно, выдается сообщение: «⚠️ Извините, я не уверен в точности ответа. Проверьте данные.» 2. **Отключение самокритики** – если в конфиге `bot.conf` установить `enable_self_critique: false`, она отключается для увеличения скорости (полезно для тестирования или простых запросов). 3. **Влияет только на обычные RAG-запросы** – для экспертных функций (METRICS, SUMMARY, CONTRADICTION) самокритика не применяется, так как их ответы уже структурированы и проверены на уровне функций. 4. **Перегенерация с тем же контекстом** – при перегенерации используется тот же контекст, что и при первом ответе, чтобы не потерять релевантность. ### **8. Извлечение метрик (KPI) из документов** **Что делает**: Анализирует базу знаний, находит числовые показатели (OEE, тактовое время, выработку, проценты, суммы, количества) и выдает в структурированном виде (JSON или маркированный список). Использует промпт, который заставляет LLM выделять только явно указанные числа/значения, без додумывания. **Уникальность**: Команда `!metrics` работает без предварительной разметки данных – LLM сама выделяет показатели. Не требуется специальных тегов или шаблонов. **Польза**: Быстрый анализ эффективности, контроль KPI по всем документам компании. Автоматизация сбора показателей для отчетности. **Примеры использования**: 1. **Извлечение всех KPI из базы знаний**: - `!metrics` - Бот ищет все документы (личные + глобальные или комнатные + глобальные) и выдает список метрик: `- OEE линии: 85,2% (первый квартал 2025)` `- Тактовое время на сборке: 120 сек` `- Выработка на одного рабочего: 450 деталей в смену` `- Время переналадки: 35 мин` `- Процент брака: 2,1%` 2. **Автоматический ответ на намерение METRICS** – если пользователь спросит: «Выведи все KPI из отчета» или «Покажи показатели эффективности», классификатор распознает намерение и вызовет функцию автоматически. 3. **Кэширование** – для команды `!metrics` результат кэшируется на 5 минут, что ускоряет повторные запросы (полезно для частого мониторинга). 4. **Ограничение количества** – выводится не более 20 метрик, чтобы не перегружать ответ. 5. **Указание источника** – каждая метрика сопровождается фрагментом источника (первые 100 символов), чтобы можно было проверить оригинал. ### **9. Проверка противоречий между документами** **Что делает**: Находит логические, числовые или терминологические расхождения в разных фрагментах базы знаний. Сравнивает факты, цифры, даты, определения. Возвращает структурированный ответ: `[OK]` если противоречий нет, или `[CONFLICT]` с описанием каждого расхождения и предполагаемой причиной. **Уникальность**: Помогает аудиторам и аналитикам обнаруживать конфликты данных. Автоматизирует процесс верификации документации. **Польза**: Исключение ошибок в нормативной базе, устранение дублирующихся требований, повышение качества документооборота. **Примеры использования**: 1. **Проверка противоречий в OEE**: - «Есть ли противоречия в расчете OEE?» - Бот ищет все фрагменты с упоминанием OEE и сравнивает цифры. Если в одном документе 85%, а в другом 90%, выдает предупреждение: `[CONFLICT] В фрагменте 1 указано 85%, в фрагменте 2 – 90%. Предполагаемая причина: разные источники или разные периоды.` 2. **Проверка сроков**: - «Проверь, нет ли противоречий в сроках реализации проекта» - Находит все даты в документах и сравнивает их. 3. **Сравнение терминов**: - «Есть ли противоречия в определении понятия "цикл производства"?» - Находит все определения и проверяет их на согласованность. 4. **Ограничение фрагментов** – для экономии токенов проверяются только первые `max_fragments` (по умолчанию 5) наиболее релевантных фрагментов. 5. **Учет первичного источника** – если один источник явно первичен (например, официальный документ), это указывается в ответе. ## 7.4. Интеллектуальная маршрутизация и поиск ### **10. Классификация намерений** **Что делает**: Определяет тип запроса пользователя по ключевым словам и контексту. Поддерживает следующие коды намерений: `FACT`, `PROCEDURE`, `COMPARISON`, `CALCULATION`, `SURGICAL`, `METRICS`, `SUMMARY`, `CONTRADICTION`, `GREETING`, `GENERAL`, `SPELLCHECK`, `TEMPLATE_FILL`. Выбирает соответствующую стратегию обработки. Результаты классификации кэшируются на 5 минут для ускорения повторных запросов. **Уникальность**: Не все RAG-боты имеют интеллектуальную маршрутизацию. Кэширование дополнительно повышает отзывчивость. **Польза**: Экономия токенов, времени и повышение точности ответов за счет выбора специализированной стратегии. **Примеры работы (как классификатор определяет тип запроса):** | Запрос пользователя | Распознанное намерение | ||| | «Какое тактовое время установлено на линии?» | `FACT` | | «Как рассчитать OEE?» | `PROCEDURE` | | «Сравни показатели производительности до и после кайдзен» | `COMPARISON` | | «Замени 5000 на 6000 в плане производства» | `SURGICAL` | | «Выведи все KPI из отчета» | `METRICS` | | «Сделай суммаризацию документа» | `SUMMARY` | | «Есть ли противоречия в расчете OEE?» | `CONTRADICTION` | | «Привет» | `GREETING` | | «Заполни шаблон договора» | `TEMPLATE_FILL` | | «Проверь орфографию» | `SPELLCHECK` | | «О чем этот документ?» | `GENERAL` | ### **11. Цепочка рассуждений (Chain-of-Thought)** **Что делает**: Для запросов с намерениями `CALCULATION` (расчет) и `PROCEDURE` (инструкция/алгоритм) бот автоматически добавляет в промпт инструкцию, требующую пошагового решения перед итоговым ответом. Модель генерирует ответ с последовательным описанием шагов, а затем итоговым результатом. **Польза**: Повышает точность расчетов и алгоритмов, позволяет пользователю проверить логику и выявить возможные ошибки на промежуточных этапах. **Примеры использования**: 1. **Расчет OEE**: - Запрос: «Рассчитай OEE для линии» - Ответ: > Шаг 1: Доступное время = 480 мин > Шаг 2: Время простоев = 45 мин > Шаг 3: Операционное время = 435 мин > Шаг 4: OEE = (435 / 480) × 100% = 90,6% > Итоговый ответ: OEE составляет 90,6%. 2. **Расчет выработки**: - Запрос: «Какая будет выработка при загрузке 110%?» - Ответ с пошаговым расчетом: > Шаг 1: Номинальная выработка = 100 ед/час > Шаг 2: При загрузке 110% выработка = 100 × 1,1 = 110 ед/час > Итог: 110 ед/час. 3. **Пошаговая инструкция**: - Запрос: «Как внедрить 5S?» - Бот выдает последовательность шагов с пояснениями. ### **12. Полнотекстовый поиск по точным фрагментам и поиск инструкций (HOW TO)** **Что делает**: При обнаружении номеров пунктов (1.1, 3.2.1), фраз в кавычках или ключевых слов «как», «инструкция», «алгоритм», «порядок», «последовательность», «этапы», «методика», «процедура», «регламент», «правила», «способ», «метод» – бот переключается с гибридного RAG на **точный подстроковый поиск** в Qdrant (MatchText). Это гарантирует попадание в нужный раздел документа, а не просто семантически похожий фрагмент. **Ключевая особенность**: Если запрос содержит вопрос «как сделать Х», бот не просто находит фрагмент с упоминанием Х, а **извлекает всю инструкцию или процедуру**, даже если она не оформлена как маркированный список, а просто описана в тексте. Для этого используется дополнительный промпт, который заставляет LLM выделить и структурировать последовательность действий. **Уникальность**: - Гарантирует юридически значимые цитаты и ссылки на пункты нормативных актов. - Может находить и выдавать пошаговые инструкции из неструктурированного текста. - Объединяет точный поиск с **цепочкой рассуждений (CoT)**, если инструкция требует расчетов или последовательных действий. **Польза**: - Позволяет получать готовые алгоритмы и процедуры без необходимости читать весь документ. - Быстрое освоение новых процессов – достаточно спросить «как сделать Х», и бот найдет инструкцию в документах. - Снижение времени на поиск регламентов и стандартов. **Примеры использования (все возможные сценарии)**: 1. **Поиск инструкции по номеру пункта**: - Запрос: «Выведи пункт 4.2 из регламента по внедрению 5S» - Ответ: ``` [Источник: Регламент_внедрения_5S.docx] Пункт 4.2. Порядок проведения аудита рабочего места: 1. Подготовка: сформировать чек-лист на основе стандарта 5S. 2. Проведение аудита: визуальный осмотр рабочих мест, фиксация нарушений. 3. Оценка: выставление баллов по каждому критерию... ``` 2. **Поиск процедуры по ключевому слову «как» + «инструкция»**: - Запрос: «Как провести хронометраж рабочего времени?» - Ответ: ``` [Источник: Методика_хронометража.pdf] Инструкция по проведению хронометража: 1. Определить цель... 2. Выбрать объект наблюдения... 3. Разработать лист наблюдений... 4. Провести наблюдение... 5. Обработать данные... 6. Сделать выводы... ``` 3. **Поиск алгоритма по ключевым словам «порядок действий», «этапы»**: - Запрос: «Опиши порядок действий при внедрении кайдзен-предложения» - Ответ с пошаговым алгоритмом. 4. **Поиск по цитате с кавычками**: - Запрос: «"Срок исполнения не более 5 рабочих дней"» - Ответ: точная цитата с указанием раздела и документа. 5. **Поиск методики по ключевым словам «методика» + «расчет»**: - Запрос: «Найди методику расчета OEE» - Ответ с формулами и пояснениями. 6. **Поиск инструкции с уточнением «напиши инструкцию»**: - Запрос: «Напиши инструкцию по безопасной работе с электроинструментом» - Ответ с полным текстом инструкции. 7. **Поиск с комбинацией: «как» + «внедрить» + конкретный инструмент**: - Запрос: «Как внедрить систему 5S на производстве?» - Ответ с пошаговым алгоритмом внедрения. 8. **Поиск регламента**: - Запрос: «Какой регламент по проведению инвентаризации?» - Ответ с описанием процедуры. 9. **Поиск по номеру документа**: - Запрос: «ГОСТ Р 12345-2023» - Находит документ с этим номером в названии или тексте. 10. **Комбинированный поиск**: - Запрос: «Порядок расчета OEE по методике из приложения 2» - Находит точный раздел и выдает инструкцию. ### **13. Расширение запроса (query expansion)** **Что делает**: Добавляет синонимы, аббревиатуры и связанные термины к исходному запросу для увеличения полноты поиска. Использует GigaChat для генерации до 10 дополнительных ключевых слов. Результаты кэшируются на 5 минут. **Уникальность**: Улучшает recall без участия пользователя. Автоматически подбирает термины, которые могут встречаться в документах. **Польза**: Помогает находить документы, даже если пользователь использует нестандартные термины или сокращения. **Примеры расширения**: | Исходный запрос | Расширенный запрос (пример) | |-----------------|-----------------------------| | «OEE» | «OEE общая эффективность оборудования производительность коэффициент использования» | | «время переналадки» | «время переналадки длительность смены инструмента SMED время простоя» | | «5S» | «5S сортировка соблюдение порядка сияние стандартизация совершенствование рабочее место» | | «Кайдзен» | «Кайдзен непрерывное улучшение малые шаги оптимизация процессов бережливое производство» | | «выработка на человека» | «выработка на человека производительность труда выработка на одного сотрудника ПТ» | | «расчет такта» | «расчет такта тактовое время Takt time формула такта время выпуска единицы» | ### **14. Переранжирование контекста (кросс-энкодер)** **Что делает**: После получения фрагментов из Qdrant, специализированная модель (кросс-энкодер) ранжирует их по релевантности запросу, отбрасывая шум. Используется локальная модель `intfloat/multilingual-e5-reranker`, что исключает затраты на токены и снижает задержку. **Уникальность**: Вместо дорогого вызова LLM используется легкий кросс-энкодер, работающий быстрее и дешевле. При этом качество ранжирования сравнимо с LLM. **Польза**: Уменьшает объем контекста, отправляемого в GigaChat, что экономит токены и улучшает точность ответа (убираются нерелевантные фрагменты). **Пример работы**: Запрос: «Какой OEE на линии А?» Qdrant вернул 30 фрагментов. Кросс-энкодер отбирает только те, где есть упоминания «OEE» и «линия А», отбрасывая фрагменты про другие линии или общие описания. В результате в GigaChat отправляется только релевантный контекст (обычно 5–10 лучших фрагментов). ## 7.5. Функции автоматизации и интеграции ### **15. Автоматическая индексация файлов в комнатах (без `!learn`)** **Что делает**: Любой файл (DOCX, PDF, XLSX, PPTX, изображение, аудио, архив), отправленный в групповой чат, автоматически индексируется в базу знаний комнаты. Не требуется включать режим обучения (`!learn`). Это работает «из коробки» для всех участников комнаты. **Уникальность**: Удобство для коллективной работы – не надо запоминать команды. Даже у Slack и Teams нет такой функции «из коробки». **Польза**: Быстрый старт для новых участников комнаты – они сразу могут задавать вопросы по документам, которые уже загружены. Автоматическое пополнение базы знаний без лишних действий. **Примеры использования**: 1. Пользователь отправляет в групповой чат файл «Регламент_отдела.docx» – бот автоматически индексирует его в комнатную БЗ, и все участники могут задавать по нему вопросы. 2. Новый сотрудник приходит в комнату – он сразу может спрашивать бота о документах, которые уже загружены, без необходимости отдельно загружать их. 3. В комнате с файлами по проекту каждый участник может добавлять новые версии документов, и бот автоматически обновляет индекс (при изменении хеша файла). 4. Если файл является архивом (ZIP, 7z), бот распаковывает его и индексирует все поддерживаемые форматы внутри. ### **16. Веб-скрапинг с рекурсивным обходом** **Что делает**: Бот может загрузить сайт по ссылке, рекурсивно обойти страницы (с ограничением глубины и количества) и проиндексировать их в базу знаний. Поддерживаются HTML-страницы и PDF-документы по ссылкам. **Уникальность**: Превращает произвольные веб-страницы в документы для RAG. Позволяет автоматически собирать информацию из внешних источников. **Польза**: Актуальная информация из внешних источников (изменения законодательства, новости отрасли, техническая документация) – автоматически попадает в базу знаний. **Примеры использования**: 1. **Индексация одной страницы**: - В режиме `!learn` (личный чат) вводите: `https://example.com/document` - Бот загружает страницу, извлекает основной текст (с помощью readability-lxml) и индексирует. 2. **Рекурсивный обход сайта**: - `https://example.com --recursive --depth 2 --max 10` - Бот загружает страницу, затем переходит по ссылкам на глубину 2 уровня, обрабатывая не более 10 страниц, и индексирует все. 3. **Индексация PDF по ссылке**: - `https://example.com/report.pdf` - Бот скачивает PDF, извлекает текст и индексирует. 4. **Задание заголовка**: - `https://example.com --title "Новый ГОСТ"` - Документ сохраняется в БЗ с указанным заголовком. 5. **Ограничения** – глубина по умолчанию 1, максимум страниц 5 (настраивается в конфиге). Это предотвращает перегрузку системы. ### **17. Поддержка голосовых сообщений (распознавание через SaluteSpeech)** **Что делает**: Аудиофайлы (.ogg, .wav, .mp3, .amr, .m4a) транскрибируются в текст через SaluteSpeech API. Полученный текст затем обрабатывается как обычный запрос (классификация, поиск, генерация ответа). Ответ отправляется текстом в чат. **Уникальность**: Редкость для RAG-ботов, удобно для мобильных клиентов. Не требует установки дополнительных приложений – работает с любым аудиофайлом. **Польза**: Можно «продиктовать» вопрос, не набирая текст. Удобно в дороге, в производственных условиях (где руки заняты) или для людей с ограниченными возможностями. **Примеры использования**: 1. Пользователь отправляет голосовое сообщение в личный чат боту (или в комнату). Бот распознает речь, превращает в текст, и если это вопрос – обрабатывает через RAG, отправляя ответ текстом (или голосом, если настроено дополнительно). 2. В мобильном клиенте (например, Conversations) пользователь нажимает кнопку записи голоса, говорит вопрос, бот отвечает в чат текстом. 3. Голосовое сообщение может содержать не только вопрос, но и команду (например, «!summary») – бот распознает и выполняет. 4. Поддерживаются длинные сообщения – транскрипция работает с учетом лимитов API. ### **18. Административные команды (`!stats`, `!status`, `!clean`)** **Что делает**: - `!stats` – показывает статистику работы бота: uptime, количество обработанных сообщений, AI-запросов, файлов, ошибок, документов в БЗ. - `!status` – проверяет доступность внешних сервисов: PostgreSQL, Qdrant, GigaChat, а также состояние дискового пространства. - `!clean` – очищает временную директорию (удаляет все временные файлы). **Уникальность**: Полный контроль без доступа к серверу. Все команды доступны из любого XMPP-клиента. **Польза**: Оперативное администрирование, мониторинг состояния системы, освобождение места на диске. **Примеры использования**: 1. **Проверка состояния сервисов**: - `!status` - Бот проверяет подключение к PostgreSQL, Qdrant, GigaChat и выводит результат: `✅ PostgreSQL Online` `✅ Qdrant Online` `✅ GigaChat Online` `💾 Диск: 512MB / 10GB (свободно 9.5GB)` 2. **Статистика работы бота**: - `!stats` - Выводит: `⏱ Uptime: 2 дня 5 часов` `💬 Сообщений: 1 234` `🤖 AI запросов: 567` `📁 Файлов обработано: 89` `❌ Ошибок: 12` `📚 Документов в БЗ: 45` 3. **Очистка временных файлов**: - `!clean` - Удаляет все файлы из временной директории (temp/), освобождая место на диске. Выводит количество удаленных объектов. 4. **Только для администраторов** – команды `!stats`, `!status`, `!clean` доступны только пользователям, перечисленным в `admin_jids` в конфиге. ## 7.6. Дополнительные возможности ### **Режим обучения (`!learn` и `!stop_learn`)** - `!learn` – включает режим обучения. Следующий файл или ссылка, отправленные в чат, будут добавлены в базу знаний (личную, комнатную или глобальную, в зависимости от контекста и флагов). - `!learn --global` – (только в личном чате, для админов) – следующий файл/ссылка станут глобальными. - `!stop_learn` – выключает режим обучения. **Пример**: `!learn` → затем отправляете файл → он индексируется. `!stop_learn` – режим выключен. ### **Работа с историей диалога** Бот автоматически сохраняет историю диалогов (личную и комнатную) в PostgreSQL. История используется для контекста при ответах. Команда `!reset` сбрасывает историю (личную или комнатную). ### **Поддержка вложенных файлов и архивов** Бот умеет распаковывать ZIP и 7z-архивы и индексировать все файлы внутри (DOCX, PDF, XLSX и т.д.). Это позволяет загружать целые пакеты документов одной ссылкой. ### **Многоязычность** Промпты настроены так, что бот может отвечать на любом языке, на котором задан вопрос, если в документах есть информация на этом языке. В системном промпте явно указано: «Ты можешь использовать информацию из документов на ЛЮБОМ языке (русском, английском, немецком и т.д.)». При необходимости бот переводит нужную часть на язык вопроса. ### **Работа с изображениями (Vision)** Если загружено изображение (JPEG, PNG, BMP, TIFF) и в конфиге включена опция `vision: true`, бот отправляет изображение в GigaChat Vision API для анализа (распознавание текста, описание содержимого). Результат отправляется в чат. ### **Работа с таблицами в DOCX** При извлечении текста из DOCX бот обрабатывает таблицы, сохраняя их структуру. Это позволяет отвечать на вопросы, требующие табличных данных. ## 7.7. Сценарий полного цикла создания коробочного решения ### Этап 1: Подготовка источников 1. Администратор загружает глобальные документы (ГОСТы, методики): ``` !learn --global → отправляет ГОСТ Р 12345-2023.pdf ``` 2. Команда проекта загружает в комнату отраслевые документы: - «Регламент работы библиотек.docx» - «Отчет о кадровом составе.xlsx» - «Методика оценки компетенций.pdf» - «План внедрения 5S.docx» 3. Бот автоматически индексирует все файлы в комнатную БЗ. 4. Пользователь делает `!summary` по каждому документу, чтобы быстро понять содержание. ### Этап 2: Сохранение шаблона 5. Пользователь загружает `Шаблон коробочного решения.docx` и сохраняет как шаблон: ``` !template_save "Коробочное решение_Библиотеки" ``` ### Этап 3: Генерация коробочного решения 6. Пользователь вводит: ``` !create "Коробочное решение_Библиотеки" ``` 7. Бот: - Находит все плейсхолдеры в шаблоне. - Для каждого плейсхолдера выполняет гибридный поиск в БЗ комнаты. - Использует расширение запроса и переранжирование. - Генерирует значение через GigaChat (с самокритикой). - Заменяет плейсхолдеры в копии шаблона. - Отправляет готовый DOCX-файл в чат. ### Этап 4: Проверка и доработка 8. Пользователь открывает готовый DOCX, проверяет содержание. 9. При необходимости делает хирургическую замену: ``` Замени ООО "Ромашка" на ООО "Тюльпан" ``` 10. Проверяет орфографию: ``` Проверь орфографию ``` 11. Получает исправленный файл и отправляет руководству или клиенту. ### Этап 5: Обновление и масштабирование 12. Если в базу знаний добавляются новые документы, можно перегенерировать коробочное решение: ``` !create "Коробочное решение_Библиотеки" ``` Бот использует обновленную БЗ и создает актуальную версию. 13. Для другого типа организаций (музеи) создается аналогичный шаблон: ``` !template_save "Коробочное решение_Музеи" !create "Коробочное решение_Музеи" ``` ---- # II. Перспективы развития Эфцекабот ## 1. Типология ботов: от общефункциональных до персонального ассистента Платформа Эфцекабот построена на едином RAG-ядре (HTTP-сервере), которое обслуживает **любое количество клиентов** – XMPP-ботов, Telegram-ботов, Mastodon-ботов, веб-интерфейсы, системы аналитики. Это означает, что одна и та же база знаний, история диалогов и логика обработки запросов доступны через любой интерфейс. Пользователь может начать диалог в XMPP, продолжить в Telegram, и контекст сохранится – все благодаря централизованному хранению истории на RAG-сервере. ### 1.1. Общие боты | Тип бота | Отдел | Примеры запросов | |-----|------|------| | **Методолог (стандарты)** | Методология, бизнес‑аналитика, внутренний контроль | «Найди требования к описанию бизнес‑процесса» | | **Писатель коробочных решений** | Методология | «Напиши коробочное решение по образцу» | | **Юрист‑эксперт** | Юридический | «Составь претензию по шаблону» | | **Финансовый аналитик** | Финансы, управленческий учет | «Рассчитай OEE по проекту X» | | **HR‑помощник** | Отдел персонала | «Образец служебной записки или бизнес‑процесса» | | **Менеджер проектов** | Проектный офис | «Сформируй выжимку по проекту за месяц» | | **ИТ‑архитектор** | IT‑департамент | «Сравни конфигурации серверов из ТЗ» | | **Комплаенс‑контроль** | Служба безопасности | «Проверь отчет на соответствие регламенту» | | **Executive‑бот** | Топ‑менеджмент | «Сводка KPI по всем проектам» | Каждый из этих ботов может быть реализован как отдельный XMPP-клиент (или другой клиент), подключающийся к общему RAG-ядру. Благодаря единому ядру, все боты используют одни и те же документы и историю, но могут иметь свои промпты, что позволяет настраивать стиль и глубину ответов под конкретную задачу. ### 1.2. Персональный ассистент **Уникальная особенность:** один и тот же бот, но с персональными настройками (история командировок, бюджетные лимиты, предпочтения по отелям, закрепленные проекты). Сотрудник общается с ботом как с личным секретарем. В новой архитектуре персональные настройки хранятся в общей БД и доступны всем клиентам. Пользователь может начать диалог в XMPP, а продолжить в Telegram – история и контекст сохраняются. **Ключевые сценарии персонального ассистента:** | Сценарий | Пример запроса | Автоматизация | |-----|------|------| | **Планирование командировки** | «Запланируй командировку в Нижний Новгород на 10–12 мая» | Бот через агента‑тревел подбирает билеты, отель, создает задачу на согласование руководителю, резервирует | | **Поиск и бронирование билетов** | «Найди ближайший рейс до Екатеринбурга на завтра утро» | Интеграция с корпоративным тревел‑агентом (API), выдача вариантов, бронирование по команде | | **Бронирование гостиницы** | «Подбери гостиницу рядом с офисом клиента в Казани, бюджет до 5000 ₽/ночь» | Агент‑отельер возвращает список, пользователь выбирает – бронь автоматически | | **Оформление командировочного удостоверения** | «Сформируй командировочное удостоверение по поездке №45» | Бот заполняет шаблон данными из бронирования, высылает PDF | | **Авансовый отчет по командировке** | «Сделай авансовый отчет за поездку в Уфу» | Бот предзаполняет даты, маршрут, суммы билетов и отеля; сотрудник добавляет фото чеков → OCR распознает и вносит суммы | | **Согласование отчета** | «Отправь отчет руководителю на подпись» | Бот пересылает отчет в личный чат руководителя, тот ставит «OK» кнопкой | | **Календарь командировок** | «Добавь поездку в мой календарь на 15–17 мая» | Синхронизация с корпоративным календарем (Exchange/Google) | | **Статус командировок** | «Какие у меня утвержденные командировки на следующую неделю?» | Бот извлекает из базы данных (или внешней системы) и отвечает | ## 2. Как бот «вызывает» агентов – архитектура оркестрации Эфцекабот выступает универсальным диспетчером. В текущей архитектуре **сами боты-клиенты не вызывают агентов напрямую**. Вместо этого: 1. Клиент (XMPP-бот, Telegram-бот и т.д.) отправляет запрос пользователя в RAG-сервер через HTTP. 2. RAG-сервер выполняет классификацию намерений (`intent_classify.py`). 3. Если запрос требует внешнего действия (бронирование, расчет, генерация отчета, OCR), RAG-сервер возвращает структурированную команду (например, в формате `[SURGICAL_REPLACE]`, `[REWRITE]`, или через теги для вызова агента). 4. Клиент (или отдельный агент-оркестратор) выполняет эту команду через API внешних систем и возвращает результат в RAG-сервер для финальной обработки. | Запрос пользователя | Намерение (intent) | Вызываемый агент | Действие агента | Результат | |----|----|----|----|----| | «Найди билеты Москва‑Питер на 15 мая» | `BOOKING` | Агент‑тревел | Запрос к API билетной системы | Список рейсов с ценами | | «Подбери гостиницу рядом с вокзалом» | `BOOKING` | Агент‑отельер | Поиск по API Booking.com / Ostrovok | Варианты отелей, кнопка бронирования | | «Сделай авансовый отчет по командировке #123» | `REPORT` | Агент‑генератор DOCX | Заполняет шаблон из данных бронирования и чеков | Готовый отчет в чат | | «Проверь этот чек» | `OCR` | Агент‑распознаватель (OCR) | Извлекает сумму, дату, назначение | Структурированные данные, которые бот вставляет в отчет | **Вывод:** RAG-сервер – это «мозг», а агенты – «руки». Без RAG-сервера агенты разрозненны; с ним они работают как единая система, управляемая естественным языком через единый HTTP API. ## 3. Экономический эффект (исходные данные для штата 300 человек) ### 3.1. Экономия на поиске информации (RAG-функции) - Время, затрачиваемое на поиск информации в документах в день на сотрудника (среднее) – **1 час**. - Доля запросов, полностью автоматизируемых ботом (типовые вопросы по регламентам, KPI, стандартам) – **30%**. - Доля запросов, где бот ускоряет поиск в 2 раза – **50%**. - Остальные 20% – сложные, где экономия меньше, но мы не учитываем их консервативно. **Экономия в часах:** - Полная автоматизация: 300 × 247 (раб. дней) × 1 × 0,3 = 22 230 часов. - Ускорение поиска: 300 × 247 × 0,5 × 0,5 = 18 525 часов (поскольку ускорение в 2 раза = 50% экономии). ### 3.2. Экономия на командировочных процессах (персональный ассистент) **Допущения:** - Количество командировок в год: 200 чел. × 44 недели = **8 800 командировок**. - Без автоматизации затраты времени на одну командировку (поиск билетов, бронирование отеля, оформление заявки, составление авансового отчета, согласование) – **2 часа** (суммарно). - С ботом (интеграция с тревел‑агентом, автоматическое заполнение форм, OCR чеков, «однонажательное» согласование) – **0,4 часа** (24 минуты). Экономия = 1,6 часа на командировку. **Экономия в часах:** 8 800 × 1,6 = **14 080 часов**. ### 3.3. Экономия на снижении ошибок и автоматической проверке документов - Бот автоматически проверяет отчеты, договоры, счета на соответствие регламентам (`CONTRADICTION`, `TEMPLATE_FILL`). Предотвращает переделки и штрафы. - Допустим, среднее время на переделку, исправление отчета, повторное согласование – 2 часа. - В компании с 300 сотрудниками происходит минимум 1000 документооборотных ошибок в год (отчеты, договоры, заявки). Бот выявляет и исправляет 80% из них. **Экономия в часах:** 800 ошибок × 2 часа = **1 600 часов** (консервативно). ### 3.4. Итоговая годовая экономия | Статья | Часы | | - | - | | Поиск информации (RAG) | 40 755 | | Командировки (бронирование + отчетность) | 14 080 | | Снижение ошибок в документообороте | 1 600 | | **Итого прямая экономия времени** | **56 435** | *Не учтены косвенные эффекты: ускорение согласования, повышение мотивации, снижение текучки.* ### 3.5. Затраты на внедрение и обслуживание | Статья | Стоимость | | | | | Развертывание инфраструктуры (серверы, настройка) | 1 млн руб. (разово) | | Разработка интеграций (агенты, тревел‑API, 1С, календарь) | 2 млн руб. (разово, можно тиражировать) | | Обслуживание, обновление БЗ, поддержка | 1 млн руб./год | | **Итого первый год** | **4 млн руб.** | | **Итого последующие годы** | **1 млн руб./год** | ## 4. Перспективы развития (12–24 месяца) ### 4.1. Уже реализованные улучшения (доступны сейчас) В текущей версии платформы уже реализованы следующие ключевые возможности: - **Цепочка рассуждений (Chain-of-Thought)** – для расчетов и инструкций модель показывает пошаговое решение. - **Кэширование классификации и расширения запроса** – результаты кэшируются на 5 минут, что ускоряет повторные запросы. - **Переранжирование через локальный кросс-энкодер** – вместо дорогого вызова LLM используется легкая модель `intfloat/multilingual-e5-reranker`. - **Обрезка истории диалога по токенам** – точный подсчет через `tiktoken`, эффективное использование контекстного окна. - **Единое RAG-ядро с HTTP API** – все клиенты (XMPP, Telegram, веб) подключаются к одному серверу. - **Генерация коробочных решений по шаблону** – команды `!create`, `!template_save`, `!template_list`, `!template_delete`. - **Автоматическая индексация файлов в комнатах** – файлы индексируются без команды `!learn`. - **Полнотекстовый поиск по точным фрагментам** – поиск по номерам пунктов, кавычкам и инструкциям. ### 4.2. Планируемые улучшения - **Интеграция с системами документооборота (СЭД)** – бот сможет подписывать документы ЭЦП, отправлять их на регистрацию, отслеживать статусы. В новой архитектуре это делается через расширение API RAG-сервера. - **Прогнозная аналитика командировок** – бот будет предлагать оптимальные маршруты, экономить на билетах за счет предварительного бронирования. - **Агент‑индексатор сетевых папок (SMB)** – бот сам сканирует общие каталоги и обновляет базу знаний, отправляя файлы на индексацию в RAG-сервер. - **Кэширование результатов генерации** – для одинаковых запросов (с использованием хеша запроса и контекста) планируется внедрение кэширования (in-memory или Redis) на уровне RAG-сервера для снижения нагрузки и ускорения ответа. - **Сбор обратной связи** – команда `!feedback` для оценки качества ответов (лайки/дизлайки) и хранение оценок в БД для последующего анализа. - **A/B-тестирование промптов** – возможность разделять пользователей на группы и применять разные версии промптов для сравнения эффективности. - **Гибкие промты** – автоматический выбор краткой или расширенной версии промпта в зависимости от длины доступного контекстного окна. - **Команда `!style`** – изменение стиля ответов (кратко/подробно/по умолчанию) по желанию пользователя. - **Подключение дополнительных клиентов** – благодаря HTTP API RAG-сервера можно легко добавить Telegram-бота, Mastodon-бота, веб-интерфейс или интеграцию с системами документооборота без изменения ядра. # III. Описание модулей Платформа Эфцекабот построена по принципу **«тонкий клиент – толстый сервер»**. Вся RAG-логика вынесена в отдельный HTTP-сервис – **RAG-сервер**, который обслуживает все клиенты (XMPP-боты, Telegram-боты, веб-интерфейсы и т.д.). Клиенты отправляют запросы на RAG-сервер через HTTP и не содержат RAG-логики. Все модули, описанные ниже, расположены в каталоге `core/`. Часть из них работает на RAG-сервере, часть – в клиентах, часть является общими утилитами. ## 1. Модуль `rag_orchestrator.py` – оркестратор RAG-пайплайна **Назначение:** это **сердце платформы**. Модуль координирует все этапы обработки запроса: - Получение истории диалога из БД (PostgreSQL). - Классификация намерений (intent). - Расширение запроса (query expansion). - Гибридный поиск (dense + sparse) в Qdrant. - Переранжирование контекста (кросс-энкодер). - Синтез ответа через GigaChat. - Самокритика с перегенерацией. - Сохранение истории диалога в БД. **Место в архитектуре:** запускается внутри RAG-сервера при обработке HTTP-запроса `/rag/query`. Не зависит от XMPP или других протоколов – может быть использован в любом клиенте через HTTP API. **Ключевые методы:** - `process_query()` – основной метод, выполняет полный цикл обработки запроса. - `index_document()` – индексация документа (вызывается из `/rag/index`). **Особенности:** - Не содержит состояния, использует переданные сервисы и промпты. - Поддерживает специализированные намерения: `METRICS`, `SUMMARY`, `CONTRADICTION`, `TEMPLATE_FILL`, `SPELLCHECK`, `SURGICAL`, `GREETING`. - Добавляет цепочку рассуждений (Chain-of-Thought) для `CALCULATION` и `PROCEDURE`. ## 2. Модуль `rag_server.py` – HTTP-сервер (FastAPI) **Назначение:** предоставляет REST API для всех клиентов. Является точкой входа в платформу. **Эндпоинты:** | Метод | Эндпоинт | Назначение | |-|-|| | POST | `/rag/query` | Выполнить RAG-запрос (история берется из БД) | | POST | `/rag/index` | Проиндексировать документ | | GET | `/health` | Проверка состояния сервера | **Место в архитектуре:** запускается как отдельный процесс (с помощью Uvicorn). Обслуживает все клиенты. Инициализирует все сервисы (БД, Qdrant, GigaChat) и создает экземпляр `RAGOrchestrator`. **Особенности:** - Использует Pydantic для валидации запросов и ответов. - Поддерживае CORS для возможности запросов с других доменов. - Имеет встроенный healthcheck для мониторинга. ## 3. Модуль `rag_client.py` – HTTP-клиент для ботов **Назначение:** используется тонкими клиентами (XMPP-ботами, Telegram-ботами) для отправки запросов к RAG-серверу. **Методы:** - `query()` – отправляет запрос на `/rag/query`. - `index_document()` – отправляет запрос на `/rag/index`. **Место в архитектуре:** встраивается в клиентские приложения вместо локального вызова RAG-логики. **Особенности:** - Асинхронный (aiohttp). - Поддерживает повторные попытки (retry) при сетевых ошибках. - Не содержит бизнес-логики – только HTTP-вызовы. ## 4. Модуль `rag_api.py` – локальный API-интерфейс **Назначение:** прослойка (facade) между ботами и `RAGOrchestrator` для локального использования (без HTTP). Этот модуль опционален – в новой архитектуре предпочтительнее использовать `RAGClient`. **Место в архитектуре:** может использоваться для тестирования или в случае, если RAG-ядро запущено в том же процессе, что и клиент. ## 5. Модули функций (каталог `functions/`) Все функции являются **чистыми, без состояния** и вызываются из `RAGOrchestrator` на сервере. Они не зависят от XMPP и используют переданные промпты и конфигурацию. ### 5.1. `intent_classify.py` – классификация намерений **Назначение:** определяет тип запроса пользователя (FACT, PROCEDURE, METRICS, SUMMARY, CONTRADICTION, SURGICAL, GREETING, GENERAL, SPELLCHECK, TEMPLATE_FILL) по тексту запроса. **Место в архитектуре:** вызывается из `RAGOrchestrator` перед поиском. **Как работает:** отправляет промпт (`intent_classify.txt`) в GigaChat, получает один из кодов, кэширует результат на 5 минут. **Вход:** текст запроса, промпт, конфиг. **Выход:** код намерения (str) или `"GENERAL"`. ### 5.2. `expand_query.py` – расширение запроса **Назначение:** добавляет синонимы, аббревиатуры и связанные термины к исходному запросу для увеличения полноты поиска. **Место в архитектуре:** вызывается перед поиском в Qdrant. **Как работает:** отправляет промпт (`expand.txt`) в GigaChat, получает до 10 дополнительных ключевых слов, кэширует на 5 минут. **Вход:** текст запроса, промпт, конфиг. **Выход:** расширенный запрос (строка) или исходный, если расширение не удалось. ### 5.3. `extract_metrics.py` – извлечение метрик **Назначение:** извлекает числовые показатели (KPI, OEE, такт, выработку, проценты) из текста в структурированном виде (JSON). **Место в архитектуре:** вызывается при намерении `METRICS`. **Как работает:** отправляет промпт (`metrics_extract.txt`) в GigaChat, парсит JSON-ответ. При неудаче – fallback-парсинг строк вида `ключ: значение`. **Вход:** контекст (текст), промпт, конфиг. **Выход:** список словарей с полями `metric_name`, `value`, `unit`, `period`, `source_fragment`. ### 5.4. `summarize_document.py` – суммаризация документа **Назначение:** создает краткий пересказ документа (≤30% от оригинала) с выделением целей, выводов и ключевых цифр. **Место в архитектуре:** вызывается при намерении `SUMMARY`. **Как работает:** отправляет промпт (`smart_summary.txt`) в GigaChat, подставляя текст документа. **Вход:** текст, название, промпт, конфиг. **Выход:** строка с кратким изложением. ### 5.5. `check_consistency.py` – проверка противоречий **Назначение:** находит логические, числовые или терминологические расхождения в разных фрагментах текста. **Место в архитектуре:** вызывается при намерении `CONTRADICTION`. **Как работает:** отправляет промпт (`consistency_check.txt`) в GigaChat, получает ответ `[OK]` или `[CONFLICT]` с описанием. **Вход:** список фрагментов, запрос, промпт, конфиг. **Выход:** строка с результатом проверки. ### 5.6. `critique_answer.py` – самокритика ответа **Назначение:** оценивает качество сгенерированного ответа по пяти критериям (соответствие источнику, отсутствие галлюцинаций, стиль, логика, запрет внешних знаний). **Место в архитектуре:** вызывается после генерации ответа (если включена в конфиге). **Как работает:** отправляет промпт (`self_critique.txt`) в GigaChat, анализирует ответ на наличие `[OK]` или `[ISSUES]`. **Вход:** запрос, контекст, ответ, промпт, конфиг. **Выход:** `True` (ответ хороший) или `False` (есть замечания). ### 5.7. `rerank_context.py` – переранжирование контекста **Назначение:** отбирает только релевантные фрагменты из результатов поиска, отбрасывая шум. Использует локальный кросс-энкодер вместо LLM. **Место в архитектуре:** вызывается после поиска в Qdrant (если контекст длиннее `min_length`). **Как работает:** отправляет фрагменты в кросс-энкодер (`intfloat/multilingual-e5-reranker`), ранжирует и возвращает только топ-N фрагментов. **Вход:** запрос, контекст, конфиг. **Выход:** отфильтрованный контекст (строка). ### 5.8. `file_processor.py` – обработка файлов **Назначение:** отправка файлов пользователю через HTTP Upload (XEP-0363) и обработка тегов `[SURGICAL_REPLACE]`, `[REWRITE]`, `[FILE]` из ответа AI. **Место в архитектуре:** вызывается из клиентов (XMPP-ботов) и из RAG-пайплайна при наличии тегов. **Как работает:** парсит ответ AI, извлекает теги, вызывает методы `FileService` для замены или создания DOCX-файлов, отправляет результат через HTTP Upload. **Вход:** ответ AI, JID пользователя, путь к файлу. **Выход:** отправленный файл или сообщение об ошибке. ### 5.9. `generate_document.py` – генерация по шаблону **Назначение:** заполняет плейсхолдеры `{{название}}` в шаблоне документа на основе данных из базы знаний. **Место в архитектуре:** вызывается из команды `!create` (через RAG-сервер). **Как работает:** находит все плейсхолдеры, для каждого выполняет поиск в БЗ, генерирует значение через GigaChat, заменяет в копии шаблона. **Вход:** шаблон (DOCX), запрос пользователя, конфиг. **Выход:** готовый DOCX-файл. ## 6. Сервисы (каталог `services/`) Долгоживущие компоненты, которые инициализируются один раз при старте RAG-сервера и предоставляют API для работы с внешними системами. | Файл | Назначение | |-----|------| | `postgres_service.py` | Пул соединений с PostgreSQL. CRUD для документов, истории диалогов, комнат, шаблонов, прав доступа. | | `qdrant_service.py` | Векторная БД. Создание коллекции, гибридный поиск (dense + sparse), полнотекстовый поиск, удаление по doc_id. | | `embedding_service.py` | Эмбеддинги GigaChat. Одиночные/пакетные запросы, кэширование (`lru_cache`), обрезка текста до 800 символов. | | `kb_service.py` | База знаний. Индексация документов (разбиение на чанки, получение эмбеддингов, сохранение в Qdrant и PostgreSQL), поиск, управление доступом. | | `file_service.py` | Извлечение текста из файлов (DOCX, PDF, XLSX, PPTX, изображения, аудио, архивы). Хирургическая замена, создание DOCX. | | `giga_client.py` | Клиент GigaChat. Методы `chat()` и `upload_file()` – без бизнес-логики. | | `reranker_service.py` | Кросс-энкодер для переранжирования (локально). Ленивая загрузка модели. | ## 7. Обработчики, команды, воркеры (для XMPP-клиентов) Эти модули работают только на стороне **тонких клиентов** (XMPP-ботов) и не входят в RAG-сервер. ### 7.1. Обработчики (`handlers/`) | Файл | Назначение | |-----|------| | `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 (для клиентов). | ### 7.2. Команды (`commands/`) | Файл | Назначение | |-----|------| | `base.py` | Базовый класс `Command`. | | `registry.py` | Регистрация команд, алиасы, подсказки. | | `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` – удаление глобального документа (админ). | ### 7.3. Воркеры (`workers/`) | Файл | Назначение | |-----|------| | `indexing_worker.py` | Фоновый воркер, который обрабатывает очередь индексации файлов и URL, отправляя их на RAG-сервер через `RAGClient`. | ## 8. Утилиты (каталог `utils/`) Вспомогательные функции, используемые как сервером, так и клиентами: | Файл | Назначение | |-----|------| | `config_loader.py` | Загрузка `core.conf` и `bot.conf`, слияние, чтение `.env`. | | `logger.py` | Настройка логирования (уровни, вывод в файл и консоль). | | `layout_converter.py` | Конвертер раскладки клавиатуры (русская ↔ английская). | | `text_utils.py` | Разбиение текста на чанки (tiktoken + razdel), подсчет токенов (`count_tokens`). | | `web_utils.py` | Веб-скрапинг (`fetch_any_url`, `crawl_url`). | | `arg_parser.py` | Парсинг аргументов команд (--flag value). | ## 9. Тесты (каталог `tests/`) Покрывают критически важные функции: - `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` – проверка орфографии. Тесты используют `pytest` и `pytest-asyncio`, не требуют реального подключения к внешним сервисам (используются моки). Запуск: `pytest tests/ -v`. ## 10. Конфигурационные файлы Платформа использует два основных конфигурационных файла: - **`core.conf`** – общие настройки для всех ботов: параметры подключения к БД, Qdrant, GigaChat, настройки чанкинга, RAG, веб-скрапера, очистки, логирования. - **`bot.conf`** – настройки конкретного профиля бота (методолог, коробочник, персональный ассистент): JID, пароль, промпты, пути к данным, ключевые слова, администраторы, параметры функций (температура, лимиты). Переменные окружения (пароли, ключи API) хранятся в `.env`. Примеры конфигурации предоставлены в файлах `core.conf.example`, `bot.conf.sample`, `env.example`. ## 11. Схема базы данных (PostgreSQL) Схема создается автоматически через `schema.sql` и включает таблицы: - **`documents`** – метаданные документов (источник, владелец, глобальный/комнатный флаг, хеш, коллекция Qdrant). - **`document_access`** – права доступа к личным документам. - **`history`** – история диалогов (личных и комнатных). - **`rooms`** – список MUC-комнат, в которых бот должен состоять. - **`room_templates`** – шаблоны коробочных решений, сохраненные в комнатах.