markov/fckbot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Редактировать README.md

Browse Source
This commit is contained in:
Markov Andrey
2026-06-30 20:03:45 +00:00
parent d4de293c1b
commit 6602a3d7d6
1 changed files with 276 additions and 267 deletions
Download Patch File Download Diff File Expand all files Collapse all files

289
README.md
View File

@@ -2,43 +2,45 @@
## 1. Рабочее название
**Эфцекабот** — (_fckbot, производное от ФЦК БОТ_) корпоративная платформа для интеллектуальной обработки документов и диалогов, реализующая гибридный RAG (Retrieval-Augmented Generation) на базе GigaChat. Платформа включает единое RAG-ядро и несколько специализированных ботов-клиентов (методолог, коробочник, персональный ассистент), работающих в корпоративном мессенджере (XMPP). Ориентирована на поддержку бережливого производства, производительности труда, нормативной документации, ИИ-метрик, разработки лучших практик и коробочных решений, а также других функций.
**Эфцекабот** — (_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` для транскрибации аудио, что централизует обработку медиафайлов.
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-ядра, что позволяет централизованно управлять кэшированием и лимитами.
- **Ejabberd** — XMPP-сервер (сообщения, MUC-комнаты, HTTP Upload);
- **PostgreSQL** — централизованное хранилище метаданных документов, истории диалогов, прав доступа, списка комнат, шаблонов и оценок обратной связи;
- **Qdrant** — векторная БД с двумя полями (dense, sparse) для гибридного поиска. Доступна только RAG-ядру;
- **GigaChat API** — генерация текста и эмбеддингов. Вызовы осуществляются только из RAG-ядра, что позволяет централизованно управлять кэшированием и лимитами.
**Философия**:
- Каждый документ принадлежит контексту (личный, комнатный, глобальный).
- Боты-клиенты не имеют собственных знаний – они только передают запросы в RAG-ядро, которое отвечает строго по загруженным материалам (строгий RAG).
- Боты-клиенты не имеют собственных знаний — они только передают запросы в RAG-ядро, которое отвечает строго по загруженным материалам (строгий RAG).
- Единая история диалога для каждого пользователя/комнаты хранится на сервере, что обеспечивает непрерывность контекста независимо от того, через какой интерфейс (XMPP, Telegram, веб) пользователь общается с системой.
- Встроен интеллектуальный маршрутизатор запросов (классификация намерений), экспертная подсистема (метрики, суммаризация, проверка противоречий, хирургическая замена) и самокритика ответов – все это реализовано в RAG-ядре и доступно всем клиентам.
- Встроен интеллектуальный маршрутизатор запросов (классификация намерений), экспертная подсистема (метрики, суммаризация, проверка противоречий, хирургическая замена) и самокритика ответов — все это реализовано в RAG-ядре и доступно всем клиентам.
**Сервисы распределены по jails FreeBSD/Linux**:
**Сервисы распределены по джейлам FreeBSD/Linux**:
- `rag-server` (Python 3.11/3.12) — HTTP-сервис RAG-ядра.
- `metabot`, `korobot`, `persobot` — отдельные XMPP-клиенты (также на Python), которые общаются с RAG-ядром через HTTP.
- `ejabberd`, `PostgreSQL`, `Qdrant` — внешние системы.
- `Ejabberd`, `PostgreSQL`, `Qdrant` — внешние системы.
Инфраструктура развернута на **FreeBSD** с использованием **джейлов** (изолированных окружений), **ZFS** (файловая система с поддержкой снэпшотов и сжатия) и **10-гигабитной** внутренней сети между сервисами. Балансировщик **HAProxy** обеспечивает маршрутизацию внешних запросов и, при необходимости, горизонтальное масштабирование. Автоматические снэпшоты ZFS настроены через `zfs-auto-snapshot` для надежного резервного копирования.
## 3. Уникальность решения
1. **Гибридный RAG (dense + sparse) с самокритикой и централизованным ядром** — не используется в корпоративных ботах массово. Коммерческие решения часто ограничиваются простым семантическим поиском без переранжирования и самокритики. Вынесение RAG-логики в отдельный HTTP-сервис позволяет легко масштабировать и подключать любые клиентские интерфейсы.
1. **Гибридный RAG (dense + sparse) с самокритикой и централизованным ядром** — не используется в корпоративных ботах массово. Коммерческие решения часто ограничиваются простым семантическим поиском без переранжирования и самокритики. Вынесение RAG-логики в отдельный HTTP-сервис позволяет легко масштабировать и подключать любые клиентские интерфейсы.
2. **Персональный ассистент как часть экосистемы** — типичные персональные ассистенты не имеют доступа к внутренней базе знаний и не умеют отвечать на сложные вопросы по документам. Эфцекабот объединяет общие и персональные функции в едином RAG-ядре, при этом каждый бот-профиль использует свои промпты, что позволяет гибко настраивать поведение под конкретные задачи.
3. **Единая чат-среда и единый RAG-бэкенд для всех коммуникаций** — не требуется переключаться между десятками каналов (чат-боты в Telegram, веб-формы, почта). Весь документооборот, командировки, экспертные вопросы — в одном интерфейсе (корпоративном мессенджере), а при необходимости те же функции доступны через Telegram, или веб-интерфейс благодаря универсальному HTTP API RAG-ядра.
3. **Единая чат-среда и единый RAG-бэкенд для всех коммуникаций** — не требуется переключаться между десятками каналов (чат-боты в Telegram, веб-формы, почта). Весь документооборот, командировки, экспертные вопросы — в одном интерфейсе (корпоративном мессенджере), а при необходимости те же функции доступны через Telegram или веб-интерфейс благодаря универсальному HTTP API RAG-ядра.
4. **Полный контроль над данными** — все компоненты развернуты внутри компании. Никакие документы или переписка не покидают периметр. История и документы хранятся только на серверах компании.
@@ -48,40 +50,42 @@
## 4. Преимущества и недостатки работы бота в чате
#### Преимущества:
#### Преимущества
- **Единое корпоративное окно** — пользователь не переключается между приложениями, получает экспертные ответы прямо в рабочем чате.
- **Мгновенный обмен файлами** — встроен HTTP Upload, бот автоматически отправляет файлы в RAG-ядро для индексации (в т.ч. в групповых комнатах).
- **Мгновенный обмен файлами** — встроен HTTP Upload, бот автоматически отправляет файлы в RAG-ядро для индексации (в том числе в групповых комнатах).
- **Учет контекста беседы** — история диалога хранится централизованно в RAG-ядре, что обеспечивает единый контекст для всех клиентов (XMPP, Telegram, веб).
- **Поддержка комнат (MUC)** — документы, загруженные в комнату, видны всем участникам, а переписка в комнате служит общим контекстом.
- **Легковесные клиенты** — боты не содержат сложной RAG-логики, что упрощает их обновление и развертывание; все изменения в RAG вносятся в одном месте — RAG-ядре.
- **Не требует установки уникального клиентского ПО** — достаточно любого XMPP-клиента (Fluux, Conversations, Gajim, Pidgin) или работать через web-интерфейс (который также может использовать RAG-ядро).
- **Не требует установки уникального клиентского ПО** — достаточно любого XMPP-клиента (Fluux, Conversations, Gajim, Pidgin) или работы через веб-интерфейс (который также может использовать 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 — облачный 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 │ │ Веб-интерф. │ │
│ │ (тонкие) │ │ (клиент) │ │ (клиент) │ │ (клиент) │ │
@@ -91,7 +95,7 @@
│ │ │ │
│ ▼ ▼ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ RAG-СЕРВЕР (HTTP API) │ │
│ │ RAG-Сервер (HTTP API) │ │
│ │ POST /rag/query – выполнить RAG-запрос │ │
│ │ POST /rag/index – проиндексировать документ │ │
│ │ POST /rag/vision – распознать текст на изображении (OCR) │ │
@@ -113,10 +117,10 @@
│ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │ │
│ └────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────┘
```
**Ключевые компоненты:**
**Ключевые компоненты**:
- **RAG-сервер** — единая точка входа для всех RAG-запросов. Содержит всю бизнес-логику (поиск, генерацию, самокритику, индексацию). Запускается как отдельный HTTP-сервис.
- **Тонкие клиенты** — боты-профили (XMPP, Telegram, Mastodon и т.д.), которые только передают запросы в RAG-сервер и не содержат RAG-логики.
- **Внешние системы** — PostgreSQL, Qdrant, GigaChat API — доступны только RAG-серверу.
@@ -127,9 +131,7 @@
```
/usr/local/etc/fckbot/ # КОРЕНЬ ПРОЕКТА
│
├── rag/ # RAG-СЕРВЕР (HTTP-ядро)
│ ├── .env.example # Шаблон переменных окружения (пароли, ключи API)
├── rag/ # RAG-СеВе (HTTP-ядро)
│ ├── auth.py # Аутентификация (проверка API-ключа)
│ ├── config_models.py # Pydantic-модели для конфигурации (AppConfig)
│ ├── create_qdrant_collection.py # Скрипт создания коллекции в Qdrant
@@ -139,14 +141,14 @@
│ ├── 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.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_consistency.py # Проверка логических/числовых/терминологических противоречий
│ │ ├── check_spelling.py # Проверка орфографии и пунктуации с сохранением форматирования
│ │ ├── critique_answer.py # Самокритика ответа по 5 критериям
│ │ ├── expand_query.py # Расширение запроса (синонимы, аббревиатуры)
@@ -169,9 +171,8 @@
│ ├── arg_parser.py # Парсинг аргументов командной строки (--flag value)
│ ├── config_loader.py # Загрузка rag.conf и bot.conf, слияние, чтение .env, создание AppConfig
│ ├── logger.py # Настройка логирования (уровни, вывод в файл и консоль)
│ ├── text_utils.py # Разбиение текста на чанки (tiktoken + razdel), подсчёт токенов
│ ├── text_utils.py # Разбиение текста на чанки (tiktoken + razdel), подсчет токенов
│ └── web_utils.py # Веб-скрапинг (fetch_any_url, crawl_url)
│
├── bots/ # ОБЩИЙ КОД БОТОВ-КЛИЕНТОВ
│ ├── bot.py # Точка входа для запуска XMPP-бота (принимает --profile-dir)
│ ├── rag_client.py # HTTP-клиент для связи с RAG-сервером (асинхронный, с повторными попытками)
@@ -192,14 +193,13 @@
│ │ ├── file_handler.py # Скачивание файлов и постановка в очередь индексации
│ │ ├── health_handler.py # Очистка временных файлов, healthcheck БД/Qdrant (для клиентов)
│ │ ├── message_handler.py # Маршрутизация входящих сообщений (команды, файлы, AI-запросы) – использует RAGClient
│ │ ├── metrics_handler.py # Счётчики (сообщения, файлы, AI-запросы, ошибки)
│ │ ├── 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/ # Каталог для постоянных копий файлов
@@ -218,8 +218,7 @@
│ │ ├── synthesis.txt # Шаблон синтеза ответа
│ │ └── system.txt # Системный промпт (роль, стиль, правила)
│ └── temp/ # Пустой каталог для временных файлов
│
├── tests/ # ЮНИТ-ТЕСТЫ (общие для всего проекта)
├── tests/ # ЮНИТ-ТеТЫ (общие для всего проекта)
│ ├── conftest.py # Фикстуры и моки для pytest
│ ├── test_check_spelling.py # Тесты проверки орфографии
│ ├── test_consistency.py # Тесты проверки противоречий
@@ -229,13 +228,11 @@
│ ├── test_hierarchical_summary.txt # Тесты иерархического резюмирования
│ ├── test_intent_classify.py # Тесты классификации намерений
│ └── test_summarize.py # Тесты суммаризации
│
├── venv/ # ВИРТУАЛЬНОЕ ОКРУЖЕНИЕ Python
│ ├── bin/ # Исполняемые файлы (python, pip, activate)
│ ├── lib/ # Установленные библиотеки
│ └── ...
│
└── .env # ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ
└── .env.example # ШАБЛОН ПЕРЕМЕННЫХ ОКРУЖЕНИЯ
├── XMPP_PASSWORD=... # Пароль для XMPP-аккаунта бота
├── DB_PASSWORD=... # Пароль для PostgreSQL
├── GIGACHAT_API_KEY=... # API-ключ GigaChat
@@ -243,7 +240,7 @@
└── RAG_API_KEY=... # API-ключ для доступа к RAG-серверу (защита эндпоинтов)
```
**Важные примечания:**
**Важные примечания**:
- Реальные профили ботов (например, `metabot/`, `korobot/`, `persobot/`) создаются администратором вручную путем копирования `template_bot_profile/` и размещаются **вне репозитория** (например, в `/usr/local/etc/fckbot/profiles/`).
- Все юнит-тесты находятся в корневом каталоге `tests/`, что упрощает их запуск и поддержку.
@@ -274,7 +271,7 @@
└─────────────┘ └─────────────┘
```
**Поток данных:**
**Поток данных**:
1. **Запрос пользователя** → XMPP-бот (ejabberd) → HTTP → RAG-сервер.
2. RAG-сервер получает историю из PostgreSQL, ищет в Qdrant, генерирует ответ через GigaChat, выполняет самокритику.
@@ -286,18 +283,18 @@
Проект покрыт 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_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`).
**Запуск всех тестов:**
**Запуск всех тестов**:
```
```bash
cd /usr/local/etc/fckbot
source venv/bin/activate
pytest tests/ -v
@@ -313,24 +310,24 @@ pytest tests/ -v
- **`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`" – путь к файлу с примерами (относительно профиля).
- **`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`) | Отвечает за получение истории из БД, её сжатие (иерархическое резюмирование) и сохранение новых сообщений. |
| **Менеджер истории** (`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(). |
| **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`. |
@@ -347,28 +344,28 @@ pytest tests/ -v
| Место | Функция | Обоснование |
| ----- | ------- | ----------- |
| **🥇 1** | Генерация по шаблону | Основной инструмент для создания коробочных решений — автоматизирует производство документов |
| **🥈 2** | Гибридный RAG | Без него бот не может отвечать по документам — фундамент системы |
| **🥉 3** | Комнатные/глобальные БЗ | Обеспечивают коллективную работу над коробочными решениями |
| **4** | Хирургическая замена | Ускоряет доработку документов, критично для подготовки финальных версий |
| **5** | Проверка орфографии | Повышает качество исходящих документов |
| **6** | Суммаризация | Ускоряет анализ больших объемов информации |
| **7** | Самокритика | Повышает надежность ответов в критических областях |
| **8** | Извлечение метрик | Автоматизирует сбор KPI |
| **9** | Проверка противоречий | Исключает ошибки в документации |
| **10** | Классификация намерений | Обеспечивает интеллектуальную маршрутизацию |
| **11** | Цепочка рассуждений | Повышает точность расчетов и инструкций |
| **12** | Полнотекстовый поиск | Гарантирует юридическую точность и поиск инструкций |
| **13** | Расширение запроса | Улучшает полноту поиска |
| **14** | Переранжирование | Экономит токены и повышает точность |
| **15** | Автоиндексация | Упрощает коллективную работу |
| **16** | Веб-скрапинг | Интегрирует внешние источники |
| **17** | Голосовые сообщения | Удобство для мобильных пользователей |
| **18** | Администрирование | Оперативный контроль без доступа к серверу |
| **1** | Генерация по шаблону | Основной инструмент для создания коробочных решений — автоматизирует производство документов. |
| **2** | Гибридный RAG | Без него бот не может отвечать по документам — фундамент системы. |
| **3** | Комнатные/глобальные БЗ | Обеспечивают коллективную работу над коробочными решениями. |
| **4** | Хирургическая замена | Ускоряет доработку документов, критично для подготовки финальных версий. |
| **5** | Проверка орфографии | Повышает качество исходящих документов. |
| **6** | Суммаризация | Ускоряет анализ больших объемов информации. |
| **7** | Самокритика | Повышает надежность ответов в критических областях. |
| **8** | Извлечение метрик | Автоматизирует сбор KPI. |
| **9** | Проверка противоречий | Исключает ошибки в документации. |
| **10** | Классификация намерений | Обеспечивает интеллектуальную маршрутизацию. |
| **11** | Цепочка рассуждений | Повышает точность расчетов и инструкций. |
| **12** | Полнотекстовый поиск | Гарантирует юридическую точность и поиск инструкций. |
| **13** | Расширение запроса | Улучшает полноту поиска. |
| **14** | Переранжирование | Экономит токены и повышает точность. |
| **15** | Автоиндексация | Упрощает коллективную работу. |
| **16** | Веб-скрапинг | Интегрирует внешние источники. |
| **17** | Голосовые сообщения | Удобство для мобильных пользователей. |
| **18** | Администрирование | Оперативный контроль без доступа к серверу. |
## 7.1. Ключевые функции для создания документов (коробочных решений)
### 🥇 **1. Генерация коробочных решений по шаблону**
### **1. Генерация коробочных решений по шаблону**
**Что делает**:
По команде `!create "Коробочное решение"` бот генерирует готовый коробочный документ на основе шаблона, заполняя все плейсхолдеры `{{...}}` данными из базы знаний комнаты. Шаблон содержит следующие разделы (соответствует файлу `Шаблон коробочного решения.docx`):
@@ -387,7 +384,7 @@ pytest tests/ -v
Превращает бота из информатора в **инструмент производства готовых коробочных решений**. Достаточно один раз настроить шаблон, и бот будет генерировать документы на основе актуальных данных из базы знаний. Все, что требуется от пользователя — загрузить в комнату документы-источники (регламенты, отчеты, методики, ГОСТы, аналитические записки).
**Польза**:
Автоматизация подготовки коробочных решений, сокращение времени на создание документов с 1-2 недель до 10-30 минут, исключение ошибок ручного ввода, единообразие документов, возможность быстрого масштабирования на любые типы организаций.
Автоматизация подготовки коробочных решений, сокращение времени на создание документов с 1–2 недель до 10–30 минут, исключение ошибок ручного ввода, единообразие документов, возможность быстрого масштабирования на любые типы организаций.
**Примеры использования (все возможные сценарии)**:
@@ -503,16 +500,15 @@ pytest tests/ -v
**Пример**: плейсхолдер `{{KPI_NAME}}` – бот найдет в английских документах «Overall Equipment Effectiveness» и переведет как «Общая эффективность оборудования» (или оставит аббревиатуру OEE, если так указано в документах).
### 🥈 **2. Гибридный RAG с самокритикой**
### **2. Гибридный RAG с самокритикой**
**Что делает**:
Это ядро системы, которое используется для поиска данных для каждого плейсхолдера шаблона. Бот выполняет:
- Семантический поиск (dense-эмбеддинги от GigaChat).
- Ключевой поиск (sparse-векторы BM25 от FastEmbed).
- Объединение через Reciprocal Rank Fusion (RRF).
- Генерацию ответа через GigaChat.
- Проверку через самокритику (оценка по 5 критериям).
- Семантический поиск (dense-эмбеддинги от GigaChat);
- Ключевой поиск (sparse-векторы BM25 от FastEmbed);
- Объединение через Reciprocal Rank Fusion (RRF);
- Генерацию ответа через GigaChat;
- Проверку через самокритику (оценка по 5 критериям);
- Перегенерацию при необходимости.
**Уникальность**:
@@ -568,7 +564,7 @@ pytest tests/ -v
4. **Поиск постановки задач**:
- Для `{{TASK_1}}` бот находит в стратегических документах перечень задач: «разработать стандарт», «обучить персонал», «внедрить систему мониторинга».
### 🥉 **3. Комнатные и глобальные базы знаний**
### **3. Комнатные и глобальные базы знаний**
**Что делает**:
Документы могут быть трех типов:
@@ -651,7 +647,7 @@ pytest tests/ -v
Пользователь загружает DOCX, затем пишет «Проверь орфографию» или «Найди ошибки». Бот разбивает текст на чанки (учитывая токены), отправляет каждый чанк в GigaChat с промптом на исправление ошибок. Исправления применяются с сохранением форматирования. Возвращает исправленный файл и список изменений в виде «было → стало».
**Уникальность**:
Автоматическое исправление ошибок в готовых документах без ручной правки. Поддерживает сложные случаи русского языка (благодаря использованию `razdel` для разбиения на предложения).
Автоматическое исправление ошибок в готовых документов без ручной правки. Поддерживает сложные случаи русского языка (благодаря использованию `razdel` для разбиения на предложения).
**Польза**:
Экономия времени на вычитку, повышение грамотности исходящих документов. Незаменимо при подготовке коробочных решений и официальных документов.
@@ -809,10 +805,10 @@ pytest tests/ -v
**Польза**:
Экономия токенов, времени и повышение точности ответов за счет выбора специализированной стратегии.
**Примеры работы (как классификатор определяет тип запроса):**
**Примеры работы (как классификатор определяет тип запроса)**:
| Запрос пользователя | Распознанное намерение |
|||
|----------------------|-------------------------|
| «Какое тактовое время установлено на линии?» | `FACT` |
| «Как рассчитать OEE?» | `PROCEDURE` |
| «Сравни показатели производительности до и после кайдзен» | `COMPARISON` |
@@ -825,7 +821,7 @@ pytest tests/ -v
| «Проверь орфографию» | `SPELLCHECK` |
| «О чем этот документ?» | `GENERAL` |
### **11. Цепочка рассуждений (Chain-of-Thought)**
### **11. Цепочка рассуждений (Chain‑of‑Thought)**
**Что делает**:
Для запросов с намерениями `CALCULATION` (расчет) и `PROCEDURE` (инструкция/алгоритм) бот автоматически добавляет в промпт инструкцию, требующую пошагового решения перед итоговым ответом. Модель генерирует ответ с последовательным описанием шагов, а затем итоговым результатом.
@@ -1048,7 +1044,6 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
### **18. Административные команды (`!stats`, `!status`, `!clean`)**
**Что делает**:
- `!stats` – показывает статистику работы бота: uptime, количество обработанных сообщений, AI-запросов, файлов, ошибок, документов в БЗ.
- `!status` – проверяет доступность внешних сервисов: PostgreSQL, Qdrant, GigaChat, а также состояние дискового пространства.
- `!clean` – очищает временную директорию (удаляет все временные файлы).
@@ -1188,8 +1183,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
!create "Коробочное решение_Музеи"
```
----
---
# II. Перспективы развития Эфцекабот
@@ -1200,16 +1194,16 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
### 1.1. Общие боты
| Тип бота | Отдел | Примеры запросов |
|-----|------|------|
| **Методолог (стандарты)** | Методология, бизнес‑аналитика, внутренний контроль | «Найди требования к описанию бизнес‑процесса» |
|----------|-------|------------------|
| **Методолог (стандарты)** | Методология, бизнес-аналитика, внутренний контроль | «Найди требования к описанию бизнес-процесса» |
| **Писатель коробочных решений** | Методология | «Напиши коробочное решение по образцу» |
| **Юрист‑эксперт** | Юридический | «Составь претензию по шаблону» |
| **Юрист-эксперт** | Юридический | «Составь претензию по шаблону» |
| **Финансовый аналитик** | Финансы, управленческий учет | «Рассчитай OEE по проекту X» |
| **HR‑помощник** | Отдел персонала | «Образец служебной записки или бизнес‑процесса» |
| **HR-помощник** | Отдел персонала | «Образец служебной записки или бизнес-процесса» |
| **Менеджер проектов** | Проектный офис | «Сформируй выжимку по проекту за месяц» |
| **ИТ‑архитектор** | IT‑департамент | «Сравни конфигурации серверов из ТЗ» |
| **Комплаенс‑контроль** | Служба безопасности | «Проверь отчет на соответствие регламенту» |
| **Executive‑бот** | Топ‑менеджмент | «Сводка KPI по всем проектам» |
| **ИТ-архитектор** | IT-департамент | «Сравни конфигурации серверов из ТЗ» |
| **Комплаенс-контроль** | Служба безопасности | «Проверь отчет на соответствие регламенту» |
| **Executive-бот** | Топ-менеджмент | «Сводка KPI по всем проектам» |
Каждый из этих ботов может быть реализован как отдельный XMPP-клиент (или другой клиент), подключающийся к общему RAG-ядру. Благодаря единому ядру, все боты используют одни и те же документы и историю, но могут иметь свои промпты, что позволяет настраивать стиль и глубину ответов под конкретную задачу.
@@ -1219,13 +1213,13 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
В новой архитектуре персональные настройки хранятся в общей БД и доступны всем клиентам. Пользователь может начать диалог в XMPP, а продолжить в Telegram – история и контекст сохраняются.
**Ключевые сценарии персонального ассистента:**
**Ключевые сценарии персонального ассистента**:
| Сценарий | Пример запроса | Автоматизация |
|-----|------|------|
| **Планирование командировки** | «Запланируй командировку в Нижний Новгород на 10–12 мая» | Бот через агента‑тревел подбирает билеты, отель, создает задачу на согласование руководителю, резервирует |
| **Поиск и бронирование билетов** | «Найди ближайший рейс до Екатеринбурга на завтра утро» | Интеграция с корпоративным тревел‑агентом (API), выдача вариантов, бронирование по команде |
| **Бронирование гостиницы** | «Подбери гостиницу рядом с офисом клиента в Казани, бюджет до 5000 ₽/ночь» | Агент‑отельер возвращает список, пользователь выбирает – бронь автоматически |
|----------|----------------|---------------|
| **Планирование командировки** | «Запланируй командировку в Нижний Новгород на 10–12 мая» | Бот через агента-тревел подбирает билеты, отель, создает задачу на согласование руководителю, резервирует |
| **Поиск и бронирование билетов** | «Найди ближайший рейс до Екатеринбурга на завтра утро» | Интеграция с корпоративным тревел-агентом (API), выдача вариантов, бронирование по команде |
| **Бронирование гостиницы** | «Подбери гостиницу рядом с офисом клиента в Казани, бюджет до 5000 ₽/ночь» | Агент-отельер возвращает список, пользователь выбирает – бронь автоматически |
| **Оформление командировочного удостоверения** | «Сформируй командировочное удостоверение по поездке №45» | Бот заполняет шаблон данными из бронирования, высылает PDF |
| **Авансовый отчет по командировке** | «Сделай авансовый отчет за поездку в Уфу» | Бот предзаполняет даты, маршрут, суммы билетов и отеля; сотрудник добавляет фото чеков → OCR распознает и вносит суммы |
| **Согласование отчета** | «Отправь отчет руководителю на подпись» | Бот пересылает отчет в личный чат руководителя, тот ставит «OK» кнопкой |
@@ -1242,11 +1236,11 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
4. Клиент (или отдельный агент-оркестратор) выполняет эту команду через API внешних систем и возвращает результат в RAG-сервер для финальной обработки.
| Запрос пользователя | Намерение (intent) | Вызываемый агент | Действие агента | Результат |
|----|----|----|----|----|
| «Найди билеты Москва‑Питер на 15 мая» | `BOOKING` | Агент‑тревел | Запрос к API билетной системы | Список рейсов с ценами |
| «Подбери гостиницу рядом с вокзалом» | `BOOKING` | Агент‑отельер | Поиск по API Booking.com / Ostrovok | Варианты отелей, кнопка бронирования |
| «Сделай авансовый отчет по командировке #123» | `REPORT` | Агент‑генератор DOCX | Заполняет шаблон из данных бронирования и чеков | Готовый отчет в чат |
| «Проверь этот чек» | `OCR` | Агент‑распознаватель (OCR) | Извлекает сумму, дату, назначение | Структурированные данные, которые бот вставляет в отчет |
|---------------------|---------------------|------------------|-----------------|-----------|
| «Найди билеты Москва-Питер на 15 мая» | `BOOKING` | Агент-тревел | Запрос к API билетной системы | Список рейсов с ценами |
| «Подбери гостиницу рядом с вокзалом» | `BOOKING` | Агент-отельер | Поиск по API Booking.com / Ostrovok | Варианты отелей, кнопка бронирования |
| «Сделай авансовый отчет по командировке #123» | `REPORT` | Агент-генератор DOCX | Заполняет шаблон из данных бронирования и чеков | Готовый отчет в чат |
| «Проверь этот чек» | `OCR` | Агент-распознаватель (OCR) | Извлекает сумму, дату, назначение | Структурированные данные, которые бот вставляет в отчет |
**Вывод:** RAG-сервер – это «мозг», а агенты – «руки». Без RAG-сервера агенты разрозненны; с ним они работают как единая система, управляемая естественным языком через единый HTTP API.
@@ -1268,7 +1262,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
**Допущения:**
- Количество командировок в год: 200 чел. × 44 недели = **8 800 командировок**.
- Без автоматизации затраты времени на одну командировку (поиск билетов, бронирование отеля, оформление заявки, составление авансового отчета, согласование) – **2 часа** (суммарно).
- С ботом (интеграция с тревел‑агентом, автоматическое заполнение форм, OCR чеков, «однонажательное» согласование) – **0,4 часа** (24 минуты). Экономия = 1,6 часа на командировку.
- С ботом (интеграция с тревел-агентом, автоматическое заполнение форм, OCR чеков, «однонажательное» согласование) – **0,4 часа** (24 минуты). Экономия = 1,6 часа на командировку.
**Экономия в часах:** 8 800 × 1,6 = **14 080 часов**.
@@ -1283,7 +1277,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
### 3.4. Итоговая годовая экономия
| Статья | Часы |
| - | - |
|--------|------|
| Поиск информации (RAG) | 40 755 |
| Командировки (бронирование + отчетность) | 14 080 |
| Снижение ошибок в документообороте | 1 600 |
@@ -1294,9 +1288,9 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
### 3.5. Затраты на внедрение и обслуживание
| Статья | Стоимость |
| | |
|--------|-----------|
| Развертывание инфраструктуры (серверы, настройка) | 1 млн руб. (разово) |
| Разработка интеграций (агенты, тревел‑API, 1С, календарь) | 2 млн руб. (разово, можно тиражировать) |
| Разработка интеграций (агенты, тревел-API, 1С, календарь) | 2 млн руб. (разово, можно тиражировать) |
| Обслуживание, обновление БЗ, поддержка | 1 млн руб./год |
| **Итого первый год** | **4 млн руб.** |
| **Итого последующие годы** | **1 млн руб./год** |
@@ -1326,7 +1320,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
- **Интеграция с системами документооборота (СЭД)** – бот сможет подписывать документы ЭЦП, отправлять их на регистрацию, отслеживать статусы. В новой архитектуре это делается через расширение API RAG-сервера.
- **Прогнозная аналитика командировок** – бот будет предлагать оптимальные маршруты, экономить на билетах за счет предварительного бронирования.
- **Агент‑индексатор сетевых папок (SMB)** – бот сам сканирует общие каталоги и обновляет базу знаний, отправляя файлы на индексацию в RAG-сервер.
- **Агент-индексатор сетевых папок (SMB)** – бот сам сканирует общие каталоги и обновляет базу знаний, отправляя файлы на индексацию в RAG-сервер.
- **Кэширование результатов генерации** – для одинаковых запросов (с использованием хеша запроса и контекста) планируется внедрение кэширования (in-memory или Redis) на уровне RAG-сервера для снижения нагрузки и ускорения ответа.
- **Сбор обратной связи** – команда `!feedback` для оценки качества ответов (лайки/дизлайки) и хранение оценок в БД для последующего анализа.
- **A/B-тестирование промптов** – возможность разделять пользователей на группы и применять разные версии промптов для сравнения эффективности.
@@ -1334,6 +1328,8 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
- **Команда `!style`** – изменение стиля ответов (кратко/подробно/по умолчанию) по желанию пользователя.
- **Подключение дополнительных клиентов** – благодаря HTTP API RAG-сервера можно легко добавить Telegram-бота, Mastodon-бота, веб-интерфейс или интеграцию с системами документооборота без изменения ядра.
---
# III. Описание модулей
Платформа Эфцекабот построена по принципу **«тонкий клиент – толстый сервер»**. Вся RAG-логика вынесена в отдельный HTTP-сервис – **RAG-сервер**, который обслуживает все клиенты (XMPP-боты, Telegram-боты, веб-интерфейсы и т.д.). Клиенты отправляют запросы на RAG-сервер через HTTP и не содержат RAG-логики.
@@ -1343,6 +1339,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
## 1. Модуль `rag_orchestrator.py` – оркестратор RAG-пайплайна
**Назначение:** это **сердце платформы**. Модуль координирует все этапы обработки запроса через менеджеры:
- `HistoryManager` – получение и сжатие истории.
- `IntentRouter` – обработка специализированных намерений.
- `QueryProcessor` – обычный RAG-пайплайн (поиск, генерация, критика).
@@ -1351,10 +1348,12 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
**Место в архитектуре:** запускается внутри 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`.
@@ -1363,10 +1362,10 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
**Назначение:** предоставляет REST API для всех клиентов. Является точкой входа в платформу.
**Эндпоинты:**
**Эндпоинты**:
| Метод | Эндпоинт | Назначение | Требует аутентификации |
|-|-|-|-|
|-------|----------|------------|------------------------|
| POST | `/rag/query` | Выполнить RAG-запрос (история берется из БД) | Да |
| POST | `/rag/index` | Проиндексировать документ | Да |
| POST | `/rag/vision` | Распознать текст на изображении (OCR) | Да |
@@ -1379,6 +1378,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
**Место в архитектуре:** запускается как отдельный процесс (с помощью Uvicorn). Обслуживает все клиенты. Инициализирует все сервисы (БД, Qdrant, GigaChat) и создает экземпляр `RAGOrchestrator`.
**Особенности:**
- Использует Pydantic для валидации запросов и ответов.
- Поддерживает CORS для возможности запросов с других доменов.
- Имеет встроенный healthcheck для мониторинга.
@@ -1391,6 +1391,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
**Назначение:** используется тонкими клиентами (XMPP-ботами, Telegram-ботами) для отправки запросов к RAG-серверу.
**Методы:**
- `query()` – отправляет запрос на `/rag/query`.
- `index_document()` – отправляет запрос на `/rag/index`.
- `vision(file_path)` – отправляет изображение на `/rag/vision`.
@@ -1400,6 +1401,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
**Место в архитектуре:** встраивается в клиентские приложения вместо локального вызова RAG-логики.
**Особенности:**
- Асинхронный (aiohttp).
- Поддерживает повторные попытки (retry) при сетевых ошибках.
- Автоматически добавляет заголовок `X-API-Key` с API-ключом.
@@ -1411,13 +1413,13 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
**Место в архитектуре:** может использоваться для тестирования или в случае, если RAG-ядро запущено в том же процессе, что и клиент.
## 5. Модуль prompt_builder.py – построитель промтов (новое)
## 5. Модуль `prompt_builder.py` – построитель промтов
**Назначение:** динамически подбирает релевантные few-shot примеры из файла data/fewshot_examples.json (или использует статические) и формирует промт по структуре «сэндвич» (важное в начале и в конце). Это улучшает качество ответов, особенно для сложных запросов.
**Назначение:** динамически подбирает релевантные few-shot примеры из файла `data/fewshot_examples.json` (или использует статические) и формирует промт по структуре «сэндвич» (важное в начале и в конце). Это улучшает качество ответов, особенно для сложных запросов.
**Формат файла** `fewshot_examples.json`:
```
```json
[
{
"keywords": ["OEE", "эффективность"],
@@ -1433,7 +1435,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
- `question` – вопрос пользователя.
- `answer` – эталонный ответ.
**Место в архитектуре:** используется в QueryProcessor при синтезе ответа.
**Место в архитектуре:** используется в `QueryProcessor` при синтезе ответа.
## 6. Модули функций (каталог `functions/`)
@@ -1483,16 +1485,16 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
**Вход:** текст, название, промпт, конфиг.
**Выход:** строка с кратким изложением.
### 6.5. hierarchical_summarize.py – иерархическое резюмирование (новое)
### 6.5. `hierarchical_summarize.py` – иерархическое резюмирование
**Назначение:** сжимает очень большие тексты (документы, историю диалога) с помощью рекурсивного резюмирования блоков. Разбивает текст на блоки по предложениям, резюмирует каждый блок через GigaChat, объединяет результаты, и при необходимости повторяет процесс рекурсивно до достижения целевой длины.
**Место в архитектуре:** вызывается из RAGOrchestrator:
**Место в архитектуре:** вызывается из `RAGOrchestrator`:
- В `process_query` – для сжатия длинной истории диалога.
- В `index_document` – для сжатия больших документов перед индексацией (через метод `_compress_document_if_needed`).
**Как работает:** использует промпт (hierarchical_summary.txt) для каждого блока.
**Как работает:** использует промпт (`hierarchical_summary.txt`) для каждого блока.
**Вход:** текст, целевой размер в токенах, размер блока, глубина.
**Выход:** сжатый текст.
@@ -1557,7 +1559,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
Долгоживущие компоненты, которые инициализируются один раз при старте RAG-сервера и предоставляют API для работы с внешними системами.
| Файл | Назначение |
|-----|------|
|------|------------|
| `postgres_service.py` | Пул соединений с PostgreSQL. CRUD для документов, истории диалогов, комнат, шаблонов, прав доступа. |
| `qdrant_service.py` | Векторная БД. Создание коллекции, гибридный поиск (dense + sparse), полнотекстовый поиск, удаление по doc_id. |
| `embedding_service.py` | Эмбеддинги GigaChat. Одиночные/пакетные запросы, кэширование (`lru_cache`), обрезка текста до 800 символов. |
@@ -1573,10 +1575,10 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
### 8.1. Обработчики (`handlers/`)
| Файл | Назначение |
|-----|------|
|------|------------|
| `metrics_handler.py` | Счетчики (сообщения, файлы, AI-запросы, ошибки). |
| `message_handler.py` | Маршрутизация входящих сообщений (использует `RAGClient`). |
| `file_handler.py` | Скачивание файлов и постановка в очередь индексации. Убраны прямые вызовы GigaChat – теперь всё через RAGClient. |
| `file_handler.py` | Скачивание файлов и постановка в очередь индексации. Убраны прямые вызовы GigaChat – теперь все через RAGClient. |
| `room_handler.py` | MUC комнаты (приглашения, вход, переподключение). |
| `subscription_handler.py` | Подписки (roster subscription). |
| `health_handler.py` | Очистка файлов, healthcheck БД/Qdrant (для клиентов). |
@@ -1584,7 +1586,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
### 8.2. Команды (`commands/`)
| Файл | Назначение |
|-----|------|
|------|------------|
| `base.py` | Базовый класс `Command`. |
| `registry.py` | Регистрация команд, алиасы, подсказки. |
| `info.py` | `!info` – краткая справка. |
@@ -1601,7 +1603,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
### 8.3. Воркеры (`workers/`)
| Файл | Назначение |
|-----|------|
|------|------------|
| `indexing_worker.py` | Фоновый воркер, который обрабатывает очередь индексации файлов и URL, отправляя их на RAG-сервер через `RAGClient`. Обработка изображений и аудио теперь через RAG-сервер. |
## 9. Утилиты (каталог `utils/`)
@@ -1609,7 +1611,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
Вспомогательные функции, используемые как сервером, так и клиентами:
| Файл | Назначение |
|-----|------|
|------|------------|
| `config_loader.py` | Загрузка `rag.conf` и `bot.conf`, слияние, чтение `.env`, создание `AppConfig` с помощью Pydantic. |
| `logger.py` | Настройка логирования (уровни, вывод в файл и консоль). |
| `layout_converter.py` | Конвертер раскладки клавиатуры (русская ↔ английская). |
@@ -1636,7 +1638,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
Платформа использует два основных конфигурационных файла:
- **`rag.conf`** – общие настройки для всех ботов: параметры подключения к БД, Qdrant, GigaChat, настройки чанкинга, RAG, веб-скрапера, очистки, логирования. Добавлены параметры управления токенами и секция summarization.
- **`rag.conf`** – общие настройки для всех ботов: параметры подключения к БД, Qdrant, GigaChat, настройки чанкинга, RAG, веб-скрапера, очистки, логирования. Добавлены параметры управления токенами и секция `summarization`.
- **`bot.conf`** – настройки конкретного профиля бота (методолог, коробочник, персональный ассистент): JID, пароль, промпты, пути к данным, ключевые слова, администраторы, параметры функций (температура, лимиты).
Переменные окружения (пароли, ключи API) хранятся в `.env`. Примеры конфигурации предоставлены в файлах `rag.conf.example`, `bot.conf.sample`, `env.example`.
@@ -1645,7 +1647,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
Схема создается автоматически через `schema.sql` и включает таблицы:
- **`documents`** – метаданные документов (источник, владелец, глобальный/комнатный флаг, хеш, коллекция Qdrant). Добавлена колонка indexed `BOOLEAN DEFAULT FALSE` для транзакционности индексации.
- **`documents`** – метаданные документов (источник, владелец, глобальный/комнатный флаг, хеш, коллекция Qdrant). Добавлена колонка `indexed BOOLEAN DEFAULT FALSE` для транзакционности индексации.
- **`document_access`** – права доступа к личным документам.
- **`history`** – история диалогов (личных и комнатных).
- **`rooms`** – список MUC-комнат, в которых бот должен состоять.
@@ -1657,22 +1659,31 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби
## 1. Генерация API-ключа
Для защиты RAG-сервера используется API-ключ, который передаётся в заголовке `X-API-Key` при каждом запросе (кроме `/health`). Ключ должен быть уникальным и сложным.
Для защиты RAG-сервера используется API-ключ, который передается в заголовке `X-API-Key` при каждом запросе (кроме `/health`). Ключ должен быть уникальным и сложным.
**Сгенерировать ключ можно одним из способов:**
```bash
# Способ 1 – через Python (рекомендуется)
### Способ 1 – через Python (рекомендуется)
```
python3 -c "import secrets; print(secrets.token_urlsafe(32))"
```
# Способ 2 – через openssl
### Способ 2 – через openssl
```
openssl rand -base64 32
```
# Способ 3 – через /dev/urandom (Linux/FreeBSD)
### Способ 3 – через /dev/urandom (Linux/FreeBSD)
```
cat /dev/urandom | tr -dc 'a-zA-Z0-9' | head -c 32; echo
```
Пример сгенерированного ключа:
```
vK9pQz5RfT7mX2wY4nB8cD6gH3jF1aE5sL0oU9iP2qR7tY6wX4zA
```
@@ -1691,6 +1702,4 @@ RAG_API_KEY=вставьте_сгенерированный_ключ_сюда
## 4. Использование в боте
В `bots/xmpp/client.py` при создании `RAGClient` автоматически передаётся `api_key=config.rag_api_key`. В `rag_client.py` ключ добавляется в заголовок `X-API-Key` при каждом запросе.
---
В `bots/xmpp/client.py` при создании `RAGClient` автоматически передается `api_key=config.rag_api_key`. В `rag_client.py` ключ добавляется в заголовок `X-API-Key` при каждом запросе.