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