2057 lines
191 KiB
Markdown
2057 lines
191 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, веб-интерфейс, системы аналитики). RAG-сервер также предоставляет эндпоинты `/rag/vision` для распознавания текста на изображениях (OCR) и `/rag/transcribe` для транскрибации аудио, что централизует обработку медиафайлов.
|
||
|
||
2. **Тонкие XMPP-боты-клиенты** — каждый профиль (методолог, коробочник, персональный ассистент) представляет собой отдельный XMPP-клиент, который подключается к ejabberd, обрабатывает команды, принимает файлы и пересылает запросы пользователей в RAG-ядро по HTTP. Боты не содержат RAG-логики, не имеют локальной БД или Qdrant, а только загружают свои промпты и передают их в запросах. Это делает их легковесными и независимыми. Вся обработка изображений и аудио выполняется на RAG-сервере, что дополнительно упрощает клиентов.
|
||
|
||
3. **Внешние системы хранения и API**:
|
||
|
||
- **Ejabberd** — XMPP-сервер (сообщения, MUC-комнаты, HTTP Upload);
|
||
- **PostgreSQL** — централизованное хранилище метаданных документов, истории диалогов, прав доступа, списка комнат, шаблонов и оценок обратной связи. Управление схемой через Alembic (миграции). Добавлена колонка `file_text` для хранения исходного текста документов.
|
||
- **Qdrant** — векторная БД с двумя полями (dense, sparse) для гибридного поиска. Доступна только RAG-ядру.
|
||
- **GigaChat API** — генерация текста и эмбеддингов. Вызовы осуществляются только из RAG-ядра, что позволяет централизованно управлять кэшированием и лимитами.
|
||
- **Redis** (опционально) — кэширование эмбеддингов (TTL 1 час) и результатов SOMA-оценок (TTL 5 мин).
|
||
- **Внешние API** — для инструментов ReAct: DuckDuckGo (поиск), OpenWeatherMap (погода), заглушки для бронирования и курсов валют.
|
||
|
||
**Философия**:
|
||
|
||
- Каждый документ принадлежит контексту (личный, комнатный, глобальный).
|
||
- Боты-клиенты не имеют собственных знаний — они только передают запросы в RAG-ядро, которое отвечает строго по загруженным материалам (строгий RAG).
|
||
- Единая история диалога для каждого пользователя/комнаты хранится на сервере, что обеспечивает непрерывность контекста независимо от того, через какой интерфейс (XMPP, Telegram, веб) пользователь общается с системой.
|
||
- Встроен интеллектуальный маршрутизатор запросов (классификация намерений), экспертная подсистема (метрики, суммаризация, проверка противоречий, хирургическая замена) и самокритика ответов — все это реализовано в RAG-ядре и доступно всем клиентам.
|
||
- Добавлены **инновационные техники**: SOMA-анализ (LLM-as-judge), ReAct (вызов внешних инструментов), планирование действий, многоагентность, реальные обработчики инструментов, фоновый ReindexWorker для переиндексации документов после сбоев.
|
||
|
||
**Сервисы распределены по джейлам FreeBSD/Linux**:
|
||
|
||
- `rag-server` (Python 3.11/3.12) — HTTP-сервис RAG-ядра.
|
||
- `metabot`, `korobot`, `persobot` — отдельные XMPP-клиенты (также на Python), которые общаются с RAG-ядром через HTTP.
|
||
- `Ejabberd`, `PostgreSQL`, `Qdrant`, `Redis` — внешние системы.
|
||
|
||
Инфраструктура развернута на **FreeBSD** с использованием **джейлов** (изолированных окружений), **ZFS** (файловая система с поддержкой снэпшотов и сжатия) и **10-гигабитной** внутренней сети между сервисами. Балансировщик **HAProxy** обеспечивает маршрутизацию внешних запросов и, при необходимости, горизонтальное масштабирование. Автоматические снэпшоты ZFS настроены через `zfs-auto-snapshot` для надежного резервного копирования.
|
||
|
||
## 3. Уникальность решения
|
||
|
||
1. **Гибридный RAG (dense + sparse) с самокритикой и централизованным ядром** — не используется в корпоративных ботах массово. Коммерческие решения часто ограничиваются простым семантическим поиском без переранжирования и самокритики. Вынесение RAG-логики в отдельный HTTP-сервис позволяет легко масштабировать и подключать любые клиентские интерфейсы.
|
||
|
||
2. **Персональный ассистент как часть экосистемы** — типичные персональные ассистенты не имеют доступа к внутренней базе знаний и не умеют отвечать на сложные вопросы по документам. Эфцекабот объединяет общие и персональные функции в едином RAG-ядре, при этом каждый бот-профиль использует свои промпты, что позволяет гибко настраивать поведение под конкретные задачи.
|
||
|
||
3. **Единая чат-среда и единый RAG-бэкенд для всех коммуникаций** — не требуется переключаться между десятками каналов (чат-боты в Telegram, веб-формы, почта). Весь документооборот, командировки, экспертные вопросы — в одном интерфейсе (корпоративном мессенджере), а при необходимости те же функции доступны через Telegram или веб-интерфейс благодаря универсальному HTTP API RAG-ядра.
|
||
|
||
4. **Полный контроль над данными** — все компоненты развернуты внутри компании. Никакие документы или переписка не покидают периметр. История и документы хранятся только на серверах компании.
|
||
|
||
5. **Открытая агентная архитектура** — можно подключить любого RPA, внешнее API, 1С, SAP, календарь, тревел-агрегатор без необходимости переписывать ядро бота — достаточно реализовать HTTP-клиент к RAG-ядру. Конкуренты, как правило, предлагают закрытые экосистемы.
|
||
|
||
6. **Автоматическая индексация файлов в комнатах** — файл, попавший в групповой чат, автоматически становится доступен всей команде через RAG-ядро. Даже у Slack и Teams нет такой функции «из коробки».
|
||
|
||
7. **Встроенные инновационные техники** — SOMA-анализ (LLM-as-judge), ReAct (вызов внешних инструментов), планирование действий, многоагентность — позволяют повысить качество ответов, экономить токены и автоматизировать сложные рабочие процессы.
|
||
|
||
## 4. Преимущества и недостатки работы бота в чате
|
||
|
||
#### Преимущества
|
||
|
||
- **Единое корпоративное окно** — пользователь не переключается между приложениями, получает экспертные ответы прямо в рабочем чате.
|
||
- **Мгновенный обмен файлами** — встроен HTTP Upload, бот автоматически отправляет файлы в RAG-ядро для индексации (в том числе в групповых комнатах).
|
||
- **Учет контекста беседы** — история диалога хранится централизованно в RAG-ядре, что обеспечивает единый контекст для всех клиентов (XMPP, Telegram, веб).
|
||
- **Поддержка комнат (MUC)** — документы, загруженные в комнату, видны всем участникам, а переписка в комнате служит общим контекстом.
|
||
- **Легковесные клиенты** — боты не содержат сложной RAG-логики, что упрощает их обновление и развертывание; все изменения в RAG вносятся в одном месте — RAG-ядре.
|
||
- **Не требует установки уникального клиентского ПО** — достаточно любого XMPP-клиента (Fluux, Conversations, Gajim, Pidgin) или работы через веб-интерфейс (который также может использовать RAG-ядро).
|
||
- **Полный контроль данных** — развертывание внутри периметра, никаких облачных сервисов.
|
||
- **Поддерживаемые форматы**: DOCX, PDF, XLSX, PPTX, TXT, CSV, JSON, изображения (OCR), аудио (SaluteSpeech), архивы ZIP/7z.
|
||
- **Размер загружаемого файла**: до 1 Гб.
|
||
- **Расширенные возможности** — SOMA-оценка ответов, ReAct-вызовы внешних API, планирование, многоагентность, фоновый ReindexWorker для восстановления после сбоев.
|
||
|
||
#### Недостатки
|
||
|
||
- **Задержка** — добавлен сетевой вызов от бота к RAG-ядру (1–2 мс внутри сети) и несколько вызовов GigaChat (3–10 секунд). Однако благодаря кэшированию (классификация, расширение, эмбеддинги, SOMA) и локальному кросс-энкодеру итоговое время ответа в большинстве случаев составляет 3–7 секунд, что приемлемо для экспертной системы.
|
||
- **Сложность отладки** — распределенная система (RAG-ядро, боты-клиенты, ejabberd, PostgreSQL, Qdrant) усложняет трассировку ошибок, но централизованное логирование, структурированные JSON-логи и единая точка входа (RAG-ядро) упрощают мониторинг.
|
||
|
||
## 5. Как чат-бот влияет на работу с GigaChat
|
||
|
||
| Аспект | Влияние |
|
||
| ------ | ------- |
|
||
| **Скорость** | GigaChat — облачный API, задержка ~1–2 секунды на вызов. В текущей архитектуре все вызовы GigaChat происходят только из RAG-ядра (не из ботов). Пайплайн может делать 2–4 вызова на запрос (классификация, расширение, генерация, критика, SOMA). Благодаря общему кэшированию (TTL 5 минут) для классификации и расширения, а также локальному кросс-энкодеру для переранжирования, количество вызовов GigaChat сокращено до минимума, что снижает итоговую задержку до 3–7 секунд. |
|
||
| **Экономия токенов** | Переранжирование и гибридный поиск (sparse + dense) уменьшают объем контекста. История диалога обрезается точно по токенам (через tiktoken) с пагинацией. Дополнительно внедрено иерархическое резюмирование для сжатия длинных диалогов и документов, что еще больше экономит токены. Централизация также позволяет агрегировать кэши и общие эмбеддинги, снижая общие затраты на токены. Кэширование SOMA-оценок (TTL 5 мин) избегает повторных вызовов. |
|
||
| **Качество ответа** | GigaChat хорошо понимает русский язык, отлично справляется с деловой и технической терминологией. Но без точного промпта и контекста возможны галлюцинации — самокритика и перегенерация, выполняемые в RAG-ядре, частично нивелируют это. Дополнительно внедрен SOMA-анализ (LLM-as-judge), который оценивает ответ по 5 критериям и при низких оценках перегенерирует его. ReAct и планирование повышают точность сложных расчётов и инструкций. Единые промпты для всех клиентов упрощают тонкую настройку качества. Иерархическое резюмирование помогает сохранить ключевую информацию в длинных документах. |
|
||
| **Надежность** | GigaChat имеет лимиты и может выдавать ошибки. RAG-ядро делает несколько попыток при эмбеддингах и генерации (retry с экспоненциальной задержкой), а также использует circuit breaker для защиты от сбоев. При отказе API возвращается сообщение о недоступности. Централизация позволяет реализовать единые политики повторных попыток и fallback. RAGClient устойчив к сетевым ошибкам (ClientConnectorError и др.). |
|
||
| **Гибридные векторы** | GigaChat генерирует только dense-эмбеддинги, sparse-векторы вычисляются через FastEmbed (`Qdrant/bm25`) локально на сервере RAG-ядра. Это разгружает GigaChat и не требует дополнительных API, а также позволяет использовать общий кэш эмбеддингов для всех клиентов. |
|
||
|
||
## 6. Архитектура проекта
|
||
|
||
### 6.1. Общая архитектура
|
||
|
||
Платформа состоит из трех основных логических слоев.
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────────────────────────-┐
|
||
│ ВНЕШНИЕ КЛИЕНТЫ (пользователи) │
|
||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
||
│ │ XMPP-боты │ │ Telegram │ │ Mastodon │ │ Веб-интерф. │ │ API │ │
|
||
│ │ (тонкие) │ │ (клиент) │ │ (клиент) │ │ (клиент) │ │ интеграции │ │
|
||
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
|
||
│ │ │ │ │ │ │
|
||
│ └────────────────┼────────────────┼────────────────┼────────────────┘ │
|
||
│ │ │ │ │
|
||
│ ▼ ▼ ▼ │
|
||
│ ┌────────────────────────────────────────────────────────────────────────────────-┐ │
|
||
│ │ RAG-Сервер (HTTP API / FastAPI) │ │
|
||
│ │ │ │
|
||
│ │ ┌──────────────────────────────────────────────────────────────────────────-┐ │ │
|
||
│ │ │ RAG Orchestrator (ядро) │ │ │
|
||
│ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │
|
||
│ │ │ │ History │ │ Intent │ │ Query │ │ Indexing │ │ │ │
|
||
│ │ │ │ Manager │ │ Router │ │ Processor │ │ Manager │ │ │ │
|
||
│ │ │ └──────────────┘ └──────────────┘ └──────┬───────┘ └──────────────────┘ │ │ │
|
||
│ │ │ │ │ │ │
|
||
│ │ │ ┌────────────────────────────────────────┼───────────────────────────-┐ │ │ │
|
||
│ │ │ │ Дополнительные модули │ │ │ │ │
|
||
│ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────┴───-───┐ ┌──────────────┐ │ │ │ │
|
||
│ │ │ │ │ SOMA │ │ ReAct │ │ Planning │ │ Agents │ │ │ │ │
|
||
│ │ │ │ │ (LLM-as- │ │ (внешние │ │ (генерация │ │ (методолог, │ │ │ │ │
|
||
│ │ │ │ │ judge) │ │ вызовы) │ │ плана) │ │ коробочник, │ │ │ │ │
|
||
│ │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ ассистент) │ │ │ │ │
|
||
│ │ │ │ └──────────────┘ │ │ │ │
|
||
│ │ │ │ ┌─────────────────────────────────────────────────────────────────┐│ │ │ │
|
||
│ │ │ │ │ ToolHandler (реальные инструменты) ││ │ │ │
|
||
│ │ │ │ │ search() │ get_weather() │ book_flight() │ exchange() ││ │ │ │
|
||
│ │ │ │ └─────────────────────────────────────────────────────────────────┘│ │ │ │
|
||
│ │ │ └─────────────────────────────────────────────────────────────────────┘ │ │ │
|
||
│ │ └──────────────────────────────────────────────────────────────────────────-┘ │ │
|
||
│ │ │ │
|
||
│ │ ┌────────────────────────────────────────────────────────────────────────-──┐ │ │
|
||
│ │ │ ReindexWorker (фоновый воркер) │ │ │
|
||
│ │ │ переиндексация документов с indexed=False │ │ │
|
||
│ │ └─────────────────────────────────────────────────────────────────────────-─┘ │ │
|
||
│ │ │ │
|
||
│ │ ┌──────────────────────────────────────────────────────────────────────────-┐ │ │
|
||
│ │ │ Эндпоинты REST API │ │ │
|
||
│ │ │ /rag/query /rag/index /rag/vision /rag/transcribe │ │ │
|
||
│ │ │ /rag/clear /rag/list /rag/delete_global │ │ │
|
||
│ │ │ /rag/template/* /rag/reset_history /rag/room/* /rag/stats │ │ │
|
||
│ │ │ /rag/generate_document │ │ │
|
||
│ │ │ /health /docs /redoc /openapi.json /metrics │ │ │
|
||
│ │ └──────────────────────────────────────────────────────────────────────────-┘ │ │
|
||
│ └────────────────────────────────────────────────────────────────────────────────-┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌────────────────────────────────────────────────────────────────────────────────-┐ │
|
||
│ │ ВНЕШНИЕ СИСТЕМЫ (данные и API) │ │
|
||
│ │ │ │
|
||
│ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌─────────────┐ │ │
|
||
│ │ │PostgreSQL │ │ Qdrant │ │ GigaChat │ │ Redis │ │ Файлы │ │ │
|
||
│ │ │(история, │ │(векторный │ │ (генерация│ │ (кэш эм- │ │ (DOCX, │ │ │
|
||
│ │ │ документы,│ │ поиск, │ │ эмбеддинги│ │ беддингов,│ │ PDF, │ │ │
|
||
│ │ │ права, │ │ гибридный │ │ Vision) │ │ SOMA) │ │ XLSX, │ │ │
|
||
│ │ │ шаблоны, │ │ dense+ │ │ │ │ │ │ PPTX, │ │ │
|
||
│ │ │ file_text│ │ sparse) │ │ │ │ │ │ аудио, │ │ │
|
||
│ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │ изображ.) │ │ │
|
||
│ │ └─────────────┘ │ │
|
||
│ │ │ │
|
||
│ │ ┌──────────────────────────────────────────────────────────────────────────┐ │ │
|
||
│ │ │ ВНЕШНИЕ API (инструменты) │ │ │
|
||
│ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌─────────────┐ │ │ │
|
||
│ │ │ │ DuckDuckGo │ │OpenWeatherMap│ │ Booking API │ │ Exchange │ │ │ │
|
||
│ │ │ │ (поиск) │ │ (погода) │ │ (заглушка) │ │ Rate API │ │ │ │
|
||
│ │ │ │ │ │ │ │ │ │ (заглушка) │ │ │ │
|
||
│ │ │ └──────────────┘ └──────────────┘ └──────────────┘ └─────────────┘ │ │ │
|
||
│ │ └──────────────────────────────────────────────────────────────────────────┘ │ │
|
||
│ └───────────────────────────────────────────────────────────────────────────────-─┘ │
|
||
└─────────────────────────────────────────────────────────────────────────────────────-─┘
|
||
```
|
||
|
||
**Ключевые компоненты**:
|
||
|
||
- **RAG-сервер** — единая точка входа для всех RAG-запросов. Содержит всю бизнес-логику (поиск, генерацию, самокритику, индексацию). Запускается как отдельный HTTP-сервис.
|
||
- **RAG Orchestrator** — фасад, координирующий менеджеры и модули:
|
||
- `HistoryManager` — управление историей (пагинация, сжатие).
|
||
- `IntentRouter` — маршрутизация специализированных намерений.
|
||
- `QueryProcessor` — интеграция SOMA, ReAct, планирования и агентов.
|
||
- `IndexingManager` — индексация с предварительным сжатием.
|
||
- **Дополнительные модули**:
|
||
- **SOMA (LLM-as-judge)** — оценка ответов с кэшированием.
|
||
- **ReAct** — вызов внешних инструментов (поиск, погода, бронирование, курс).
|
||
- **Planning** — генерация пошагового плана.
|
||
- **Agents** — многоагентная архитектура (методолог, коробочник, ассистент).
|
||
- **ToolHandler** — реальные обработчики инструментов.
|
||
- **ReindexWorker** — фоновый воркер для переиндексации документов после сбоев.
|
||
- **Эндпоинты** — основные, административные, управление шаблонами, комнатами, статистика, генерация документов, health, метрики.
|
||
- **Внешние системы** — PostgreSQL (с `file_text`, управление через Alembic), Qdrant (гибридный поиск), GigaChat, Redis (кэширование), файлы, внешние API.
|
||
|
||
### 6.2. Структура каталогов проекта
|
||
|
||
Проект организован по принципу разделения ответственности: RAG-сервер и боты-клиенты имеют свои независимые каталоги. Тесты вынесены в корень проекта.
|
||
|
||
```
|
||
/usr/local/etc/fckbot/ # КОРЕНЬ ПРОЕКТА
|
||
│
|
||
├── alembic.ini # Конфигурация Alembic (миграции)
|
||
│
|
||
├── rag/ # RAG-ядро (HTTP-сервер)
|
||
│ ├── alembic/ # Миграции PostgreSQL
|
||
│ │ ├── env.py # Настройка окружения для Alembic
|
||
│ │ ├── script.py.mako # Шаблон для миграций
|
||
│ │ └── versions/ # Папка с миграциями
|
||
│ ├── auth.py # Аутентификация (проверка API-ключа)
|
||
│ ├── config_models.py # Pydantic-модели для конфигурации (AppConfig)
|
||
│ ├── create_qdrant_collection.py # Скрипт создания коллекции в Qdrant
|
||
│ ├── history_manager.py # Менеджер истории диалогов (сжатие, пагинация, обрезка)
|
||
│ ├── indexing_manager.py # Менеджер индексации документов (сжатие, вызов KBService)
|
||
│ ├── intent_router.py # Маршрутизатор специализированных намерений
|
||
│ ├── prompt_builder.py # Построитель промтов (few-shot, сэндвич, санитизация)
|
||
│ ├── query_processor.py # Обработчик RAG-запросов (поиск, синтез, критика, SOMA, ReAct, планирование, агенты)
|
||
│ ├── rag_api.py # Локальный API-интерфейс (facade)
|
||
│ ├── rag.conf.example # Шаблон конфига RAG-сервера (YAML): БД, Qdrant, GigaChat, Redis, новые параметры
|
||
│ ├── rag_orchestrator.py # Оркестратор RAG-пайплайна (менеджеры, ToolHandler)
|
||
│ ├── rag_server.py # HTTP-сервер на FastAPI + Uvicorn (точка входа)
|
||
│ ├── README.md # Документация (этот файл)
|
||
│ ├── requirements.txt # Зависимости Python (включая tenacity, pybreaker, redis, aioredis, python-json-logger)
|
||
│ ├── schema.sql # Схема PostgreSQL (используется только для тестов; в продакшене — Alembic)
|
||
│ ├── functions/ # Чистые функции (без состояния)
|
||
│ │ ├── check_consistency.py # Проверка противоречий
|
||
│ │ ├── check_spelling.py # Проверка орфографии
|
||
│ │ ├── critique_answer.py # Самокритика ответа
|
||
│ │ ├── expand_query.py # Расширение запроса
|
||
│ │ ├── extract_metrics.py # Извлечение KPI в JSON
|
||
│ │ ├── file_processor.py # Обработка файлов, теги SURGICAL_REPLACE и др.
|
||
│ │ ├── generate_document.py # Генерация документа по шаблону
|
||
│ │ ├── hierarchical_summarize.py # Иерархическое резюмирование
|
||
│ │ ├── intent_classify.py # Классификация намерений
|
||
│ │ ├── plan_generation.py # Генерация плана действий (новый)
|
||
│ │ ├── react.py # Цикл ReAct (вызов внешних инструментов)
|
||
│ │ ├── rerank_context.py # Переранжирование контекста
|
||
│ │ ├── soma_evaluate.py # SOMA-анализ (LLM-as-judge) с кэшированием
|
||
│ │ ├── summarize_document.py # Суммаризация документа
|
||
│ │ └── tools.py # Реальные обработчики инструментов (поиск, погода, бронирование, курс)
|
||
│ ├── services/ # Сервисы (долгоживущие компоненты)
|
||
│ │ ├── embedding_service.py # Эмбеддинги GigaChat с кэшированием (Redis + локальный)
|
||
│ │ ├── file_service.py # Извлечение текста из файлов, транскрибация (экранирование путей)
|
||
│ │ ├── giga_client.py # Клиент GigaChat с retry и circuit breaker
|
||
│ │ ├── kb_service.py # База знаний (индексация, поиск, управление доступом, file_text)
|
||
│ │ ├── postgres_service.py # Пул соединений с PostgreSQL (с проверкой таблиц, Alembic)
|
||
│ │ ├── qdrant_service.py # Векторная БД (гибридный поиск, полнотекстовый, индексы)
|
||
│ │ └── reranker_service.py # Кросс-энкодер с асинхронной загрузкой модели
|
||
│ ├── utils/ # Утилиты
|
||
│ │ ├── arg_parser.py # Парсинг аргументов командной строки
|
||
│ │ ├── config_loader.py # Загрузка конфигов, слияние, создание AppConfig
|
||
│ │ ├── logger.py # Настройка логирования (с поддержкой JSON-формата)
|
||
│ │ ├── text_utils.py # Разбиение на чанки, подсчет токенов
|
||
│ │ └── web_utils.py # Веб-скрапинг (с ограничением размера)
|
||
│ └── workers/ # Фоновые воркеры
|
||
│ └── reindex_worker.py # Переиндексация документов с indexed=False
|
||
│
|
||
├── bots/ # ОБЩИЙ КОД БОТОВ-КЛИЕНТОВ
|
||
│ ├── bot.py # Точка входа для запуска XMPP-бота (принимает --profile-dir)
|
||
│ ├── rag_client.py # HTTP-клиент для связи с RAG-сервером (асинхронный, с повторными попытками)
|
||
│ ├── commands/ # Команды ботов (XMPP-интерфейс)
|
||
│ │ ├── base.py # Базовый класс Command (алиасы, права доступа, кэширование)
|
||
│ │ ├── create.py # !create – генерация документа по шаблону
|
||
│ │ ├── expert.py # !summary, !metrics – экспертные функции
|
||
│ │ ├── global_remove.py # !global_remove – удаление глобального документа (админ)
|
||
│ │ ├── help.py # !help – подробная справка по командам
|
||
│ │ ├── info.py # !info – краткая справка
|
||
│ │ ├── kb.py # !clear, !global_clear, !kb – управление базой знаний
|
||
│ │ ├── learn.py # !learn, !stop_learn, !global_learn – режим обучения
|
||
│ │ ├── other.py # !reset – сброс истории
|
||
│ │ ├── registry.py # Регистрация команд, алиасы, подсказки при опечатке
|
||
│ │ ├── stats.py # !stats, !status, !clean – администрирование
|
||
│ │ └── template.py # !template_save, !template_list, !template_delete – шаблоны
|
||
│ ├── handlers/ # Обработчики XMPP событий
|
||
│ │ ├── file_handler.py # Скачивание файлов и постановка в очередь индексации
|
||
│ │ ├── health_handler.py # Очистка временных файлов, healthcheck БД/Qdrant (для клиентов)
|
||
│ │ ├── message_handler.py # Маршрутизация входящих сообщений (команды, файлы, AI-запросы) – использует RAGClient
|
||
│ │ ├── metrics_handler.py # Счетчики (сообщения, файлы, AI-запросы, ошибки)
|
||
│ │ ├── room_handler.py # MUC комнаты (приглашения, вход, переподключение)
|
||
│ │ └── subscription_handler.py # Подписки (roster subscription)
|
||
│ ├── workers/ # Фоновые воркеры
|
||
│ │ └── indexing_worker.py # Индексация файлов и URL (отправляет на RAG-сервер через RAGClient)
|
||
│ └── xmpp/ # XMPP-клиент
|
||
│ └── client.py # Основной класс Bot (наследует slixmpp.ClientXMPP)
|
||
│
|
||
├── template_bot_profile/ # ШАБЛОН ПРОФИЛЯ (для создания новых ботов)
|
||
│ ├── bot.conf.sample # Пример конфига бота-клиента (копируется в bot.conf)
|
||
│ ├── data/ # Каталог для постоянных копий файлов
|
||
│ │ └── fewshot_examples.json # Примеры few-shot (можно редактировать)
|
||
│ ├── prompts/ # Пример промптов (копируются в профиль)
|
||
│ │ ├── consistency_check.txt # Проверка противоречий между фрагментами
|
||
│ │ ├── expand.txt # Расширение запроса (синонимы, аббревиатуры)
|
||
│ │ ├── generate_document.txt # Генерация документа по шаблону
|
||
│ │ ├── hierarchical_summary.txt # Иерархическое резюмирование
|
||
│ │ ├── intent_classify.txt # Классификация намерений
|
||
│ │ ├── metrics_extract.txt # Извлечение KPI в JSON
|
||
│ │ ├── quality_criteria.txt # Дополнительные критерии качества ответа
|
||
│ │ ├── self_critique.txt # Самокритика ответа
|
||
│ │ ├── smart_summary.txt # Суммаризация документа
|
||
│ │ ├── spellcheck.txt # Проверка орфографии и пунктуации
|
||
│ │ ├── synthesis.txt # Шаблон синтеза ответа
|
||
│ │ ├── soma_evaluate.txt # Промпт для SOMA
|
||
│ │ ├── react_system.txt # Системный промпт для ReAct
|
||
│ │ ├── planning.txt # Промпт для генерации плана
|
||
│ │ └── system.txt # Системный промпт (роль, стиль, правила)
|
||
│ └── temp/ # Пустой каталог для временных файлов
|
||
│
|
||
├── tests/ # ЮНИТ-ТеТЫ (общие для всего проекта)
|
||
│ ├── conftest.py # Фикстуры и моки для pytest
|
||
│ ├── test_check_spelling.py # Тесты проверки орфографии
|
||
│ ├── test_consistency.py # Тесты проверки противоречий
|
||
│ ├── test_critique.py # Тесты самокритики
|
||
│ ├── test_expand_query.py # Тесты расширения запроса
|
||
│ ├── test_extract_metrics.py # Тесты извлечения метрик
|
||
│ ├── test_hierarchical_summary.txt # Тесты иерархического резюмирования
|
||
│ ├── test_intent_classify.py # Тесты классификации намерений
|
||
│ └── test_summarize.py # Тесты суммаризации
|
||
│
|
||
├── venv/ # ВИРТУАЛЬНОЕ ОКРУЖЕНИЕ Python
|
||
│ ├── bin/ # Исполняемые файлы (python, pip, activate)
|
||
│ ├── lib/ # Установленные библиотеки
|
||
│ └── ...
|
||
│
|
||
└── .env.example # ШАБЛОН ПЕРЕМЕННЫХ ОКРУЖЕНИЯ
|
||
├── XMPP_PASSWORD=... # Пароль для XMPP-аккаунта бота
|
||
├── DB_PASSWORD=... # Пароль для PostgreSQL
|
||
├── GIGACHAT_API_KEY=... # API-ключ GigaChat
|
||
├── SALUTE_SPEECH_AUTH=... # Авторизация для SaluteSpeech (голосовые сообщения)
|
||
└── RAG_API_KEY=... # API-ключ для доступа к RAG-серверу (защита эндпоинтов)
|
||
```
|
||
|
||
**Важные примечания**:
|
||
|
||
- Реальные профили ботов создаются администратором вручную вне репозитория.
|
||
- Конфигурационные файлы и переменные окружения не хранятся в репозитории.
|
||
- Управление схемой PostgreSQL — через Alembic (миграции в `rag/alembic/`).
|
||
- Все новые модули (SOMA, ReAct, планирование, агенты, ToolHandler, ReindexWorker) интегрированы в основной пайплайн.
|
||
|
||
### 6.3. Взаимодействие компонентов
|
||
|
||
```
|
||
┌─────────────┐ HTTP ┌─────────────┐ SQL ┌─────────────┐
|
||
│ Пользова- │ ──────────────▶│ RAG- │ ──────────────▶│ PostgreSQL │
|
||
│ тель │ │ сервер │ │ (история, │
|
||
│ (XMPP) │ ◀──────────────│ (ядро) │ ◀──────────────│ документы, │
|
||
└─────────────┘ └─────────────┘ │ file_text) │
|
||
│ │ └─────────────┘
|
||
│ XMPP │ HTTP (gRPC) │
|
||
▼ ▼ ▼
|
||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||
│ ejabberd │ │ Qdrant │ │ GigaChat │
|
||
│ (чат-серв.) │ │ (векторная │ │ (API) │
|
||
└─────────────┘ │ БД) │ └─────────────┘
|
||
│ └─────────────┘ │
|
||
│ XMPP │ │
|
||
▼ ▼ ▼
|
||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||
│ XMPP-бот │ │ FastEmbed │ │ Файлы │
|
||
│ (тонкий) │ │ (локальный │ │ (диск) │
|
||
│ клиент │ │ кросс-энк.) │ └─────────────┘
|
||
└─────────────┘ └─────────────┘
|
||
│ │ │
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||
│ Redis │ │ Tool- │ │ Reindex- │
|
||
│ (кэш эм- │ │ Handler │ │ Worker │
|
||
│ беддингов, │ │ (внешние │ │ (фоновый) │
|
||
│ SOMA) │ │ API) │ └─────────────┘
|
||
└─────────────┘ └─────────────┘
|
||
```
|
||
|
||
**Поток данных**:
|
||
|
||
1. **Запрос пользователя** → XMPP-бот → HTTP → RAG-сервер.
|
||
2. RAG-сервер:
|
||
- Получает историю из PostgreSQL (с пагинацией и обрезкой).
|
||
- Выполняет классификацию намерений.
|
||
- При необходимости вызывает SOMA, ReAct, планирование, агентов.
|
||
- Ищет в Qdrant (гибридный поиск), переранжирует, генерирует ответ через GigaChat.
|
||
- Выполняет самокритику и SOMA-оценку, при низких оценках перегенерирует.
|
||
- Сохраняет историю в PostgreSQL.
|
||
3. **Ответ** → HTTP → XMPP-бот → ejabberd → пользователь.
|
||
4. **Индексация файла** → XMPP-бот → HTTP → RAG-сервер → разбиение на чанки, эмбеддинги (кэшируются в Redis), сохранение в Qdrant и PostgreSQL (с `file_text`).
|
||
5. **OCR/транскрибация** → XMPP-бот → HTTP → RAG-сервер → распознанный текст.
|
||
6. **ReindexWorker** периодически проверяет документы с `indexed=False` и переиндексирует их, используя сохранённый `file_text`.
|
||
7. **ReAct** вызывает внешние API через ToolHandler (поиск, погода, бронирование, курс).
|
||
|
||
### 6.4. Тестирование
|
||
|
||
Проект покрыт unit-тестами и интеграционными тестами.
|
||
|
||
**Unit-тесты** (в `tests/`) проверяют критически важные функции:
|
||
|
||
- классификацию намерений (`test_intent_classify.py`);
|
||
- расширение запроса (`test_expand_query.py`);
|
||
- извлечение метрик (`test_extract_metrics.py`);
|
||
- суммаризацию (`test_summarize.py`);
|
||
- проверку противоречий (`test_consistency.py`);
|
||
- самокритику (`test_critique.py`);
|
||
- проверку орфографии (`test_check_spelling.py`);
|
||
- иерархическое резюмирование (`test_hierarchical_summarize.py`).
|
||
|
||
**Интеграционные тесты** (в `tests/integration/`) проверяют:
|
||
|
||
- эндпоинты RAG-сервера (`test_endpoints.py`) – `/rag/clear`, `/rag/list`, `/rag/delete_global`, `/rag/template/*`, `/rag/reset_history`, `/rag/room/*`, `/rag/stats`, `/rag/generate_document`.
|
||
- переработанные команды бота (`test_commands.py`) – `!clear`, `!kb`, `!global_remove`, `!reset`, `!template_*`, `!stats`, `!status`, `!create`, `!summary`, `!metrics`, `!learn` и др.
|
||
|
||
**Запуск всех тестов**:
|
||
|
||
```bash
|
||
cd /usr/local/etc/fckbot
|
||
source venv/bin/activate
|
||
pytest tests/ -v
|
||
```
|
||
|
||
Для тестирования RAG-сервера отдельно можно использовать `curl` или Postman.
|
||
|
||
### 6.5. Конфигурационные параметры
|
||
|
||
В `bot.conf` доступны следующие параметры RAG-пайплайна (добавлены новые):
|
||
|
||
- **`max_context_tokens`** — лимит токенов для истории диалога (по умолчанию 3000).
|
||
- **`rerank.min_length`** — порог длины контекста для переранжирования (по умолчанию 5000).
|
||
- **`rag_server_url`** — URL RAG-сервера (используется ботами).
|
||
- **`mention_keyword`** — ключевое слово для упоминания бота в группах.
|
||
- **`fewshot`** — настройки few-shot примеров (`max_examples`, `examples_file`).
|
||
|
||
#### Включение/отключение новых функций
|
||
enable_soma: true
|
||
enable_react: true
|
||
enable_planning: true
|
||
enable_agents: true
|
||
enable_reindex: true
|
||
|
||
#### Параметры SOMA
|
||
soma_temperature: 0.1
|
||
soma_threshold: 3.5
|
||
soma_cache_ttl: 300 # TTL кэша SOMA (сек)
|
||
soma_timeout: 30
|
||
|
||
#### Параметры ReAct
|
||
react_temperature: 0.3
|
||
react_max_iterations: 5
|
||
|
||
#### Параметры планирования
|
||
planning_temperature: 0.2
|
||
|
||
#### Параметры ReindexWorker
|
||
reindex_interval: 300 # интервал проверки (сек)
|
||
reindex_batch_size: 10
|
||
|
||
#### Параметры агентов
|
||
agent_temperature: 0.3
|
||
|
||
#### API-ключи для инструментов
|
||
weather_api_key: "" # для OpenWeatherMap
|
||
|
||
#### Redis для кэширования
|
||
redis_url: "redis://localhost:6379"
|
||
|
||
#### Лимиты истории
|
||
max_history_message_length: 10000
|
||
|
||
Эти параметры позволяют гибко настраивать поведение без изменения кода.
|
||
|
||
### 6.6. Основные слои (что есть что)
|
||
|
||
| Слой | Назначение |
|
||
| ---- | ---------- |
|
||
| **RAG-сервер** (`rag_server.py`) | HTTP-сервис, обрабатывающий все RAG-запросы. Содержит оркестратор, ReindexWorker, ToolHandler. Предоставляет эндпоинты для команд бота, статистики, шаблонов, комнат. |
|
||
| **RAG-оркестратор** (`rag_orchestrator.py`) | Фасад, координирующий менеджеры и модули. Содержит `HistoryManager`, `IntentRouter`, `QueryProcessor`, `IndexingManager`. |
|
||
| **Менеджер истории** (`history_manager.py`) | Получение истории из БД, сжатие (иерархическое резюмирование), сохранение новых сообщений. Поддерживает пагинацию и обрезку сообщений. |
|
||
| **Маршрутизатор намерений** (`intent_router.py`) | Обрабатывает специализированные намерения (METRICS, SUMMARY, CONTRADICTION, TEMPLATE_FILL, SURGICAL, GREETING, SPELLCHECK). |
|
||
| **Процессор запросов** (`query_processor.py`) | Выполняет RAG-пайплайн с интеграцией SOMA, ReAct, планирования и агентов. Использует ToolHandler для вызова внешних инструментов. |
|
||
| **Построитель промтов** (`prompt_builder.py`) | Динамический подбор few-shot, санитизация пользовательских данных, структура «сэндвич». |
|
||
| **Менеджер индексации** (`indexing_manager.py`) | Сжимает большие документы, вызывает KBService. |
|
||
| **HTTP-клиент** (`rag_client.py`) | Используется ботами для отправки запросов к RAG-серверу. Асинхронный, с повторными попытками. |
|
||
| **Сервисы** (`services/`) | Долгоживущие компоненты: PostgreSQL, Qdrant, эмбеддинги, база знаний, файлы, GigaChat, переранжирование. |
|
||
| **Функции** (`functions/`) | Чистые функции: классификация, расширение, суммаризация, проверка противоречий, самокритика, иерархическое резюмирование, SOMA, ReAct, планирование, генерация плана, инструменты. |
|
||
| **XMPP-боты-клиенты** (`xmpp/client.py`) | Тонкие клиенты, только XMPP-логика и команды, все RAG-запросы через `rag_client.py`. |
|
||
| **Обработчики XMPP** (`handlers/`) | Реагируют на события XMPP, маршрутизируют запросы. |
|
||
| **Воркеры** (`workers/`) | Фоновые задачи: `indexing_worker` (индексация файлов и URL) и `reindex_worker` (переиндексация после сбоев). |
|
||
| **Команды** (`commands/`) | Реализуют команды бота, используют только `RAGClient`. |
|
||
| **Утилиты** (`utils/`) | Вспомогательные функции (конфигурация, логирование, чанкинг, веб-скрапинг, парсинг аргументов). |
|
||
| **Alembic** (`alembic/`) | Управление версиями схемы PostgreSQL. |
|
||
|
||
|
||
## 7. Функции бота
|
||
|
||
Ниже представлен полный перечень функций платформы Эфцекабот, доступных пользователям. Каждая функция описана максимально детально: указано, что она делает, в чем ее уникальность, какая от нее польза, а также приведены **все возможные сценарии использования** — от простых запросов до сложных рабочих процессов.
|
||
|
||
### Ранжирование по ценности
|
||
|
||
| Место | Функция | Обоснование |
|
||
| ----- | ------- | ----------- |
|
||
| **1** | Генерация по шаблону | Основной инструмент для создания коробочных решений — автоматизирует производство документов. |
|
||
| **2** | Гибридный RAG | Без него бот не может отвечать по документам — фундамент системы. |
|
||
| **3** | Комнатные/глобальные БЗ | Обеспечивают коллективную работу над коробочными решениями. |
|
||
| **4** | SOMA-анализ (LLM-as-judge) | Значительно повышает качество ответов, экономит токены за счёт кэширования. |
|
||
| **5** | ReAct (вызов внешних инструментов) | Открывает возможность выполнения реальных действий (поиск, погода, бронирование). |
|
||
| **6** | Планирование действий | Повышает точность расчётов и инструкций. |
|
||
| **7** | Многоагентность | Позволяет специализировать ботов под разные роли, повышая качество экспертных ответов. |
|
||
| **8** | Хирургическая замена | Ускоряет доработку документов. |
|
||
| **9** | Проверка орфографии | Повышает качество исходящих документов. |
|
||
| **10** | Суммаризация | Ускоряет анализ больших объемов информации. |
|
||
| **11** | Самокритика | Повышает надежность ответов. |
|
||
| **12** | Извлечение метрик | Автоматизирует сбор KPI. |
|
||
| **13** | Проверка противоречий | Исключает ошибки в документации. |
|
||
| **14** | Классификация намерений | Обеспечивает интеллектуальную маршрутизацию. |
|
||
| **15** | Цепочка рассуждений | Повышает точность расчетов и инструкций. |
|
||
| **16** | Полнотекстовый поиск | Гарантирует юридическую точность и поиск инструкций. |
|
||
| **17** | Расширение запроса | Улучшает полноту поиска. |
|
||
| **18** | Переранжирование | Экономит токены и повышает точность. |
|
||
| **19** | Автоиндексация | Упрощает коллективную работу. |
|
||
| **20** | Веб-скрапинг | Интегрирует внешние источники. |
|
||
| **21** | Голосовые сообщения | Удобство для мобильных пользователей. |
|
||
| **22** | Администрирование | Оперативный контроль без доступа к серверу. |
|
||
|
||
## 7.1. Ключевые функции для создания документов (коробочных решений)
|
||
|
||
### **1. Генерация коробочных решений по шаблону**
|
||
|
||
**Что делает**:
|
||
По команде `!create "Коробочное решение"` бот генерирует готовый коробочный документ на основе шаблона, заполняя все плейсхолдеры `{{...}}` данными из базы знаний комнаты. Шаблон содержит следующие разделы (соответствует файлу `Шаблон коробочного решения.docx`):
|
||
|
||
1. **Профиль коробочного решения** — параметры внедрения, ресурсы, сроки.
|
||
2. **Актуальность коробочного решения** — потенциал повышения производительности, задачи, ожидаемые результаты.
|
||
3. **Решаемая проблема** — типовой процесс (до улучшения), проблемные зоны, коренные причины.
|
||
4. **Решение** — целевой процесс (после улучшения), детальное описание решений, результаты внедрения.
|
||
5. **Алгоритм внедрения коробочного решения** — состав рабочей группы, последовательность этапов.
|
||
6. **Риски** — описание рисков и мер по их снижению.
|
||
7. **Термины, сокращения, определения** — глоссарий из документов комнаты.
|
||
8. **Сопроводительные документы** — перечень приложений, шаблонов, регламентов.
|
||
9. **Лучшие практики** — ссылки на реализованные аналогичные решения.
|
||
|
||
**Уникальность**:
|
||
Превращает бота из информатора в **инструмент производства готовых коробочных решений**. Достаточно один раз настроить шаблон, и бот будет генерировать документы на основе актуальных данных из базы знаний. Все, что требуется от пользователя — загрузить в комнату документы-источники (регламенты, отчеты, методики, ГОСТы, аналитические записки).
|
||
|
||
**Польза**:
|
||
Автоматизация подготовки коробочных решений, сокращение времени на создание документов с 1–2 недель до 10–30 минут, исключение ошибок ручного ввода, единообразие документов, возможность быстрого масштабирования на любые типы организаций.
|
||
|
||
**Примеры использования (все возможные сценарии)**:
|
||
|
||
#### 1.1. Сохранение шаблона коробочного решения
|
||
|
||
Загружаете в чат DOCX-файл `Шаблон коробочного решения.docx` (содержит плейсхолдеры вида `{{DOC_CODE}}`, `{{TARGET_ORG_TYPES}}` и т.д.). Вводите:
|
||
|
||
```
|
||
!template_save "Коробочное решение v1.0"
|
||
```
|
||
|
||
Бот сохраняет шаблон в БД комнаты как `"Коробочное решение v1.0"`. Если шаблон с таким именем уже существует – он перезаписывается.
|
||
|
||
#### 1.2. Просмотр всех шаблонов в комнате
|
||
|
||
```
|
||
!template_list
|
||
```
|
||
|
||
Бот выводит список: «Коробочное решение v1.0», «Коробочное решение v2.0», «Договор поставки» и т.д.
|
||
|
||
#### 1.3. Генерация коробочного решения
|
||
|
||
Вы вводите:
|
||
|
||
```
|
||
!create "Коробочное решение v1.0"
|
||
```
|
||
|
||
Бот выполняет следующие шаги:
|
||
|
||
1. **Извлекает шаблон** из БД комнаты.
|
||
2. **Находит все плейсхолдеры** в шаблоне (их около 70+):
|
||
- Профиль: `{{DOC_CODE}}`, `{{TARGET_ORG_TYPES}}`, `{{TARGET_ORG_COUNT}}`, `{{FINANCIAL_RESOURCES}}`, `{{HUMAN_RESOURCES}}`, `{{IMPLEMENTATION_TERM_MIN}}`, `{{KPI_NAME}}`, `{{KPI_BEFORE}}`, `{{KPI_AFTER}}` и т.д.
|
||
- Актуальность: `{{PROCESS_NAME}}`, `{{DATA_DATE}}`, `{{TOTAL_STAFF}}`, `{{TYPICAL_PROBLEM_DESCRIPTION}}`, `{{PREREQUISITE_1}}`, `{{TASK_1}}`, `{{RESULT_1}}` и т.д.
|
||
- Решаемая проблема: `{{STAGE_1_NAME}}`, `{{STAGE_1_ACTORS}}`, `{{STAGE_1_PROBLEMS}}`, `{{ROOT_CAUSE_1}}` и т.д.
|
||
- Решение: `{{TARGET_STAGE_1_DESC}}`, `{{IMPROVEMENT_1}}`, `{{SOLUTION_1_NAME}}`, `{{SOLUTION_1_DESCRIPTION}}`, `{{KPI_1_NAME}}` и т.д.
|
||
- Алгоритм внедрения: `{{ROLE_1}}`, `{{ROLE_1_DUTIES}}`, `{{STAGE1_DURATION}}`, `{{STAGE1_ACTIONS}}` и т.д.
|
||
- Риски: `{{RISK_1_NAME}}`, `{{RISK_1_DESCRIPTION}}`, `{{RISK_1_MITIGATION}}`.
|
||
- Термины: `{{TERM_1}}`, `{{TERM_1_DEF}}`.
|
||
- Сопроводительные документы: `{{APPENDIX_1_NAME}}`.
|
||
- Лучшие практики: `{{BEST_PRACTICE_1_LINK}}`, `{{BEST_PRACTICE_1_DESC}}`.
|
||
|
||
3. **Для каждого плейсхолдера выполняет поиск** в базе знаний комнаты (личные + комнатные + глобальные документы). Поиск использует:
|
||
- Семантический поиск (dense-эмбеддинги) — для общих запросов.
|
||
- Полнотекстовый поиск (MatchText) — для точных цитат и номеров пунктов.
|
||
- Расширение запроса (query expansion) — добавляет синонимы и аббревиатуры.
|
||
- Переранжирование (кросс-энкодер) — отбирает только релевантные фрагменты.
|
||
|
||
4. **Формирует промпт для GigaChat** с инструкцией заполнить плейсхолдер на основе найденных фрагментов. Промпт содержит контекст из фрагментов документов и сам плейсхолдер.
|
||
|
||
5. **Генерирует значение для каждого плейсхолдера** — например, для `{{TYPICAL_PROBLEM_DESCRIPTION}}` GigaChat напишет: «В региональной системе наблюдается дефицит сотрудников с профильным образованием (только 30% из 100), нерегулярное планирование, отсутствие единой методики оценки компетенций».
|
||
|
||
6. **Заменяет плейсхолдеры в копии шаблона**, сохраняя все форматирование (жирный шрифт, курсив, цвета, таблицы, колонтитулы). Замена выполняется с учетом возможного разбиения текста на несколько `runs` в DOCX, что повышает точность.
|
||
|
||
7. **Отправляет готовый DOCX-файл в чат**.
|
||
|
||
**Пример заполнения (фрагменты)**:
|
||
|
||
```
|
||
**{{DOC_CODE}}** → **КР-5S-2025-001**
|
||
**{{TARGET_ORG_TYPES}}** → «Библиотеки, культурно-досуговые учреждения»
|
||
**{{TARGET_ORG_COUNT}}** → «47»
|
||
**{{FINANCIAL_RESOURCES}}** → «1 200»
|
||
**{{HUMAN_RESOURCES}}** → «5»
|
||
**{{IMPLEMENTATION_TERM_MIN}}** → «3»
|
||
**{{KPI_NAME}}** → «Процент сотрудников с профильным образованием»
|
||
**{{KPI_BEFORE}}** → «30%»
|
||
**{{KPI_AFTER}}** → «85%»
|
||
```
|
||
|
||
#### 1.4. Обновление коробочного решения
|
||
|
||
Если вы улучшили шаблон или изменили структуру, загружаете новую версию DOCX и повторяете:
|
||
|
||
```
|
||
!template_save "Коробочное решение v1.0"
|
||
```
|
||
|
||
Старый шаблон перезаписывается новым. Все последующие генерации будут использовать обновленный шаблон.
|
||
|
||
#### 1.5. Удаление шаблона
|
||
|
||
```
|
||
!template_delete "Коробочное решение v1.0"
|
||
```
|
||
|
||
Шаблон удаляется из БД комнаты.
|
||
|
||
#### 1.6. Кастомизация шаблона под конкретный проект
|
||
|
||
Вы можете создать несколько версий шаблона для разных типов организаций или отраслей:
|
||
|
||
```
|
||
!template_save "Коробочное решение_Библиотеки"
|
||
!template_save "Коробочное решение_Музеи"
|
||
!template_save "Коробочное решение_Образование"
|
||
```
|
||
|
||
Затем генерировать нужную версию:
|
||
|
||
```
|
||
!create "Коробочное решение_Библиотеки"
|
||
```
|
||
|
||
#### 1.7. Использование общих знаний (если разрешено)
|
||
|
||
Если для какого-то плейсхолдера не нашлось данных в БЗ (например, `{{BEST_PRACTICE_1_LINK}}`), бот может использовать свои общие знания для заполнения (если в конфиге `allow_public_knowledge: true`). Это полезно для лучших практик и терминов.
|
||
|
||
#### 1.8. Многоязычность
|
||
|
||
Если в документах есть информация на иностранном языке, бот переведет ее на язык шаблона (русский) и заполнит плейсхолдер.
|
||
|
||
**Пример**: плейсхолдер `{{KPI_NAME}}` – бот найдет в английских документах «Overall Equipment Effectiveness» и переведет как «Общая эффективность оборудования» (или оставит аббревиатуру OEE, если так указано в документах).
|
||
|
||
### **2. Гибридный RAG с самокритикой**
|
||
|
||
**Что делает**:
|
||
Это ядро системы, которое используется для поиска данных для каждого плейсхолдера шаблона. Бот выполняет:
|
||
- Семантический поиск (dense-эмбеддинги от GigaChat);
|
||
- Ключевой поиск (sparse-векторы BM25 от FastEmbed);
|
||
- Объединение через Reciprocal Rank Fusion (RRF);
|
||
- Генерацию ответа через GigaChat;
|
||
- Проверку через самокритику (оценка по 5 критериям);
|
||
- Перегенерацию при необходимости.
|
||
|
||
**Уникальность**:
|
||
Комбинация двух типов поиска + самокритика – это значительно повышает точность и доверие к ответам. Редкая функция для корпоративных ботов.
|
||
|
||
**Польза**:
|
||
Гарантирует, что ответ или каждое значение в коробочном решении основано на реальных документах, а не на выдумках LLM. Это критично для юридической и финансовой достоверности. Это фундамент, без которого остальные функции теряют смысл.
|
||
|
||
**Примеры использования**:
|
||
|
||
1. **Фактологический вопрос (FACT)**:
|
||
- «Какое тактовое время установлено на линии сборки?»
|
||
- Бот ищет в документах (регламент линии, паспорт оборудования) и выдает точное значение с указанием источника:
|
||
`Тактовое время на линии сборки составляет 120 секунд. [Источник: Регламент_линии_2025.docx]`
|
||
|
||
2. **Инструкция / процедура (PROCEDURE)**:
|
||
- «Как рассчитать OEE для станка?»
|
||
- Бот находит алгоритм расчета в методических документах и выдает пошаговое руководство (с цепочкой рассуждений).
|
||
|
||
3. **Сравнение показателей (COMPARISON)**:
|
||
- «Сравни производительность труда до и после внедрения кайдзен»
|
||
- Бот находит данные в отчетах (по периодам) и выдает сравнительный анализ с цифрами.
|
||
|
||
4. **Расчет по формуле (CALCULATION)**:
|
||
- «Рассчитай ожидаемую выработку на следующую смену при загрузке 120%»
|
||
- Бот использует формулу из документов, выполняет расчет (пошагово) и выдает результат.
|
||
|
||
5. **Поиск по юридически значимым пунктам**:
|
||
- «Выведи пункт 3.2.1 из договора №123»
|
||
- Бот переключается на точный подстроковый поиск (см. пункт 12) и выдает цитату.
|
||
|
||
6. **Общий вопрос (GENERAL)**:
|
||
- «О чем этот документ?»
|
||
- Бот дает краткое описание на основе содержания (если есть контекст).
|
||
|
||
7. **Приветствие (GREETING)**:
|
||
- «Привет» – бот отвечает вежливо, без поиска.
|
||
|
||
**Примеры использования для коробочных решений**:
|
||
|
||
1. **Поиск KPI по ключевым словам**:
|
||
- Для плейсхолдера `{{KPI_NAME}}` бот ищет в документах упоминания показателей: «OEE», «процент брака», «выработка на человека».
|
||
- Находит в отчетах: «Процент сотрудников с профильным образованием».
|
||
- Возвращает точное название.
|
||
|
||
2. **Поиск числовых значений**:
|
||
- Для `{{KPI_BEFORE}}` и `{{KPI_AFTER}}` бот находит в документах цифры: «в 2024 году – 30%», «целевой показатель – 85%».
|
||
- Возвращает числа.
|
||
|
||
3. **Поиск корневых причин проблем**:
|
||
- Для `{{ROOT_CAUSE_1}}` бот анализирует документы и выделяет ключевые проблемы: «дефицит кадров», «отсутствие регламентов», «нерегулярное планирование».
|
||
|
||
4. **Поиск постановки задач**:
|
||
- Для `{{TASK_1}}` бот находит в стратегических документах перечень задач: «разработать стандарт», «обучить персонал», «внедрить систему мониторинга».
|
||
|
||
### **3. Комнатные и глобальные базы знаний**
|
||
|
||
**Что делает**:
|
||
Документы могут быть трех типов:
|
||
- **Личные** – видны только владельцу (загружаются в личном чате без флагов).
|
||
- **Комнатные** – доступны всем участникам комнаты (автоматически при загрузке в групповой чат).
|
||
- **Глобальные** – доступны всем пользователям (загружаются администратором с флагом `--global` в личном чате).
|
||
|
||
Последний загруженный файл привязан к комнате, что предотвращает перезапись файлов разных пользователей в одной комнате.
|
||
|
||
**Уникальность**:
|
||
Позволяет естественно разграничивать доступ и организовывать коллективную работу. Редко встречается в RAG-ботах.
|
||
|
||
**Польза**:
|
||
Юридические документы для всех сотрудников (глобальные), конфиденциальные отчеты для отдела (комнатные), личные заметки – все в одном боте. Команда может совместно разрабатывать шаблоны и коробочные решения.
|
||
|
||
**Примеры использования**:
|
||
|
||
1. **Личная БЗ**:
|
||
- В личном чате с ботом загружаете файл (например, личный план работы). Бот индексирует его как личный – доступен только вам.
|
||
|
||
2. **Комнатная БЗ**:
|
||
- В групповом чате загружаете файл (регламент отдела). Бот автоматически индексирует его в комнатную БЗ – доступен всем участникам комнаты.
|
||
|
||
3. **Глобальная БЗ**:
|
||
- Администратор в личном чате вводит:
|
||
`!learn --global`
|
||
Затем отправляет файл (или ссылку). Бот индексирует документ как глобальный – доступен всем пользователям во всех контекстах.
|
||
|
||
4. **Просмотр доступных документов**:
|
||
- `!kb` – в личном чате покажет список личных + глобальных документов.
|
||
- `!kb` в комнате – покажет комнатные + глобальные документы.
|
||
|
||
5. **Очистка БЗ**:
|
||
- `!clear` – в личном чате очищает личную БЗ.
|
||
- `!clear` в комнате (только админ) – очищает комнатную БЗ.
|
||
- `!global_clear` (админ, личный чат) – очищает глобальную БЗ.
|
||
|
||
6. **Удаление конкретного глобального документа** (админ):
|
||
- `!global_remove "Название документа"` – удаляет документ из глобальной БЗ по точному названию.
|
||
|
||
## 7.2. Функции работы с документами
|
||
|
||
### **4. «Хирургическая» (точечная) замена текста в DOCX**
|
||
|
||
**Что делает**:
|
||
По запросу «замени старое слово на новое» бот выполняет **умную замену** с учетом грамматических форм (падежи, числа, роды) без потери форматирования. Поддерживает замену словоформ (например, «учеников» → «строителей»). Работает только с DOCX, использует морфологический анализатор `mawo-pymorphy3`.
|
||
|
||
**Уникальность**:
|
||
Очень редкая функция для RAG-систем; превращает бота из информатора в инструмент редактирования документов.
|
||
|
||
**Польза**:
|
||
Автоматизация рутинных правок в отчетах, договорах, планах. Снижение человеческих ошибок. Экономия времени на переделку документов.
|
||
|
||
**Примеры использования (все возможные сценарии)**:
|
||
|
||
1. **Простая замена**:
|
||
- Загружаете DOCX, затем вводите:
|
||
`Замени ООО "Ромашка" на ООО "Тюльпан"`
|
||
- Бот заменяет все вхождения во всех падежах (ООО "Ромашка", "Ромашке", "Ромашку" и т.д.) и возвращает исправленный файл.
|
||
|
||
2. **Замена с морфологией**:
|
||
- `Замени учеников на строителей`
|
||
- Бот заменит «ученик», «ученика», «ученикам», «учениками» и т.д. на соответствующие формы «строитель», «строителя», «строителям», «строителями» и т.д.
|
||
|
||
3. **Замена дат или чисел**:
|
||
- `Замени 2024 на 2025`
|
||
- Заменит все цифры 2024 (в том числе в тексте и таблицах) на 2025.
|
||
|
||
4. **Множественные замены** – можно загрузить файл и выполнить несколько команд подряд, бот будет применять их последовательно (каждая команда работает с последним измененным файлом).
|
||
|
||
5. **Замена в таблицах и колонтитулах** – замены выполняются во всех элементах документа, включая таблицы, сноски, колонтитулы и надписи.
|
||
|
||
6. **Сохранение форматирования** – замены выполняются без потери жирного шрифта, курсива, подчеркивания, цветов, размеров шрифта, выравнивания.
|
||
|
||
7. **Работа с архивами** – если загружен ZIP-архив, бот распаковывает его, выполняет замену во всех DOCX-файлах внутри и упаковывает обратно (если включена поддержка архивов).
|
||
|
||
### **5. Проверка орфографии**
|
||
|
||
**Что делает**:
|
||
Пользователь загружает DOCX, затем пишет «Проверь орфографию» или «Найди ошибки». Бот разбивает текст на чанки (учитывая токены), отправляет каждый чанк в GigaChat с промптом на исправление ошибок. Исправления применяются с сохранением форматирования. Возвращает исправленный файл и список изменений в виде «было → стало».
|
||
|
||
**Уникальность**:
|
||
Автоматическое исправление ошибок в готовых документов без ручной правки. Поддерживает сложные случаи русского языка (благодаря использованию `razdel` для разбиения на предложения).
|
||
|
||
**Польза**:
|
||
Экономия времени на вычитку, повышение грамотности исходящих документов. Незаменимо при подготовке коробочных решений и официальных документов.
|
||
|
||
**Примеры использования**:
|
||
|
||
1. **Базовая проверка**:
|
||
- Загружаете DOCX, пишете:
|
||
`Проверь орфографию`
|
||
- Бот возвращает исправленный файл и список всех исправлений:
|
||
`было «пашол» → стало «пошел»`
|
||
`было «молоко хлеб» → стало «молоко, хлеб»`
|
||
|
||
2. **Альтернативные команды**:
|
||
- `Найди ошибки в документе`
|
||
- `Исправь ошибки`
|
||
- `Проверь грамматику`
|
||
- Работают аналогично.
|
||
|
||
3. **Проверка с сохранением стиля** – бот исправляет только орфографические и пунктуационные ошибки, не меняет структуру предложений, не заменяет синонимы, не улучшает стилистику (это сделано намеренно, чтобы сохранить авторский стиль).
|
||
|
||
4. **Обработка ошибок парсинга** – если GigaChat не смог сформировать список изменений в требуемом формате (`[CHANGES]...[/CHANGES]`), бот покажет сырой ответ модели, чтобы исправления не потерялись, и предложит проверить вручную.
|
||
|
||
5. **Работа с большими документами** – текст разбивается на чанки (по токенам) и обрабатывается последовательно, что позволяет проверять документы любого размера.
|
||
|
||
6. **Только в личном чате** – проверка орфографии доступна только в личном чате с ботом (для безопасности и предотвращения спама в комнатах).
|
||
|
||
### **6. Суммаризация документа**
|
||
|
||
**Что делает**:
|
||
Создает краткий пересказ (≤30% от оригинала) с выделением целей, выводов и ключевых цифр. Использует промпт, который фокусируется на наиболее важных аспектах документа.
|
||
|
||
**Уникальность**:
|
||
Не просто сжатие, а интеллектуальное выделение самой важной информации на основе промпта (а не просто первые предложения).
|
||
|
||
**Польза**:
|
||
Быстрое ознакомление с объемными регламентами, отчетами, ГОСТами. Ускоряет анализ больших документов при разработке коробочных решений.
|
||
|
||
**Примеры использования**:
|
||
|
||
1. **Суммаризация последнего загруженного файла**:
|
||
- `!summary`
|
||
- Бот выдает краткое изложение документа (не более 30% объема) с выделением цели, выводов и ключевых цифр. В конце обязательно указывается источник.
|
||
|
||
2. **Автоматическая суммаризация при намерении SUMMARY** – если пользователь спросит «Сделай суммаризацию документа», классификатор распознает это намерение и вызовет функцию автоматически (без команды `!summary`).
|
||
|
||
3. **Фокус на числовых показателях** – если в документе есть OEE, такт, выработка, проценты, они выделяются в отдельный раздел.
|
||
|
||
4. **Быстрое ознакомление** – можно использовать для регламентов, ГОСТов, длинных отчетов, чтобы понять суть за 1–2 минуты.
|
||
|
||
5. **Ограничение длины** – если документ длиннее `max_chars` (по умолчанию 8000 символов), он обрезается по границам предложений (с использованием `razdel`), чтобы суммаризация была по полному тексту.
|
||
|
||
## 7.3. Функции анализа и качества
|
||
|
||
### **7. Самокритика ответа с перегенерацией**
|
||
|
||
**Что делает**:
|
||
После генерации ответа другой экземпляр LLM оценивает его по пяти критериям:
|
||
1. Соответствие источнику – все ли факты подтверждаются контекстом.
|
||
2. Отсутствие галлюцинаций – нет ли информации, отсутствующей в контексте.
|
||
3. Соблюдение стиля и форматирования (нет LaTeX, есть источники, правильные списки).
|
||
4. Логическая связность – ответ не противоречит сам себе.
|
||
5. Запрет внешних знаний – не используются личные знания модели (если `allow_public_knowledge = false`).
|
||
|
||
При неудовлетворительной оценке ответ перегенерируется один раз. Если и после перегенерации неудовлетворительно, выдается сообщение о неуверенности.
|
||
|
||
**Уникальность**:
|
||
Редкий механизм самоконтроля, повышающий доверие к боту. Работает как «человек проверяет себя».
|
||
|
||
**Польза**:
|
||
Снижает вероятность ошибочного ответа, особенно в критических областях (юриспруденция, финансы, медицина, нормативная документация).
|
||
|
||
**Примеры использования**:
|
||
|
||
1. **Обычный запрос** – самокритика работает в фоновом режиме. Если ответ не проходит проверку, бот перегенерирует его один раз. Если и после перегенерации неудовлетворительно, выдается сообщение:
|
||
«⚠️ Извините, я не уверен в точности ответа. Проверьте данные.»
|
||
|
||
2. **Отключение самокритики** – если в конфиге `bot.conf` установить `enable_self_critique: false`, она отключается для увеличения скорости (полезно для тестирования или простых запросов).
|
||
|
||
3. **Влияет только на обычные RAG-запросы** – для экспертных функций (METRICS, SUMMARY, CONTRADICTION) самокритика не применяется, так как их ответы уже структурированы и проверены на уровне функций.
|
||
|
||
4. **Перегенерация с тем же контекстом** – при перегенерации используется тот же контекст, что и при первом ответе, чтобы не потерять релевантность.
|
||
|
||
### **8. Извлечение метрик (KPI) из документов**
|
||
|
||
**Что делает**:
|
||
Анализирует базу знаний, находит числовые показатели (OEE, тактовое время, выработку, проценты, суммы, количества) и выдает в структурированном виде (JSON или маркированный список). Использует промпт, который заставляет LLM выделять только явно указанные числа/значения, без додумывания.
|
||
|
||
**Уникальность**:
|
||
Команда `!metrics` работает без предварительной разметки данных – LLM сама выделяет показатели. Не требуется специальных тегов или шаблонов.
|
||
|
||
**Польза**:
|
||
Быстрый анализ эффективности, контроль KPI по всем документам компании. Автоматизация сбора показателей для отчетности.
|
||
|
||
**Примеры использования**:
|
||
|
||
1. **Извлечение всех KPI из базы знаний**:
|
||
- `!metrics`
|
||
- Бот ищет все документы (личные + глобальные или комнатные + глобальные) и выдает список метрик:
|
||
`- OEE линии: 85,2% (первый квартал 2025)`
|
||
`- Тактовое время на сборке: 120 сек`
|
||
`- Выработка на одного рабочего: 450 деталей в смену`
|
||
`- Время переналадки: 35 мин`
|
||
`- Процент брака: 2,1%`
|
||
|
||
2. **Автоматический ответ на намерение METRICS** – если пользователь спросит:
|
||
«Выведи все KPI из отчета» или «Покажи показатели эффективности», классификатор распознает намерение и вызовет функцию автоматически.
|
||
|
||
3. **Кэширование** – для команды `!metrics` результат кэшируется на 5 минут, что ускоряет повторные запросы (полезно для частого мониторинга).
|
||
|
||
4. **Ограничение количества** – выводится не более 20 метрик, чтобы не перегружать ответ.
|
||
|
||
5. **Указание источника** – каждая метрика сопровождается фрагментом источника (первые 100 символов), чтобы можно было проверить оригинал.
|
||
|
||
### **9. Проверка противоречий между документами**
|
||
|
||
**Что делает**:
|
||
Находит логические, числовые или терминологические расхождения в разных фрагментах базы знаний. Сравнивает факты, цифры, даты, определения. Возвращает структурированный ответ: `[OK]` если противоречий нет, или `[CONFLICT]` с описанием каждого расхождения и предполагаемой причиной.
|
||
|
||
**Уникальность**:
|
||
Помогает аудиторам и аналитикам обнаруживать конфликты данных. Автоматизирует процесс верификации документации.
|
||
|
||
**Польза**:
|
||
Исключение ошибок в нормативной базе, устранение дублирующихся требований, повышение качества документооборота.
|
||
|
||
**Примеры использования**:
|
||
|
||
1. **Проверка противоречий в OEE**:
|
||
- «Есть ли противоречия в расчете OEE?»
|
||
- Бот ищет все фрагменты с упоминанием OEE и сравнивает цифры. Если в одном документе 85%, а в другом 90%, выдает предупреждение:
|
||
`[CONFLICT] В фрагменте 1 указано 85%, в фрагменте 2 – 90%. Предполагаемая причина: разные источники или разные периоды.`
|
||
|
||
2. **Проверка сроков**:
|
||
- «Проверь, нет ли противоречий в сроках реализации проекта»
|
||
- Находит все даты в документах и сравнивает их.
|
||
|
||
3. **Сравнение терминов**:
|
||
- «Есть ли противоречия в определении понятия "цикл производства"?»
|
||
- Находит все определения и проверяет их на согласованность.
|
||
|
||
4. **Ограничение фрагментов** – для экономии токенов проверяются только первые `max_fragments` (по умолчанию 5) наиболее релевантных фрагментов.
|
||
|
||
5. **Учет первичного источника** – если один источник явно первичен (например, официальный документ), это указывается в ответе.
|
||
|
||
#### **10. SOMA-анализ (LLM-as-judge)**
|
||
|
||
**Что делает**:
|
||
После генерации ответа другой экземпляр LLM (или тот же, с другим системным промптом) оценивает ответ по пяти критериям:
|
||
|
||
1. **Релевантность** – насколько ответ соответствует вопросу.
|
||
2. **Полнота** – охвачены ли все аспекты вопроса.
|
||
3. **Отсутствие галлюцинаций** – факты подтверждены контекстом.
|
||
4. **Стиль и читаемость** – логичность, ясность, отсутствие излишней сложности.
|
||
5. **Полезность** – содержит ли ответ практические рекомендации или чёткие выводы.
|
||
|
||
Каждый критерий оценивается по шкале от 1 до 5. Если средняя оценка ниже порога (по умолчанию 3.5), ответ перегенерируется (с повышенной температурой для разнообразия) и оценивается повторно. Если и повторная оценка неудовлетворительна, пользователю выводится предупреждение о неуверенности.
|
||
|
||
**Результаты SOMA-оценок кэшируются** на 5 минут (TTL настраивается) на основе хеша `(query, context, answer)`, чтобы избежать повторных вызовов GigaChat для идентичных запросов.
|
||
|
||
**Уникальность**:
|
||
SOMA-анализ обеспечивает **автоматический контроль качества** без участия человека, что редко встречается в корпоративных RAG-ботах. Кэширование снижает затраты на токены.
|
||
|
||
**Польза**:
|
||
Повышает доверие к ответам, особенно в критических областях. Позволяет A/B-тестировать промпты и модели, так как SOMA даёт объективную метрику качества.
|
||
|
||
**Примеры использования**:
|
||
|
||
- Все обычные RAG-запросы (GENERAL, FACT, PROCEDURE, COMPARISON, CALCULATION) проходят SOMA-оценку (если включена).
|
||
- При низкой оценке бот перегенерирует ответ, что особенно полезно для сложных расчётов и юридических вопросов.
|
||
- Результаты SOMA могут использоваться для сбора статистики качества и оптимизации промптов.
|
||
|
||
#### **11. ReAct (вызов внешних инструментов) – НОВОЕ!**
|
||
|
||
**Что делает**:
|
||
ReAct (Reasoning + Acting) — это итеративный цикл, в котором модель:
|
||
|
||
1. **Генерирует мысль** (обдумывает, что нужно сделать).
|
||
2. **Выбирает действие** (вызов внешнего инструмента).
|
||
3. **Наблюдает результат** (получает ответ от API).
|
||
4. **Повторяет** до тех пор, пока не будет готов финальный ответ.
|
||
|
||
Доступные инструменты (реализованы в `ToolHandler`):
|
||
|
||
- **Поиск в интернете** (DuckDuckGo Instant Answer API) – находит факты, новости, определения.
|
||
- **Погода** (OpenWeatherMap API) – текущая погода в указанном городе (требуется API-ключ).
|
||
- **Бронирование авиабилетов** (заглушка для демонстрации).
|
||
- **Курс валют** (заглушка для демонстрации).
|
||
|
||
ReAct автоматически активируется, если запрос содержит ключевые слова «найди», «поищи», «забронируй», «погода», «билеты», «курс» и т.д. (настраивается в `_needs_external_data`).
|
||
|
||
**Уникальность**:
|
||
Редкая возможность для корпоративных RAG-ботов — выполнять **реальные действия** через внешние API, а не только генерировать текст. Это превращает бота из пассивного информатора в активного помощника.
|
||
|
||
**Польза**:
|
||
- Быстрый доступ к актуальной информации из интернета.
|
||
- Автоматизация поиска билетов, отелей, погоды.
|
||
- Возможность расширения инструментов под любые корпоративные API (1С, SAP, календари).
|
||
|
||
**Примеры использования**:
|
||
|
||
1. **Поиск информации**:
|
||
- Запрос: «Найди последние новости о квантовых вычислениях»
|
||
- Бот выполняет поиск через DuckDuckGo и возвращает краткую выжимку.
|
||
2. **Погода**:
|
||
- Запрос: «Какая погода в Москве завтра?»
|
||
- Бот вызывает OpenWeatherMap и возвращает прогноз.
|
||
3. **Бронирование** (заглушка):
|
||
- Запрос: «Забронируй билет Москва-Сочи на 15 июля»
|
||
- Бот имитирует бронирование, демонстрируя возможную интеграцию.
|
||
4. **Комбинированный сценарий**:
|
||
- Запрос: «Найди информацию о достопримечательностях Парижа и какая там погода?»
|
||
- Бот сначала ищет достопримечательности, затем погоду, объединяет ответы.
|
||
|
||
#### **12. Планирование действий**
|
||
|
||
**Что делает**:
|
||
Для сложных запросов (расчёты, многошаговые инструкции) бот сначала генерирует **пошаговый план**, а затем последовательно выполняет каждый шаг. План содержит описание шага, необходимые данные и ожидаемый результат. Это повышает точность и логичность ответов.
|
||
|
||
**Уникальность**:
|
||
Планирование добавляет **метакогнитивный уровень** – модель обдумывает структуру ответа перед его генерацией, что улучшает качество для сложных задач.
|
||
|
||
**Польза**:
|
||
|
||
- Повышает точность расчётов и алгоритмов.
|
||
- Улучшает структурированность ответов для инструкций.
|
||
- Позволяет пользователю видеть логику решения.
|
||
|
||
**Примеры использования**:
|
||
|
||
1. **Расчёт OEE**:
|
||
- Запрос: «Рассчитай OEE для линии»
|
||
- Бот генерирует план: 1) найти доступное время, 2) вычислить время простоев, 3) рассчитать производительность и качество, 4) вычислить OEE. Затем выполняет каждый шаг, показывая промежуточные результаты.
|
||
|
||
2. **Инструкция по внедрению 5S**:
|
||
- Запрос: «Как внедрить 5S на производстве?»
|
||
- Бот создаёт план из 5 этапов, затем последовательно описывает каждый.
|
||
|
||
#### **13. Многоагентность**
|
||
|
||
**Что делает**:
|
||
В системе могут одновременно работать несколько специализированных агентов:
|
||
- **Методолог** – экспертиза в стандартах, ГОСТах, методиках.
|
||
- **Коробочник** – генерация коробочных решений, шаблонов.
|
||
- **Персональный ассистент** – командировки, календарь, бронирование.
|
||
|
||
Координатор (`AgentCoordinator`) автоматически выбирает подходящего агента на основе ключевых слов запроса. Например, если запрос содержит «методолог», «стандарт», «ГОСТ» — вызывается методолог. Агенты могут обмениваться сообщениями для решения сложных задач.
|
||
|
||
**Уникальность**:
|
||
Многоагентная архитектура позволяет **декомпозировать сложные задачи** между специализированными ИИ-ассистентами, что повышает качество и релевантность ответов. Это редкость для корпоративных RAG-ботов.
|
||
|
||
**Польза**:
|
||
- Каждый агент настроен на свою предметную область, использует соответствующие промпты.
|
||
- Пользователь может задавать вопросы разной тематики одному боту, а маршрутизация будет автоматической.
|
||
- Возможность расширения новыми агентами без изменения ядра.
|
||
|
||
**Примеры использования**:
|
||
|
||
1. **Запрос к методологу**:
|
||
- «Найди требования к описанию бизнес-процесса в ГОСТ Р ИСО 9001» → автоматически направляется агенту-методологу.
|
||
2. **Запрос к коробочнику**:
|
||
- «Создай коробочное решение для библиотеки» → направляется агенту-коробочнику.
|
||
3. **Запрос к ассистенту**:
|
||
- «Запланируй командировку в Казань на следующую неделю» → направляется агенту-ассистенту.
|
||
4. **Совместная работа агентов**:
|
||
- Если запрос требует и методологии, и коробочного решения, координатор может организовать диалог между агентами.
|
||
|
||
#### **14. Реальные инструменты (ToolHandler)**
|
||
|
||
**Что делает**:
|
||
`ToolHandler` предоставляет реальные обработчики для внешних API:
|
||
|
||
- `search(query)` – поиск через DuckDuckGo Instant Answer API (без ключа).
|
||
- `get_weather(city)` – погода через OpenWeatherMap API (требуется `weather_api_key`).
|
||
- `book_flight(origin, destination, date)` – заглушка для демонстрации.
|
||
- `get_exchange_rate(from_currency, to_currency)` – заглушка для демонстрации.
|
||
|
||
Все инструменты асинхронны, используют `aiohttp`, имеют таймауты и обработку ошибок.
|
||
|
||
**Уникальность**:
|
||
Инструменты интегрированы в ReAct-цикл, что позволяет модели динамически решать, когда и какой инструмент вызывать. Это делает бота активным, а не пассивным.
|
||
|
||
**Польза**:
|
||
|
||
- Реализация реальных действий (поиск, погода) повышает практическую ценность.
|
||
- Заглушки для бронирования и курсов демонстрируют возможности интеграции с любыми API.
|
||
- Легко добавлять новые инструменты через расширение `ToolHandler`.
|
||
|
||
**Примеры использования** (см. раздел ReAct).
|
||
|
||
## 7.4. Интеллектуальная маршрутизация и поиск
|
||
|
||
### **15. Классификация намерений**
|
||
|
||
**Что делает**:
|
||
Определяет тип запроса пользователя по ключевым словам и контексту. Поддерживает следующие коды намерений: `FACT`, `PROCEDURE`, `COMPARISON`, `CALCULATION`, `SURGICAL`, `METRICS`, `SUMMARY`, `CONTRADICTION`, `GREETING`, `GENERAL`, `SPELLCHECK`, `TEMPLATE_FILL`. Выбирает соответствующую стратегию обработки. Результаты классификации кэшируются на 5 минут для ускорения повторных запросов.
|
||
|
||
**Уникальность**:
|
||
Не все RAG-боты имеют интеллектуальную маршрутизацию. Кэширование дополнительно повышает отзывчивость.
|
||
|
||
**Польза**:
|
||
Экономия токенов, времени и повышение точности ответов за счет выбора специализированной стратегии.
|
||
|
||
**Примеры работы (как классификатор определяет тип запроса)**:
|
||
|
||
| Запрос пользователя | Распознанное намерение |
|
||
|----------------------|-------------------------|
|
||
| «Какое тактовое время установлено на линии?» | `FACT` |
|
||
| «Как рассчитать OEE?» | `PROCEDURE` |
|
||
| «Сравни показатели производительности до и после кайдзен» | `COMPARISON` |
|
||
| «Замени 5000 на 6000 в плане производства» | `SURGICAL` |
|
||
| «Выведи все KPI из отчета» | `METRICS` |
|
||
| «Сделай суммаризацию документа» | `SUMMARY` |
|
||
| «Есть ли противоречия в расчете OEE?» | `CONTRADICTION` |
|
||
| «Привет» | `GREETING` |
|
||
| «Заполни шаблон договора» | `TEMPLATE_FILL` |
|
||
| «Проверь орфографию» | `SPELLCHECK` |
|
||
| «О чем этот документ?» | `GENERAL` |
|
||
|
||
### **16. Цепочка рассуждений (Chain‑of‑Thought)**
|
||
|
||
**Что делает**:
|
||
Для запросов с намерениями `CALCULATION` (расчет) и `PROCEDURE` (инструкция/алгоритм) бот автоматически добавляет в промпт инструкцию, требующую пошагового решения перед итоговым ответом. Модель генерирует ответ с последовательным описанием шагов, а затем итоговым результатом.
|
||
|
||
**Польза**:
|
||
Повышает точность расчетов и алгоритмов, позволяет пользователю проверить логику и выявить возможные ошибки на промежуточных этапах.
|
||
|
||
**Примеры использования**:
|
||
|
||
1. **Расчет OEE**:
|
||
- Запрос: «Рассчитай OEE для линии»
|
||
- Ответ:
|
||
> Шаг 1: Доступное время = 480 мин
|
||
> Шаг 2: Время простоев = 45 мин
|
||
> Шаг 3: Операционное время = 435 мин
|
||
> Шаг 4: OEE = (435 / 480) × 100% = 90,6%
|
||
> Итоговый ответ: OEE составляет 90,6%.
|
||
|
||
2. **Расчет выработки**:
|
||
- Запрос: «Какая будет выработка при загрузке 110%?»
|
||
- Ответ с пошаговым расчетом:
|
||
> Шаг 1: Номинальная выработка = 100 ед/час
|
||
> Шаг 2: При загрузке 110% выработка = 100 × 1,1 = 110 ед/час
|
||
> Итог: 110 ед/час.
|
||
|
||
3. **Пошаговая инструкция**:
|
||
- Запрос: «Как внедрить 5S?»
|
||
- Бот выдает последовательность шагов с пояснениями.
|
||
|
||
### **17. Полнотекстовый поиск по точным фрагментам и поиск инструкций (HOW TO)**
|
||
|
||
**Что делает**:
|
||
При обнаружении номеров пунктов (1.1, 3.2.1), фраз в кавычках или ключевых слов «как», «инструкция», «алгоритм», «порядок», «последовательность», «этапы», «методика», «процедура», «регламент», «правила», «способ», «метод» – бот переключается с гибридного RAG на **точный подстроковый поиск** в Qdrant (MatchText). Это гарантирует попадание в нужный раздел документа, а не просто семантически похожий фрагмент.
|
||
|
||
**Ключевая особенность**:
|
||
Если запрос содержит вопрос «как сделать Х», бот не просто находит фрагмент с упоминанием Х, а **извлекает всю инструкцию или процедуру**, даже если она не оформлена как маркированный список, а просто описана в тексте. Для этого используется дополнительный промпт, который заставляет LLM выделить и структурировать последовательность действий.
|
||
|
||
**Уникальность**:
|
||
- Гарантирует юридически значимые цитаты и ссылки на пункты нормативных актов.
|
||
- Может находить и выдавать пошаговые инструкции из неструктурированного текста.
|
||
- Объединяет точный поиск с **цепочкой рассуждений (CoT)**, если инструкция требует расчетов или последовательных действий.
|
||
|
||
**Польза**:
|
||
- Позволяет получать готовые алгоритмы и процедуры без необходимости читать весь документ.
|
||
- Быстрое освоение новых процессов – достаточно спросить «как сделать Х», и бот найдет инструкцию в документах.
|
||
- Снижение времени на поиск регламентов и стандартов.
|
||
|
||
**Примеры использования (все возможные сценарии)**:
|
||
|
||
1. **Поиск инструкции по номеру пункта**:
|
||
- Запрос: «Выведи пункт 4.2 из регламента по внедрению 5S»
|
||
- Ответ:
|
||
```
|
||
[Источник: Регламент_внедрения_5S.docx]
|
||
Пункт 4.2. Порядок проведения аудита рабочего места:
|
||
1. Подготовка: сформировать чек-лист на основе стандарта 5S.
|
||
2. Проведение аудита: визуальный осмотр рабочих мест, фиксация нарушений.
|
||
3. Оценка: выставление баллов по каждому критерию...
|
||
```
|
||
|
||
2. **Поиск процедуры по ключевому слову «как» + «инструкция»**:
|
||
- Запрос: «Как провести хронометраж рабочего времени?»
|
||
- Ответ:
|
||
```
|
||
[Источник: Методика_хронометража.pdf]
|
||
Инструкция по проведению хронометража:
|
||
1. Определить цель...
|
||
2. Выбрать объект наблюдения...
|
||
3. Разработать лист наблюдений...
|
||
4. Провести наблюдение...
|
||
5. Обработать данные...
|
||
6. Сделать выводы...
|
||
```
|
||
|
||
3. **Поиск алгоритма по ключевым словам «порядок действий», «этапы»**:
|
||
- Запрос: «Опиши порядок действий при внедрении кайдзен-предложения»
|
||
- Ответ с пошаговым алгоритмом.
|
||
|
||
4. **Поиск по цитате с кавычками**:
|
||
- Запрос: «"Срок исполнения не более 5 рабочих дней"»
|
||
- Ответ: точная цитата с указанием раздела и документа.
|
||
|
||
5. **Поиск методики по ключевым словам «методика» + «расчет»**:
|
||
- Запрос: «Найди методику расчета OEE»
|
||
- Ответ с формулами и пояснениями.
|
||
|
||
6. **Поиск инструкции с уточнением «напиши инструкцию»**:
|
||
- Запрос: «Напиши инструкцию по безопасной работе с электроинструментом»
|
||
- Ответ с полным текстом инструкции.
|
||
|
||
7. **Поиск с комбинацией: «как» + «внедрить» + конкретный инструмент**:
|
||
- Запрос: «Как внедрить систему 5S на производстве?»
|
||
- Ответ с пошаговым алгоритмом внедрения.
|
||
|
||
8. **Поиск регламента**:
|
||
- Запрос: «Какой регламент по проведению инвентаризации?»
|
||
- Ответ с описанием процедуры.
|
||
|
||
9. **Поиск по номеру документа**:
|
||
- Запрос: «ГОСТ Р 12345-2023»
|
||
- Находит документ с этим номером в названии или тексте.
|
||
|
||
10. **Комбинированный поиск**:
|
||
- Запрос: «Порядок расчета OEE по методике из приложения 2»
|
||
- Находит точный раздел и выдает инструкцию.
|
||
|
||
### **18. Расширение запроса (query expansion)**
|
||
|
||
**Что делает**:
|
||
Добавляет синонимы, аббревиатуры и связанные термины к исходному запросу для увеличения полноты поиска. Использует GigaChat для генерации до 10 дополнительных ключевых слов. Результаты кэшируются на 5 минут.
|
||
|
||
**Уникальность**:
|
||
Улучшает recall без участия пользователя. Автоматически подбирает термины, которые могут встречаться в документах.
|
||
|
||
**Польза**:
|
||
Помогает находить документы, даже если пользователь использует нестандартные термины или сокращения.
|
||
|
||
**Примеры расширения**:
|
||
|
||
| Исходный запрос | Расширенный запрос (пример) |
|
||
|-----------------|-----------------------------|
|
||
| «OEE» | «OEE общая эффективность оборудования производительность коэффициент использования» |
|
||
| «время переналадки» | «время переналадки длительность смены инструмента SMED время простоя» |
|
||
| «5S» | «5S сортировка соблюдение порядка сияние стандартизация совершенствование рабочее место» |
|
||
| «Кайдзен» | «Кайдзен непрерывное улучшение малые шаги оптимизация процессов бережливое производство» |
|
||
| «выработка на человека» | «выработка на человека производительность труда выработка на одного сотрудника ПТ» |
|
||
| «расчет такта» | «расчет такта тактовое время Takt time формула такта время выпуска единицы» |
|
||
|
||
### **19. Переранжирование контекста (кросс-энкодер)**
|
||
|
||
**Что делает**:
|
||
После получения фрагментов из Qdrant, специализированная модель (кросс-энкодер) ранжирует их по релевантности запросу, отбрасывая шум. Используется локальная модель `intfloat/multilingual-e5-reranker`, что исключает затраты на токены и снижает задержку.
|
||
|
||
**Уникальность**:
|
||
Вместо дорогого вызова LLM используется легкий кросс-энкодер, работающий быстрее и дешевле. При этом качество ранжирования сравнимо с LLM.
|
||
|
||
**Польза**:
|
||
Уменьшает объем контекста, отправляемого в GigaChat, что экономит токены и улучшает точность ответа (убираются нерелевантные фрагменты).
|
||
|
||
**Пример работы**:
|
||
Запрос: «Какой OEE на линии А?»
|
||
Qdrant вернул 30 фрагментов. Кросс-энкодер отбирает только те, где есть упоминания «OEE» и «линия А», отбрасывая фрагменты про другие линии или общие описания. В результате в GigaChat отправляется только релевантный контекст (обычно 5–10 лучших фрагментов).
|
||
|
||
## 7.5. Функции автоматизации и интеграции
|
||
|
||
### **20. Автоматическая индексация файлов в комнатах (без `!learn`)**
|
||
|
||
**Что делает**:
|
||
Любой файл (DOCX, PDF, XLSX, PPTX, изображение, аудио, архив), отправленный в групповой чат, автоматически индексируется в базу знаний комнаты. Не требуется включать режим обучения (`!learn`). Это работает «из коробки» для всех участников комнаты.
|
||
|
||
**Уникальность**:
|
||
Удобство для коллективной работы – не надо запоминать команды. Даже у Slack и Teams нет такой функции «из коробки».
|
||
|
||
**Польза**:
|
||
Быстрый старт для новых участников комнаты – они сразу могут задавать вопросы по документам, которые уже загружены. Автоматическое пополнение базы знаний без лишних действий.
|
||
|
||
**Примеры использования**:
|
||
|
||
1. Пользователь отправляет в групповой чат файл «Регламент_отдела.docx» – бот автоматически индексирует его в комнатную БЗ, и все участники могут задавать по нему вопросы.
|
||
|
||
2. Новый сотрудник приходит в комнату – он сразу может спрашивать бота о документах, которые уже загружены, без необходимости отдельно загружать их.
|
||
|
||
3. В комнате с файлами по проекту каждый участник может добавлять новые версии документов, и бот автоматически обновляет индекс (при изменении хеша файла).
|
||
|
||
4. Если файл является архивом (ZIP, 7z), бот распаковывает его и индексирует все поддерживаемые форматы внутри.
|
||
|
||
### **21. Веб-скрапинг с рекурсивным обходом**
|
||
|
||
**Что делает**:
|
||
Бот может загрузить сайт по ссылке, рекурсивно обойти страницы (с ограничением глубины и количества) и проиндексировать их в базу знаний. Поддерживаются HTML-страницы и PDF-документы по ссылкам.
|
||
|
||
**Уникальность**:
|
||
Превращает произвольные веб-страницы в документы для RAG. Позволяет автоматически собирать информацию из внешних источников.
|
||
|
||
**Польза**:
|
||
Актуальная информация из внешних источников (изменения законодательства, новости отрасли, техническая документация) – автоматически попадает в базу знаний.
|
||
|
||
**Примеры использования**:
|
||
|
||
1. **Индексация одной страницы**:
|
||
- В режиме `!learn` (личный чат) вводите:
|
||
`https://example.com/document`
|
||
- Бот загружает страницу, извлекает основной текст (с помощью readability-lxml) и индексирует.
|
||
|
||
2. **Рекурсивный обход сайта**:
|
||
- `https://example.com --recursive --depth 2 --max 10`
|
||
- Бот загружает страницу, затем переходит по ссылкам на глубину 2 уровня, обрабатывая не более 10 страниц, и индексирует все.
|
||
|
||
3. **Индексация PDF по ссылке**:
|
||
- `https://example.com/report.pdf`
|
||
- Бот скачивает PDF, извлекает текст и индексирует.
|
||
|
||
4. **Задание заголовка**:
|
||
- `https://example.com --title "Новый ГОСТ"`
|
||
- Документ сохраняется в БЗ с указанным заголовком.
|
||
|
||
5. **Ограничения** – глубина по умолчанию 1, максимум страниц 5 (настраивается в конфиге). Это предотвращает перегрузку системы.
|
||
|
||
### **22. Поддержка голосовых сообщений (распознавание через SaluteSpeech)**
|
||
|
||
**Что делает**:
|
||
Аудиофайлы (.ogg, .wav, .mp3, .amr, .m4a) транскрибируются в текст через SaluteSpeech API. Полученный текст затем обрабатывается как обычный запрос (классификация, поиск, генерация ответа). Ответ отправляется текстом в чат.
|
||
|
||
**Уникальность**:
|
||
Редкость для RAG-ботов, удобно для мобильных клиентов. Не требует установки дополнительных приложений – работает с любым аудиофайлом.
|
||
|
||
**Польза**:
|
||
Можно «продиктовать» вопрос, не набирая текст. Удобно в дороге, в производственных условиях (где руки заняты) или для людей с ограниченными возможностями.
|
||
|
||
**Примеры использования**:
|
||
|
||
1. Пользователь отправляет голосовое сообщение в личный чат боту (или в комнату). Бот распознает речь, превращает в текст, и если это вопрос – обрабатывает через RAG, отправляя ответ текстом (или голосом, если настроено дополнительно).
|
||
|
||
2. В мобильном клиенте (например, Conversations) пользователь нажимает кнопку записи голоса, говорит вопрос, бот отвечает в чат текстом.
|
||
|
||
3. Голосовое сообщение может содержать не только вопрос, но и команду (например, «!summary») – бот распознает и выполняет.
|
||
|
||
4. Поддерживаются длинные сообщения – транскрипция работает с учетом лимитов API.
|
||
|
||
### **23. Административные команды (`!stats`, `!status`, `!clean`)**
|
||
|
||
**Что делает**:
|
||
- `!stats` – показывает статистику работы бота: uptime, количество обработанных сообщений, AI-запросов, файлов, ошибок, документов в БЗ.
|
||
- `!status` – проверяет доступность внешних сервисов: PostgreSQL, Qdrant, GigaChat, а также состояние дискового пространства.
|
||
- `!clean` – очищает временную директорию (удаляет все временные файлы).
|
||
|
||
**Уникальность**:
|
||
Полный контроль без доступа к серверу. Все команды доступны из любого XMPP-клиента.
|
||
|
||
**Польза**:
|
||
Оперативное администрирование, мониторинг состояния системы, освобождение места на диске.
|
||
|
||
**Примеры использования**:
|
||
|
||
1. **Проверка состояния сервисов**:
|
||
- `!status`
|
||
- Бот проверяет подключение к PostgreSQL, Qdrant, GigaChat и выводит результат:
|
||
`✅ PostgreSQL Online`
|
||
`✅ Qdrant Online`
|
||
`✅ GigaChat Online`
|
||
`💾 Диск: 512MB / 10GB (свободно 9.5GB)`
|
||
|
||
2. **Статистика работы бота**:
|
||
- `!stats`
|
||
- Выводит:
|
||
`⏱ Uptime: 2 дня 5 часов`
|
||
`💬 Сообщений: 1 234`
|
||
`🤖 AI запросов: 567`
|
||
`📁 Файлов обработано: 89`
|
||
`❌ Ошибок: 12`
|
||
`📚 Документов в БЗ: 45`
|
||
|
||
3. **Очистка временных файлов**:
|
||
- `!clean`
|
||
- Удаляет все файлы из временной директории (temp/), освобождая место на диске. Выводит количество удаленных объектов.
|
||
|
||
4. **Только для администраторов** – команды `!stats`, `!status`, `!clean` доступны только пользователям, перечисленным в `admin_jids` в конфиге.
|
||
|
||
## 7.6. Дополнительные возможности
|
||
|
||
### **Режим обучения (`!learn` и `!stop_learn`)**
|
||
|
||
- `!learn` – включает режим обучения. Следующий файл или ссылка, отправленные в чат, будут добавлены в базу знаний (личную, комнатную или глобальную, в зависимости от контекста и флагов).
|
||
- `!learn --global` – (только в личном чате, для админов) – следующий файл/ссылка станут глобальными.
|
||
- `!stop_learn` – выключает режим обучения.
|
||
|
||
**Пример**:
|
||
`!learn` → затем отправляете файл → он индексируется.
|
||
`!stop_learn` – режим выключен.
|
||
|
||
### **Работа с историей диалога**
|
||
|
||
Бот автоматически сохраняет историю диалогов (личную и комнатную) в PostgreSQL. История используется для контекста при ответах. Команда `!reset` сбрасывает историю (личную или комнатную). Для длинных диалогов применяется иерархическое резюмирование, чтобы сжать историю и не превысить лимит токенов.
|
||
|
||
### **Поддержка вложенных файлов и архивов**
|
||
|
||
Бот умеет распаковывать ZIP и 7z-архивы и индексировать все файлы внутри (DOCX, PDF, XLSX и т.д.). Это позволяет загружать целые пакеты документов одной ссылкой.
|
||
|
||
### **Многоязычность**
|
||
|
||
Промпты настроены так, что бот может отвечать на любом языке, на котором задан вопрос, если в документах есть информация на этом языке. В системном промпте явно указано: «Ты можешь использовать информацию из документов на ЛЮБОМ языке (русском, английском, немецком и т.д.)». При необходимости бот переводит нужную часть на язык вопроса.
|
||
|
||
### **Работа с изображениями (Vision)**
|
||
|
||
Если загружено изображение (JPEG, PNG, BMP, TIFF) и в конфиге включена опция `vision: true`, бот отправляет изображение на RAG-сервер (эндпоинт `/rag/vision`) для распознавания текста (OCR). Распознанный текст отправляется в чат.
|
||
|
||
### **Работа с таблицами в DOCX**
|
||
|
||
При извлечении текста из DOCX бот обрабатывает таблицы, сохраняя их структуру. Это позволяет отвечать на вопросы, требующие табличных данных.
|
||
|
||
## 7.7. Сценарий полного цикла создания коробочного решения
|
||
|
||
### Этап 1: Подготовка источников
|
||
|
||
1. Администратор загружает глобальные документы (ГОСТы, методики):
|
||
```
|
||
!learn --global → отправляет ГОСТ Р 12345-2023.pdf
|
||
```
|
||
|
||
2. Команда проекта загружает в комнату отраслевые документы:
|
||
- «Регламент работы библиотек.docx»
|
||
- «Отчет о кадровом составе.xlsx»
|
||
- «Методика оценки компетенций.pdf»
|
||
- «План внедрения 5S.docx»
|
||
|
||
3. Бот автоматически индексирует все файлы в комнатную БЗ.
|
||
|
||
4. Пользователь делает `!summary` по каждому документу, чтобы быстро понять содержание.
|
||
|
||
### Этап 2: Сохранение шаблона
|
||
|
||
5. Пользователь загружает `Шаблон коробочного решения.docx` и сохраняет как шаблон:
|
||
```
|
||
!template_save "Коробочное решение_Библиотеки"
|
||
```
|
||
|
||
### Этап 3: Генерация коробочного решения
|
||
|
||
6. Пользователь вводит:
|
||
```
|
||
!create "Коробочное решение_Библиотеки"
|
||
```
|
||
|
||
7. Бот:
|
||
- Находит все плейсхолдеры в шаблоне.
|
||
- Для каждого плейсхолдера выполняет гибридный поиск в БЗ комнаты.
|
||
- Использует расширение запроса и переранжирование.
|
||
- Генерирует значение через GigaChat (с самокритикой).
|
||
- Заменяет плейсхолдеры в копии шаблона.
|
||
- Отправляет готовый DOCX-файл в чат.
|
||
|
||
### Этап 4: Проверка и доработка
|
||
|
||
8. Пользователь открывает готовый DOCX, проверяет содержание.
|
||
|
||
9. При необходимости делает хирургическую замену:
|
||
```
|
||
Замени ООО "Ромашка" на ООО "Тюльпан"
|
||
```
|
||
|
||
10. Проверяет орфографию:
|
||
```
|
||
Проверь орфографию
|
||
```
|
||
|
||
11. Получает исправленный файл и отправляет руководству или клиенту.
|
||
|
||
### Этап 5: Обновление и масштабирование
|
||
|
||
12. Если в базу знаний добавляются новые документы, можно перегенерировать коробочное решение:
|
||
```
|
||
!create "Коробочное решение_Библиотеки"
|
||
```
|
||
Бот использует обновленную БЗ и создает актуальную версию.
|
||
|
||
13. Для другого типа организаций (музеи) создается аналогичный шаблон:
|
||
```
|
||
!template_save "Коробочное решение_Музеи"
|
||
!create "Коробочное решение_Музеи"
|
||
```
|
||
|
||
---
|
||
|
||
# II. Перспективы развития Эфцекабот
|
||
|
||
## 1. Типология ботов: от общефункциональных до персонального ассистента
|
||
|
||
Платформа Эфцекабот построена на едином RAG-ядре (HTTP-сервере), которое обслуживает **любое количество клиентов** – XMPP-ботов, Telegram-ботов, Mastodon-ботов, веб-интерфейсы, системы аналитики. Это означает, что одна и та же база знаний, история диалогов и логика обработки запросов доступны через любой интерфейс. Пользователь может начать диалог в XMPP, продолжить в Telegram, и контекст сохранится – все благодаря централизованному хранению истории на RAG-сервере.
|
||
|
||
### 1.1. Общие боты
|
||
|
||
| Тип бота | Отдел | Примеры запросов |
|
||
|----------|-------|------------------|
|
||
| **Методолог (стандарты)** | Методология, бизнес-аналитика, внутренний контроль | «Найди требования к описанию бизнес-процесса» |
|
||
| **Писатель коробочных решений** | Методология | «Напиши коробочное решение по образцу» |
|
||
| **Юрист-эксперт** | Юридический | «Составь претензию по шаблону» |
|
||
| **Финансовый аналитик** | Финансы, управленческий учет | «Рассчитай OEE по проекту X» |
|
||
| **HR-помощник** | Отдел персонала | «Образец служебной записки или бизнес-процесса» |
|
||
| **Менеджер проектов** | Проектный офис | «Сформируй выжимку по проекту за месяц» |
|
||
| **ИТ-архитектор** | IT-департамент | «Сравни конфигурации серверов из ТЗ» |
|
||
| **Комплаенс-контроль** | Служба безопасности | «Проверь отчет на соответствие регламенту» |
|
||
| **Executive-бот** | Топ-менеджмент | «Сводка KPI по всем проектам» |
|
||
|
||
Каждый из этих ботов может быть реализован как отдельный XMPP-клиент (или другой клиент), подключающийся к общему RAG-ядру. Благодаря единому ядру, все боты используют одни и те же документы и историю, но могут иметь свои промпты, что позволяет настраивать стиль и глубину ответов под конкретную задачу.
|
||
|
||
### 1.2. Персональный ассистент
|
||
|
||
**Уникальная особенность:** один и тот же бот, но с персональными настройками (история командировок, бюджетные лимиты, предпочтения по отелям, закрепленные проекты). Сотрудник общается с ботом как с личным секретарем.
|
||
|
||
В новой архитектуре персональные настройки хранятся в общей БД и доступны всем клиентам. Пользователь может начать диалог в XMPP, а продолжить в Telegram – история и контекст сохраняются.
|
||
|
||
**Ключевые сценарии персонального ассистента**:
|
||
|
||
| Сценарий | Пример запроса | Автоматизация |
|
||
|----------|----------------|---------------|
|
||
| **Планирование командировки** | «Запланируй командировку в Нижний Новгород на 10–12 мая» | Бот через агента-тревел подбирает билеты, отель, создает задачу на согласование руководителю, резервирует |
|
||
| **Поиск и бронирование билетов** | «Найди ближайший рейс до Екатеринбурга на завтра утро» | Интеграция с корпоративным тревел-агентом (API), выдача вариантов, бронирование по команде |
|
||
| **Бронирование гостиницы** | «Подбери гостиницу рядом с офисом клиента в Казани, бюджет до 5000 ₽/ночь» | Агент-отельер возвращает список, пользователь выбирает – бронь автоматически |
|
||
| **Оформление командировочного удостоверения** | «Сформируй командировочное удостоверение по поездке №45» | Бот заполняет шаблон данными из бронирования, высылает PDF |
|
||
| **Авансовый отчет по командировке** | «Сделай авансовый отчет за поездку в Уфу» | Бот предзаполняет даты, маршрут, суммы билетов и отеля; сотрудник добавляет фото чеков → OCR распознает и вносит суммы |
|
||
| **Согласование отчета** | «Отправь отчет руководителю на подпись» | Бот пересылает отчет в личный чат руководителя, тот ставит «OK» кнопкой |
|
||
| **Календарь командировок** | «Добавь поездку в мой календарь на 15–17 мая» | Синхронизация с корпоративным календарем (Exchange/Google) |
|
||
| **Статус командировок** | «Какие у меня утвержденные командировки на следующую неделю?» | Бот извлекает из базы данных (или внешней системы) и отвечает |
|
||
|
||
## 2. Как бот «вызывает» агентов – архитектура оркестрации
|
||
|
||
Эфцекабот выступает универсальным диспетчером. В текущей архитектуре **сами боты-клиенты не вызывают агентов напрямую**. Вместо этого:
|
||
|
||
1. Клиент (XMPP-бот, Telegram-бот и т.д.) отправляет запрос пользователя в RAG-сервер через HTTP.
|
||
2. RAG-сервер выполняет классификацию намерений (`intent_classify.py`).
|
||
3. Если запрос требует внешнего действия (бронирование, расчет, генерация отчета, OCR), RAG-сервер возвращает структурированную команду (например, в формате `[SURGICAL_REPLACE]`, `[REWRITE]`, или через теги для вызова агента).
|
||
4. Клиент (или отдельный агент-оркестратор) выполняет эту команду через API внешних систем и возвращает результат в RAG-сервер для финальной обработки.
|
||
|
||
| Запрос пользователя | Намерение (intent) | Вызываемый агент | Действие агента | Результат |
|
||
|---------------------|---------------------|------------------|-----------------|-----------|
|
||
| «Найди билеты Москва-Питер на 15 мая» | `BOOKING` | Агент-тревел | Запрос к API билетной системы | Список рейсов с ценами |
|
||
| «Подбери гостиницу рядом с вокзалом» | `BOOKING` | Агент-отельер | Поиск по API Booking.com / Ostrovok | Варианты отелей, кнопка бронирования |
|
||
| «Сделай авансовый отчет по командировке #123» | `REPORT` | Агент-генератор DOCX | Заполняет шаблон из данных бронирования и чеков | Готовый отчет в чат |
|
||
| «Проверь этот чек» | `OCR` | Агент-распознаватель (OCR) | Извлекает сумму, дату, назначение | Структурированные данные, которые бот вставляет в отчет |
|
||
|
||
**Вывод:** RAG-сервер – это «мозг», а агенты – «руки». Без RAG-сервера агенты разрозненны; с ним они работают как единая система, управляемая естественным языком через единый HTTP API.
|
||
|
||
## 3. Экономический эффект (исходные данные для штата 300 человек)
|
||
|
||
### 3.1. Экономия на поиске информации (RAG-функции)
|
||
|
||
- Время, затрачиваемое на поиск информации в документах в день на сотрудника (среднее) – **1 час**.
|
||
- Доля запросов, полностью автоматизируемых ботом (типовые вопросы по регламентам, KPI, стандартам) – **30%**.
|
||
- Доля запросов, где бот ускоряет поиск в 2 раза – **50%**.
|
||
- Остальные 20% – сложные, где экономия меньше, но мы не учитываем их консервативно.
|
||
|
||
**Экономия в часах:**
|
||
- Полная автоматизация: 300 × 247 (раб. дней) × 1 × 0,3 = 22 230 часов.
|
||
- Ускорение поиска: 300 × 247 × 0,5 × 0,5 = 18 525 часов (поскольку ускорение в 2 раза = 50% экономии).
|
||
|
||
### 3.2. Экономия на командировочных процессах (персональный ассистент)
|
||
|
||
**Допущения:**
|
||
- Количество командировок в год: 200 чел. × 44 недели = **8 800 командировок**.
|
||
- Без автоматизации затраты времени на одну командировку (поиск билетов, бронирование отеля, оформление заявки, составление авансового отчета, согласование) – **2 часа** (суммарно).
|
||
- С ботом (интеграция с тревел-агентом, автоматическое заполнение форм, OCR чеков, «однонажательное» согласование) – **0,4 часа** (24 минуты). Экономия = 1,6 часа на командировку.
|
||
|
||
**Экономия в часах:** 8 800 × 1,6 = **14 080 часов**.
|
||
|
||
### 3.3. Экономия на снижении ошибок и автоматической проверке документов
|
||
|
||
- Бот автоматически проверяет отчеты, договоры, счета на соответствие регламентам (`CONTRADICTION`, `TEMPLATE_FILL`). Предотвращает переделки и штрафы.
|
||
- Допустим, среднее время на переделку, исправление отчета, повторное согласование – 2 часа.
|
||
- В компании с 300 сотрудниками происходит минимум 1000 документооборотных ошибок в год (отчеты, договоры, заявки). Бот выявляет и исправляет 80% из них.
|
||
|
||
**Экономия в часах:** 800 ошибок × 2 часа = **1 600 часов** (консервативно).
|
||
|
||
### 3.4. Итоговая годовая экономия
|
||
|
||
| Статья | Часы |
|
||
|--------|------|
|
||
| Поиск информации (RAG) | 40 755 |
|
||
| Командировки (бронирование + отчетность) | 14 080 |
|
||
| Снижение ошибок в документообороте | 1 600 |
|
||
| **Итого прямая экономия времени** | **56 435** |
|
||
|
||
*Не учтены косвенные эффекты: ускорение согласования, повышение мотивации, снижение текучки.*
|
||
|
||
### 3.5. Затраты на внедрение и обслуживание
|
||
|
||
| Статья | Стоимость |
|
||
|--------|-----------|
|
||
| Развертывание инфраструктуры (серверы, настройка) | 1 млн руб. (разово) |
|
||
| Разработка интеграций (агенты, тревел-API, 1С, календарь) | 2 млн руб. (разово, можно тиражировать) |
|
||
| Обслуживание, обновление БЗ, поддержка | 1 млн руб./год |
|
||
| **Итого первый год** | **4 млн руб.** |
|
||
| **Итого последующие годы** | **1 млн руб./год** |
|
||
|
||
## 4. Перспективы развития (12–24 месяца)
|
||
|
||
### 4.1. Уже реализованные улучшения (доступны сейчас)
|
||
|
||
В текущей версии платформы уже реализованы следующие ключевые возможности (дополнены):
|
||
|
||
- **Цепочка рассуждений (Chain-of-Thought)** – для расчетов и инструкций модель показывает пошаговое решение.
|
||
- **Кэширование классификации и расширения запроса** – результаты кэшируются на 5 минут, что ускоряет повторные запросы.
|
||
- **Переранжирование через локальный кросс-энкодер** – вместо дорогого вызова LLM используется легкая модель `intfloat/multilingual-e5-reranker`.
|
||
- **Обрезка истории диалога по токенам** – точный подсчет через `tiktoken`, эффективное использование контекстного окна. Добавлена пагинация и обрезка сообщений до лимита.
|
||
- **Единое RAG-ядро с HTTP API** – все клиенты (XMPP, Telegram, веб) подключаются к одному серверу.
|
||
- **Генерация коробочных решений по шаблону** – команды `!create`, `!template_save`, `!template_list`, `!template_delete`.
|
||
- **Автоматическая индексация файлов в комнатах** – файлы индексируются без команды `!learn`.
|
||
- **Полнотекстовый поиск по точным фрагментам** – поиск по номерам пунктов, кавычкам и инструкциям.
|
||
- **Рефакторинг оркестратора** – `RAGOrchestrator` разбит на менеджеры (HistoryManager, IntentRouter, QueryProcessor, IndexingManager), что повышает тестируемость и сопровождаемость.
|
||
- **Конфигурация на Pydantic** – вместо ручной загрузки используется `AppConfig` с валидацией и автодополнением.
|
||
- **Аутентификация через API-ключ** – все эндпоинты RAG-сервера защищены заголовком `X-API-Key` (кроме `/health`).
|
||
- **Автоматическая документация OpenAPI** – доступны Swagger UI (`/docs`) и ReDoc (`/redoc`), а также сырая спецификация (`/openapi.json`).
|
||
- **Генерация API-ключа** – в `.env` добавлена переменная `RAG_API_KEY`.
|
||
- **Динамические few-shot примеры** – подбор релевантных примеров на основе запроса и построение промта по структуре «сэндвич».
|
||
- **SOMA-анализ (LLM-as-judge)** – автоматическая оценка качества ответов с перегенерацией при низких оценках. Результаты кэшируются (TTL 5 мин).
|
||
- **ReAct (вызов внешних инструментов)** – модель может итеративно вызывать внешние API (поиск, погода, бронирование, курс). Реализованы реальные обработчики.
|
||
- **Планирование действий** – генерация пошагового плана для сложных запросов (расчёты, инструкции).
|
||
- **Многоагентная архитектура** – координатор и специализированные агенты (методолог, коробочник, персональный ассистент).
|
||
- **Фоновый ReindexWorker** – автоматическая переиндексация документов с `indexed=False` (восстановление после сбоев).
|
||
- **Улучшения безопасности** – экранирование путей (shlex.quote), санитизация пользовательского ввода (ChatML), ограничение CORS, rate limiting (slowapi), retry + circuit breaker для GigaChat.
|
||
- **Кэширование эмбеддингов в Redis** – снижение нагрузки на GigaChat, экономия токенов.
|
||
- **Пагинация и обрезка истории диалога** – защита от переполнения БД, ускорение запросов.
|
||
- **Хранение исходного текста документов в PostgreSQL** (колонка `file_text`) – позволяет переиндексировать документы без потери данных.
|
||
- **Миграции через Alembic** – управление схемой БД через версионные миграции.
|
||
- **Интеграционные тесты** – покрытие новых эндпоинтов и команд.
|
||
- **Структурированное JSON-логирование** – для централизованного сбора логов (ELK/Loki).
|
||
|
||
### 4.2. Планируемые улучшения
|
||
|
||
- **Интеграция с системами документооборота (СЭД)** – бот сможет подписывать документы ЭЦП, отправлять их на регистрацию, отслеживать статусы.
|
||
- **Прогнозная аналитика командировок** – бот будет предлагать оптимальные маршруты, экономить на билетах за счет предварительного бронирования.
|
||
- **Агент-индексатор сетевых папок (SMB)** – бот сам сканирует общие каталоги и обновляет базу знаний.
|
||
- **Кэширование результатов генерации** – для одинаковых запросов (с использованием хеша запроса и контекста) планируется внедрение кэширования (Redis) на уровне RAG-сервера.
|
||
- **Сбор обратной связи** – команда `!feedback` для оценки качества ответов (лайки/дизлайки) и хранение оценок в БД.
|
||
- **A/B-тестирование промптов** – возможность разделять пользователей на группы и применять разные версии промптов.
|
||
- **Гибкие промты** – автоматический выбор краткой или расширенной версии промпта в зависимости от длины доступного контекстного окна.
|
||
- **Команда `!style`** – изменение стиля ответов (кратко/подробно/по умолчанию).
|
||
- **Подключение дополнительных клиентов** – Telegram, МАХ, без изменения ядра.
|
||
|
||
---
|
||
|
||
# III. Описание модулей
|
||
|
||
Платформа Эфцекабот построена по принципу **«тонкий клиент – толстый сервер»**. Вся RAG-логика вынесена в отдельный HTTP-сервис – **RAG-сервер**, который обслуживает все клиенты. Клиенты отправляют запросы на RAG-сервер через HTTP и не содержат RAG-логики.
|
||
|
||
Все модули, описанные ниже, расположены в каталоге `rag/`. Часть из них работает на RAG-сервере, часть – в клиентах, часть является общими утилитами.
|
||
|
||
## 1. Модуль `rag_orchestrator.py` – оркестратор RAG-пайплайна
|
||
|
||
**Назначение:** это **сердце платформы**. Модуль координирует все этапы обработки запроса через менеджеры:
|
||
|
||
- `HistoryManager` – получение и сжатие истории.
|
||
- `IntentRouter` – обработка специализированных намерений.
|
||
- `QueryProcessor` – обычный RAG-пайплайн (поиск, генерация, критика).
|
||
- `IndexingManager` – индексация документов с предварительным сжатием.
|
||
|
||
**Добавлены новые параметры:** `tool_handler` для передачи реальных обработчиков инструментов в `QueryProcessor`.
|
||
|
||
**Ключевые методы:**
|
||
|
||
- `process_query()` – основной метод, выполняет полный цикл обработки запроса.
|
||
- `index_document()` – индексация документа (вызывается из `/rag/index`). Перед индексацией применяет иерархическое резюмирование, если документ слишком большой.
|
||
|
||
**Особенности:**
|
||
|
||
- Не содержит состояния, использует переданные сервисы и промпты.
|
||
- Поддерживает специализированные намерения: `METRICS`, `SUMMARY`, `CONTRADICTION`, `TEMPLATE_FILL`, `SPELLCHECK`, `SURGICAL`, `GREETING`.
|
||
- Добавляет цепочку рассуждений (Chain-of-Thought) для `CALCULATION` и `PROCEDURE`.
|
||
- Включает интеграцию SOMA, ReAct, планирования и агентов через `QueryProcessor`.
|
||
|
||
|
||
|
||
## 2. Модуль `rag_server.py` – HTTP-сервер (FastAPI)
|
||
|
||
**Назначение:** предоставляет REST API для всех клиентов. Является точкой входа в платформу.
|
||
|
||
**Эндпоинты** (добавлены новые):
|
||
|
||
| Метод | Эндпоинт | Назначение | Требует аутентификации |
|
||
|-------|----------|------------|------------------------|
|
||
| POST | `/rag/query` | Выполнить RAG-запрос (история берется из БД) | Да |
|
||
| POST | `/rag/index` | Проиндексировать документ | Да |
|
||
| POST | `/rag/vision` | Распознать текст на изображении (OCR) | Да |
|
||
| POST | `/rag/transcribe` | Транскрибировать аудио (SaluteSpeech) | Да |
|
||
| POST | `/rag/clear` | Очистка БЗ (личной/комнатной/глобальной) | Да |
|
||
| POST | `/rag/list` | Список документов | Да |
|
||
| POST | `/rag/delete_global` | Удаление глобального документа | Да (админ) |
|
||
| POST | `/rag/template/save` | Сохранить шаблон | Да |
|
||
| POST | `/rag/template/list` | Список шаблонов комнаты | Да |
|
||
| POST | `/rag/template/delete` | Удалить шаблон | Да |
|
||
| POST | `/rag/reset_history` | Сброс истории диалога | Да |
|
||
| POST | `/rag/room/add` | Добавить комнату | Да |
|
||
| GET | `/rag/room/list` | Список комнат | Да |
|
||
| POST | `/rag/stats` | Статистика | Да (админ) |
|
||
| POST | `/rag/generate_document` | Генерация документа по шаблону | Да |
|
||
| GET | `/health` | Проверка состояния сервера | Нет |
|
||
| GET | `/metrics` | Метрики Prometheus | Нет |
|
||
| GET | `/docs` | Swagger UI | Нет |
|
||
| GET | `/redoc` | ReDoc | Нет |
|
||
| GET | `/openapi.json` | OpenAPI-спецификация | Нет |
|
||
|
||
**Место в архитектуре:** запускается как отдельный процесс (с помощью Uvicorn). Обслуживает все клиенты. Инициализирует все сервисы (БД, Qdrant, GigaChat) и создает экземпляр `RAGOrchestrator`.
|
||
|
||
**Особенности:**
|
||
|
||
- Использует Pydantic для валидации запросов и ответов.
|
||
- Поддерживает CORS для возможности запросов с других доменов.
|
||
- Имеет встроенный healthcheck для мониторинга.
|
||
- Эндпоинты `/rag/vision` и `/rag/transcribe` используют `FileService` для обработки медиафайлов.
|
||
- Аутентификация через API-ключ (`X-API-Key`).
|
||
- Полная OpenAPI-документация с примерами и кодами ошибок.
|
||
- Graceful shutdown (сигналы SIGTERM/SIGINT) с остановкой ReindexWorker и закрытием ToolHandler.
|
||
- Расширенный `/health` с проверкой PostgreSQL и Qdrant.
|
||
- Ограничение CORS через переменную окружения.
|
||
- Метрики Prometheus (`/metrics`).
|
||
- Структурированное JSON-логирование.
|
||
- Гарантированное удаление временных файлов (`tempfile.TemporaryDirectory`).
|
||
- Интеграция ReindexWorker, SOMA, ReAct, планирования, агентов, ToolHandler.
|
||
|
||
|
||
## 3. Модуль `rag_client.py` – HTTP-клиент для ботов
|
||
|
||
**Назначение:** используется тонкими клиентами для отправки запросов к RAG-серверу.
|
||
|
||
**Методы:**
|
||
|
||
- `query()` – отправляет запрос на `/rag/query`.
|
||
- `index_document()` – отправляет запрос на `/rag/index`.
|
||
- `vision(file_path)` – отправляет изображение на `/rag/vision`.
|
||
- `transcribe(file_path)` – отправляет аудио на `/rag/transcribe`.
|
||
- `health_check()` – проверяет доступность сервера.
|
||
- `clear()` – очистка БЗ.
|
||
- `list_documents()` – список документов.
|
||
- `delete_global()` – удаление глобального документа.
|
||
- `template_save()`, `template_list()`, `template_delete()` – управление шаблонами.
|
||
- `reset_history()` – сброс истории.
|
||
- `add_room()`, `get_rooms()` – управление комнатами.
|
||
- `get_stats()` – статистика.
|
||
- `generate_document()` – генерация документа по шаблону.
|
||
|
||
**Особенности:**
|
||
|
||
- Асинхронный (aiohttp).
|
||
- Поддерживает повторные попытки (retry) при сетевых ошибках.
|
||
- Автоматически добавляет заголовок `X-API-Key`.
|
||
- Не содержит бизнес-логики – только HTTP-вызовы.
|
||
|
||
## 4. Модуль `rag_api.py` – локальный API-интерфейс
|
||
|
||
**Назначение:** прослойка (facade) между ботами и `RAGOrchestrator` для локального использования (без HTTP). Этот модуль опционален – в новой архитектуре предпочтительнее использовать `RAGClient`.
|
||
|
||
**Место в архитектуре:** может использоваться для тестирования или в случае, если RAG-ядро запущено в том же процессе, что и клиент.
|
||
|
||
## 5. Модуль `prompt_builder.py` – построитель промтов
|
||
|
||
**Назначение:** динамически подбирает релевантные few-shot примеры из файла `data/fewshot_examples.json` (или использует статические) и формирует промт по структуре «сэндвич» (важное в начале и в конце). Это улучшает качество ответов, особенно для сложных запросов.
|
||
|
||
**Формат файла** `fewshot_examples.json`:
|
||
|
||
```json
|
||
[
|
||
{
|
||
"keywords": ["OEE", "эффективность"],
|
||
"intents": ["PROCEDURE", "CALCULATION"],
|
||
"question": "Как рассчитать OEE?",
|
||
"answer": "OEE = Доступность × Производительность × Качество."
|
||
}
|
||
]
|
||
```
|
||
|
||
- `keywords` – список ключевых слов для поиска релевантности.
|
||
- `intents` – список намерений, для которых применим пример.
|
||
- `question` – вопрос пользователя.
|
||
- `answer` – эталонный ответ.
|
||
|
||
**Место в архитектуре:** используется в `QueryProcessor` при синтезе ответа.
|
||
|
||
**Добавлена санитизация пользовательских данных (`_sanitize`) для защиты от инъекций ChatML.**
|
||
|
||
## 6. Модули функций (каталог `functions/`)
|
||
|
||
Все функции являются чистыми, без состояния. Добавлены новые:
|
||
|
||
- **`soma_evaluate.py`** – SOMA-анализ (LLM-as-judge) с кэшированием.
|
||
- **`react.py`** – цикл ReAct с улучшенным fallback-парсингом JSON.
|
||
- **`plan_generation.py`** – генерация плана действий.
|
||
- **`tools.py`** – реальные обработчики инструментов (поиск, погода, бронирование, курс).
|
||
|
||
Обновлены:
|
||
- `rerank_context.py` – использует асинхронную загрузку модели.
|
||
- `critique_answer.py` – самокритика по 5 критериям (без изменений).
|
||
|
||
### 6.1. `intent_classify.py` – классификация намерений
|
||
|
||
**Назначение:** определяет тип запроса пользователя (FACT, PROCEDURE, METRICS, SUMMARY, CONTRADICTION, SURGICAL, GREETING, GENERAL, SPELLCHECK, TEMPLATE_FILL) по тексту запроса. **Примеры в промпте перемешаны для уменьшения эффекта якорения.**
|
||
|
||
**Место в архитектуре:** вызывается из `RAGOrchestrator` перед поиском.
|
||
|
||
**Как работает:** отправляет промпт (`intent_classify.txt`) в GigaChat, получает один из кодов, кэширует результат на 5 минут.
|
||
|
||
**Вход:** текст запроса, промпт, конфиг.
|
||
**Выход:** код намерения (str) или `"GENERAL"`.
|
||
|
||
### 6.2. `expand_query.py` – расширение запроса
|
||
|
||
**Назначение:** добавляет синонимы, аббревиатуры и связанные термины к исходному запросу для увеличения полноты поиска.
|
||
|
||
**Место в архитектуре:** вызывается перед поиском в Qdrant.
|
||
|
||
**Как работает:** отправляет промпт (`expand.txt`) в GigaChat, получает до 10 дополнительных ключевых слов, кэширует на 5 минут.
|
||
|
||
**Вход:** текст запроса, промпт, конфиг.
|
||
**Выход:** расширенный запрос (строка) или исходный, если расширение не удалось.
|
||
|
||
### 6.3. `extract_metrics.py` – извлечение метрик
|
||
|
||
**Назначение:** извлекает числовые показатели (KPI, OEE, такт, выработку, проценты) из текста в структурированном виде (JSON).
|
||
|
||
**Место в архитектуре:** вызывается при намерении `METRICS`.
|
||
|
||
**Как работает:** отправляет промпт (`metrics_extract.txt`) в GigaChat, парсит JSON-ответ. При неудаче – fallback-парсинг строк вида `ключ: значение`.
|
||
|
||
**Вход:** контекст (текст), промпт, конфиг.
|
||
**Выход:** список словарей с полями `metric_name`, `value`, `unit`, `period`, `source_fragment`.
|
||
|
||
### 6.4. `summarize_document.py` – суммаризация документа
|
||
|
||
**Назначение:** создает краткий пересказ документа (≤30% от оригинала) с выделением целей, выводов и ключевых цифр.
|
||
|
||
**Место в архитектуре:** вызывается при намерении `SUMMARY`.
|
||
|
||
**Как работает:** отправляет промпт (`smart_summary.txt`) в GigaChat, подставляя текст документа.
|
||
|
||
**Вход:** текст, название, промпт, конфиг.
|
||
**Выход:** строка с кратким изложением.
|
||
|
||
### 6.5. `hierarchical_summarize.py` – иерархическое резюмирование
|
||
|
||
**Назначение:** сжимает очень большие тексты (документы, историю диалога) с помощью рекурсивного резюмирования блоков. Разбивает текст на блоки по предложениям, резюмирует каждый блок через GigaChat, объединяет результаты, и при необходимости повторяет процесс рекурсивно до достижения целевой длины.
|
||
|
||
**Место в архитектуре:** вызывается из `RAGOrchestrator`:
|
||
|
||
- В `process_query` – для сжатия длинной истории диалога.
|
||
- В `index_document` – для сжатия больших документов перед индексацией (через метод `_compress_document_if_needed`).
|
||
|
||
**Как работает:** использует промпт (`hierarchical_summary.txt`) для каждого блока.
|
||
|
||
**Вход:** текст, целевой размер в токенах, размер блока, глубина.
|
||
**Выход:** сжатый текст.
|
||
|
||
### 6.6. `check_consistency.py` – проверка противоречий
|
||
|
||
**Назначение:** находит логические, числовые или терминологические расхождения в разных фрагментах текста.
|
||
|
||
**Место в архитектуре:** вызывается при намерении `CONTRADICTION`.
|
||
|
||
**Как работает:** отправляет промпт (`consistency_check.txt`) в GigaChat, получает ответ `[OK]` или `[CONFLICT]` с описанием.
|
||
|
||
**Вход:** список фрагментов, запрос, промпт, конфиг.
|
||
**Выход:** строка с результатом проверки.
|
||
|
||
### 6.7. `critique_answer.py` – самокритика ответа
|
||
|
||
**Назначение:** оценивает качество сгенерированного ответа по пяти критериям (соответствие источнику, отсутствие галлюцинаций, стиль, логика, запрет внешних знаний).
|
||
|
||
**Место в архитектуре:** вызывается после генерации ответа (если включена в конфиге).
|
||
|
||
**Как работает:** отправляет промпт (`self_critique.txt`) в GigaChat, анализирует ответ на наличие `[OK]` или `[ISSUES]`.
|
||
|
||
**Вход:** запрос, контекст, ответ, промпт, конфиг.
|
||
**Выход:** `True` (ответ хороший) или `False` (есть замечания).
|
||
|
||
### 6.8. `rerank_context.py` – переранжирование контекста
|
||
|
||
**Назначение:** отбирает только релевантные фрагменты из результатов поиска, отбрасывая шум. Использует локальный кросс-энкодер вместо LLM.
|
||
|
||
**Место в архитектуре:** вызывается после поиска в Qdrant (если контекст длиннее `min_length`).
|
||
|
||
**Как работает:** отправляет фрагменты в кросс-энкодер (`intfloat/multilingual-e5-reranker`), ранжирует и возвращает только топ-N фрагментов.
|
||
|
||
**Вход:** запрос, контекст, конфиг.
|
||
**Выход:** отфильтрованный контекст (строка).
|
||
|
||
### 6.9. `file_processor.py` – обработка файлов
|
||
|
||
**Назначение:** отправка файлов пользователю через HTTP Upload (XEP-0363) и обработка тегов `[SURGICAL_REPLACE]`, `[REWRITE]`, `[FILE]` из ответа AI.
|
||
|
||
**Место в архитектуре:** вызывается из клиентов (XMPP-ботов) и из RAG-пайплайна при наличии тегов.
|
||
|
||
**Как работает:** парсит ответ AI, извлекает теги, вызывает методы `FileService` для замены или создания DOCX-файлов, отправляет результат через HTTP Upload.
|
||
|
||
**Вход:** ответ AI, JID пользователя, путь к файлу.
|
||
**Выход:** отправленный файл или сообщение об ошибке.
|
||
|
||
### 6.10. `generate_document.py` – генерация по шаблону
|
||
|
||
**Назначение:** заполняет плейсхолдеры `{{название}}` в шаблоне документа на основе данных из базы знаний.
|
||
|
||
**Место в архитектуре:** вызывается из команды `!create` (через RAG-сервер).
|
||
|
||
**Как работает:** находит все плейсхолдеры, для каждого выполняет поиск в БЗ, генерирует значение через GigaChat, заменяет в копии шаблона.
|
||
|
||
**Вход:** шаблон (DOCX), запрос пользователя, конфиг.
|
||
**Выход:** готовый DOCX-файл.
|
||
|
||
## 7. Сервисы (каталог `services/`)
|
||
|
||
Долгоживущие компоненты, которые инициализируются один раз при старте RAG-сервера и предоставляют API для работы с внешними системами.
|
||
|
||
| Файл | Назначение |
|
||
|------|------------|
|
||
| `postgres_service.py` | Пул соединений с PostgreSQL. CRUD для документов, истории диалогов, комнат, шаблонов, прав доступа. Добавлена колонка `file_text`, проверка таблиц (Alembic), составные индексы для полнотекстового поиска, пагинация в get_history. |
|
||
| `qdrant_service.py` | Векторная БД. Создание коллекции, гибридный поиск (dense + sparse), полнотекстовый поиск, удаление по `doc_id`. Сохранение `file_text` при индексации, метод `reindex_failed_documents()`. |
|
||
| `embedding_service.py` | Эмбеддинги GigaChat. Одиночные/пакетные запросы, кэширование (`lru_cache`), обрезка текста до 800 символов. Внедрён Redis для кэширования эмбеддингов (с fallback на локальный кэш).|
|
||
| `kb_service.py` | База знаний. Индексация документов (разбиение на чанки, получение эмбеддингов, сохранение в Qdrant и PostgreSQL), поиск, управление доступом. Транзакционная индексация с флагом `indexed`. |
|
||
| `file_service.py` | Извлечение текста из файлов (DOCX, PDF, XLSX, PPTX, изображения, аудио, архивы). Хирургическая замена, создание DOCX. Используется на RAG-сервере для OCR и транскрибации. |
|
||
| `giga_client.py` | Клиент GigaChat. Методы `chat()` и `upload_file()` – без бизнес-логики. Добавлены retry (tenacity) и circuit breaker (pybreaker). |
|
||
| `reranker_service.py` | Кросс-энкодер для переранжирования (локально). Ленивая загрузка модели. Асинхронная загрузка модели с использованием `asyncio.Lock` и `asyncio.Event`. |
|
||
| `file_service.py` | Экранирование путей (`shlex.quote`) в `transcribe_audio`. |
|
||
| `web_utils.py` | Ограничение размера загружаемого контента в `fetch_any_url`. |
|
||
|
||
|
||
## 8. Обработчики, команды, воркеры (для XMPP-клиентов)
|
||
|
||
Эти модули работают только на стороне **тонких клиентов** (XMPP-ботов) и не входят в RAG-сервер.
|
||
|
||
**Команды** переписаны на использование `RAGClient`, удалены обращения к `kb`, `db`, `qdrant`.
|
||
- **`room_handler.py`** – сохранение комнат на сервере через `rag_client.add_room()`, загрузка комнат при старте.
|
||
- **`file_handler.py`** – гарантированное удаление временных файлов (`tempfile.TemporaryDirectory`).
|
||
- **`client.py`** – загрузка комнат с сервера, периодическая очистка словарей `_last_file_path` и `last_file_texts`.
|
||
- **`reindex_worker.py`** (новый) – фоновый воркер для переиндексации документов с `indexed=False`.
|
||
|
||
### 8.1. Обработчики (`handlers/`)
|
||
|
||
| Файл | Назначение |
|
||
|------|------------|
|
||
| `metrics_handler.py` | Счетчики (сообщения, файлы, AI-запросы, ошибки). |
|
||
| `message_handler.py` | Маршрутизация входящих сообщений (использует `RAGClient`). |
|
||
| `file_handler.py` | Скачивание файлов и постановка в очередь индексации. Убраны прямые вызовы GigaChat – теперь все через RAGClient. |
|
||
| `room_handler.py` | MUC комнаты (приглашения, вход, переподключение). |
|
||
| `subscription_handler.py` | Подписки (roster subscription). |
|
||
| `health_handler.py` | Очистка файлов, healthcheck БД/Qdrant (для клиентов). |
|
||
|
||
### 8.2. Команды (`commands/`)
|
||
|
||
| Файл | Назначение |
|
||
|------|------------|
|
||
| `base.py` | Базовый класс `Command`. |
|
||
| `registry.py` | Регистрация команд, алиасы, подсказки. |
|
||
| `info.py` | `!info` – краткая справка. |
|
||
| `help.py` | `!help` – подробная справка. |
|
||
| `learn.py` | `!learn`, `!stop_learn`, `!global_learn`. |
|
||
| `kb.py` | `!clear`, `!global_clear`, `!kb`. |
|
||
| `stats.py` | `!stats`, `!status`, `!clean` (админ). |
|
||
| `expert.py` | `!summary`, `!metrics`. |
|
||
| `other.py` | `!reset`. |
|
||
| `template.py` | `!template_save`, `!template_list`, `!template_delete`. |
|
||
| `create.py` | `!create` – генерация документа по шаблону. |
|
||
| `global_remove.py` | `!global_remove` – удаление глобального документа (админ). |
|
||
|
||
### 8.3. Воркеры (`workers/`)
|
||
|
||
| Файл | Назначение |
|
||
|------|------------|
|
||
| `indexing_worker.py` | Фоновый воркер, который обрабатывает очередь индексации файлов и URL, отправляя их на RAG-сервер через `RAGClient`. Обработка изображений и аудио теперь через RAG-сервер. |
|
||
|
||
## 9. Утилиты (каталог `utils/`)
|
||
|
||
Вспомогательные функции, используемые как сервером, так и клиентами:
|
||
|
||
| Файл | Назначение |
|
||
|------|------------|
|
||
| `config_loader.py` | Загрузка `rag.conf` и `bot.conf`, слияние, чтение `.env`, создание `AppConfig` с помощью Pydantic. |
|
||
| `logger.py` | Настройка логирования (уровни, вывод в файл и консоль). |
|
||
| `layout_converter.py` | Конвертер раскладки клавиатуры (русская ↔ английская). |
|
||
| `text_utils.py` | Разбиение текста на чанки (tiktoken + razdel), подсчет токенов (`count_tokens`). |
|
||
| `web_utils.py` | Веб-скрапинг (`fetch_any_url`, `crawl_url`). |
|
||
| `arg_parser.py` | Парсинг аргументов команд (--flag value). |
|
||
|
||
- **`logger.py`** – добавлена поддержка JSON-логирования (параметр `json_format`).
|
||
- **`web_utils.py`** – ограничение размера загружаемого контента.
|
||
|
||
## 10. Тесты (каталог `tests/`)
|
||
|
||
Покрывают критически важные функции:
|
||
|
||
- `test_intent_classify.py` – классификация намерений.
|
||
- `test_expand_query.py` – расширение запроса.
|
||
- `test_extract_metrics.py` – извлечение метрик.
|
||
- `test_summarize.py` – суммаризация.
|
||
- `test_consistency.py` – проверка противоречий.
|
||
- `test_critique.py` – самокритика.
|
||
- `test_check_spelling.py` – проверка орфографии.
|
||
- `test_hierarchical_summarize.py` – иерархическое резюмирование.
|
||
|
||
Тесты используют `pytest` и `pytest-asyncio`, не требуют реального подключения к внешним сервисам (используются моки). Запуск: `pytest tests/ -v`.
|
||
|
||
- **Unit-тесты** – без изменений.
|
||
- **Интеграционные тесты** – добавлены `test_endpoints.py` и `test_commands.py` для проверки новых эндпоинтов и команд.
|
||
|
||
## 11. Конфигурационные файлы
|
||
|
||
Платформа использует два основных конфигурационных файла:
|
||
|
||
- **`rag.conf`** – общие настройки для всех ботов: параметры подключения к БД, Qdrant, GigaChat, настройки чанкинга, RAG, веб-скрапера, очистки, логирования. Добавлены параметры управления токенами и секция `summarization`.
|
||
- **`bot.conf`** – настройки конкретного профиля бота (методолог, коробочник, персональный ассистент): JID, пароль, промпты, пути к данным, ключевые слова, администраторы, параметры функций (температура, лимиты).
|
||
|
||
Переменные окружения (пароли, ключи API) хранятся в `.env`. Примеры конфигурации предоставлены в файлах `rag.conf.example`, `bot.conf.sample`, `env.example`.
|
||
|
||
## 12. Схема базы данных (PostgreSQL)
|
||
|
||
Схема управляется через Alembic. Таблицы:
|
||
|
||
- **`documents`** – добавлена колонка `file_text TEXT` для хранения исходного текста документа.
|
||
- **`document_access`** – права доступа.
|
||
- **`history`** – история диалогов.
|
||
- **`rooms`** – список MUC-комнат.
|
||
- **`room_templates`** – шаблоны.
|
||
|
||
Индексы: добавлены составные индексы `(room_jid, source_name)` и `(owner_jid, source_name)` для ускорения полнотекстового поиска.
|
||
|
||
---
|
||
|
||
# IV. Руководство по настройке аутентификации и доступу к API
|
||
|
||
# IV. Руководство по настройке аутентификации и доступу к API
|
||
|
||
## 1. Генерация API-ключа
|
||
|
||
Для защиты RAG-сервера используется API-ключ в заголовке `X-API-Key`. Сгенерировать ключ:
|
||
|
||
```bash
|
||
python3 -c "import secrets; print(secrets.token_urlsafe(32))"
|
||
```
|
||
|
||
## 2. Прописать ключ в переменные окружения
|
||
|
||
В `.env` добавьте:
|
||
|
||
```env
|
||
RAG_API_KEY=ваш_ключ
|
||
```
|
||
|
||
## 3. Использование в Swagger UI
|
||
|
||
Откройте `http://localhost:8080/docs`, нажмите **Authorize**, введите ключ.
|
||
|
||
## 4. Использование в боте
|
||
|
||
В `client.py` `RAGClient` автоматически использует `config.rag_api_key`.
|
||
|
||
## 5. Миграции Alembic
|
||
|
||
Для управления схемой БД используйте Alembic. Установите переменную окружения `FCKBOT_PROFILE_DIR` с путём к профилю бота, затем:
|
||
|
||
```bash
|
||
alembic upgrade head
|
||
```
|
||
|
||
Для создания новой миграции:
|
||
|
||
```bash
|
||
alembic revision --autogenerate -m "описание"
|
||
``` |