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 — централизованное хранилище метаданных документов, истории диалогов, прав доступа, списка комнат, шаблонов и оценок обратной связи.
   • Qdrant — векторная БД с двумя полями (dense, sparse) для гибридного поиска. Доступна только RAG-ядру.
   • GigaChat API — генерация текста и эмбеддингов. Вызовы осуществляются только из RAG-ядра, что позволяет централизованно управлять кэшированием и лимитами.

Философия:

• Каждый документ принадлежит контексту (личный, комнатный, глобальный).
• Боты-клиенты не имеют собственных знаний – они только передают запросы в RAG-ядро, которое отвечает строго по загруженным материалам (строгий RAG).
• Единая история диалога для каждого пользователя/комнаты хранится на сервере, что обеспечивает непрерывность контекста независимо от того, через какой интерфейс (XMPP, Telegram, веб) пользователь общается с системой.
• Встроен интеллектуальный маршрутизатор запросов (классификация намерений), экспертная подсистема (метрики, суммаризация, проверка противоречий, хирургическая замена) и самокритика ответов – все это реализовано в RAG-ядре и доступно всем клиентам.

Сервисы распределены по jails FreeBSD/Linux:

• rag-server (Python 3.11/3.12) — HTTP-сервис RAG-ядра.
• metabot, korobot, persobot — отдельные XMPP-клиенты (также на Python), которые общаются с RAG-ядром через HTTP.
• ejabberd, PostgreSQL, Qdrant — внешние системы.

3. Уникальность решения

1. Гибридный RAG (dense + sparse) с самокритикой и централизованным ядром — не используется в корпоративных ботах массово. Коммерческие решения часто ограничиваются простым семантическим поиском без переранжирования и самокритики. Вынесение RAG-логики в отдельный HTTP-сервис позволяет легко масштабировать и подключать любые клиентские интерфейсы.

2. Персональный ассистент как часть экосистемы — типичные персональные ассистенты не имеют доступа к внутренней базе знаний и не умеют отвечать на сложные вопросы по документам. Эфцекабот объединяет общие и персональные функции в едином RAG-ядре, при этом каждый бот-профиль использует свои промпты, что позволяет гибко настраивать поведение под конкретные задачи.

3. Единая чат-среда и единый RAG-бэкенд для всех коммуникаций — не требуется переключаться между десятками каналов (чат-боты в Telegram, веб-формы, почта). Весь документооборот, командировки, экспертные вопросы — в одном интерфейсе (корпоративном мессенджере), а при необходимости те же функции доступны через Telegram, или веб-интерфейс благодаря универсальному HTTP API RAG-ядра.

4. Полный контроль над данными — все компоненты развернуты внутри компании. Никакие документы или переписка не покидают периметр. История и документы хранятся только на серверах компании.

5. Открытая агентная архитектура — можно подключить любого RPA, внешнее API, 1С, SAP, календарь, тревел-агрегатор без необходимости переписывать ядро бота — достаточно реализовать HTTP-клиент к RAG-ядру. Конкуренты, как правило, предлагают закрытые экосистемы.

6. Автоматическая индексация файлов в комнатах — файл, попавший в групповой чат, автоматически становится доступен всей команде через RAG-ядро. Даже у Slack и Teams нет такой функции «из коробки».

4. Преимущества и недостатки работы бота в чате

Преимущества:

• Единое корпоративное окно — пользователь не переключается между приложениями, получает экспертные ответы прямо в рабочем чате.
• Мгновенный обмен файлами — встроен HTTP Upload, бот автоматически отправляет файлы в RAG-ядро для индексации (в т.ч. в групповых комнатах).
• Учет контекста беседы — история диалога хранится централизованно в RAG-ядре, что обеспечивает единый контекст для всех клиентов (XMPP, Telegram, веб).
• Поддержка комнат (MUC) — документы, загруженные в комнату, видны всем участникам, а переписка в комнате служит общим контекстом.
• Легковесные клиенты — боты не содержат сложной RAG-логики, что упрощает их обновление и развертывание; все изменения в RAG вносятся в одном месте — RAG-ядре.
• Не требует установки уникального клиентского ПО — достаточно любого XMPP-клиента (Fluux, Conversations, Gajim, Pidgin) или работать через web-интерфейс (который также может использовать RAG-ядро).
• Полный контроль данных — развертывание внутри периметра, никаких облачных сервисов.
• Поддерживаемые форматы: DOCX, PDF, XLSX, PPTX, TXT, CSV, JSON, изображения (OCR), аудио (SaluteSpeech), архивы ZIP/7z.
• Размер загружаемого файла: до 1 Гб.

Недостатки:

• Задержка — добавлен сетевой вызов от бота к RAG-ядру (1–2 мс внутри сети) и несколько вызовов GigaChat (3–10 секунд). Однако благодаря кэшированию (классификация, расширение, эмбеддинги) и локальному кросс-энкодеру итоговое время ответа в большинстве случаев составляет 3–7 секунд, что приемлемо для экспертной системы.
• Сложность отладки — распределенная система (RAG-ядро, боты-клиенты, ejabberd, PostgreSQL, Qdrant) усложняет трассировку ошибок, но централизованное логирование и единая точка входа (RAG-ядро) упрощают мониторинг.

5. Как чат-бот влияет на работу с GigaChat

Аспект	Влияние
Скорость	GigaChat – облачный API, задержка ~1–2 секунды на вызов. В текущей архитектуре все вызовы GigaChat происходят только из RAG-ядра (не из ботов). Пайплайн может делать 2–4 вызова на запрос (классификация, расширение, генерация, критика). Благодаря общему кэшированию (TTL 5 минут) для классификации и расширения, а также локальному кросс-энкодеру для переранжирования, количество вызовов GigaChat сокращено до минимума, что снижает итоговую задержку до 3–7 секунд.
Экономия токенов	Переранжирование и гибридный поиск (sparse + dense) уменьшают объём контекста. История диалога обрезается точно по токенам (через tiktoken) на стороне RAG-ядра, что позволяет эффективнее использовать контекстное окно. Дополнительно внедрено иерархическое резюмирование для сжатия длинных диалогов и документов, что ещё больше экономит токены. Централизация также позволяет агрегировать кэши и общие эмбеддинги, снижая общие затраты на токены.
Качество ответа	GigaChat хорошо понимает русский язык, отлично справляется с деловой и технической терминологией. Но без точного промпта и контекста возможны галлюцинации – самокритика и перегенерация, выполняемые в RAG-ядре, частично нивелируют это. Единые промпты для всех клиентов упрощают тонкую настройку качества. Иерархическое резюмирование помогает сохранить ключевую информацию в длинных документах.
Надежность	GigaChat имеет лимиты и может выдавать ошибки. RAG-ядро делает несколько попыток при эмбеддингах и генерации, а при отказе API возвращает сообщение о недоступности. Централизация позволяет реализовать единые политики повторных попыток и fallback. RAGClient устойчив к сетевым ошибкам (ClientConnectorError и др.)
Гибридные векторы	GigaChat генерирует только dense-эмбеддинги, sparse-векторы вычисляются через FastEmbed (Qdrant/bm25) локально на сервере RAG-ядра. Это разгружает GigaChat и не требует дополнительных API, а также позволяет использовать общий кэш эмбеддингов для всех клиентов.

6. Архитектура проекта

6.1. Общая архитектура

Платформа состоит из трех основных логических слоев:

┌──────────────────────────────────────────────────────────────────────┐
│                    ВНЕШНИЕ КЛИЕНТЫ (пользователи)                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  │
│  │  XMPP-боты  │  │  Telegram   │  │  Mastodon   │  │ Веб-интерф. │  │
│  │  (тонкие)   │  │  (клиент)   │  │  (клиент)   │  │  (клиент)   │  │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  │
│         │                │                │                │         │
│         └────────────────┼────────────────┼────────────────┘         │
│                          │                │                          │
│                          ▼                ▼                          │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │                    RAG-СЕРВЕР (HTTP API)                       │  │
│  │  POST /rag/query      – выполнить RAG-запрос                   │  │
│  │  POST /rag/index      – проиндексировать документ              │  │
│  │  POST /rag/vision     – распознать текст на изображении (OCR)  │  │
│  │  POST /rag/transcribe – транскрибировать аудио                 │  │
│  │  GET  /health         – проверить состояние                    │  │
│  │  GET  /docs           – Swagger UI (интерактивная документация)│  │
│  │  GET  /redoc          – ReDoc (альтернативная документация)    │  │
│  │  GET  /openapi.json   – OpenAPI-спецификация                   │  │
│  └────────────────────────────────────────────────────────────────┘  │
│                                   │                                  │
│                                   ▼                                  │
│  ┌────────────────────────────────────────────────────────────────┐  │
│  │                ВНЕШНИЕ СИСТЕМЫ (данные и API)                  │  │
│  │  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌───────────┐    │  │
│  │  │PostgreSQL │  │  Qdrant   │  │ GigaChat  │  │   Файлы   │    │  │
│  │  │(история,  │  │(векторный │  │ (генерация│  │ (DOCX,    │    │  │
│  │  │ документы,│  │  поиск)   │  │эмбеддинги)│  │  PDF и    │    │  │
│  │  │  права)   │  │           │  │           │  │  т.д.)    │    │  │
│  │  └───────────┘  └───────────┘  └───────────┘  └───────────┘    │  │
│  └────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────┘

Ключевые компоненты:

• RAG-сервер — единая точка входа для всех RAG-запросов. Содержит всю бизнес-логику (поиск, генерацию, самокритику, индексацию). Запускается как отдельный HTTP-сервис.
• Тонкие клиенты — боты-профили (XMPP, Telegram, Mastodon и т.д.), которые только передают запросы в RAG-сервер и не содержат RAG-логики.
• Внешние системы — PostgreSQL, Qdrant, GigaChat API — доступны только RAG-серверу.

6.2. Структура каталогов проекта

Проект организован по принципу разделения ответственности: RAG-сервер и боты-клиенты имеют свои независимые каталоги. Тесты вынесены в корень проекта.

/usr/local/etc/fckbot/ # КОРЕНЬ ПРОЕКТА
│
├── rag/                               # RAG-СЕРВЕР (HTTP-ядро)
│   ├── .env.example                   # Шаблон переменных окружения (пароли, ключи API)
│   ├── 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-запросов (поиск, синтез, критика)
│   ├── rag_api.py                     # Локальный API-интерфейс (facade) для вызова RAG-логики без HTTP
│   ├── rag.conf                       # Конфиг RAG-сервера (YAML): БД, Qdrant, GigaChat, чанкинг, RAG, HTTP-сервер
│   ├── rag_orchestrator.py            # Оркестратор RAG-пайплайна: фасад, координирующий менеджеры
│   ├── rag_server.py                  # HTTP-сервер на FastAPI + Uvicorn (точка входа RAG-ядра)
│   ├── README.md                      # Документация RAG-сервера (этот файл)
│   ├── requirements.txt               # Список зависимостей Python для всего проекта
│   ├── schema.sql                     # Схема PostgreSQL (единая БД для всех ботов)
│   ├── functions/                     # Чистые функции (без состояния)
│   │   ├── check_consistency.py       # Проверка логических/числовых/терминологических противоречий между фрагментами
│   │   ├── check_spelling.py          # Проверка орфографии и пунктуации с сохранением форматирования
│   │   ├── critique_answer.py         # Самокритика ответа по 5 критериям
│   │   ├── expand_query.py            # Расширение запроса (синонимы, аббревиатуры)
│   │   ├── extract_metrics.py         # Извлечение числовых показателей (KPI) в JSON
│   │   ├── file_processor.py          # Отправка файлов через HTTP Upload и обработка тегов [SURGICAL_REPLACE], [REWRITE], [FILE]
│   │   ├── generate_document.py       # Генерация документа по шаблону (заполнение плейсхолдеров {{...}})
│   │   ├── hierarchical_summarize.py  # Иерархическое резюмирование
│   │   ├── intent_classify.py         # Классификация намерений пользователя (FACT, PROCEDURE, METRICS и др.)
│   │   ├── rerank_context.py          # Переранжирование контекста через локальный кросс-энкодер
│   │   └── summarize_document.py      # Суммаризация документа (краткий пересказ ≤30%)
│   ├── services/                      # Сервисы (долгоживущие компоненты)
│   │   ├── embedding_service.py       # Эмбеддинги GigaChat (одиночные/пакетные запросы с кэшированием)
│   │   ├── file_service.py            # Извлечение текста из файлов (DOCX, PDF, XLSX, PPTX, изображения, аудио, архивы)
│   │   ├── giga_client.py             # Клиент GigaChat (chat, upload_file) – без бизнес-логики
│   │   ├── kb_service.py              # База знаний (индексация, поиск, управление доступом)
│   │   ├── postgres_service.py        # Пул соединений с PostgreSQL (CRUD для документов, истории, комнат, шаблонов)
│   │   ├── qdrant_service.py          # Векторная БД (создание коллекции, гибридный поиск, удаление)
│   │   └── reranker_service.py        # Кросс-энкодер для переранжирования (локально, модель intfloat/multilingual-e5-reranker)
│   └── utils/                         # Утилиты (без бизнес-логики)
│       ├── arg_parser.py              # Парсинг аргументов командной строки (--flag value)
│       ├── config_loader.py           # Загрузка rag.conf и bot.conf, слияние, чтение .env, создание AppConfig
│       ├── logger.py                  # Настройка логирования (уровни, вывод в файл и консоль)
│       ├── text_utils.py              # Разбиение текста на чанки (tiktoken + razdel), подсчёт токенов
│       └── web_utils.py               # Веб-скрапинг (fetch_any_url, crawl_url)
│
├── 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              # Шаблон синтеза ответа
│   │   └── 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                               # ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ
    ├── XMPP_PASSWORD=...              # Пароль для XMPP-аккаунта бота
    ├── DB_PASSWORD=...                # Пароль для PostgreSQL
    ├── GIGACHAT_API_KEY=...           # API-ключ GigaChat
    ├── SALUTE_SPEECH_AUTH=...         # Авторизация для SaluteSpeech (голосовые сообщения)
    └── RAG_API_KEY=...                # API-ключ для доступа к RAG-серверу (защита эндпоинтов)

Важные примечания:

• Реальные профили ботов (например, metabot/, korobot/, persobot/) создаются администратором вручную путем копирования template_bot_profile/ и размещаются вне репозитория (например, в /usr/local/etc/fckbot/profiles/).
• Все юнит-тесты находятся в корневом каталоге tests/, что упрощает их запуск и поддержку.
• Конфигурационные файлы (rag.conf, bot.conf) и переменные окружения (.env) не хранятся в репозитории и создаются отдельно.

6.3. Взаимодействие компонентов

┌─────────────┐      HTTP      ┌─────────────┐      SQL       ┌─────────────┐
│   Пользова- │ ──────────────▶│    RAG-     │ ──────────────▶│ PostgreSQL  │
│    тель     │                │   сервер    │                │  (история,  │
│   (XMPP)    │ ◀──────────────│   (ядро)    │ ◀──────────────│  документы) │
└─────────────┘                └─────────────┘                └─────────────┘
      │                               │                              │
      │ XMPP                          │ HTTP (gRPC)                  │
      ▼                               ▼                              ▼
┌─────────────┐                ┌─────────────┐                ┌─────────────┐
│  ejabberd   │                │   Qdrant    │                │  GigaChat   │
│ (чат-серв.) │                │ (векторная  │                │   (API)     │
└─────────────┘                │     БД)     │                └─────────────┘
      │                        └─────────────┘                       │
      │ XMPP                          │                              │
      ▼                               ▼                              ▼
┌─────────────┐                ┌─────────────┐                ┌─────────────┐
│  XMPP-бот   │                │ FastEmbed   │                │   Файлы     │
│  (тонкий)   │                │ (локальный  │                │   (диск)    │
│  клиент     │                │ кросс-энк.) │                └─────────────┘
└─────────────┘                └─────────────┘

Поток данных:

1. Запрос пользователя → XMPP-бот (ejabberd) → HTTP → RAG-сервер.
2. RAG-сервер получает историю из PostgreSQL, ищет в Qdrant, генерирует ответ через GigaChat, выполняет самокритику.
3. Ответ → HTTP → XMPP-бот → ejabberd → пользователь.
4. Индексация файла → XMPP-бот → файл → HTTP → RAG-сервер → Qdrant + PostgreSQL.
5. OCR/транскрибация → XMPP-бот → медиафайл → HTTP → RAG-сервер (эндпоинты /rag/vision и /rag/transcribe) → распознанный текст → пользователь.

6.4. Тестирование

Проект покрыт unit-тестами с использованием pytest и pytest-asyncio. Тесты находятся в корневом каталоге 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).

Запуск всех тестов:

cd /usr/local/etc/fckbot
source venv/bin/activate
pytest tests/ -v

Для тестирования RAG-сервера отдельно можно использовать curl или Postman для отправки запросов на эндпоинты.

6.5. Конфигурационные параметры

В rag.conf и bot.conf доступны следующие параметры RAG-пайплайна:

• max_context_tokens — лимит токенов для истории диалога (по умолчанию 3000). Используется точный подсчет через библиотеку tiktoken. Рекомендуемое значение: 2000–4000 токенов в зависимости от модели.
• rerank.min_length — порог длины контекста (в символах) для запуска переранжирования (по умолчанию 5000). Если контекст короче, переранжирование не выполняется, что экономит ресурсы.
• rag_server_url — URL RAG-сервера (используется ботами-клиентами). Пример: "http://localhost:8080".
• mention_keyword — ключевое слово, на которое бот реагирует в групповых чатах (в дополнение к упоминанию по JID и нику). Если параметр не указан, используется имя бота. Пример: mention_keyword: "методолог".
• fewshot – настройки динамических few-shot примеров:
  • max_examples: 3 – максимальное количество примеров, включаемых в промт.
  • examples_file: "data/fewshot_examples.json" – путь к файлу с примерами (относительно профиля).

Эти параметры позволяют настраивать поведение без изменения кода. Переопределение параметров из rag.conf в bot.conf дает гибкость для разных профилей.

6.6. Основные слои (что есть что)

Слой	Назначение
RAG-сервер (rag_server.py)	HTTP-сервис, обрабатывающий все RAG-запросы. Содержит оркестратор (RAGOrchestrator), который выполняет классификацию, поиск, генерацию и самокритику. Также предоставляет эндпоинты для OCR и транскрибации. Запускается как отдельный процесс. Доступен по HTTP всем клиентам.
RAG-оркестратор (rag_orchestrator.py)	Фасад, координирующий работу менеджеров: HistoryManager, IntentRouter, QueryProcessor, IndexingManager. Не зависит от XMPP.
Менеджер истории (history_manager.py)	Отвечает за получение истории из БД, её сжатие (иерархическое резюмирование) и сохранение новых сообщений.
Маршрутизатор намерений (intent_router.py)	Обрабатывает специализированные намерения (METRICS, SUMMARY, CONTRADICTION, TEMPLATE_FILL, SURGICAL, GREETING, SPELLCHECK) и возвращает готовый ответ.
Процессор запросов (query_processor.py)	Выполняет обычный RAG-пайплайн (расширение, поиск, переранжирование, синтез, критика) для GENERAL, FACT, PROCEDURE, COMPARISON, CALCULATION.
Построитель промтов (prompt_builder.py)	Динамический подбор few-shot примеров и формирование промта по принципу «сэндвича» (важное в начале и в конце).
Менеджер индексации (indexing_manager.py)	Сжимает большие документы перед индексацией и вызывает KBService.
HTTP-клиент (rag_client.py)	Используется ботами-клиентами для отправки запросов в RAG-сервер. Асинхронный, с повторными попытками. Содержит методы vision() и transcribe().
Сервисы (services/)	Долгоживущие компоненты, предоставляющие API для работы с внешними системами (PostgreSQL, Qdrant, GigaChat, файлы). Используются только RAG-сервером и оркестратором. Не содержат бизнес-логики.
Функции (functions/)	Независимые чистые функции, каждая решает одну конкретную задачу: классификация, расширение, суммаризация, проверка противоречий, самокритика, иерархическое резюмирование и т.д. Не имеют состояния, вызываются из оркестратора.
XMPP-боты-клиенты (xmpp/client.py)	Тонкие клиенты, подключающиеся к ejabberd. Содержат только XMPP-логику, команды и загрузку промптов. Все RAG-запросы отправляют в RAG-сервер через rag_client.py.
Обработчики XMPP (handlers/)	Реагируют на события XMPP (сообщения, приглашения, подписки). Маршрутизируют запросы: команды, файлы, AI-запросы (через RAG-клиент).
Воркеры (workers/)	Фоновые асинхронные задачи: индексация файлов и URL (через HTTP-запросы в RAG-сервер).
Команды (commands/)	Классы, реализующие команды бота (!help, !learn, !summary, !metrics и т.д.). Каждая команда — отдельный файл, наследуемый от Command.
Утилиты (utils/)	Вспомогательные функции без бизнес-логики: загрузка конфигурации, логирование, конвертер раскладки, разбиение текста на чанки, веб-скрапинг, парсинг аргументов.

7. Функции бота

Ниже представлен полный перечень функций платформы Эфцекабот, доступных пользователям. Каждая функция описана максимально детально: указано, что она делает, в чем ее уникальность, какая от нее польза, а также приведены все возможные сценарии использования — от простых запросов до сложных рабочих процессов.

Ранжирование по ценности

Место	Функция	Обоснование
🥇 1	Генерация по шаблону	Основной инструмент для создания коробочных решений — автоматизирует производство документов
🥈 2	Гибридный RAG	Без него бот не может отвечать по документам — фундамент системы
🥉 3	Комнатные/глобальные БЗ	Обеспечивают коллективную работу над коробочными решениями
4	Хирургическая замена	Ускоряет доработку документов, критично для подготовки финальных версий
5	Проверка орфографии	Повышает качество исходящих документов
6	Суммаризация	Ускоряет анализ больших объемов информации
7	Самокритика	Повышает надежность ответов в критических областях
8	Извлечение метрик	Автоматизирует сбор KPI
9	Проверка противоречий	Исключает ошибки в документации
10	Классификация намерений	Обеспечивает интеллектуальную маршрутизацию
11	Цепочка рассуждений	Повышает точность расчетов и инструкций
12	Полнотекстовый поиск	Гарантирует юридическую точность и поиск инструкций
13	Расширение запроса	Улучшает полноту поиска
14	Переранжирование	Экономит токены и повышает точность
15	Автоиндексация	Упрощает коллективную работу
16	Веб-скрапинг	Интегрирует внешние источники
17	Голосовые сообщения	Удобство для мобильных пользователей
18	Администрирование	Оперативный контроль без доступа к серверу

7.1. Ключевые функции для создания документов (коробочных решений)

🥇 1. Генерация коробочных решений по шаблону

Что делает:
По команде !create "Коробочное решение" бот генерирует готовый коробочный документ на основе шаблона, заполняя все плейсхолдеры {{...}} данными из базы знаний комнаты. Шаблон содержит следующие разделы (соответствует файлу Шаблон коробочного решения.docx):

1. Профиль коробочного решения — параметры внедрения, ресурсы, сроки.
2. Актуальность коробочного решения — потенциал повышения производительности, задачи, ожидаемые результаты.
3. Решаемая проблема — типовой процесс (до улучшения), проблемные зоны, коренные причины.
4. Решение — целевой процесс (после улучшения), детальное описание решений, результаты внедрения.
5. Алгоритм внедрения коробочного решения — состав рабочей группы, последовательность этапов.
6. Риски — описание рисков и мер по их снижению.
7. Термины, сокращения, определения — глоссарий из документов комнаты.
8. Сопроводительные документы — перечень приложений, шаблонов, регламентов.
9. Лучшие практики — ссылки на реализованные аналогичные решения.

Уникальность:
Превращает бота из информатора в инструмент производства готовых коробочных решений. Достаточно один раз настроить шаблон, и бот будет генерировать документы на основе актуальных данных из базы знаний. Все, что требуется от пользователя — загрузить в комнату документы-источники (регламенты, отчеты, методики, ГОСТы, аналитические записки).

Польза:
Автоматизация подготовки коробочных решений, сокращение времени на создание документов с 1-2 недель до 10-30 минут, исключение ошибок ручного ввода, единообразие документов, возможность быстрого масштабирования на любые типы организаций.

Примеры использования (все возможные сценарии):

1.1. Сохранение шаблона коробочного решения

Загружаете в чат DOCX-файл Шаблон коробочного решения.docx (содержит плейсхолдеры вида {{DOC_CODE}}, {{TARGET_ORG_TYPES}} и т.д.). Вводите:

!template_save "Коробочное решение v1.0"

Бот сохраняет шаблон в БД комнаты как "Коробочное решение v1.0". Если шаблон с таким именем уже существует – он перезаписывается.

1.2. Просмотр всех шаблонов в комнате

!template_list

Бот выводит список: «Коробочное решение v1.0», «Коробочное решение v2.0», «Договор поставки» и т.д.

1.3. Генерация коробочного решения

Вы вводите:

!create "Коробочное решение v1.0"

Бот выполняет следующие шаги:

1. Извлекает шаблон из БД комнаты.

2. Находит все плейсхолдеры в шаблоне (их около 70+):

   • Профиль: {{DOC_CODE}}, {{TARGET_ORG_TYPES}}, {{TARGET_ORG_COUNT}}, {{FINANCIAL_RESOURCES}}, {{HUMAN_RESOURCES}}, {{IMPLEMENTATION_TERM_MIN}}, {{KPI_NAME}}, {{KPI_BEFORE}}, {{KPI_AFTER}} и т.д.
   • Актуальность: {{PROCESS_NAME}}, {{DATA_DATE}}, {{TOTAL_STAFF}}, {{TYPICAL_PROBLEM_DESCRIPTION}}, {{PREREQUISITE_1}}, {{TASK_1}}, {{RESULT_1}} и т.д.
   • Решаемая проблема: {{STAGE_1_NAME}}, {{STAGE_1_ACTORS}}, {{STAGE_1_PROBLEMS}}, {{ROOT_CAUSE_1}} и т.д.
   • Решение: {{TARGET_STAGE_1_DESC}}, {{IMPROVEMENT_1}}, {{SOLUTION_1_NAME}}, {{SOLUTION_1_DESCRIPTION}}, {{KPI_1_NAME}} и т.д.
   • Алгоритм внедрения: {{ROLE_1}}, {{ROLE_1_DUTIES}}, {{STAGE1_DURATION}}, {{STAGE1_ACTIONS}} и т.д.
   • Риски: {{RISK_1_NAME}}, {{RISK_1_DESCRIPTION}}, {{RISK_1_MITIGATION}}.
   • Термины: {{TERM_1}}, {{TERM_1_DEF}}.
   • Сопроводительные документы: {{APPENDIX_1_NAME}}.
   • Лучшие практики: {{BEST_PRACTICE_1_LINK}}, {{BEST_PRACTICE_1_DESC}}.

3. Для каждого плейсхолдера выполняет поиск в базе знаний комнаты (личные + комнатные + глобальные документы). Поиск использует:

   • Семантический поиск (dense-эмбеддинги) — для общих запросов.
   • Полнотекстовый поиск (MatchText) — для точных цитат и номеров пунктов.
   • Расширение запроса (query expansion) — добавляет синонимы и аббревиатуры.
   • Переранжирование (кросс-энкодер) — отбирает только релевантные фрагменты.

4. Формирует промпт для GigaChat с инструкцией заполнить плейсхолдер на основе найденных фрагментов. Промпт содержит контекст из фрагментов документов и сам плейсхолдер.

5. Генерирует значение для каждого плейсхолдера — например, для {{TYPICAL_PROBLEM_DESCRIPTION}} GigaChat напишет: «В региональной системе наблюдается дефицит сотрудников с профильным образованием (только 30% из 100), нерегулярное планирование, отсутствие единой методики оценки компетенций».

6. Заменяет плейсхолдеры в копии шаблона, сохраняя все форматирование (жирный шрифт, курсив, цвета, таблицы, колонтитулы). Замена выполняется с учетом возможного разбиения текста на несколько runs в DOCX, что повышает точность.

7. Отправляет готовый DOCX-файл в чат.

Пример заполнения (фрагменты):

**{{DOC_CODE}}** → **КР-5S-2025-001**
**{{TARGET_ORG_TYPES}}** → «Библиотеки, культурно-досуговые учреждения»
**{{TARGET_ORG_COUNT}}** → «47»
**{{FINANCIAL_RESOURCES}}** → «1 200»
**{{HUMAN_RESOURCES}}** → «5»
**{{IMPLEMENTATION_TERM_MIN}}** → «3»
**{{KPI_NAME}}** → «Процент сотрудников с профильным образованием»
**{{KPI_BEFORE}}** → «30%»
**{{KPI_AFTER}}** → «85%»

1.4. Обновление коробочного решения

Если вы улучшили шаблон или изменили структуру, загружаете новую версию DOCX и повторяете:

!template_save "Коробочное решение v1.0"

Старый шаблон перезаписывается новым. Все последующие генерации будут использовать обновленный шаблон.

1.5. Удаление шаблона

!template_delete "Коробочное решение v1.0"

Шаблон удаляется из БД комнаты.

1.6. Кастомизация шаблона под конкретный проект

Вы можете создать несколько версий шаблона для разных типов организаций или отраслей:

!template_save "Коробочное решение_Библиотеки"
!template_save "Коробочное решение_Музеи"
!template_save "Коробочное решение_Образование"

Затем генерировать нужную версию:

!create "Коробочное решение_Библиотеки"

1.7. Использование общих знаний (если разрешено)

Если для какого-то плейсхолдера не нашлось данных в БЗ (например, {{BEST_PRACTICE_1_LINK}}), бот может использовать свои общие знания для заполнения (если в конфиге allow_public_knowledge: true). Это полезно для лучших практик и терминов.

1.8. Многоязычность

Если в документах есть информация на иностранном языке, бот переведет ее на язык шаблона (русский) и заполнит плейсхолдер.

Пример: плейсхолдер {{KPI_NAME}} – бот найдет в английских документах «Overall Equipment Effectiveness» и переведет как «Общая эффективность оборудования» (или оставит аббревиатуру OEE, если так указано в документах).

🥈 2. Гибридный RAG с самокритикой

Что делает:
Это ядро системы, которое используется для поиска данных для каждого плейсхолдера шаблона. Бот выполняет:

• Семантический поиск (dense-эмбеддинги от GigaChat).
• Ключевой поиск (sparse-векторы BM25 от FastEmbed).
• Объединение через Reciprocal Rank Fusion (RRF).
• Генерацию ответа через GigaChat.
• Проверку через самокритику (оценка по 5 критериям).
• Перегенерацию при необходимости.

Уникальность:
Комбинация двух типов поиска + самокритика – это значительно повышает точность и доверие к ответам. Редкая функция для корпоративных ботов.

Польза:
Гарантирует, что ответ или каждое значение в коробочном решении основано на реальных документах, а не на выдумках LLM. Это критично для юридической и финансовой достоверности. Это фундамент, без которого остальные функции теряют смысл.

Примеры использования:

1. Фактологический вопрос (FACT):

   • «Какое тактовое время установлено на линии сборки?»
   • Бот ищет в документах (регламент линии, паспорт оборудования) и выдает точное значение с указанием источника:
     Тактовое время на линии сборки составляет 120 секунд. [Источник: Регламент_линии_2025.docx]

2. Инструкция / процедура (PROCEDURE):

   • «Как рассчитать OEE для станка?»
   • Бот находит алгоритм расчета в методических документах и выдает пошаговое руководство (с цепочкой рассуждений).

3. Сравнение показателей (COMPARISON):

   • «Сравни производительность труда до и после внедрения кайдзен»
   • Бот находит данные в отчетах (по периодам) и выдает сравнительный анализ с цифрами.

4. Расчет по формуле (CALCULATION):

   • «Рассчитай ожидаемую выработку на следующую смену при загрузке 120%»
   • Бот использует формулу из документов, выполняет расчет (пошагово) и выдает результат.

5. Поиск по юридически значимым пунктам:

   • «Выведи пункт 3.2.1 из договора №123»
   • Бот переключается на точный подстроковый поиск (см. пункт 12) и выдает цитату.

6. Общий вопрос (GENERAL):

   • «О чем этот документ?»
   • Бот дает краткое описание на основе содержания (если есть контекст).

7. Приветствие (GREETING):

   • «Привет» – бот отвечает вежливо, без поиска.

Примеры использования для коробочных решений:

1. Поиск KPI по ключевым словам:

   • Для плейсхолдера {{KPI_NAME}} бот ищет в документах упоминания показателей: «OEE», «процент брака», «выработка на человека».
   • Находит в отчетах: «Процент сотрудников с профильным образованием».
   • Возвращает точное название.

2. Поиск числовых значений:

   • Для {{KPI_BEFORE}} и {{KPI_AFTER}} бот находит в документах цифры: «в 2024 году – 30%», «целевой показатель – 85%».
   • Возвращает числа.

3. Поиск корневых причин проблем:

   • Для {{ROOT_CAUSE_1}} бот анализирует документы и выделяет ключевые проблемы: «дефицит кадров», «отсутствие регламентов», «нерегулярное планирование».

4. Поиск постановки задач:

   • Для {{TASK_1}} бот находит в стратегических документах перечень задач: «разработать стандарт», «обучить персонал», «внедрить систему мониторинга».

🥉 3. Комнатные и глобальные базы знаний

Что делает:
Документы могут быть трех типов:

• Личные – видны только владельцу (загружаются в личном чате без флагов).
• Комнатные – доступны всем участникам комнаты (автоматически при загрузке в групповой чат).
• Глобальные – доступны всем пользователям (загружаются администратором с флагом --global в личном чате).

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

Уникальность:
Позволяет естественно разграничивать доступ и организовывать коллективную работу. Редко встречается в RAG-ботах.

Польза:
Юридические документы для всех сотрудников (глобальные), конфиденциальные отчеты для отдела (комнатные), личные заметки – все в одном боте. Команда может совместно разрабатывать шаблоны и коробочные решения.

Примеры использования:

1. Личная БЗ:

   • В личном чате с ботом загружаете файл (например, личный план работы). Бот индексирует его как личный – доступен только вам.

2. Комнатная БЗ:

   • В групповом чате загружаете файл (регламент отдела). Бот автоматически индексирует его в комнатную БЗ – доступен всем участникам комнаты.

3. Глобальная БЗ:

   • Администратор в личном чате вводит:
     !learn --global
     Затем отправляет файл (или ссылку). Бот индексирует документ как глобальный – доступен всем пользователям во всех контекстах.

4. Просмотр доступных документов:

   • !kb – в личном чате покажет список личных + глобальных документов.
   • !kb в комнате – покажет комнатные + глобальные документы.

5. Очистка БЗ:

   • !clear – в личном чате очищает личную БЗ.
   • !clear в комнате (только админ) – очищает комнатную БЗ.
   • !global_clear (админ, личный чат) – очищает глобальную БЗ.

6. Удаление конкретного глобального документа (админ):

   • !global_remove "Название документа" – удаляет документ из глобальной БЗ по точному названию.

7.2. Функции работы с документами

4. «Хирургическая» (точечная) замена текста в DOCX

Что делает:
По запросу «замени старое слово на новое» бот выполняет умную замену с учетом грамматических форм (падежи, числа, роды) без потери форматирования. Поддерживает замену словоформ (например, «учеников» → «строителей»). Работает только с DOCX, использует морфологический анализатор mawo-pymorphy3.

Уникальность:
Очень редкая функция для RAG-систем; превращает бота из информатора в инструмент редактирования документов.

Польза:
Автоматизация рутинных правок в отчетах, договорах, планах. Снижение человеческих ошибок. Экономия времени на переделку документов.

Примеры использования (все возможные сценарии):

1. Простая замена:

   • Загружаете DOCX, затем вводите:
     Замени ООО "Ромашка" на ООО "Тюльпан"
   • Бот заменяет все вхождения во всех падежах (ООО "Ромашка", "Ромашке", "Ромашку" и т.д.) и возвращает исправленный файл.

2. Замена с морфологией:

   • Замени учеников на строителей
   • Бот заменит «ученик», «ученика», «ученикам», «учениками» и т.д. на соответствующие формы «строитель», «строителя», «строителям», «строителями» и т.д.

3. Замена дат или чисел:

   • Замени 2024 на 2025
   • Заменит все цифры 2024 (в том числе в тексте и таблицах) на 2025.

4. Множественные замены – можно загрузить файл и выполнить несколько команд подряд, бот будет применять их последовательно (каждая команда работает с последним измененным файлом).

5. Замена в таблицах и колонтитулах – замены выполняются во всех элементах документа, включая таблицы, сноски, колонтитулы и надписи.

6. Сохранение форматирования – замены выполняются без потери жирного шрифта, курсива, подчеркивания, цветов, размеров шрифта, выравнивания.

7. Работа с архивами – если загружен ZIP-архив, бот распаковывает его, выполняет замену во всех DOCX-файлах внутри и упаковывает обратно (если включена поддержка архивов).

5. Проверка орфографии

Что делает:
Пользователь загружает DOCX, затем пишет «Проверь орфографию» или «Найди ошибки». Бот разбивает текст на чанки (учитывая токены), отправляет каждый чанк в GigaChat с промптом на исправление ошибок. Исправления применяются с сохранением форматирования. Возвращает исправленный файл и список изменений в виде «было → стало».

Уникальность:
Автоматическое исправление ошибок в готовых документах без ручной правки. Поддерживает сложные случаи русского языка (благодаря использованию razdel для разбиения на предложения).

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

Примеры использования:

1. Базовая проверка:

   • Загружаете DOCX, пишете:
     Проверь орфографию
   • Бот возвращает исправленный файл и список всех исправлений:
     было «пашол» → стало «пошел»
было «молоко хлеб» → стало «молоко, хлеб»

2. Альтернативные команды:

   • Найди ошибки в документе
   • Исправь ошибки
   • Проверь грамматику
   • Работают аналогично.

3. Проверка с сохранением стиля – бот исправляет только орфографические и пунктуационные ошибки, не меняет структуру предложений, не заменяет синонимы, не улучшает стилистику (это сделано намеренно, чтобы сохранить авторский стиль).

4. Обработка ошибок парсинга – если GigaChat не смог сформировать список изменений в требуемом формате ([CHANGES]...[/CHANGES]), бот покажет сырой ответ модели, чтобы исправления не потерялись, и предложит проверить вручную.

5. Работа с большими документами – текст разбивается на чанки (по токенам) и обрабатывается последовательно, что позволяет проверять документы любого размера.

6. Только в личном чате – проверка орфографии доступна только в личном чате с ботом (для безопасности и предотвращения спама в комнатах).

6. Суммаризация документа

Что делает:
Создает краткий пересказ (≤30% от оригинала) с выделением целей, выводов и ключевых цифр. Использует промпт, который фокусируется на наиболее важных аспектах документа.

Уникальность:
Не просто сжатие, а интеллектуальное выделение самой важной информации на основе промпта (а не просто первые предложения).

Польза:
Быстрое ознакомление с объемными регламентами, отчетами, ГОСТами. Ускоряет анализ больших документов при разработке коробочных решений.

Примеры использования:

1. Суммаризация последнего загруженного файла:

   • !summary
   • Бот выдает краткое изложение документа (не более 30% объема) с выделением цели, выводов и ключевых цифр. В конце обязательно указывается источник.

2. Автоматическая суммаризация при намерении SUMMARY – если пользователь спросит «Сделай суммаризацию документа», классификатор распознает это намерение и вызовет функцию автоматически (без команды !summary).

3. Фокус на числовых показателях – если в документе есть OEE, такт, выработка, проценты, они выделяются в отдельный раздел.

4. Быстрое ознакомление – можно использовать для регламентов, ГОСТов, длинных отчетов, чтобы понять суть за 1–2 минуты.

5. Ограничение длины – если документ длиннее max_chars (по умолчанию 8000 символов), он обрезается по границам предложений (с использованием razdel), чтобы суммаризация была по полному тексту.

7.3. Функции анализа и качества

7. Самокритика ответа с перегенерацией

Что делает:
После генерации ответа другой экземпляр LLM оценивает его по пяти критериям:

1. Соответствие источнику – все ли факты подтверждаются контекстом.
2. Отсутствие галлюцинаций – нет ли информации, отсутствующей в контексте.
3. Соблюдение стиля и форматирования (нет LaTeX, есть источники, правильные списки).
4. Логическая связность – ответ не противоречит сам себе.
5. Запрет внешних знаний – не используются личные знания модели (если allow_public_knowledge = false).

При неудовлетворительной оценке ответ перегенерируется один раз. Если и после перегенерации неудовлетворительно, выдается сообщение о неуверенности.

Уникальность:
Редкий механизм самоконтроля, повышающий доверие к боту. Работает как «человек проверяет себя».

Польза:
Снижает вероятность ошибочного ответа, особенно в критических областях (юриспруденция, финансы, медицина, нормативная документация).

Примеры использования:

1. Обычный запрос – самокритика работает в фоновом режиме. Если ответ не проходит проверку, бот перегенерирует его один раз. Если и после перегенерации неудовлетворительно, выдается сообщение:
   «⚠️ Извините, я не уверен в точности ответа. Проверьте данные.»

2. Отключение самокритики – если в конфиге bot.conf установить enable_self_critique: false, она отключается для увеличения скорости (полезно для тестирования или простых запросов).

3. Влияет только на обычные RAG-запросы – для экспертных функций (METRICS, SUMMARY, CONTRADICTION) самокритика не применяется, так как их ответы уже структурированы и проверены на уровне функций.

4. Перегенерация с тем же контекстом – при перегенерации используется тот же контекст, что и при первом ответе, чтобы не потерять релевантность.

8. Извлечение метрик (KPI) из документов

Что делает:
Анализирует базу знаний, находит числовые показатели (OEE, тактовое время, выработку, проценты, суммы, количества) и выдает в структурированном виде (JSON или маркированный список). Использует промпт, который заставляет LLM выделять только явно указанные числа/значения, без додумывания.

Уникальность:
Команда !metrics работает без предварительной разметки данных – LLM сама выделяет показатели. Не требуется специальных тегов или шаблонов.

Польза:
Быстрый анализ эффективности, контроль KPI по всем документам компании. Автоматизация сбора показателей для отчетности.

Примеры использования:

1. Извлечение всех KPI из базы знаний:

   • !metrics
   • Бот ищет все документы (личные + глобальные или комнатные + глобальные) и выдает список метрик:
     - OEE линии: 85,2% (первый квартал 2025)
- Тактовое время на сборке: 120 сек
- Выработка на одного рабочего: 450 деталей в смену
- Время переналадки: 35 мин
- Процент брака: 2,1%

2. Автоматический ответ на намерение METRICS – если пользователь спросит:
   «Выведи все KPI из отчета» или «Покажи показатели эффективности», классификатор распознает намерение и вызовет функцию автоматически.

3. Кэширование – для команды !metrics результат кэшируется на 5 минут, что ускоряет повторные запросы (полезно для частого мониторинга).

4. Ограничение количества – выводится не более 20 метрик, чтобы не перегружать ответ.

5. Указание источника – каждая метрика сопровождается фрагментом источника (первые 100 символов), чтобы можно было проверить оригинал.

9. Проверка противоречий между документами

Что делает:
Находит логические, числовые или терминологические расхождения в разных фрагментах базы знаний. Сравнивает факты, цифры, даты, определения. Возвращает структурированный ответ: [OK] если противоречий нет, или [CONFLICT] с описанием каждого расхождения и предполагаемой причиной.

Уникальность:
Помогает аудиторам и аналитикам обнаруживать конфликты данных. Автоматизирует процесс верификации документации.

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

Примеры использования:

1. Проверка противоречий в OEE:

   • «Есть ли противоречия в расчете OEE?»
   • Бот ищет все фрагменты с упоминанием OEE и сравнивает цифры. Если в одном документе 85%, а в другом 90%, выдает предупреждение:
     [CONFLICT] В фрагменте 1 указано 85%, в фрагменте 2 – 90%. Предполагаемая причина: разные источники или разные периоды.

2. Проверка сроков:

   • «Проверь, нет ли противоречий в сроках реализации проекта»
   • Находит все даты в документах и сравнивает их.

3. Сравнение терминов:

   • «Есть ли противоречия в определении понятия "цикл производства"?»
   • Находит все определения и проверяет их на согласованность.

4. Ограничение фрагментов – для экономии токенов проверяются только первые max_fragments (по умолчанию 5) наиболее релевантных фрагментов.

5. Учет первичного источника – если один источник явно первичен (например, официальный документ), это указывается в ответе.

7.4. Интеллектуальная маршрутизация и поиск

10. Классификация намерений

Что делает:
Определяет тип запроса пользователя по ключевым словам и контексту. Поддерживает следующие коды намерений: FACT, PROCEDURE, COMPARISON, CALCULATION, SURGICAL, METRICS, SUMMARY, CONTRADICTION, GREETING, GENERAL, SPELLCHECK, TEMPLATE_FILL. Выбирает соответствующую стратегию обработки. Результаты классификации кэшируются на 5 минут для ускорения повторных запросов.

Уникальность:
Не все RAG-боты имеют интеллектуальную маршрутизацию. Кэширование дополнительно повышает отзывчивость.

Польза:
Экономия токенов, времени и повышение точности ответов за счет выбора специализированной стратегии.

Примеры работы (как классификатор определяет тип запроса):

| Запрос пользователя | Распознанное намерение | ||| | «Какое тактовое время установлено на линии?» | FACT | | «Как рассчитать OEE?» | PROCEDURE | | «Сравни показатели производительности до и после кайдзен» | COMPARISON | | «Замени 5000 на 6000 в плане производства» | SURGICAL | | «Выведи все KPI из отчета» | METRICS | | «Сделай суммаризацию документа» | SUMMARY | | «Есть ли противоречия в расчете OEE?» | CONTRADICTION | | «Привет» | GREETING | | «Заполни шаблон договора» | TEMPLATE_FILL | | «Проверь орфографию» | SPELLCHECK | | «О чем этот документ?» | GENERAL |

11. Цепочка рассуждений (Chain-of-Thought)

Что делает:
Для запросов с намерениями CALCULATION (расчет) и PROCEDURE (инструкция/алгоритм) бот автоматически добавляет в промпт инструкцию, требующую пошагового решения перед итоговым ответом. Модель генерирует ответ с последовательным описанием шагов, а затем итоговым результатом.

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

Примеры использования:

1. Расчет OEE:

   • Запрос: «Рассчитай OEE для линии»
   • Ответ:

     Шаг 1: Доступное время = 480 мин
     Шаг 2: Время простоев = 45 мин
     Шаг 3: Операционное время = 435 мин
     Шаг 4: OEE = (435 / 480) × 100% = 90,6%
     Итоговый ответ: OEE составляет 90,6%.

2. Расчет выработки:

   • Запрос: «Какая будет выработка при загрузке 110%?»
   • Ответ с пошаговым расчетом:

     Шаг 1: Номинальная выработка = 100 ед/час
     Шаг 2: При загрузке 110% выработка = 100 × 1,1 = 110 ед/час
     Итог: 110 ед/час.

3. Пошаговая инструкция:

   • Запрос: «Как внедрить 5S?»
   • Бот выдает последовательность шагов с пояснениями.

12. Полнотекстовый поиск по точным фрагментам и поиск инструкций (HOW TO)

Что делает:
При обнаружении номеров пунктов (1.1, 3.2.1), фраз в кавычках или ключевых слов «как», «инструкция», «алгоритм», «порядок», «последовательность», «этапы», «методика», «процедура», «регламент», «правила», «способ», «метод» – бот переключается с гибридного RAG на точный подстроковый поиск в Qdrant (MatchText). Это гарантирует попадание в нужный раздел документа, а не просто семантически похожий фрагмент.

Ключевая особенность:
Если запрос содержит вопрос «как сделать Х», бот не просто находит фрагмент с упоминанием Х, а извлекает всю инструкцию или процедуру, даже если она не оформлена как маркированный список, а просто описана в тексте. Для этого используется дополнительный промпт, который заставляет LLM выделить и структурировать последовательность действий.

Уникальность:

• Гарантирует юридически значимые цитаты и ссылки на пункты нормативных актов.
• Может находить и выдавать пошаговые инструкции из неструктурированного текста.
• Объединяет точный поиск с цепочкой рассуждений (CoT), если инструкция требует расчетов или последовательных действий.

Польза:

• Позволяет получать готовые алгоритмы и процедуры без необходимости читать весь документ.
• Быстрое освоение новых процессов – достаточно спросить «как сделать Х», и бот найдет инструкцию в документах.
• Снижение времени на поиск регламентов и стандартов.

Примеры использования (все возможные сценарии):

1. Поиск инструкции по номеру пункта:

   • Запрос: «Выведи пункт 4.2 из регламента по внедрению 5S»
   • Ответ:

     [Источник: Регламент_внедрения_5S.docx]
     Пункт 4.2. Порядок проведения аудита рабочего места:
     1. Подготовка: сформировать чек-лист на основе стандарта 5S.
     2. Проведение аудита: визуальный осмотр рабочих мест, фиксация нарушений.
     3. Оценка: выставление баллов по каждому критерию...
     

2. Поиск процедуры по ключевому слову «как» + «инструкция»:

   • Запрос: «Как провести хронометраж рабочего времени?»
   • Ответ:

     [Источник: Методика_хронометража.pdf]
     Инструкция по проведению хронометража:
     1. Определить цель...
     2. Выбрать объект наблюдения...
     3. Разработать лист наблюдений...
     4. Провести наблюдение...
     5. Обработать данные...
     6. Сделать выводы...
     

3. Поиск алгоритма по ключевым словам «порядок действий», «этапы»:

   • Запрос: «Опиши порядок действий при внедрении кайдзен-предложения»
   • Ответ с пошаговым алгоритмом.

4. Поиск по цитате с кавычками:

   • Запрос: «"Срок исполнения не более 5 рабочих дней"»
   • Ответ: точная цитата с указанием раздела и документа.

5. Поиск методики по ключевым словам «методика» + «расчет»:

   • Запрос: «Найди методику расчета OEE»
   • Ответ с формулами и пояснениями.

6. Поиск инструкции с уточнением «напиши инструкцию»:

   • Запрос: «Напиши инструкцию по безопасной работе с электроинструментом»
   • Ответ с полным текстом инструкции.

7. Поиск с комбинацией: «как» + «внедрить» + конкретный инструмент:

   • Запрос: «Как внедрить систему 5S на производстве?»
   • Ответ с пошаговым алгоритмом внедрения.

8. Поиск регламента:

   • Запрос: «Какой регламент по проведению инвентаризации?»
   • Ответ с описанием процедуры.

9. Поиск по номеру документа:

   • Запрос: «ГОСТ Р 12345-2023»
   • Находит документ с этим номером в названии или тексте.

10. Комбинированный поиск:

    • Запрос: «Порядок расчета OEE по методике из приложения 2»
    • Находит точный раздел и выдает инструкцию.

13. Расширение запроса (query expansion)

Что делает:
Добавляет синонимы, аббревиатуры и связанные термины к исходному запросу для увеличения полноты поиска. Использует GigaChat для генерации до 10 дополнительных ключевых слов. Результаты кэшируются на 5 минут.

Уникальность:
Улучшает recall без участия пользователя. Автоматически подбирает термины, которые могут встречаться в документах.

Польза:
Помогает находить документы, даже если пользователь использует нестандартные термины или сокращения.

Примеры расширения:

Исходный запрос	Расширенный запрос (пример)
«OEE»	«OEE общая эффективность оборудования производительность коэффициент использования»
«время переналадки»	«время переналадки длительность смены инструмента SMED время простоя»
«5S»	«5S сортировка соблюдение порядка сияние стандартизация совершенствование рабочее место»
«Кайдзен»	«Кайдзен непрерывное улучшение малые шаги оптимизация процессов бережливое производство»
«выработка на человека»	«выработка на человека производительность труда выработка на одного сотрудника ПТ»
«расчет такта»	«расчет такта тактовое время Takt time формула такта время выпуска единицы»

14. Переранжирование контекста (кросс-энкодер)

Что делает:
После получения фрагментов из Qdrant, специализированная модель (кросс-энкодер) ранжирует их по релевантности запросу, отбрасывая шум. Используется локальная модель intfloat/multilingual-e5-reranker, что исключает затраты на токены и снижает задержку.

Уникальность:
Вместо дорогого вызова LLM используется легкий кросс-энкодер, работающий быстрее и дешевле. При этом качество ранжирования сравнимо с LLM.

Польза:
Уменьшает объем контекста, отправляемого в GigaChat, что экономит токены и улучшает точность ответа (убираются нерелевантные фрагменты).

Пример работы:
Запрос: «Какой OEE на линии А?»
Qdrant вернул 30 фрагментов. Кросс-энкодер отбирает только те, где есть упоминания «OEE» и «линия А», отбрасывая фрагменты про другие линии или общие описания. В результате в GigaChat отправляется только релевантный контекст (обычно 5–10 лучших фрагментов).

7.5. Функции автоматизации и интеграции

15. Автоматическая индексация файлов в комнатах (без !learn)

Что делает:
Любой файл (DOCX, PDF, XLSX, PPTX, изображение, аудио, архив), отправленный в групповой чат, автоматически индексируется в базу знаний комнаты. Не требуется включать режим обучения (!learn). Это работает «из коробки» для всех участников комнаты.

Уникальность:
Удобство для коллективной работы – не надо запоминать команды. Даже у Slack и Teams нет такой функции «из коробки».

Польза:
Быстрый старт для новых участников комнаты – они сразу могут задавать вопросы по документам, которые уже загружены. Автоматическое пополнение базы знаний без лишних действий.

Примеры использования:

1. Пользователь отправляет в групповой чат файл «Регламент_отдела.docx» – бот автоматически индексирует его в комнатную БЗ, и все участники могут задавать по нему вопросы.

2. Новый сотрудник приходит в комнату – он сразу может спрашивать бота о документах, которые уже загружены, без необходимости отдельно загружать их.

3. В комнате с файлами по проекту каждый участник может добавлять новые версии документов, и бот автоматически обновляет индекс (при изменении хеша файла).

4. Если файл является архивом (ZIP, 7z), бот распаковывает его и индексирует все поддерживаемые форматы внутри.

16. Веб-скрапинг с рекурсивным обходом

Что делает:
Бот может загрузить сайт по ссылке, рекурсивно обойти страницы (с ограничением глубины и количества) и проиндексировать их в базу знаний. Поддерживаются HTML-страницы и PDF-документы по ссылкам.

Уникальность:
Превращает произвольные веб-страницы в документы для RAG. Позволяет автоматически собирать информацию из внешних источников.

Польза:
Актуальная информация из внешних источников (изменения законодательства, новости отрасли, техническая документация) – автоматически попадает в базу знаний.

Примеры использования:

1. Индексация одной страницы:

   • В режиме !learn (личный чат) вводите:
     https://example.com/document
   • Бот загружает страницу, извлекает основной текст (с помощью readability-lxml) и индексирует.

2. Рекурсивный обход сайта:

   • https://example.com --recursive --depth 2 --max 10
   • Бот загружает страницу, затем переходит по ссылкам на глубину 2 уровня, обрабатывая не более 10 страниц, и индексирует все.

3. Индексация PDF по ссылке:

   • https://example.com/report.pdf
   • Бот скачивает PDF, извлекает текст и индексирует.

4. Задание заголовка:

   • https://example.com --title "Новый ГОСТ"
   • Документ сохраняется в БЗ с указанным заголовком.

5. Ограничения – глубина по умолчанию 1, максимум страниц 5 (настраивается в конфиге). Это предотвращает перегрузку системы.

17. Поддержка голосовых сообщений (распознавание через SaluteSpeech)

Что делает:
Аудиофайлы (.ogg, .wav, .mp3, .amr, .m4a) транскрибируются в текст через SaluteSpeech API. Полученный текст затем обрабатывается как обычный запрос (классификация, поиск, генерация ответа). Ответ отправляется текстом в чат.

Уникальность:
Редкость для RAG-ботов, удобно для мобильных клиентов. Не требует установки дополнительных приложений – работает с любым аудиофайлом.

Польза:
Можно «продиктовать» вопрос, не набирая текст. Удобно в дороге, в производственных условиях (где руки заняты) или для людей с ограниченными возможностями.

Примеры использования:

1. Пользователь отправляет голосовое сообщение в личный чат боту (или в комнату). Бот распознает речь, превращает в текст, и если это вопрос – обрабатывает через RAG, отправляя ответ текстом (или голосом, если настроено дополнительно).

2. В мобильном клиенте (например, Conversations) пользователь нажимает кнопку записи голоса, говорит вопрос, бот отвечает в чат текстом.

3. Голосовое сообщение может содержать не только вопрос, но и команду (например, «!summary») – бот распознает и выполняет.

4. Поддерживаются длинные сообщения – транскрипция работает с учетом лимитов API.

18. Административные команды (!stats, !status, !clean)

Что делает:

• !stats – показывает статистику работы бота: uptime, количество обработанных сообщений, AI-запросов, файлов, ошибок, документов в БЗ.
• !status – проверяет доступность внешних сервисов: PostgreSQL, Qdrant, GigaChat, а также состояние дискового пространства.
• !clean – очищает временную директорию (удаляет все временные файлы).

Уникальность:
Полный контроль без доступа к серверу. Все команды доступны из любого XMPP-клиента.

Польза:
Оперативное администрирование, мониторинг состояния системы, освобождение места на диске.

Примеры использования:

1. Проверка состояния сервисов:

   • !status
   • Бот проверяет подключение к PostgreSQL, Qdrant, GigaChat и выводит результат:
     ✅ PostgreSQL Online
✅ Qdrant Online
✅ GigaChat Online
💾 Диск: 512MB / 10GB (свободно 9.5GB)

2. Статистика работы бота:

   • !stats
   • Выводит:
     ⏱ Uptime: 2 дня 5 часов
💬 Сообщений: 1 234
🤖 AI запросов: 567
📁 Файлов обработано: 89
❌ Ошибок: 12
📚 Документов в БЗ: 45

3. Очистка временных файлов:

   • !clean
   • Удаляет все файлы из временной директории (temp/), освобождая место на диске. Выводит количество удаленных объектов.

4. Только для администраторов – команды !stats, !status, !clean доступны только пользователям, перечисленным в admin_jids в конфиге.

7.6. Дополнительные возможности

Режим обучения (!learn и !stop_learn)

• !learn – включает режим обучения. Следующий файл или ссылка, отправленные в чат, будут добавлены в базу знаний (личную, комнатную или глобальную, в зависимости от контекста и флагов).
• !learn --global – (только в личном чате, для админов) – следующий файл/ссылка станут глобальными.
• !stop_learn – выключает режим обучения.

Пример:
!learn → затем отправляете файл → он индексируется.
!stop_learn – режим выключен.

Работа с историей диалога

Бот автоматически сохраняет историю диалогов (личную и комнатную) в PostgreSQL. История используется для контекста при ответах. Команда !reset сбрасывает историю (личную или комнатную). Для длинных диалогов применяется иерархическое резюмирование, чтобы сжать историю и не превысить лимит токенов.

Поддержка вложенных файлов и архивов

Бот умеет распаковывать ZIP и 7z-архивы и индексировать все файлы внутри (DOCX, PDF, XLSX и т.д.). Это позволяет загружать целые пакеты документов одной ссылкой.

Многоязычность

Промпты настроены так, что бот может отвечать на любом языке, на котором задан вопрос, если в документах есть информация на этом языке. В системном промпте явно указано: «Ты можешь использовать информацию из документов на ЛЮБОМ языке (русском, английском, немецком и т.д.)». При необходимости бот переводит нужную часть на язык вопроса.

Работа с изображениями (Vision)

Если загружено изображение (JPEG, PNG, BMP, TIFF) и в конфиге включена опция vision: true, бот отправляет изображение на 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, которую можно сгенерировать командой python3 -c "import secrets; print(secrets.token_urlsafe(32))".
• Динамические few-shot примеры – подбор релевантных примеров на основе запроса и построение промта по структуре «сэндвич».

4.2. Планируемые улучшения

• Интеграция с системами документооборота (СЭД) – бот сможет подписывать документы ЭЦП, отправлять их на регистрацию, отслеживать статусы. В новой архитектуре это делается через расширение API RAG-сервера.
• Прогнозная аналитика командировок – бот будет предлагать оптимальные маршруты, экономить на билетах за счет предварительного бронирования.
• Агент‑индексатор сетевых папок (SMB) – бот сам сканирует общие каталоги и обновляет базу знаний, отправляя файлы на индексацию в RAG-сервер.
• Кэширование результатов генерации – для одинаковых запросов (с использованием хеша запроса и контекста) планируется внедрение кэширования (in-memory или Redis) на уровне RAG-сервера для снижения нагрузки и ускорения ответа.
• Сбор обратной связи – команда !feedback для оценки качества ответов (лайки/дизлайки) и хранение оценок в БД для последующего анализа.
• A/B-тестирование промптов – возможность разделять пользователей на группы и применять разные версии промптов для сравнения эффективности.
• Гибкие промты – автоматический выбор краткой или расширенной версии промпта в зависимости от длины доступного контекстного окна.
• Команда !style – изменение стиля ответов (кратко/подробно/по умолчанию) по желанию пользователя.
• Подключение дополнительных клиентов – благодаря HTTP API RAG-сервера можно легко добавить Telegram-бота, Mastodon-бота, веб-интерфейс или интеграцию с системами документооборота без изменения ядра.

III. Описание модулей

Платформа Эфцекабот построена по принципу «тонкий клиент – толстый сервер». Вся RAG-логика вынесена в отдельный HTTP-сервис – RAG-сервер, который обслуживает все клиенты (XMPP-боты, Telegram-боты, веб-интерфейсы и т.д.). Клиенты отправляют запросы на RAG-сервер через HTTP и не содержат RAG-логики.

Все модули, описанные ниже, расположены в каталоге rag/. Часть из них работает на RAG-сервере, часть – в клиентах, часть является общими утилитами.

1. Модуль rag_orchestrator.py – оркестратор RAG-пайплайна

Назначение: это сердце платформы. Модуль координирует все этапы обработки запроса через менеджеры:

• HistoryManager – получение и сжатие истории.
• IntentRouter – обработка специализированных намерений.
• QueryProcessor – обычный RAG-пайплайн (поиск, генерация, критика).
• IndexingManager – индексация документов с предварительным сжатием.

Место в архитектуре: запускается внутри RAG-сервера при обработке HTTP-запроса /rag/query. Не зависит от XMPP или других протоколов – может быть использован в любом клиенте через HTTP API.

Ключевые методы:

• process_query() – основной метод, выполняет полный цикл обработки запроса.
• index_document() – индексация документа (вызывается из /rag/index). Перед индексацией применяет иерархическое резюмирование, если документ слишком большой.

Особенности:

• Не содержит состояния, использует переданные сервисы и промпты.
• Поддерживает специализированные намерения: METRICS, SUMMARY, CONTRADICTION, TEMPLATE_FILL, SPELLCHECK, SURGICAL, GREETING.
• Добавляет цепочку рассуждений (Chain-of-Thought) для CALCULATION и PROCEDURE.

2. Модуль rag_server.py – HTTP-сервер (FastAPI)

Назначение: предоставляет REST API для всех клиентов. Является точкой входа в платформу.

Эндпоинты:

Метод	Эндпоинт	Назначение	Требует аутентификации
POST	/rag/query	Выполнить RAG-запрос (история берется из БД)	Да
POST	/rag/index	Проиндексировать документ	Да
POST	/rag/vision	Распознать текст на изображении (OCR)	Да
POST	/rag/transcribe	Транскрибировать аудио (SaluteSpeech)	Да
GET	/health	Проверка состояния сервера	Нет
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-документация с примерами и кодами ошибок.

3. Модуль rag_client.py – HTTP-клиент для ботов

Назначение: используется тонкими клиентами (XMPP-ботами, Telegram-ботами) для отправки запросов к RAG-серверу.

Методы:

• query() – отправляет запрос на /rag/query.
• index_document() – отправляет запрос на /rag/index.
• vision(file_path) – отправляет изображение на /rag/vision.
• transcribe(file_path) – отправляет аудио на /rag/transcribe.
• health_check() – проверяет доступность сервера.

Место в архитектуре: встраивается в клиентские приложения вместо локального вызова RAG-логики.

Особенности:

• Асинхронный (aiohttp).
• Поддерживает повторные попытки (retry) при сетевых ошибках.
• Автоматически добавляет заголовок X-API-Key с API-ключом.
• Не содержит бизнес-логики – только HTTP-вызовы.

4. Модуль rag_api.py – локальный API-интерфейс

Назначение: прослойка (facade) между ботами и RAGOrchestrator для локального использования (без HTTP). Этот модуль опционален – в новой архитектуре предпочтительнее использовать RAGClient.

Место в архитектуре: может использоваться для тестирования или в случае, если RAG-ядро запущено в том же процессе, что и клиент.

5. Модуль prompt_builder.py – построитель промтов (новое)

Назначение: динамически подбирает релевантные few-shot примеры из файла data/fewshot_examples.json (или использует статические) и формирует промт по структуре «сэндвич» (важное в начале и в конце). Это улучшает качество ответов, особенно для сложных запросов.

Формат файла fewshot_examples.json:

[
  {
    "keywords": ["OEE", "эффективность"],
    "intents": ["PROCEDURE", "CALCULATION"],
    "question": "Как рассчитать OEE?",
    "answer": "OEE = Доступность × Производительность × Качество."
  }
]

• keywords – список ключевых слов для поиска релевантности.
• intents – список намерений, для которых применим пример.
• question – вопрос пользователя.
• answer – эталонный ответ.

Место в архитектуре: используется в QueryProcessor при синтезе ответа.

6. Модули функций (каталог functions/)

Все функции являются чистыми, без состояния и вызываются из RAGOrchestrator на сервере. Они не зависят от XMPP и используют переданные промпты и конфигурацию.

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 для документов, истории диалогов, комнат, шаблонов, прав доступа.
qdrant_service.py	Векторная БД. Создание коллекции, гибридный поиск (dense + sparse), полнотекстовый поиск, удаление по doc_id.
embedding_service.py	Эмбеддинги GigaChat. Одиночные/пакетные запросы, кэширование (lru_cache), обрезка текста до 800 символов.
kb_service.py	База знаний. Индексация документов (разбиение на чанки, получение эмбеддингов, сохранение в Qdrant и PostgreSQL), поиск, управление доступом. Транзакционная индексация с флагом indexed.
file_service.py	Извлечение текста из файлов (DOCX, PDF, XLSX, PPTX, изображения, аудио, архивы). Хирургическая замена, создание DOCX. Используется на RAG-сервере для OCR и транскрибации.
giga_client.py	Клиент GigaChat. Методы chat() и upload_file() – без бизнес-логики.
reranker_service.py	Кросс-энкодер для переранжирования (локально). Ленивая загрузка модели.

8. Обработчики, команды, воркеры (для XMPP-клиентов)

Эти модули работают только на стороне тонких клиентов (XMPP-ботов) и не входят в RAG-сервер.

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).

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.

11. Конфигурационные файлы

Платформа использует два основных конфигурационных файла:

• rag.conf – общие настройки для всех ботов: параметры подключения к БД, Qdrant, GigaChat, настройки чанкинга, RAG, веб-скрапера, очистки, логирования. Добавлены параметры управления токенами и секция summarization.
• bot.conf – настройки конкретного профиля бота (методолог, коробочник, персональный ассистент): JID, пароль, промпты, пути к данным, ключевые слова, администраторы, параметры функций (температура, лимиты).

Переменные окружения (пароли, ключи API) хранятся в .env. Примеры конфигурации предоставлены в файлах rag.conf.example, bot.conf.sample, env.example.

12. Схема базы данных (PostgreSQL)

Схема создается автоматически через schema.sql и включает таблицы:

• documents – метаданные документов (источник, владелец, глобальный/комнатный флаг, хеш, коллекция Qdrant). Добавлена колонка indexed BOOLEAN DEFAULT FALSE для транзакционности индексации.
• document_access – права доступа к личным документам.
• history – история диалогов (личных и комнатных).
• rooms – список MUC-комнат, в которых бот должен состоять.
• room_templates – шаблоны коробочных решений, сохраненные в комнатах.

---

IV. Руководство по настройке аутентификации и доступу к API

1. Генерация API-ключа

Для защиты RAG-сервера используется API-ключ, который передаётся в заголовке X-API-Key при каждом запросе (кроме /health). Ключ должен быть уникальным и сложным.

Сгенерировать ключ можно одним из способов:

# Способ 1 – через Python (рекомендуется)
python3 -c "import secrets; print(secrets.token_urlsafe(32))"

# Способ 2 – через openssl
openssl rand -base64 32

# Способ 3 – через /dev/urandom (Linux/FreeBSD)
cat /dev/urandom | tr -dc 'a-zA-Z0-9' | head -c 32; echo

Пример сгенерированного ключа:

vK9pQz5RfT7mX2wY4nB8cD6gH3jF1aE5sL0oU9iP2qR7tY6wX4zA

2. Прописать ключ в переменные окружения

В файл .env (в корне проекта) добавьте строку:

RAG_API_KEY=вставьте_сгенерированный_ключ_сюда

3. Использование в Swagger UI (документация)

После запуска RAG-сервера откройте в браузере http://localhost:8080/docs. Нажмите кнопку "Authorize" (замочек) в правом верхнем углу, введите сгенерированный ключ в поле APIKeyHeader, нажмите "Authorize". Теперь можно выполнять запросы прямо из интерфейса.

4. Использование в боте

В bots/xmpp/client.py при создании RAGClient автоматически передаётся api_key=config.rag_api_key. В rag_client.py ключ добавляется в заголовок X-API-Key при каждом запросе.

---