# 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, веб-интерфейс, системы аналитики). RAG-сервер также предоставляет эндпоинты `/rag/vision` для распознавания текста на изображениях (OCR) и `/rag/transcribe` для транскрибации аудио, что централизует обработку медиафайлов. 2. **Тонкие XMPP-боты-клиенты** — каждый профиль (методолог, коробочник, персональный ассистент) представляет собой отдельный XMPP-клиент, который подключается к ejabberd, обрабатывает команды, принимает файлы и пересылает запросы пользователей в RAG-ядро по HTTP. Боты не содержат RAG-логики, не имеют локальной БД или Qdrant, а только загружают свои промпты и передают их в запросах. Это делает их легковесными и независимыми. Вся обработка изображений и аудио выполняется на RAG-сервере, что дополнительно упрощает клиентов. 3. **Внешние системы хранения и API**: - **Ejabberd** — XMPP-сервер (сообщения, MUC-комнаты, HTTP Upload); - **PostgreSQL** — централизованное хранилище метаданных документов, истории диалогов, прав доступа, списка комнат, шаблонов и оценок обратной связи. Управление схемой через Alembic (миграции). Добавлена колонка `file_text` для хранения исходного текста документов. - **Qdrant** — векторная БД с двумя полями (dense, sparse) для гибридного поиска. Доступна только RAG-ядру. - **GigaChat API** — генерация текста и эмбеддингов. Вызовы осуществляются только из RAG-ядра, что позволяет централизованно управлять кэшированием и лимитами. - **Redis** (опционально) — кэширование эмбеддингов (TTL 1 час) и результатов SOMA-оценок (TTL 5 мин). - **Внешние API** — для инструментов ReAct: DuckDuckGo (поиск), OpenWeatherMap (погода), заглушки для бронирования и курсов валют. **Философия**: - Каждый документ принадлежит контексту (личный, комнатный, глобальный). - Боты-клиенты не имеют собственных знаний — они только передают запросы в RAG-ядро, которое отвечает строго по загруженным материалам (строгий RAG). - Единая история диалога для каждого пользователя/комнаты хранится на сервере, что обеспечивает непрерывность контекста независимо от того, через какой интерфейс (XMPP, Telegram, веб) пользователь общается с системой. - Встроен интеллектуальный маршрутизатор запросов (классификация намерений), экспертная подсистема (метрики, суммаризация, проверка противоречий, хирургическая замена) и самокритика ответов — все это реализовано в RAG-ядре и доступно всем клиентам. - Добавлены **инновационные техники**: SOMA-анализ (LLM-as-judge), ReAct (вызов внешних инструментов), планирование действий, многоагентность, реальные обработчики инструментов, фоновый ReindexWorker для переиндексации документов после сбоев. **Сервисы распределены по джейлам FreeBSD/Linux**: - `rag-server` (Python 3.11/3.12) — HTTP-сервис RAG-ядра. - `metabot`, `korobot`, `persobot` — отдельные XMPP-клиенты (также на Python), которые общаются с RAG-ядром через HTTP. - `Ejabberd`, `PostgreSQL`, `Qdrant`, `Redis` — внешние системы. Инфраструктура развернута на **FreeBSD** с использованием **джейлов** (изолированных окружений), **ZFS** (файловая система с поддержкой снэпшотов и сжатия) и **10-гигабитной** внутренней сети между сервисами. Балансировщик **HAProxy** обеспечивает маршрутизацию внешних запросов и, при необходимости, горизонтальное масштабирование. Автоматические снэпшоты ZFS настроены через `zfs-auto-snapshot` для надежного резервного копирования. ## 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 нет такой функции «из коробки». 7. **Встроенные инновационные техники** — SOMA-анализ (LLM-as-judge), ReAct (вызов внешних инструментов), планирование действий, многоагентность — позволяют повысить качество ответов, экономить токены и автоматизировать сложные рабочие процессы. ## 4. Преимущества и недостатки работы бота в чате #### Преимущества - **Единое корпоративное окно** — пользователь не переключается между приложениями, получает экспертные ответы прямо в рабочем чате. - **Мгновенный обмен файлами** — встроен HTTP Upload, бот автоматически отправляет файлы в RAG-ядро для индексации (в том числе в групповых комнатах). - **Учет контекста беседы** — история диалога хранится централизованно в RAG-ядре, что обеспечивает единый контекст для всех клиентов (XMPP, Telegram, веб). - **Поддержка комнат (MUC)** — документы, загруженные в комнату, видны всем участникам, а переписка в комнате служит общим контекстом. - **Легковесные клиенты** — боты не содержат сложной RAG-логики, что упрощает их обновление и развертывание; все изменения в RAG вносятся в одном месте — RAG-ядре. - **Не требует установки уникального клиентского ПО** — достаточно любого XMPP-клиента (Fluux, Conversations, Gajim, Pidgin) или работы через веб-интерфейс (который также может использовать RAG-ядро). - **Полный контроль данных** — развертывание внутри периметра, никаких облачных сервисов. - **Поддерживаемые форматы**: DOCX, PDF, XLSX, PPTX, TXT, CSV, JSON, изображения (OCR), аудио (SaluteSpeech), архивы ZIP/7z. - **Размер загружаемого файла**: до 1 Гб. - **Расширенные возможности** — SOMA-оценка ответов, ReAct-вызовы внешних API, планирование, многоагентность, фоновый ReindexWorker для восстановления после сбоев. #### Недостатки - **Задержка** — добавлен сетевой вызов от бота к RAG-ядру (1–2 мс внутри сети) и несколько вызовов GigaChat (3–10 секунд). Однако благодаря кэшированию (классификация, расширение, эмбеддинги, SOMA) и локальному кросс-энкодеру итоговое время ответа в большинстве случаев составляет 3–7 секунд, что приемлемо для экспертной системы. - **Сложность отладки** — распределенная система (RAG-ядро, боты-клиенты, ejabberd, PostgreSQL, Qdrant) усложняет трассировку ошибок, но централизованное логирование, структурированные JSON-логи и единая точка входа (RAG-ядро) упрощают мониторинг. ## 5. Как чат-бот влияет на работу с GigaChat | Аспект | Влияние | | ------ | ------- | | **Скорость** | GigaChat — облачный API, задержка ~1–2 секунды на вызов. В текущей архитектуре все вызовы GigaChat происходят только из RAG-ядра (не из ботов). Пайплайн может делать 2–4 вызова на запрос (классификация, расширение, генерация, критика, SOMA). Благодаря общему кэшированию (TTL 5 минут) для классификации и расширения, а также локальному кросс-энкодеру для переранжирования, количество вызовов GigaChat сокращено до минимума, что снижает итоговую задержку до 3–7 секунд. | | **Экономия токенов** | Переранжирование и гибридный поиск (sparse + dense) уменьшают объем контекста. История диалога обрезается точно по токенам (через tiktoken) с пагинацией. Дополнительно внедрено иерархическое резюмирование для сжатия длинных диалогов и документов, что еще больше экономит токены. Централизация также позволяет агрегировать кэши и общие эмбеддинги, снижая общие затраты на токены. Кэширование SOMA-оценок (TTL 5 мин) избегает повторных вызовов. | | **Качество ответа** | GigaChat хорошо понимает русский язык, отлично справляется с деловой и технической терминологией. Но без точного промпта и контекста возможны галлюцинации — самокритика и перегенерация, выполняемые в RAG-ядре, частично нивелируют это. Дополнительно внедрен SOMA-анализ (LLM-as-judge), который оценивает ответ по 5 критериям и при низких оценках перегенерирует его. ReAct и планирование повышают точность сложных расчётов и инструкций. Единые промпты для всех клиентов упрощают тонкую настройку качества. Иерархическое резюмирование помогает сохранить ключевую информацию в длинных документах. | | **Надежность** | GigaChat имеет лимиты и может выдавать ошибки. RAG-ядро делает несколько попыток при эмбеддингах и генерации (retry с экспоненциальной задержкой), а также использует circuit breaker для защиты от сбоев. При отказе API возвращается сообщение о недоступности. Централизация позволяет реализовать единые политики повторных попыток и fallback. RAGClient устойчив к сетевым ошибкам (ClientConnectorError и др.). | | **Гибридные векторы** | GigaChat генерирует только dense-эмбеддинги, sparse-векторы вычисляются через FastEmbed (`Qdrant/bm25`) локально на сервере RAG-ядра. Это разгружает GigaChat и не требует дополнительных API, а также позволяет использовать общий кэш эмбеддингов для всех клиентов. | ## 6. Архитектура проекта ### 6.1. Общая архитектура Платформа состоит из трех основных логических слоев. ``` ┌──────────────────────────────────────────────────────────────────────────────────────-┐ │ ВНЕШНИЕ КЛИЕНТЫ (пользователи) │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ XMPP-боты │ │ Telegram │ │ Mastodon │ │ Веб-интерф. │ │ API │ │ │ │ (тонкие) │ │ (клиент) │ │ (клиент) │ │ (клиент) │ │ интеграции │ │ │ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ │ │ │ │ │ │ │ │ └────────────────┼────────────────┼────────────────┼────────────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌────────────────────────────────────────────────────────────────────────────────-┐ │ │ │ RAG-Сервер (HTTP API / FastAPI) │ │ │ │ │ │ │ │ ┌──────────────────────────────────────────────────────────────────────────-┐ │ │ │ │ │ RAG Orchestrator (ядро) │ │ │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │ │ │ │ │ History │ │ Intent │ │ Query │ │ Indexing │ │ │ │ │ │ │ │ Manager │ │ Router │ │ Processor │ │ Manager │ │ │ │ │ │ │ └──────────────┘ └──────────────┘ └──────┬───────┘ └──────────────────┘ │ │ │ │ │ │ │ │ │ │ │ │ │ ┌────────────────────────────────────────┼───────────────────────────-┐ │ │ │ │ │ │ │ Дополнительные модули │ │ │ │ │ │ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────┴───-───┐ ┌──────────────┐ │ │ │ │ │ │ │ │ │ SOMA │ │ ReAct │ │ Planning │ │ Agents │ │ │ │ │ │ │ │ │ │ (LLM-as- │ │ (внешние │ │ (генерация │ │ (методолог, │ │ │ │ │ │ │ │ │ │ judge) │ │ вызовы) │ │ плана) │ │ коробочник, │ │ │ │ │ │ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ ассистент) │ │ │ │ │ │ │ │ │ └──────────────┘ │ │ │ │ │ │ │ │ ┌─────────────────────────────────────────────────────────────────┐│ │ │ │ │ │ │ │ │ ToolHandler (реальные инструменты) ││ │ │ │ │ │ │ │ │ search() │ get_weather() │ book_flight() │ exchange() ││ │ │ │ │ │ │ │ └─────────────────────────────────────────────────────────────────┘│ │ │ │ │ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │ │ │ └──────────────────────────────────────────────────────────────────────────-┘ │ │ │ │ │ │ │ │ ┌────────────────────────────────────────────────────────────────────────-──┐ │ │ │ │ │ ReindexWorker (фоновый воркер) │ │ │ │ │ │ переиндексация документов с indexed=False │ │ │ │ │ └─────────────────────────────────────────────────────────────────────────-─┘ │ │ │ │ │ │ │ │ ┌──────────────────────────────────────────────────────────────────────────-┐ │ │ │ │ │ Эндпоинты REST API │ │ │ │ │ │ /rag/query /rag/index /rag/vision /rag/transcribe │ │ │ │ │ │ /rag/clear /rag/list /rag/delete_global │ │ │ │ │ │ /rag/template/* /rag/reset_history /rag/room/* /rag/stats │ │ │ │ │ │ /rag/generate_document │ │ │ │ │ │ /health /docs /redoc /openapi.json /metrics │ │ │ │ │ └──────────────────────────────────────────────────────────────────────────-┘ │ │ │ └────────────────────────────────────────────────────────────────────────────────-┘ │ │ │ │ │ ▼ │ │ ┌────────────────────────────────────────────────────────────────────────────────-┐ │ │ │ ВНЕШНИЕ СИСТЕМЫ (данные и API) │ │ │ │ │ │ │ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌─────────────┐ │ │ │ │ │PostgreSQL │ │ Qdrant │ │ GigaChat │ │ Redis │ │ Файлы │ │ │ │ │ │(история, │ │(векторный │ │ (генерация│ │ (кэш эм- │ │ (DOCX, │ │ │ │ │ │ документы,│ │ поиск, │ │ эмбеддинги│ │ беддингов,│ │ PDF, │ │ │ │ │ │ права, │ │ гибридный │ │ Vision) │ │ SOMA) │ │ XLSX, │ │ │ │ │ │ шаблоны, │ │ dense+ │ │ │ │ │ │ PPTX, │ │ │ │ │ │ file_text│ │ sparse) │ │ │ │ │ │ аудио, │ │ │ │ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │ изображ.) │ │ │ │ │ └─────────────┘ │ │ │ │ │ │ │ │ ┌──────────────────────────────────────────────────────────────────────────┐ │ │ │ │ │ ВНЕШНИЕ API (инструменты) │ │ │ │ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌─────────────┐ │ │ │ │ │ │ │ DuckDuckGo │ │OpenWeatherMap│ │ Booking API │ │ Exchange │ │ │ │ │ │ │ │ (поиск) │ │ (погода) │ │ (заглушка) │ │ Rate API │ │ │ │ │ │ │ │ │ │ │ │ │ │ (заглушка) │ │ │ │ │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ └─────────────┘ │ │ │ │ │ └──────────────────────────────────────────────────────────────────────────┘ │ │ │ └───────────────────────────────────────────────────────────────────────────────-─┘ │ └─────────────────────────────────────────────────────────────────────────────────────-─┘ ``` **Ключевые компоненты**: - **RAG-сервер** — единая точка входа для всех RAG-запросов. Содержит всю бизнес-логику (поиск, генерацию, самокритику, индексацию). Запускается как отдельный HTTP-сервис. - **RAG Orchestrator** — фасад, координирующий менеджеры и модули: - `HistoryManager` — управление историей (пагинация, сжатие). - `IntentRouter` — маршрутизация специализированных намерений. - `QueryProcessor` — интеграция SOMA, ReAct, планирования и агентов. - `IndexingManager` — индексация с предварительным сжатием. - **Дополнительные модули**: - **SOMA (LLM-as-judge)** — оценка ответов с кэшированием. - **ReAct** — вызов внешних инструментов (поиск, погода, бронирование, курс). - **Planning** — генерация пошагового плана. - **Agents** — многоагентная архитектура (методолог, коробочник, ассистент). - **ToolHandler** — реальные обработчики инструментов. - **ReindexWorker** — фоновый воркер для переиндексации документов после сбоев. - **Эндпоинты** — основные, административные, управление шаблонами, комнатами, статистика, генерация документов, health, метрики. - **Внешние системы** — PostgreSQL (с `file_text`, управление через Alembic), Qdrant (гибридный поиск), GigaChat, Redis (кэширование), файлы, внешние API. ### 6.2. Структура каталогов проекта Проект организован по принципу разделения ответственности: RAG-сервер и боты-клиенты имеют свои независимые каталоги. Тесты вынесены в корень проекта. ``` /usr/local/etc/fckbot/ # КОРЕНЬ ПРОЕКТА │ ├── alembic.ini # Конфигурация Alembic (миграции) │ ├── rag/ # RAG-ядро (HTTP-сервер) │ ├── alembic/ # Миграции PostgreSQL │ │ ├── env.py # Настройка окружения для Alembic │ │ ├── script.py.mako # Шаблон для миграций │ │ └── versions/ # Папка с миграциями │ ├── auth.py # Аутентификация (проверка API-ключа) │ ├── config_models.py # Pydantic-модели для конфигурации (AppConfig) │ ├── create_qdrant_collection.py # Скрипт создания коллекции в Qdrant │ ├── history_manager.py # Менеджер истории диалогов (сжатие, пагинация, обрезка) │ ├── indexing_manager.py # Менеджер индексации документов (сжатие, вызов KBService) │ ├── intent_router.py # Маршрутизатор специализированных намерений │ ├── prompt_builder.py # Построитель промтов (few-shot, сэндвич, санитизация) │ ├── query_processor.py # Обработчик RAG-запросов (поиск, синтез, критика, SOMA, ReAct, планирование, агенты) │ ├── rag_api.py # Локальный API-интерфейс (facade) │ ├── rag.conf.example # Шаблон конфига RAG-сервера (YAML): БД, Qdrant, GigaChat, Redis, новые параметры │ ├── rag_orchestrator.py # Оркестратор RAG-пайплайна (менеджеры, ToolHandler) │ ├── rag_server.py # HTTP-сервер на FastAPI + Uvicorn (точка входа) │ ├── README.md # Документация (этот файл) │ ├── requirements.txt # Зависимости Python (включая tenacity, pybreaker, redis, aioredis, python-json-logger) │ ├── schema.sql # Схема PostgreSQL (используется только для тестов; в продакшене — Alembic) │ ├── functions/ # Чистые функции (без состояния) │ │ ├── check_consistency.py # Проверка противоречий │ │ ├── check_spelling.py # Проверка орфографии │ │ ├── critique_answer.py # Самокритика ответа │ │ ├── expand_query.py # Расширение запроса │ │ ├── extract_metrics.py # Извлечение KPI в JSON │ │ ├── file_processor.py # Обработка файлов, теги SURGICAL_REPLACE и др. │ │ ├── generate_document.py # Генерация документа по шаблону │ │ ├── hierarchical_summarize.py # Иерархическое резюмирование │ │ ├── intent_classify.py # Классификация намерений │ │ ├── plan_generation.py # Генерация плана действий (новый) │ │ ├── react.py # Цикл ReAct (вызов внешних инструментов) │ │ ├── rerank_context.py # Переранжирование контекста │ │ ├── soma_evaluate.py # SOMA-анализ (LLM-as-judge) с кэшированием │ │ ├── summarize_document.py # Суммаризация документа │ │ └── tools.py # Реальные обработчики инструментов (поиск, погода, бронирование, курс) │ ├── services/ # Сервисы (долгоживущие компоненты) │ │ ├── embedding_service.py # Эмбеддинги GigaChat с кэшированием (Redis + локальный) │ │ ├── file_service.py # Извлечение текста из файлов, транскрибация (экранирование путей) │ │ ├── giga_client.py # Клиент GigaChat с retry и circuit breaker │ │ ├── kb_service.py # База знаний (индексация, поиск, управление доступом, file_text) │ │ ├── postgres_service.py # Пул соединений с PostgreSQL (с проверкой таблиц, Alembic) │ │ ├── qdrant_service.py # Векторная БД (гибридный поиск, полнотекстовый, индексы) │ │ └── reranker_service.py # Кросс-энкодер с асинхронной загрузкой модели │ ├── utils/ # Утилиты │ │ ├── arg_parser.py # Парсинг аргументов командной строки │ │ ├── config_loader.py # Загрузка конфигов, слияние, создание AppConfig │ │ ├── logger.py # Настройка логирования (с поддержкой JSON-формата) │ │ ├── text_utils.py # Разбиение на чанки, подсчет токенов │ │ └── web_utils.py # Веб-скрапинг (с ограничением размера) │ └── workers/ # Фоновые воркеры │ └── reindex_worker.py # Переиндексация документов с indexed=False │ ├── bots/ # ОБЩИЙ КОД БОТОВ-КЛИЕНТОВ │ ├── bot.py # Точка входа для запуска XMPP-бота (принимает --profile-dir) │ ├── rag_client.py # HTTP-клиент для связи с RAG-сервером (асинхронный, с повторными попытками) │ ├── commands/ # Команды ботов (XMPP-интерфейс) │ │ ├── base.py # Базовый класс Command (алиасы, права доступа, кэширование) │ │ ├── create.py # !create – генерация документа по шаблону │ │ ├── expert.py # !summary, !metrics – экспертные функции │ │ ├── global_remove.py # !global_remove – удаление глобального документа (админ) │ │ ├── help.py # !help – подробная справка по командам │ │ ├── info.py # !info – краткая справка │ │ ├── kb.py # !clear, !global_clear, !kb – управление базой знаний │ │ ├── learn.py # !learn, !stop_learn, !global_learn – режим обучения │ │ ├── other.py # !reset – сброс истории │ │ ├── registry.py # Регистрация команд, алиасы, подсказки при опечатке │ │ ├── stats.py # !stats, !status, !clean – администрирование │ │ └── template.py # !template_save, !template_list, !template_delete – шаблоны │ ├── handlers/ # Обработчики XMPP событий │ │ ├── file_handler.py # Скачивание файлов и постановка в очередь индексации │ │ ├── health_handler.py # Очистка временных файлов, healthcheck БД/Qdrant (для клиентов) │ │ ├── message_handler.py # Маршрутизация входящих сообщений (команды, файлы, AI-запросы) – использует RAGClient │ │ ├── metrics_handler.py # Счетчики (сообщения, файлы, AI-запросы, ошибки) │ │ ├── room_handler.py # MUC комнаты (приглашения, вход, переподключение) │ │ └── subscription_handler.py # Подписки (roster subscription) │ ├── workers/ # Фоновые воркеры │ │ └── indexing_worker.py # Индексация файлов и URL (отправляет на RAG-сервер через RAGClient) │ └── xmpp/ # XMPP-клиент │ └── client.py # Основной класс Bot (наследует slixmpp.ClientXMPP) │ ├── template_bot_profile/ # ШАБЛОН ПРОФИЛЯ (для создания новых ботов) │ ├── bot.conf.sample # Пример конфига бота-клиента (копируется в bot.conf) │ ├── data/ # Каталог для постоянных копий файлов │ │ └── fewshot_examples.json # Примеры few-shot (можно редактировать) │ ├── prompts/ # Пример промптов (копируются в профиль) │ │ ├── consistency_check.txt # Проверка противоречий между фрагментами │ │ ├── expand.txt # Расширение запроса (синонимы, аббревиатуры) │ │ ├── generate_document.txt # Генерация документа по шаблону │ │ ├── hierarchical_summary.txt # Иерархическое резюмирование │ │ ├── intent_classify.txt # Классификация намерений │ │ ├── metrics_extract.txt # Извлечение KPI в JSON │ │ ├── quality_criteria.txt # Дополнительные критерии качества ответа │ │ ├── self_critique.txt # Самокритика ответа │ │ ├── smart_summary.txt # Суммаризация документа │ │ ├── spellcheck.txt # Проверка орфографии и пунктуации │ │ ├── synthesis.txt # Шаблон синтеза ответа │ │ ├── soma_evaluate.txt # Промпт для SOMA │ │ ├── react_system.txt # Системный промпт для ReAct │ │ ├── planning.txt # Промпт для генерации плана │ │ └── system.txt # Системный промпт (роль, стиль, правила) │ └── temp/ # Пустой каталог для временных файлов │ ├── tests/ # ЮНИТ-ТеТЫ (общие для всего проекта) │ ├── conftest.py # Фикстуры и моки для pytest │ ├── test_check_spelling.py # Тесты проверки орфографии │ ├── test_consistency.py # Тесты проверки противоречий │ ├── test_critique.py # Тесты самокритики │ ├── test_expand_query.py # Тесты расширения запроса │ ├── test_extract_metrics.py # Тесты извлечения метрик │ ├── test_hierarchical_summary.txt # Тесты иерархического резюмирования │ ├── test_intent_classify.py # Тесты классификации намерений │ └── test_summarize.py # Тесты суммаризации │ ├── venv/ # ВИРТУАЛЬНОЕ ОКРУЖЕНИЕ Python │ ├── bin/ # Исполняемые файлы (python, pip, activate) │ ├── lib/ # Установленные библиотеки │ └── ... │ └── .env.example # ШАБЛОН ПЕРЕМЕННЫХ ОКРУЖЕНИЯ ├── XMPP_PASSWORD=... # Пароль для XMPP-аккаунта бота ├── DB_PASSWORD=... # Пароль для PostgreSQL ├── GIGACHAT_API_KEY=... # API-ключ GigaChat ├── SALUTE_SPEECH_AUTH=... # Авторизация для SaluteSpeech (голосовые сообщения) └── RAG_API_KEY=... # API-ключ для доступа к RAG-серверу (защита эндпоинтов) ``` **Важные примечания**: - Реальные профили ботов создаются администратором вручную вне репозитория. - Конфигурационные файлы и переменные окружения не хранятся в репозитории. - Управление схемой PostgreSQL — через Alembic (миграции в `rag/alembic/`). - Все новые модули (SOMA, ReAct, планирование, агенты, ToolHandler, ReindexWorker) интегрированы в основной пайплайн. ### 6.3. Взаимодействие компонентов ``` ┌─────────────┐ HTTP ┌─────────────┐ SQL ┌─────────────┐ │ Пользова- │ ──────────────▶│ RAG- │ ──────────────▶│ PostgreSQL │ │ тель │ │ сервер │ │ (история, │ │ (XMPP) │ ◀──────────────│ (ядро) │ ◀──────────────│ документы, │ └─────────────┘ └─────────────┘ │ file_text) │ │ │ └─────────────┘ │ XMPP │ HTTP (gRPC) │ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ ejabberd │ │ Qdrant │ │ GigaChat │ │ (чат-серв.) │ │ (векторная │ │ (API) │ └─────────────┘ │ БД) │ └─────────────┘ │ └─────────────┘ │ │ XMPP │ │ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ XMPP-бот │ │ FastEmbed │ │ Файлы │ │ (тонкий) │ │ (локальный │ │ (диск) │ │ клиент │ │ кросс-энк.) │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ │ │ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Redis │ │ Tool- │ │ Reindex- │ │ (кэш эм- │ │ Handler │ │ Worker │ │ беддингов, │ │ (внешние │ │ (фоновый) │ │ SOMA) │ │ API) │ └─────────────┘ └─────────────┘ └─────────────┘ ``` **Поток данных**: 1. **Запрос пользователя** → XMPP-бот → HTTP → RAG-сервер. 2. RAG-сервер: - Получает историю из PostgreSQL (с пагинацией и обрезкой). - Выполняет классификацию намерений. - При необходимости вызывает SOMA, ReAct, планирование, агентов. - Ищет в Qdrant (гибридный поиск), переранжирует, генерирует ответ через GigaChat. - Выполняет самокритику и SOMA-оценку, при низких оценках перегенерирует. - Сохраняет историю в PostgreSQL. 3. **Ответ** → HTTP → XMPP-бот → ejabberd → пользователь. 4. **Индексация файла** → XMPP-бот → HTTP → RAG-сервер → разбиение на чанки, эмбеддинги (кэшируются в Redis), сохранение в Qdrant и PostgreSQL (с `file_text`). 5. **OCR/транскрибация** → XMPP-бот → HTTP → RAG-сервер → распознанный текст. 6. **ReindexWorker** периодически проверяет документы с `indexed=False` и переиндексирует их, используя сохранённый `file_text`. 7. **ReAct** вызывает внешние API через ToolHandler (поиск, погода, бронирование, курс). ### 6.4. Тестирование Проект покрыт unit-тестами и интеграционными тестами. **Unit-тесты** (в `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`); - иерархическое резюмирование (`test_hierarchical_summarize.py`). **Интеграционные тесты** (в `tests/integration/`) проверяют: - эндпоинты RAG-сервера (`test_endpoints.py`) – `/rag/clear`, `/rag/list`, `/rag/delete_global`, `/rag/template/*`, `/rag/reset_history`, `/rag/room/*`, `/rag/stats`, `/rag/generate_document`. - переработанные команды бота (`test_commands.py`) – `!clear`, `!kb`, `!global_remove`, `!reset`, `!template_*`, `!stats`, `!status`, `!create`, `!summary`, `!metrics`, `!learn` и др. **Запуск всех тестов**: ```bash cd /usr/local/etc/fckbot source venv/bin/activate pytest tests/ -v ``` Для тестирования RAG-сервера отдельно можно использовать `curl` или Postman. ### 6.5. Конфигурационные параметры В `bot.conf` доступны следующие параметры RAG-пайплайна (добавлены новые): - **`max_context_tokens`** — лимит токенов для истории диалога (по умолчанию 3000). - **`rerank.min_length`** — порог длины контекста для переранжирования (по умолчанию 5000). - **`rag_server_url`** — URL RAG-сервера (используется ботами). - **`mention_keyword`** — ключевое слово для упоминания бота в группах. - **`fewshot`** — настройки few-shot примеров (`max_examples`, `examples_file`). #### Включение/отключение новых функций enable_soma: true enable_react: true enable_planning: true enable_agents: true enable_reindex: true #### Параметры SOMA soma_temperature: 0.1 soma_threshold: 3.5 soma_cache_ttl: 300 # TTL кэша SOMA (сек) soma_timeout: 30 #### Параметры ReAct react_temperature: 0.3 react_max_iterations: 5 #### Параметры планирования planning_temperature: 0.2 #### Параметры ReindexWorker reindex_interval: 300 # интервал проверки (сек) reindex_batch_size: 10 #### Параметры агентов agent_temperature: 0.3 #### API-ключи для инструментов weather_api_key: "" # для OpenWeatherMap #### Redis для кэширования redis_url: "redis://localhost:6379" #### Лимиты истории max_history_message_length: 10000 Эти параметры позволяют гибко настраивать поведение без изменения кода. ### 6.6. Основные слои (что есть что) | Слой | Назначение | | ---- | ---------- | | **RAG-сервер** (`rag_server.py`) | HTTP-сервис, обрабатывающий все RAG-запросы. Содержит оркестратор, ReindexWorker, ToolHandler. Предоставляет эндпоинты для команд бота, статистики, шаблонов, комнат. | | **RAG-оркестратор** (`rag_orchestrator.py`) | Фасад, координирующий менеджеры и модули. Содержит `HistoryManager`, `IntentRouter`, `QueryProcessor`, `IndexingManager`. | | **Менеджер истории** (`history_manager.py`) | Получение истории из БД, сжатие (иерархическое резюмирование), сохранение новых сообщений. Поддерживает пагинацию и обрезку сообщений. | | **Маршрутизатор намерений** (`intent_router.py`) | Обрабатывает специализированные намерения (METRICS, SUMMARY, CONTRADICTION, TEMPLATE_FILL, SURGICAL, GREETING, SPELLCHECK). | | **Процессор запросов** (`query_processor.py`) | Выполняет RAG-пайплайн с интеграцией SOMA, ReAct, планирования и агентов. Использует ToolHandler для вызова внешних инструментов. | | **Построитель промтов** (`prompt_builder.py`) | Динамический подбор few-shot, санитизация пользовательских данных, структура «сэндвич». | | **Менеджер индексации** (`indexing_manager.py`) | Сжимает большие документы, вызывает KBService. | | **HTTP-клиент** (`rag_client.py`) | Используется ботами для отправки запросов к RAG-серверу. Асинхронный, с повторными попытками. | | **Сервисы** (`services/`) | Долгоживущие компоненты: PostgreSQL, Qdrant, эмбеддинги, база знаний, файлы, GigaChat, переранжирование. | | **Функции** (`functions/`) | Чистые функции: классификация, расширение, суммаризация, проверка противоречий, самокритика, иерархическое резюмирование, SOMA, ReAct, планирование, генерация плана, инструменты. | | **XMPP-боты-клиенты** (`xmpp/client.py`) | Тонкие клиенты, только XMPP-логика и команды, все RAG-запросы через `rag_client.py`. | | **Обработчики XMPP** (`handlers/`) | Реагируют на события XMPP, маршрутизируют запросы. | | **Воркеры** (`workers/`) | Фоновые задачи: `indexing_worker` (индексация файлов и URL) и `reindex_worker` (переиндексация после сбоев). | | **Команды** (`commands/`) | Реализуют команды бота, используют только `RAGClient`. | | **Утилиты** (`utils/`) | Вспомогательные функции (конфигурация, логирование, чанкинг, веб-скрапинг, парсинг аргументов). | | **Alembic** (`alembic/`) | Управление версиями схемы PostgreSQL. | ## 7. Функции бота Ниже представлен полный перечень функций платформы Эфцекабот, доступных пользователям. Каждая функция описана максимально детально: указано, что она делает, в чем ее уникальность, какая от нее польза, а также приведены **все возможные сценарии использования** — от простых запросов до сложных рабочих процессов. ### Ранжирование по ценности | Место | Функция | Обоснование | | ----- | ------- | ----------- | | **1** | Генерация по шаблону | Основной инструмент для создания коробочных решений — автоматизирует производство документов. | | **2** | Гибридный RAG | Без него бот не может отвечать по документам — фундамент системы. | | **3** | Комнатные/глобальные БЗ | Обеспечивают коллективную работу над коробочными решениями. | | **4** | SOMA-анализ (LLM-as-judge) | Значительно повышает качество ответов, экономит токены за счёт кэширования. | | **5** | ReAct (вызов внешних инструментов) | Открывает возможность выполнения реальных действий (поиск, погода, бронирование). | | **6** | Планирование действий | Повышает точность расчётов и инструкций. | | **7** | Многоагентность | Позволяет специализировать ботов под разные роли, повышая качество экспертных ответов. | | **8** | Хирургическая замена | Ускоряет доработку документов. | | **9** | Проверка орфографии | Повышает качество исходящих документов. | | **10** | Суммаризация | Ускоряет анализ больших объемов информации. | | **11** | Самокритика | Повышает надежность ответов. | | **12** | Извлечение метрик | Автоматизирует сбор KPI. | | **13** | Проверка противоречий | Исключает ошибки в документации. | | **14** | Классификация намерений | Обеспечивает интеллектуальную маршрутизацию. | | **15** | Цепочка рассуждений | Повышает точность расчетов и инструкций. | | **16** | Полнотекстовый поиск | Гарантирует юридическую точность и поиск инструкций. | | **17** | Расширение запроса | Улучшает полноту поиска. | | **18** | Переранжирование | Экономит токены и повышает точность. | | **19** | Автоиндексация | Упрощает коллективную работу. | | **20** | Веб-скрапинг | Интегрирует внешние источники. | | **21** | Голосовые сообщения | Удобство для мобильных пользователей. | | **22** | Администрирование | Оперативный контроль без доступа к серверу. | ## 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. **Учет первичного источника** – если один источник явно первичен (например, официальный документ), это указывается в ответе. #### **10. SOMA-анализ (LLM-as-judge)** **Что делает**: После генерации ответа другой экземпляр LLM (или тот же, с другим системным промптом) оценивает ответ по пяти критериям: 1. **Релевантность** – насколько ответ соответствует вопросу. 2. **Полнота** – охвачены ли все аспекты вопроса. 3. **Отсутствие галлюцинаций** – факты подтверждены контекстом. 4. **Стиль и читаемость** – логичность, ясность, отсутствие излишней сложности. 5. **Полезность** – содержит ли ответ практические рекомендации или чёткие выводы. Каждый критерий оценивается по шкале от 1 до 5. Если средняя оценка ниже порога (по умолчанию 3.5), ответ перегенерируется (с повышенной температурой для разнообразия) и оценивается повторно. Если и повторная оценка неудовлетворительна, пользователю выводится предупреждение о неуверенности. **Результаты SOMA-оценок кэшируются** на 5 минут (TTL настраивается) на основе хеша `(query, context, answer)`, чтобы избежать повторных вызовов GigaChat для идентичных запросов. **Уникальность**: SOMA-анализ обеспечивает **автоматический контроль качества** без участия человека, что редко встречается в корпоративных RAG-ботах. Кэширование снижает затраты на токены. **Польза**: Повышает доверие к ответам, особенно в критических областях. Позволяет A/B-тестировать промпты и модели, так как SOMA даёт объективную метрику качества. **Примеры использования**: - Все обычные RAG-запросы (GENERAL, FACT, PROCEDURE, COMPARISON, CALCULATION) проходят SOMA-оценку (если включена). - При низкой оценке бот перегенерирует ответ, что особенно полезно для сложных расчётов и юридических вопросов. - Результаты SOMA могут использоваться для сбора статистики качества и оптимизации промптов. #### **11. ReAct (вызов внешних инструментов) – НОВОЕ!** **Что делает**: ReAct (Reasoning + Acting) — это итеративный цикл, в котором модель: 1. **Генерирует мысль** (обдумывает, что нужно сделать). 2. **Выбирает действие** (вызов внешнего инструмента). 3. **Наблюдает результат** (получает ответ от API). 4. **Повторяет** до тех пор, пока не будет готов финальный ответ. Доступные инструменты (реализованы в `ToolHandler`): - **Поиск в интернете** (DuckDuckGo Instant Answer API) – находит факты, новости, определения. - **Погода** (OpenWeatherMap API) – текущая погода в указанном городе (требуется API-ключ). - **Бронирование авиабилетов** (заглушка для демонстрации). - **Курс валют** (заглушка для демонстрации). ReAct автоматически активируется, если запрос содержит ключевые слова «найди», «поищи», «забронируй», «погода», «билеты», «курс» и т.д. (настраивается в `_needs_external_data`). **Уникальность**: Редкая возможность для корпоративных RAG-ботов — выполнять **реальные действия** через внешние API, а не только генерировать текст. Это превращает бота из пассивного информатора в активного помощника. **Польза**: - Быстрый доступ к актуальной информации из интернета. - Автоматизация поиска билетов, отелей, погоды. - Возможность расширения инструментов под любые корпоративные API (1С, SAP, календари). **Примеры использования**: 1. **Поиск информации**: - Запрос: «Найди последние новости о квантовых вычислениях» - Бот выполняет поиск через DuckDuckGo и возвращает краткую выжимку. 2. **Погода**: - Запрос: «Какая погода в Москве завтра?» - Бот вызывает OpenWeatherMap и возвращает прогноз. 3. **Бронирование** (заглушка): - Запрос: «Забронируй билет Москва-Сочи на 15 июля» - Бот имитирует бронирование, демонстрируя возможную интеграцию. 4. **Комбинированный сценарий**: - Запрос: «Найди информацию о достопримечательностях Парижа и какая там погода?» - Бот сначала ищет достопримечательности, затем погоду, объединяет ответы. #### **12. Планирование действий** **Что делает**: Для сложных запросов (расчёты, многошаговые инструкции) бот сначала генерирует **пошаговый план**, а затем последовательно выполняет каждый шаг. План содержит описание шага, необходимые данные и ожидаемый результат. Это повышает точность и логичность ответов. **Уникальность**: Планирование добавляет **метакогнитивный уровень** – модель обдумывает структуру ответа перед его генерацией, что улучшает качество для сложных задач. **Польза**: - Повышает точность расчётов и алгоритмов. - Улучшает структурированность ответов для инструкций. - Позволяет пользователю видеть логику решения. **Примеры использования**: 1. **Расчёт OEE**: - Запрос: «Рассчитай OEE для линии» - Бот генерирует план: 1) найти доступное время, 2) вычислить время простоев, 3) рассчитать производительность и качество, 4) вычислить OEE. Затем выполняет каждый шаг, показывая промежуточные результаты. 2. **Инструкция по внедрению 5S**: - Запрос: «Как внедрить 5S на производстве?» - Бот создаёт план из 5 этапов, затем последовательно описывает каждый. #### **13. Многоагентность** **Что делает**: В системе могут одновременно работать несколько специализированных агентов: - **Методолог** – экспертиза в стандартах, ГОСТах, методиках. - **Коробочник** – генерация коробочных решений, шаблонов. - **Персональный ассистент** – командировки, календарь, бронирование. Координатор (`AgentCoordinator`) автоматически выбирает подходящего агента на основе ключевых слов запроса. Например, если запрос содержит «методолог», «стандарт», «ГОСТ» — вызывается методолог. Агенты могут обмениваться сообщениями для решения сложных задач. **Уникальность**: Многоагентная архитектура позволяет **декомпозировать сложные задачи** между специализированными ИИ-ассистентами, что повышает качество и релевантность ответов. Это редкость для корпоративных RAG-ботов. **Польза**: - Каждый агент настроен на свою предметную область, использует соответствующие промпты. - Пользователь может задавать вопросы разной тематики одному боту, а маршрутизация будет автоматической. - Возможность расширения новыми агентами без изменения ядра. **Примеры использования**: 1. **Запрос к методологу**: - «Найди требования к описанию бизнес-процесса в ГОСТ Р ИСО 9001» → автоматически направляется агенту-методологу. 2. **Запрос к коробочнику**: - «Создай коробочное решение для библиотеки» → направляется агенту-коробочнику. 3. **Запрос к ассистенту**: - «Запланируй командировку в Казань на следующую неделю» → направляется агенту-ассистенту. 4. **Совместная работа агентов**: - Если запрос требует и методологии, и коробочного решения, координатор может организовать диалог между агентами. #### **14. Реальные инструменты (ToolHandler)** **Что делает**: `ToolHandler` предоставляет реальные обработчики для внешних API: - `search(query)` – поиск через DuckDuckGo Instant Answer API (без ключа). - `get_weather(city)` – погода через OpenWeatherMap API (требуется `weather_api_key`). - `book_flight(origin, destination, date)` – заглушка для демонстрации. - `get_exchange_rate(from_currency, to_currency)` – заглушка для демонстрации. Все инструменты асинхронны, используют `aiohttp`, имеют таймауты и обработку ошибок. **Уникальность**: Инструменты интегрированы в ReAct-цикл, что позволяет модели динамически решать, когда и какой инструмент вызывать. Это делает бота активным, а не пассивным. **Польза**: - Реализация реальных действий (поиск, погода) повышает практическую ценность. - Заглушки для бронирования и курсов демонстрируют возможности интеграции с любыми API. - Легко добавлять новые инструменты через расширение `ToolHandler`. **Примеры использования** (см. раздел ReAct). ## 7.4. Интеллектуальная маршрутизация и поиск ### **15. Классификация намерений** **Что делает**: Определяет тип запроса пользователя по ключевым словам и контексту. Поддерживает следующие коды намерений: `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` | ### **16. Цепочка рассуждений (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?» - Бот выдает последовательность шагов с пояснениями. ### **17. Полнотекстовый поиск по точным фрагментам и поиск инструкций (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» - Находит точный раздел и выдает инструкцию. ### **18. Расширение запроса (query expansion)** **Что делает**: Добавляет синонимы, аббревиатуры и связанные термины к исходному запросу для увеличения полноты поиска. Использует GigaChat для генерации до 10 дополнительных ключевых слов. Результаты кэшируются на 5 минут. **Уникальность**: Улучшает recall без участия пользователя. Автоматически подбирает термины, которые могут встречаться в документах. **Польза**: Помогает находить документы, даже если пользователь использует нестандартные термины или сокращения. **Примеры расширения**: | Исходный запрос | Расширенный запрос (пример) | |-----------------|-----------------------------| | «OEE» | «OEE общая эффективность оборудования производительность коэффициент использования» | | «время переналадки» | «время переналадки длительность смены инструмента SMED время простоя» | | «5S» | «5S сортировка соблюдение порядка сияние стандартизация совершенствование рабочее место» | | «Кайдзен» | «Кайдзен непрерывное улучшение малые шаги оптимизация процессов бережливое производство» | | «выработка на человека» | «выработка на человека производительность труда выработка на одного сотрудника ПТ» | | «расчет такта» | «расчет такта тактовое время Takt time формула такта время выпуска единицы» | ### **19. Переранжирование контекста (кросс-энкодер)** **Что делает**: После получения фрагментов из Qdrant, специализированная модель (кросс-энкодер) ранжирует их по релевантности запросу, отбрасывая шум. Используется локальная модель `intfloat/multilingual-e5-reranker`, что исключает затраты на токены и снижает задержку. **Уникальность**: Вместо дорогого вызова LLM используется легкий кросс-энкодер, работающий быстрее и дешевле. При этом качество ранжирования сравнимо с LLM. **Польза**: Уменьшает объем контекста, отправляемого в GigaChat, что экономит токены и улучшает точность ответа (убираются нерелевантные фрагменты). **Пример работы**: Запрос: «Какой OEE на линии А?» Qdrant вернул 30 фрагментов. Кросс-энкодер отбирает только те, где есть упоминания «OEE» и «линия А», отбрасывая фрагменты про другие линии или общие описания. В результате в GigaChat отправляется только релевантный контекст (обычно 5–10 лучших фрагментов). ## 7.5. Функции автоматизации и интеграции ### **20. Автоматическая индексация файлов в комнатах (без `!learn`)** **Что делает**: Любой файл (DOCX, PDF, XLSX, PPTX, изображение, аудио, архив), отправленный в групповой чат, автоматически индексируется в базу знаний комнаты. Не требуется включать режим обучения (`!learn`). Это работает «из коробки» для всех участников комнаты. **Уникальность**: Удобство для коллективной работы – не надо запоминать команды. Даже у Slack и Teams нет такой функции «из коробки». **Польза**: Быстрый старт для новых участников комнаты – они сразу могут задавать вопросы по документам, которые уже загружены. Автоматическое пополнение базы знаний без лишних действий. **Примеры использования**: 1. Пользователь отправляет в групповой чат файл «Регламент_отдела.docx» – бот автоматически индексирует его в комнатную БЗ, и все участники могут задавать по нему вопросы. 2. Новый сотрудник приходит в комнату – он сразу может спрашивать бота о документах, которые уже загружены, без необходимости отдельно загружать их. 3. В комнате с файлами по проекту каждый участник может добавлять новые версии документов, и бот автоматически обновляет индекс (при изменении хеша файла). 4. Если файл является архивом (ZIP, 7z), бот распаковывает его и индексирует все поддерживаемые форматы внутри. ### **21. Веб-скрапинг с рекурсивным обходом** **Что делает**: Бот может загрузить сайт по ссылке, рекурсивно обойти страницы (с ограничением глубины и количества) и проиндексировать их в базу знаний. Поддерживаются 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 (настраивается в конфиге). Это предотвращает перегрузку системы. ### **22. Поддержка голосовых сообщений (распознавание через SaluteSpeech)** **Что делает**: Аудиофайлы (.ogg, .wav, .mp3, .amr, .m4a) транскрибируются в текст через SaluteSpeech API. Полученный текст затем обрабатывается как обычный запрос (классификация, поиск, генерация ответа). Ответ отправляется текстом в чат. **Уникальность**: Редкость для RAG-ботов, удобно для мобильных клиентов. Не требует установки дополнительных приложений – работает с любым аудиофайлом. **Польза**: Можно «продиктовать» вопрос, не набирая текст. Удобно в дороге, в производственных условиях (где руки заняты) или для людей с ограниченными возможностями. **Примеры использования**: 1. Пользователь отправляет голосовое сообщение в личный чат боту (или в комнату). Бот распознает речь, превращает в текст, и если это вопрос – обрабатывает через RAG, отправляя ответ текстом (или голосом, если настроено дополнительно). 2. В мобильном клиенте (например, Conversations) пользователь нажимает кнопку записи голоса, говорит вопрос, бот отвечает в чат текстом. 3. Голосовое сообщение может содержать не только вопрос, но и команду (например, «!summary») – бот распознает и выполняет. 4. Поддерживаются длинные сообщения – транскрипция работает с учетом лимитов API. ### **23. Административные команды (`!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`, бот отправляет изображение на RAG-сервер (эндпоинт `/rag/vision`) для распознавания текста (OCR). Распознанный текст отправляется в чат. ### **Работа с таблицами в 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`. - **Полнотекстовый поиск по точным фрагментам** – поиск по номерам пунктов, кавычкам и инструкциям. - **Рефакторинг оркестратора** – `RAGOrchestrator` разбит на менеджеры (HistoryManager, IntentRouter, QueryProcessor, IndexingManager), что повышает тестируемость и сопровождаемость. - **Конфигурация на Pydantic** – вместо ручной загрузки используется `AppConfig` с валидацией и автодополнением. - **Аутентификация через API-ключ** – все эндпоинты RAG-сервера защищены заголовком `X-API-Key` (кроме `/health`). - **Автоматическая документация OpenAPI** – доступны Swagger UI (`/docs`) и ReDoc (`/redoc`), а также сырая спецификация (`/openapi.json`). - **Генерация API-ключа** – в `.env` добавлена переменная `RAG_API_KEY`. - **Динамические few-shot примеры** – подбор релевантных примеров на основе запроса и построение промта по структуре «сэндвич». - **SOMA-анализ (LLM-as-judge)** – автоматическая оценка качества ответов с перегенерацией при низких оценках. Результаты кэшируются (TTL 5 мин). - **ReAct (вызов внешних инструментов)** – модель может итеративно вызывать внешние API (поиск, погода, бронирование, курс). Реализованы реальные обработчики. - **Планирование действий** – генерация пошагового плана для сложных запросов (расчёты, инструкции). - **Многоагентная архитектура** – координатор и специализированные агенты (методолог, коробочник, персональный ассистент). - **Фоновый ReindexWorker** – автоматическая переиндексация документов с `indexed=False` (восстановление после сбоев). - **Улучшения безопасности** – экранирование путей (shlex.quote), санитизация пользовательского ввода (ChatML), ограничение CORS, rate limiting (slowapi), retry + circuit breaker для GigaChat. - **Кэширование эмбеддингов в Redis** – снижение нагрузки на GigaChat, экономия токенов. - **Пагинация и обрезка истории диалога** – защита от переполнения БД, ускорение запросов. - **Хранение исходного текста документов в PostgreSQL** (колонка `file_text`) – позволяет переиндексировать документы без потери данных. - **Миграции через Alembic** – управление схемой БД через версионные миграции. - **Интеграционные тесты** – покрытие новых эндпоинтов и команд. - **Структурированное JSON-логирование** – для централизованного сбора логов (ELK/Loki). ### 4.2. Планируемые улучшения - **Интеграция с системами документооборота (СЭД)** – бот сможет подписывать документы ЭЦП, отправлять их на регистрацию, отслеживать статусы. - **Прогнозная аналитика командировок** – бот будет предлагать оптимальные маршруты, экономить на билетах за счет предварительного бронирования. - **Агент-индексатор сетевых папок (SMB)** – бот сам сканирует общие каталоги и обновляет базу знаний. - **Кэширование результатов генерации** – для одинаковых запросов (с использованием хеша запроса и контекста) планируется внедрение кэширования (Redis) на уровне RAG-сервера. - **Сбор обратной связи** – команда `!feedback` для оценки качества ответов (лайки/дизлайки) и хранение оценок в БД. - **A/B-тестирование промптов** – возможность разделять пользователей на группы и применять разные версии промптов. - **Гибкие промты** – автоматический выбор краткой или расширенной версии промпта в зависимости от длины доступного контекстного окна. - **Команда `!style`** – изменение стиля ответов (кратко/подробно/по умолчанию). - **Подключение дополнительных клиентов** – Telegram, МАХ, без изменения ядра. --- # III. Описание модулей Платформа Эфцекабот построена по принципу **«тонкий клиент – толстый сервер»**. Вся RAG-логика вынесена в отдельный HTTP-сервис – **RAG-сервер**, который обслуживает все клиенты. Клиенты отправляют запросы на RAG-сервер через HTTP и не содержат RAG-логики. Все модули, описанные ниже, расположены в каталоге `rag/`. Часть из них работает на RAG-сервере, часть – в клиентах, часть является общими утилитами. ## 1. Модуль `rag_orchestrator.py` – оркестратор RAG-пайплайна **Назначение:** это **сердце платформы**. Модуль координирует все этапы обработки запроса через менеджеры: - `HistoryManager` – получение и сжатие истории. - `IntentRouter` – обработка специализированных намерений. - `QueryProcessor` – обычный RAG-пайплайн (поиск, генерация, критика). - `IndexingManager` – индексация документов с предварительным сжатием. **Добавлены новые параметры:** `tool_handler` для передачи реальных обработчиков инструментов в `QueryProcessor`. **Ключевые методы:** - `process_query()` – основной метод, выполняет полный цикл обработки запроса. - `index_document()` – индексация документа (вызывается из `/rag/index`). Перед индексацией применяет иерархическое резюмирование, если документ слишком большой. **Особенности:** - Не содержит состояния, использует переданные сервисы и промпты. - Поддерживает специализированные намерения: `METRICS`, `SUMMARY`, `CONTRADICTION`, `TEMPLATE_FILL`, `SPELLCHECK`, `SURGICAL`, `GREETING`. - Добавляет цепочку рассуждений (Chain-of-Thought) для `CALCULATION` и `PROCEDURE`. - Включает интеграцию SOMA, ReAct, планирования и агентов через `QueryProcessor`. ## 2. Модуль `rag_server.py` – HTTP-сервер (FastAPI) **Назначение:** предоставляет REST API для всех клиентов. Является точкой входа в платформу. **Эндпоинты** (добавлены новые): | Метод | Эндпоинт | Назначение | Требует аутентификации | |-------|----------|------------|------------------------| | POST | `/rag/query` | Выполнить RAG-запрос (история берется из БД) | Да | | POST | `/rag/index` | Проиндексировать документ | Да | | POST | `/rag/vision` | Распознать текст на изображении (OCR) | Да | | POST | `/rag/transcribe` | Транскрибировать аудио (SaluteSpeech) | Да | | POST | `/rag/clear` | Очистка БЗ (личной/комнатной/глобальной) | Да | | POST | `/rag/list` | Список документов | Да | | POST | `/rag/delete_global` | Удаление глобального документа | Да (админ) | | POST | `/rag/template/save` | Сохранить шаблон | Да | | POST | `/rag/template/list` | Список шаблонов комнаты | Да | | POST | `/rag/template/delete` | Удалить шаблон | Да | | POST | `/rag/reset_history` | Сброс истории диалога | Да | | POST | `/rag/room/add` | Добавить комнату | Да | | GET | `/rag/room/list` | Список комнат | Да | | POST | `/rag/stats` | Статистика | Да (админ) | | POST | `/rag/generate_document` | Генерация документа по шаблону | Да | | GET | `/health` | Проверка состояния сервера | Нет | | GET | `/metrics` | Метрики Prometheus | Нет | | GET | `/docs` | Swagger UI | Нет | | GET | `/redoc` | ReDoc | Нет | | GET | `/openapi.json` | OpenAPI-спецификация | Нет | **Место в архитектуре:** запускается как отдельный процесс (с помощью Uvicorn). Обслуживает все клиенты. Инициализирует все сервисы (БД, Qdrant, GigaChat) и создает экземпляр `RAGOrchestrator`. **Особенности:** - Использует Pydantic для валидации запросов и ответов. - Поддерживает CORS для возможности запросов с других доменов. - Имеет встроенный healthcheck для мониторинга. - Эндпоинты `/rag/vision` и `/rag/transcribe` используют `FileService` для обработки медиафайлов. - Аутентификация через API-ключ (`X-API-Key`). - Полная OpenAPI-документация с примерами и кодами ошибок. - Graceful shutdown (сигналы SIGTERM/SIGINT) с остановкой ReindexWorker и закрытием ToolHandler. - Расширенный `/health` с проверкой PostgreSQL и Qdrant. - Ограничение CORS через переменную окружения. - Метрики Prometheus (`/metrics`). - Структурированное JSON-логирование. - Гарантированное удаление временных файлов (`tempfile.TemporaryDirectory`). - Интеграция ReindexWorker, SOMA, ReAct, планирования, агентов, ToolHandler. ## 3. Модуль `rag_client.py` – HTTP-клиент для ботов **Назначение:** используется тонкими клиентами для отправки запросов к RAG-серверу. **Методы:** - `query()` – отправляет запрос на `/rag/query`. - `index_document()` – отправляет запрос на `/rag/index`. - `vision(file_path)` – отправляет изображение на `/rag/vision`. - `transcribe(file_path)` – отправляет аудио на `/rag/transcribe`. - `health_check()` – проверяет доступность сервера. - `clear()` – очистка БЗ. - `list_documents()` – список документов. - `delete_global()` – удаление глобального документа. - `template_save()`, `template_list()`, `template_delete()` – управление шаблонами. - `reset_history()` – сброс истории. - `add_room()`, `get_rooms()` – управление комнатами. - `get_stats()` – статистика. - `generate_document()` – генерация документа по шаблону. **Особенности:** - Асинхронный (aiohttp). - Поддерживает повторные попытки (retry) при сетевых ошибках. - Автоматически добавляет заголовок `X-API-Key`. - Не содержит бизнес-логики – только HTTP-вызовы. ## 4. Модуль `rag_api.py` – локальный API-интерфейс **Назначение:** прослойка (facade) между ботами и `RAGOrchestrator` для локального использования (без HTTP). Этот модуль опционален – в новой архитектуре предпочтительнее использовать `RAGClient`. **Место в архитектуре:** может использоваться для тестирования или в случае, если RAG-ядро запущено в том же процессе, что и клиент. ## 5. Модуль `prompt_builder.py` – построитель промтов **Назначение:** динамически подбирает релевантные few-shot примеры из файла `data/fewshot_examples.json` (или использует статические) и формирует промт по структуре «сэндвич» (важное в начале и в конце). Это улучшает качество ответов, особенно для сложных запросов. **Формат файла** `fewshot_examples.json`: ```json [ { "keywords": ["OEE", "эффективность"], "intents": ["PROCEDURE", "CALCULATION"], "question": "Как рассчитать OEE?", "answer": "OEE = Доступность × Производительность × Качество." } ] ``` - `keywords` – список ключевых слов для поиска релевантности. - `intents` – список намерений, для которых применим пример. - `question` – вопрос пользователя. - `answer` – эталонный ответ. **Место в архитектуре:** используется в `QueryProcessor` при синтезе ответа. **Добавлена санитизация пользовательских данных (`_sanitize`) для защиты от инъекций ChatML.** ## 6. Модули функций (каталог `functions/`) Все функции являются чистыми, без состояния. Добавлены новые: - **`soma_evaluate.py`** – SOMA-анализ (LLM-as-judge) с кэшированием. - **`react.py`** – цикл ReAct с улучшенным fallback-парсингом JSON. - **`plan_generation.py`** – генерация плана действий. - **`tools.py`** – реальные обработчики инструментов (поиск, погода, бронирование, курс). Обновлены: - `rerank_context.py` – использует асинхронную загрузку модели. - `critique_answer.py` – самокритика по 5 критериям (без изменений). ### 6.1. `intent_classify.py` – классификация намерений **Назначение:** определяет тип запроса пользователя (FACT, PROCEDURE, METRICS, SUMMARY, CONTRADICTION, SURGICAL, GREETING, GENERAL, SPELLCHECK, TEMPLATE_FILL) по тексту запроса. **Примеры в промпте перемешаны для уменьшения эффекта якорения.** **Место в архитектуре:** вызывается из `RAGOrchestrator` перед поиском. **Как работает:** отправляет промпт (`intent_classify.txt`) в GigaChat, получает один из кодов, кэширует результат на 5 минут. **Вход:** текст запроса, промпт, конфиг. **Выход:** код намерения (str) или `"GENERAL"`. ### 6.2. `expand_query.py` – расширение запроса **Назначение:** добавляет синонимы, аббревиатуры и связанные термины к исходному запросу для увеличения полноты поиска. **Место в архитектуре:** вызывается перед поиском в Qdrant. **Как работает:** отправляет промпт (`expand.txt`) в GigaChat, получает до 10 дополнительных ключевых слов, кэширует на 5 минут. **Вход:** текст запроса, промпт, конфиг. **Выход:** расширенный запрос (строка) или исходный, если расширение не удалось. ### 6.3. `extract_metrics.py` – извлечение метрик **Назначение:** извлекает числовые показатели (KPI, OEE, такт, выработку, проценты) из текста в структурированном виде (JSON). **Место в архитектуре:** вызывается при намерении `METRICS`. **Как работает:** отправляет промпт (`metrics_extract.txt`) в GigaChat, парсит JSON-ответ. При неудаче – fallback-парсинг строк вида `ключ: значение`. **Вход:** контекст (текст), промпт, конфиг. **Выход:** список словарей с полями `metric_name`, `value`, `unit`, `period`, `source_fragment`. ### 6.4. `summarize_document.py` – суммаризация документа **Назначение:** создает краткий пересказ документа (≤30% от оригинала) с выделением целей, выводов и ключевых цифр. **Место в архитектуре:** вызывается при намерении `SUMMARY`. **Как работает:** отправляет промпт (`smart_summary.txt`) в GigaChat, подставляя текст документа. **Вход:** текст, название, промпт, конфиг. **Выход:** строка с кратким изложением. ### 6.5. `hierarchical_summarize.py` – иерархическое резюмирование **Назначение:** сжимает очень большие тексты (документы, историю диалога) с помощью рекурсивного резюмирования блоков. Разбивает текст на блоки по предложениям, резюмирует каждый блок через GigaChat, объединяет результаты, и при необходимости повторяет процесс рекурсивно до достижения целевой длины. **Место в архитектуре:** вызывается из `RAGOrchestrator`: - В `process_query` – для сжатия длинной истории диалога. - В `index_document` – для сжатия больших документов перед индексацией (через метод `_compress_document_if_needed`). **Как работает:** использует промпт (`hierarchical_summary.txt`) для каждого блока. **Вход:** текст, целевой размер в токенах, размер блока, глубина. **Выход:** сжатый текст. ### 6.6. `check_consistency.py` – проверка противоречий **Назначение:** находит логические, числовые или терминологические расхождения в разных фрагментах текста. **Место в архитектуре:** вызывается при намерении `CONTRADICTION`. **Как работает:** отправляет промпт (`consistency_check.txt`) в GigaChat, получает ответ `[OK]` или `[CONFLICT]` с описанием. **Вход:** список фрагментов, запрос, промпт, конфиг. **Выход:** строка с результатом проверки. ### 6.7. `critique_answer.py` – самокритика ответа **Назначение:** оценивает качество сгенерированного ответа по пяти критериям (соответствие источнику, отсутствие галлюцинаций, стиль, логика, запрет внешних знаний). **Место в архитектуре:** вызывается после генерации ответа (если включена в конфиге). **Как работает:** отправляет промпт (`self_critique.txt`) в GigaChat, анализирует ответ на наличие `[OK]` или `[ISSUES]`. **Вход:** запрос, контекст, ответ, промпт, конфиг. **Выход:** `True` (ответ хороший) или `False` (есть замечания). ### 6.8. `rerank_context.py` – переранжирование контекста **Назначение:** отбирает только релевантные фрагменты из результатов поиска, отбрасывая шум. Использует локальный кросс-энкодер вместо LLM. **Место в архитектуре:** вызывается после поиска в Qdrant (если контекст длиннее `min_length`). **Как работает:** отправляет фрагменты в кросс-энкодер (`intfloat/multilingual-e5-reranker`), ранжирует и возвращает только топ-N фрагментов. **Вход:** запрос, контекст, конфиг. **Выход:** отфильтрованный контекст (строка). ### 6.9. `file_processor.py` – обработка файлов **Назначение:** отправка файлов пользователю через HTTP Upload (XEP-0363) и обработка тегов `[SURGICAL_REPLACE]`, `[REWRITE]`, `[FILE]` из ответа AI. **Место в архитектуре:** вызывается из клиентов (XMPP-ботов) и из RAG-пайплайна при наличии тегов. **Как работает:** парсит ответ AI, извлекает теги, вызывает методы `FileService` для замены или создания DOCX-файлов, отправляет результат через HTTP Upload. **Вход:** ответ AI, JID пользователя, путь к файлу. **Выход:** отправленный файл или сообщение об ошибке. ### 6.10. `generate_document.py` – генерация по шаблону **Назначение:** заполняет плейсхолдеры `{{название}}` в шаблоне документа на основе данных из базы знаний. **Место в архитектуре:** вызывается из команды `!create` (через RAG-сервер). **Как работает:** находит все плейсхолдеры, для каждого выполняет поиск в БЗ, генерирует значение через GigaChat, заменяет в копии шаблона. **Вход:** шаблон (DOCX), запрос пользователя, конфиг. **Выход:** готовый DOCX-файл. ## 7. Сервисы (каталог `services/`) Долгоживущие компоненты, которые инициализируются один раз при старте RAG-сервера и предоставляют API для работы с внешними системами. | Файл | Назначение | |------|------------| | `postgres_service.py` | Пул соединений с PostgreSQL. CRUD для документов, истории диалогов, комнат, шаблонов, прав доступа. Добавлена колонка `file_text`, проверка таблиц (Alembic), составные индексы для полнотекстового поиска, пагинация в get_history. | | `qdrant_service.py` | Векторная БД. Создание коллекции, гибридный поиск (dense + sparse), полнотекстовый поиск, удаление по `doc_id`. Сохранение `file_text` при индексации, метод `reindex_failed_documents()`. | | `embedding_service.py` | Эмбеддинги GigaChat. Одиночные/пакетные запросы, кэширование (`lru_cache`), обрезка текста до 800 символов. Внедрён Redis для кэширования эмбеддингов (с fallback на локальный кэш).| | `kb_service.py` | База знаний. Индексация документов (разбиение на чанки, получение эмбеддингов, сохранение в Qdrant и PostgreSQL), поиск, управление доступом. Транзакционная индексация с флагом `indexed`. | | `file_service.py` | Извлечение текста из файлов (DOCX, PDF, XLSX, PPTX, изображения, аудио, архивы). Хирургическая замена, создание DOCX. Используется на RAG-сервере для OCR и транскрибации. | | `giga_client.py` | Клиент GigaChat. Методы `chat()` и `upload_file()` – без бизнес-логики. Добавлены retry (tenacity) и circuit breaker (pybreaker). | | `reranker_service.py` | Кросс-энкодер для переранжирования (локально). Ленивая загрузка модели. Асинхронная загрузка модели с использованием `asyncio.Lock` и `asyncio.Event`. | | `file_service.py` | Экранирование путей (`shlex.quote`) в `transcribe_audio`. | | `web_utils.py` | Ограничение размера загружаемого контента в `fetch_any_url`. | ## 8. Обработчики, команды, воркеры (для XMPP-клиентов) Эти модули работают только на стороне **тонких клиентов** (XMPP-ботов) и не входят в RAG-сервер. **Команды** переписаны на использование `RAGClient`, удалены обращения к `kb`, `db`, `qdrant`. - **`room_handler.py`** – сохранение комнат на сервере через `rag_client.add_room()`, загрузка комнат при старте. - **`file_handler.py`** – гарантированное удаление временных файлов (`tempfile.TemporaryDirectory`). - **`client.py`** – загрузка комнат с сервера, периодическая очистка словарей `_last_file_path` и `last_file_texts`. - **`reindex_worker.py`** (новый) – фоновый воркер для переиндексации документов с `indexed=False`. ### 8.1. Обработчики (`handlers/`) | Файл | Назначение | |------|------------| | `metrics_handler.py` | Счетчики (сообщения, файлы, AI-запросы, ошибки). | | `message_handler.py` | Маршрутизация входящих сообщений (использует `RAGClient`). | | `file_handler.py` | Скачивание файлов и постановка в очередь индексации. Убраны прямые вызовы GigaChat – теперь все через RAGClient. | | `room_handler.py` | MUC комнаты (приглашения, вход, переподключение). | | `subscription_handler.py` | Подписки (roster subscription). | | `health_handler.py` | Очистка файлов, healthcheck БД/Qdrant (для клиентов). | ### 8.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` – удаление глобального документа (админ). | ### 8.3. Воркеры (`workers/`) | Файл | Назначение | |------|------------| | `indexing_worker.py` | Фоновый воркер, который обрабатывает очередь индексации файлов и URL, отправляя их на RAG-сервер через `RAGClient`. Обработка изображений и аудио теперь через RAG-сервер. | ## 9. Утилиты (каталог `utils/`) Вспомогательные функции, используемые как сервером, так и клиентами: | Файл | Назначение | |------|------------| | `config_loader.py` | Загрузка `rag.conf` и `bot.conf`, слияние, чтение `.env`, создание `AppConfig` с помощью Pydantic. | | `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). | - **`logger.py`** – добавлена поддержка JSON-логирования (параметр `json_format`). - **`web_utils.py`** – ограничение размера загружаемого контента. ## 10. Тесты (каталог `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` – проверка орфографии. - `test_hierarchical_summarize.py` – иерархическое резюмирование. Тесты используют `pytest` и `pytest-asyncio`, не требуют реального подключения к внешним сервисам (используются моки). Запуск: `pytest tests/ -v`. - **Unit-тесты** – без изменений. - **Интеграционные тесты** – добавлены `test_endpoints.py` и `test_commands.py` для проверки новых эндпоинтов и команд. ## 11. Конфигурационные файлы Платформа использует два основных конфигурационных файла: - **`rag.conf`** – общие настройки для всех ботов: параметры подключения к БД, Qdrant, GigaChat, настройки чанкинга, RAG, веб-скрапера, очистки, логирования. Добавлены параметры управления токенами и секция `summarization`. - **`bot.conf`** – настройки конкретного профиля бота (методолог, коробочник, персональный ассистент): JID, пароль, промпты, пути к данным, ключевые слова, администраторы, параметры функций (температура, лимиты). Переменные окружения (пароли, ключи API) хранятся в `.env`. Примеры конфигурации предоставлены в файлах `rag.conf.example`, `bot.conf.sample`, `env.example`. ## 12. Схема базы данных (PostgreSQL) Схема управляется через Alembic. Таблицы: - **`documents`** – добавлена колонка `file_text TEXT` для хранения исходного текста документа. - **`document_access`** – права доступа. - **`history`** – история диалогов. - **`rooms`** – список MUC-комнат. - **`room_templates`** – шаблоны. Индексы: добавлены составные индексы `(room_jid, source_name)` и `(owner_jid, source_name)` для ускорения полнотекстового поиска. --- # IV. Руководство по настройке аутентификации и доступу к API # IV. Руководство по настройке аутентификации и доступу к API ## 1. Генерация API-ключа Для защиты RAG-сервера используется API-ключ в заголовке `X-API-Key`. Сгенерировать ключ: ```bash python3 -c "import secrets; print(secrets.token_urlsafe(32))" ``` ## 2. Прописать ключ в переменные окружения В `.env` добавьте: ```env RAG_API_KEY=ваш_ключ ``` ## 3. Использование в Swagger UI Откройте `http://localhost:8080/docs`, нажмите **Authorize**, введите ключ. ## 4. Использование в боте В `client.py` `RAGClient` автоматически использует `config.rag_api_key`. ## 5. Миграции Alembic Для управления схемой БД используйте Alembic. Установите переменную окружения `FCKBOT_PROFILE_DIR` с путём к профилю бота, затем: ```bash alembic upgrade head ``` Для создания новой миграции: ```bash alembic revision --autogenerate -m "описание" ```