diff --git a/README.md b/README.md index ffb520a..b6b3abb 100644 --- a/README.md +++ b/README.md @@ -8,16 +8,18 @@ **Архитектура**: платформа состоит из трех основных слоев. -1. **RAG-ядро (HTTP-сервис)** — центральный компонент, выполняющий все этапы обработки запросов: классификацию намерений, расширение запроса, гибридный поиск (dense + sparse) в Qdrant, переранжирование через локальный кросс-энкодер, синтез ответа через GigaChat, самокритику и перегенерацию. Ядро также управляет индексацией документов и хранением истории диалогов в PostgreSQL. RAG-ядро реализовано как отдельный HTTP-сервер (FastAPI + Uvicorn), что позволяет использовать его для любых клиентов (XMPP, Telegram, Mastodon, веб-интерфейс, системы аналитики). RAG-сервер также предоставляет эндпоинты `/rag/vision` для распознавания текста на изображениях (OCR) и `/rag/transcribe` для транскрибации аудио, что централизует обработку медиафайлов. +1. **RAG-ядро (HTTP-сервис)** — центральный компонент, выполняющий все этапы обработки запросов: классификацию намерений, расширение запроса, гибридный поиск (dense + sparse) в Qdrant, переранжирование через локальный кросс-энкодер, синтез ответа через GigaChat, самокритику и перегенерацию. Ядро также управляет индексацией документов и хранением истории диалогов в PostgreSQL. RAG-ядро реализовано как отдельный HTTP-сервер (FastAPI + Uvicorn), что позволяет использовать его для любых клиентов (XMPP, Telegram, Mastodon, веб-интерфейс, системы аналитики). RAG-сервер также предоставляет эндпоинты `/rag/vision` для распознавания текста на изображениях (OCR) и `/rag/transcribe` для транскрибации аудио, что централизует обработку медиафайлов. 2. **Тонкие XMPP-боты-клиенты** — каждый профиль (методолог, коробочник, персональный ассистент) представляет собой отдельный XMPP-клиент, который подключается к ejabberd, обрабатывает команды, принимает файлы и пересылает запросы пользователей в RAG-ядро по HTTP. Боты не содержат RAG-логики, не имеют локальной БД или Qdrant, а только загружают свои промпты и передают их в запросах. Это делает их легковесными и независимыми. Вся обработка изображений и аудио выполняется на RAG-сервере, что дополнительно упрощает клиентов. 3. **Внешние системы хранения и API**: - **Ejabberd** — XMPP-сервер (сообщения, MUC-комнаты, HTTP Upload); -- **PostgreSQL** — централизованное хранилище метаданных документов, истории диалогов, прав доступа, списка комнат, шаблонов и оценок обратной связи; -- **Qdrant** — векторная БД с двумя полями (dense, sparse) для гибридного поиска. Доступна только RAG-ядру; +- **PostgreSQL** — централизованное хранилище метаданных документов, истории диалогов, прав доступа, списка комнат, шаблонов и оценок обратной связи. Управление схемой через Alembic (миграции). Добавлена колонка `file_text` для хранения исходного текста документов. +- **Qdrant** — векторная БД с двумя полями (dense, sparse) для гибридного поиска. Доступна только RAG-ядру. - **GigaChat API** — генерация текста и эмбеддингов. Вызовы осуществляются только из RAG-ядра, что позволяет централизованно управлять кэшированием и лимитами. +- **Redis** (опционально) — кэширование эмбеддингов (TTL 1 час) и результатов SOMA-оценок (TTL 5 мин). +- **Внешние API** — для инструментов ReAct: DuckDuckGo (поиск), OpenWeatherMap (погода), заглушки для бронирования и курсов валют. **Философия**: @@ -25,18 +27,19 @@ - Боты-клиенты не имеют собственных знаний — они только передают запросы в 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` — внешние системы. +- `Ejabberd`, `PostgreSQL`, `Qdrant`, `Redis` — внешние системы. Инфраструктура развернута на **FreeBSD** с использованием **джейлов** (изолированных окружений), **ZFS** (файловая система с поддержкой снэпшотов и сжатия) и **10-гигабитной** внутренней сети между сервисами. Балансировщик **HAProxy** обеспечивает маршрутизацию внешних запросов и, при необходимости, горизонтальное масштабирование. Автоматические снэпшоты ZFS настроены через `zfs-auto-snapshot` для надежного резервного копирования. ## 3. Уникальность решения -1. **Гибридный RAG (dense + sparse) с самокритикой и централизованным ядром** — не используется в корпоративных ботах массово. Коммерческие решения часто ограничиваются простым семантическим поиском без переранжирования и самокритики. Вынесение RAG-логики в отдельный HTTP-сервис позволяет легко масштабировать и подключать любые клиентские интерфейсы. +1. **Гибридный RAG (dense + sparse) с самокритикой и централизованным ядром** — не используется в корпоративных ботах массово. Коммерческие решения часто ограничиваются простым семантическим поиском без переранжирования и самокритики. Вынесение RAG-логики в отдельный HTTP-сервис позволяет легко масштабировать и подключать любые клиентские интерфейсы. 2. **Персональный ассистент как часть экосистемы** — типичные персональные ассистенты не имеют доступа к внутренней базе знаний и не умеют отвечать на сложные вопросы по документам. Эфцекабот объединяет общие и персональные функции в едином RAG-ядре, при этом каждый бот-профиль использует свои промпты, что позволяет гибко настраивать поведение под конкретные задачи. @@ -48,6 +51,8 @@ 6. **Автоматическая индексация файлов в комнатах** — файл, попавший в групповой чат, автоматически становится доступен всей команде через RAG-ядро. Даже у Slack и Teams нет такой функции «из коробки». +7. **Встроенные инновационные техники** — SOMA-анализ (LLM-as-judge), ReAct (вызов внешних инструментов), планирование действий, многоагентность — позволяют повысить качество ответов, экономить токены и автоматизировать сложные рабочие процессы. + ## 4. Преимущества и недостатки работы бота в чате #### Преимущества @@ -61,20 +66,21 @@ - **Полный контроль данных** — развертывание внутри периметра, никаких облачных сервисов. - **Поддерживаемые форматы**: DOCX, PDF, XLSX, PPTX, TXT, CSV, JSON, изображения (OCR), аудио (SaluteSpeech), архивы ZIP/7z. - **Размер загружаемого файла**: до 1 Гб. +- **Расширенные возможности** — SOMA-оценка ответов, ReAct-вызовы внешних API, планирование, многоагентность, фоновый ReindexWorker для восстановления после сбоев. #### Недостатки -- **Задержка** — добавлен сетевой вызов от бота к RAG-ядру (1–2 мс внутри сети) и несколько вызовов GigaChat (3–10 секунд). Однако благодаря кэшированию (классификация, расширение, эмбеддинги) и локальному кросс-энкодеру итоговое время ответа в большинстве случаев составляет 3–7 секунд, что приемлемо для экспертной системы. -- **Сложность отладки** — распределенная система (RAG-ядро, боты-клиенты, ejabberd, PostgreSQL, Qdrant) усложняет трассировку ошибок, но централизованное логирование и единая точка входа (RAG-ядро) упрощают мониторинг. +- **Задержка** — добавлен сетевой вызов от бота к 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 вызова на запрос (классификация, расширение, генерация, критика). Благодаря общему кэшированию (TTL 5 минут) для классификации и расширения, а также локальному кросс-энкодеру для переранжирования, количество вызовов GigaChat сокращено до минимума, что снижает итоговую задержку до 3–7 секунд. | -| **Экономия токенов** | Переранжирование и гибридный поиск (sparse + dense) уменьшают объем контекста. История диалога обрезается точно по токенам (через tiktoken) на стороне RAG-ядра, что позволяет эффективнее использовать контекстное окно. Дополнительно внедрено иерархическое резюмирование для сжатия длинных диалогов и документов, что еще больше экономит токены. Централизация также позволяет агрегировать кэши и общие эмбеддинги, снижая общие затраты на токены. | -| **Качество ответа** | GigaChat хорошо понимает русский язык, отлично справляется с деловой и технической терминологией. Но без точного промпта и контекста возможны галлюцинации — самокритика и перегенерация, выполняемые в RAG-ядре, частично нивелируют это. Единые промпты для всех клиентов упрощают тонкую настройку качества. Иерархическое резюмирование помогает сохранить ключевую информацию в длинных документах. | -| **Надежность** | GigaChat имеет лимиты и может выдавать ошибки. RAG-ядро делает несколько попыток при эмбеддингах и генерации, а при отказе API возвращает сообщение о недоступности. Централизация позволяет реализовать единые политики повторных попыток и fallback. RAGClient устойчив к сетевым ошибкам (ClientConnectorError и др.). | +| **Скорость** | GigaChat — облачный API, задержка ~1–2 секунды на вызов. В текущей архитектуре все вызовы GigaChat происходят только из RAG-ядра (не из ботов). Пайплайн может делать 2–4 вызова на запрос (классификация, расширение, генерация, критика, 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. Архитектура проекта @@ -84,46 +90,99 @@ Платформа состоит из трех основных логических слоев. ``` -┌──────────────────────────────────────────────────────────────────────┐ -│ ВНеНИЕ КЛИЕНТЫ (пользователи) │ -│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ -│ │ XMPP-боты │ │ Telegram │ │ Mastodon │ │ Веб-интерф. │ │ -│ │ (тонкие) │ │ (клиент) │ │ (клиент) │ │ (клиент) │ │ -│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │ -│ │ │ │ │ │ -│ └────────────────┼────────────────┼────────────────┘ │ -│ │ │ │ -│ ▼ ▼ │ -│ ┌────────────────────────────────────────────────────────────────┐ │ -│ │ RAG-Сервер (HTTP API) │ │ -│ │ POST /rag/query – выполнить RAG-запрос │ │ -│ │ POST /rag/index – проиндексировать документ │ │ -│ │ POST /rag/vision – распознать текст на изображении (OCR) │ │ -│ │ POST /rag/transcribe – транскрибировать аудио │ │ -│ │ GET /health – проверить состояние │ │ -│ │ GET /docs – Swagger UI (интерактивная документация)│ │ -│ │ GET /redoc – ReDoc (альтернативная документация) │ │ -│ │ GET /openapi.json – OpenAPI-спецификация │ │ -│ └────────────────────────────────────────────────────────────────┘ │ -│ │ │ -│ ▼ │ -│ ┌────────────────────────────────────────────────────────────────┐ │ -│ │ ВНЕШНИЕ СИСТЕМЫ (данные и API) │ │ -│ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │ -│ │ │PostgreSQL │ │ Qdrant │ │ GigaChat │ │ Файлы │ │ │ -│ │ │(история, │ │(векторный │ │ (генерация│ │ (DOCX, │ │ │ -│ │ │ документы,│ │ поиск) │ │эмбеддинги)│ │ PDF и │ │ │ -│ │ │ права) │ │ │ │ │ │ т.д.) │ │ │ -│ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │ │ -│ └────────────────────────────────────────────────────────────────┘ │ -└──────────────────────────────────────────────────────────────────────┘ +┌──────────────────────────────────────────────────────────────────────────────────────-┐ +│ ВНЕШНИЕ КЛИЕНТЫ (пользователи) │ +│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ +│ │ 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-сервис. -- **Тонкие клиенты** — боты-профили (XMPP, Telegram, Mastodon и т.д.), которые только передают запросы в RAG-сервер и не содержат RAG-логики. -- **Внешние системы** — PostgreSQL, Qdrant, GigaChat API — доступны только RAG-серверу. +- **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. Структура каталогов проекта @@ -131,48 +190,62 @@ ``` /usr/local/etc/fckbot/ # КОРЕНЬ ПРОЕКТА -├── rag/ # RAG-СеВе (HTTP-ядро) +│ +├── 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 # Менеджер истории диалогов (сжатие, сохранение) +│ ├── history_manager.py # Менеджер истории диалогов (сжатие, пагинация, обрезка) │ ├── indexing_manager.py # Менеджер индексации документов (сжатие, вызов KBService) │ ├── intent_router.py # Маршрутизатор специализированных намерений -│ ├── prompt_builder.py # Построитель промтов (динамические few-shot, сэндвич) -│ ├── query_processor.py # Обработчик обычных RAG-запросов (поиск, синтез, критика) -│ ├── rag_api.py # Локальный API-интерфейс (facade) для вызова RAG-логики без HTTP -│ ├── rag.conf # Конфиг RAG-сервера (YAML): БД, Qdrant, GigaChat, чанкинг, RAG, HTTP -│ ├── rag_orchestrator.py # Оркестратор RAG-пайплайна: фасад, координирующий менеджеры -│ ├── rag_server.py # HTTP-сервер на FastAPI + Uvicorn (точка входа RAG-ядра) -│ ├── README.md # Документация RAG-сервера (этот файл) -│ ├── requirements.txt # Список зависимостей Python для всего проекта -│ ├── schema.sql # Схема PostgreSQL (единая БД для всех ботов) +│ ├── 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 # Самокритика ответа по 5 критериям -│ │ ├── expand_query.py # Расширение запроса (синонимы, аббревиатуры) -│ │ ├── extract_metrics.py # Извлечение числовых показателей (KPI) в JSON -│ │ ├── file_processor.py # Отправка файлов через HTTP Upload и обработка тегов [SURGICAL_REPLACE], [REWRITE], [FILE] -│ │ ├── generate_document.py # Генерация документа по шаблону (заполнение плейсхолдеров {{...}}) +│ │ ├── 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 # Классификация намерений пользователя (FACT, PROCEDURE, METRICS и др.) -│ │ ├── rerank_context.py # Переранжирование контекста через локальный кросс-энкодер -│ │ └── summarize_document.py # Суммаризация документа (краткий пересказ ≤30%) +│ │ ├── 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 (одиночные/пакетные запросы с кэшированием) -│ │ ├── file_service.py # Извлечение текста из файлов (DOCX, PDF, XLSX, PPTX, изображения, аудио, архивы) -│ │ ├── giga_client.py # Клиент GigaChat (chat, upload_file) – без бизнес-логики -│ │ ├── kb_service.py # База знаний (индексация, поиск, управление доступом) -│ │ ├── postgres_service.py # Пул соединений с PostgreSQL (CRUD для документов, истории, комнат, шаблонов) -│ │ ├── qdrant_service.py # Векторная БД (создание коллекции, гибридный поиск, удаление) -│ │ └── reranker_service.py # Кросс-энкодер для переранжирования (локально, модель intfloat/multilingual-e5-reranker) -│ └── utils/ # Утилиты (без бизнес-логики) -│ ├── arg_parser.py # Парсинг аргументов командной строки (--flag value) -│ ├── config_loader.py # Загрузка rag.conf и bot.conf, слияние, чтение .env, создание AppConfig -│ ├── logger.py # Настройка логирования (уровни, вывод в файл и консоль) -│ ├── text_utils.py # Разбиение текста на чанки (tiktoken + razdel), подсчет токенов -│ └── web_utils.py # Веб-скрапинг (fetch_any_url, crawl_url) +│ │ ├── 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-сервером (асинхронный, с повторными попытками) @@ -200,6 +273,7 @@ │ │ └── indexing_worker.py # Индексация файлов и URL (отправляет на RAG-сервер через RAGClient) │ └── xmpp/ # XMPP-клиент │ └── client.py # Основной класс Bot (наследует slixmpp.ClientXMPP) +│ ├── template_bot_profile/ # ШАБЛОН ПРОФИЛЯ (для создания новых ботов) │ ├── bot.conf.sample # Пример конфига бота-клиента (копируется в bot.conf) │ ├── data/ # Каталог для постоянных копий файлов @@ -216,8 +290,12 @@ │ │ ├── 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 # Тесты проверки орфографии @@ -228,10 +306,12 @@ │ ├── 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 @@ -242,9 +322,10 @@ **Важные примечания**: -- Реальные профили ботов (например, `metabot/`, `korobot/`, `persobot/`) создаются администратором вручную путем копирования `template_bot_profile/` и размещаются **вне репозитория** (например, в `/usr/local/etc/fckbot/profiles/`). -- Все юнит-тесты находятся в корневом каталоге `tests/`, что упрощает их запуск и поддержку. -- Конфигурационные файлы (`rag.conf`, `bot.conf`) и переменные окружения (`.env`) не хранятся в репозитории и создаются отдельно. +- Реальные профили ботов создаются администратором вручную вне репозитория. +- Конфигурационные файлы и переменные окружения не хранятся в репозитории. +- Управление схемой PostgreSQL — через Alembic (миграции в `rag/alembic/`). +- Все новые модули (SOMA, ReAct, планирование, агенты, ToolHandler, ReindexWorker) интегрированы в основной пайплайн. ### 6.3. Взаимодействие компонентов @@ -252,9 +333,9 @@ ┌─────────────┐ HTTP ┌─────────────┐ SQL ┌─────────────┐ │ Пользова- │ ──────────────▶│ RAG- │ ──────────────▶│ PostgreSQL │ │ тель │ │ сервер │ │ (история, │ -│ (XMPP) │ ◀──────────────│ (ядро) │ ◀──────────────│ документы) │ -└─────────────┘ └─────────────┘ └─────────────┘ - │ │ │ +│ (XMPP) │ ◀──────────────│ (ядро) │ ◀──────────────│ документы, │ +└─────────────┘ └─────────────┘ │ file_text) │ + │ │ └─────────────┘ │ XMPP │ HTTP (gRPC) │ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ @@ -268,20 +349,39 @@ │ XMPP-бот │ │ FastEmbed │ │ Файлы │ │ (тонкий) │ │ (локальный │ │ (диск) │ │ клиент │ │ кросс-энк.) │ └─────────────┘ +└─────────────┘ └─────────────┘ + │ │ │ + │ │ │ + ▼ ▼ ▼ +┌─────────────┐ ┌─────────────┐ ┌─────────────┐ +│ Redis │ │ Tool- │ │ Reindex- │ +│ (кэш эм- │ │ Handler │ │ Worker │ +│ беддингов, │ │ (внешние │ │ (фоновый) │ +│ SOMA) │ │ API) │ └─────────────┘ └─────────────┘ └─────────────┘ ``` **Поток данных**: -1. **Запрос пользователя** → XMPP-бот (ejabberd) → HTTP → RAG-сервер. -2. RAG-сервер получает историю из PostgreSQL, ищет в Qdrant, генерирует ответ через GigaChat, выполняет самокритику. +1. **Запрос пользователя** → XMPP-бот → HTTP → RAG-сервер. +2. RAG-сервер: + - Получает историю из PostgreSQL (с пагинацией и обрезкой). + - Выполняет классификацию намерений. + - При необходимости вызывает SOMA, ReAct, планирование, агентов. + - Ищет в Qdrant (гибридный поиск), переранжирует, генерирует ответ через GigaChat. + - Выполняет самокритику и SOMA-оценку, при низких оценках перегенерирует. + - Сохраняет историю в PostgreSQL. 3. **Ответ** → HTTP → XMPP-бот → ejabberd → пользователь. -4. **Индексация файла** → XMPP-бот → файл → HTTP → RAG-сервер → Qdrant + PostgreSQL. -5. **OCR/транскрибация** → XMPP-бот → медиафайл → HTTP → RAG-сервер (эндпоинты /rag/vision и /rag/transcribe) → распознанный текст → пользователь. +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-тестами с использованием `pytest` и `pytest-asyncio`. Тесты находятся в корневом каталоге `tests/` и проверяют критически важные функции: +Проект покрыт unit-тестами и интеграционными тестами. + +**Unit-тесты** (в `tests/`) проверяют критически важные функции: - классификацию намерений (`test_intent_classify.py`); - расширение запроса (`test_expand_query.py`); @@ -292,6 +392,11 @@ - проверку орфографии (`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 @@ -300,41 +405,77 @@ source venv/bin/activate pytest tests/ -v ``` -Для тестирования RAG-сервера отдельно можно использовать `curl` или Postman для отправки запросов на эндпоинты. +Для тестирования RAG-сервера отдельно можно использовать `curl` или Postman. ### 6.5. Конфигурационные параметры -В `rag.conf` и `bot.conf` доступны следующие параметры RAG-пайплайна: +В `bot.conf` доступны следующие параметры RAG-пайплайна (добавлены новые): -- **`max_context_tokens`** — лимит **токенов** для истории диалога (по умолчанию 3000). Используется точный подсчет через библиотеку `tiktoken`. Рекомендуемое значение: 2000–4000 токенов в зависимости от модели. -- **`rerank.min_length`** — порог длины контекста (в символах) для запуска переранжирования (по умолчанию 5000). Если контекст короче, переранжирование не выполняется, что экономит ресурсы. -- **`rag_server_url`** — URL RAG-сервера (используется ботами-клиентами). Пример: `"http://localhost:8080"`. -- **`mention_keyword`** — ключевое слово, на которое бот реагирует в групповых чатах (в дополнение к упоминанию по JID и нику). Если параметр не указан, используется имя бота. Пример: `mention_keyword: "методолог"`. -- **`fewshot`** — настройки динамических few-shot примеров: - - `max_examples`: 3 — максимальное количество примеров, включаемых в промт. - - `examples_file`: "`data/fewshot_examples.json`" — путь к файлу с примерами (относительно профиля). +- **`max_context_tokens`** — лимит токенов для истории диалога (по умолчанию 3000). +- **`rerank.min_length`** — порог длины контекста для переранжирования (по умолчанию 5000). +- **`rag_server_url`** — URL RAG-сервера (используется ботами). +- **`mention_keyword`** — ключевое слово для упоминания бота в группах. +- **`fewshot`** — настройки few-shot примеров (`max_examples`, `examples_file`). -Эти параметры позволяют настраивать поведение без изменения кода. Переопределение параметров из `rag.conf` в `bot.conf` дает гибкость для разных профилей. +#### Включение/отключение новых функций +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-запросы. Содержит оркестратор (`RAGOrchestrator`), который выполняет классификацию, поиск, генерацию и самокритику. Также предоставляет эндпоинты для OCR и транскрибации. Запускается как отдельный процесс. Доступен по HTTP всем клиентам. | -| **RAG-оркестратор** (`rag_orchestrator.py`) | Фасад, координирующий работу менеджеров: `HistoryManager`, `IntentRouter`, `QueryProcessor`, `IndexingManager`. Не зависит от XMPP. | -| **Менеджер истории** (`history_manager.py`) | Отвечает за получение истории из БД, ее сжатие (иерархическое резюмирование) и сохранение новых сообщений. | -| **Маршрутизатор намерений** (`intent_router.py`) | Обрабатывает специализированные намерения (METRICS, SUMMARY, CONTRADICTION, TEMPLATE_FILL, SURGICAL, GREETING, SPELLCHECK) и возвращает готовый ответ. | -| **Процессор запросов** (`query_processor.py`) | Выполняет обычный RAG-пайплайн (расширение, поиск, переранжирование, синтез, критика) для GENERAL, FACT, PROCEDURE, COMPARISON, CALCULATION. | -| **Построитель промтов** (`prompt_builder.py`) | Динамический подбор few-shot примеров и формирование промта по принципу «сэндвича» (важное в начале и в конце). | -| **Менеджер индексации** (`indexing_manager.py`) | Сжимает большие документы перед индексацией и вызывает `KBService`. | -| **HTTP-клиент** (`rag_client.py`) | Используется ботами-клиентами для отправки запросов в RAG-сервер. Асинхронный, с повторными попытками. Содержит методы `vision()` и `transcribe()`. | -| **Сервисы** (`services/`) | Долгоживущие компоненты, предоставляющие API для работы с внешними системами (PostgreSQL, Qdrant, GigaChat, файлы). Используются только RAG-сервером и оркестратором. Не содержат бизнес-логики. | -| **Функции** (`functions/`) | Независимые чистые функции, каждая решает одну конкретную задачу: классификация, расширение, суммаризация, проверка противоречий, самокритика, иерархическое резюмирование и т.д. Не имеют состояния, вызываются из оркестратора. | -| **XMPP-боты-клиенты** (`xmpp/client.py`) | Тонкие клиенты, подключающиеся к ejabberd. Содержат только XMPP-логику, команды и загрузку промптов. Все RAG-запросы отправляют в RAG-сервер через `rag_client.py`. | -| **Обработчики XMPP** (`handlers/`) | Реагируют на события XMPP (сообщения, приглашения, подписки). Маршрутизируют запросы: команды, файлы, AI-запросы (через RAG-клиент). | -| **Воркеры** (`workers/`) | Фоновые асинхронные задачи: индексация файлов и URL (через HTTP-запросы в RAG-сервер). | -| **Команды** (`commands/`) | Классы, реализующие команды бота (`!help`, `!learn`, `!summary`, `!metrics` и т.д.). Каждая команда — отдельный файл, наследуемый от `Command`. | -| **Утилиты** (`utils/`) | Вспомогательные функции без бизнес-логики: загрузка конфигурации, логирование, конвертер раскладки, разбиение текста на чанки, веб-скрапинг, парсинг аргументов. | +| **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. Функции бота @@ -347,21 +488,25 @@ pytest tests/ -v | **1** | Генерация по шаблону | Основной инструмент для создания коробочных решений — автоматизирует производство документов. | | **2** | Гибридный RAG | Без него бот не может отвечать по документам — фундамент системы. | | **3** | Комнатные/глобальные БЗ | Обеспечивают коллективную работу над коробочными решениями. | -| **4** | Хирургическая замена | Ускоряет доработку документов, критично для подготовки финальных версий. | -| **5** | Проверка орфографии | Повышает качество исходящих документов. | -| **6** | Суммаризация | Ускоряет анализ больших объемов информации. | -| **7** | Самокритика | Повышает надежность ответов в критических областях. | -| **8** | Извлечение метрик | Автоматизирует сбор KPI. | -| **9** | Проверка противоречий | Исключает ошибки в документации. | -| **10** | Классификация намерений | Обеспечивает интеллектуальную маршрутизацию. | -| **11** | Цепочка рассуждений | Повышает точность расчетов и инструкций. | -| **12** | Полнотекстовый поиск | Гарантирует юридическую точность и поиск инструкций. | -| **13** | Расширение запроса | Улучшает полноту поиска. | -| **14** | Переранжирование | Экономит токены и повышает точность. | -| **15** | Автоиндексация | Упрощает коллективную работу. | -| **16** | Веб-скрапинг | Интегрирует внешние источники. | -| **17** | Голосовые сообщения | Удобство для мобильных пользователей. | -| **18** | Администрирование | Оперативный контроль без доступа к серверу. | +| **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. Ключевые функции для создания документов (коробочных решений) @@ -792,9 +937,154 @@ pytest tests/ -v 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. Интеллектуальная маршрутизация и поиск -### **10. Классификация намерений** +### **15. Классификация намерений** **Что делает**: Определяет тип запроса пользователя по ключевым словам и контексту. Поддерживает следующие коды намерений: `FACT`, `PROCEDURE`, `COMPARISON`, `CALCULATION`, `SURGICAL`, `METRICS`, `SUMMARY`, `CONTRADICTION`, `GREETING`, `GENERAL`, `SPELLCHECK`, `TEMPLATE_FILL`. Выбирает соответствующую стратегию обработки. Результаты классификации кэшируются на 5 минут для ускорения повторных запросов. @@ -821,7 +1111,7 @@ pytest tests/ -v | «Проверь орфографию» | `SPELLCHECK` | | «О чем этот документ?» | `GENERAL` | -### **11. Цепочка рассуждений (Chain‑of‑Thought)** +### **16. Цепочка рассуждений (Chain‑of‑Thought)** **Что делает**: Для запросов с намерениями `CALCULATION` (расчет) и `PROCEDURE` (инструкция/алгоритм) бот автоматически добавляет в промпт инструкцию, требующую пошагового решения перед итоговым ответом. Модель генерирует ответ с последовательным описанием шагов, а затем итоговым результатом. @@ -851,7 +1141,7 @@ pytest tests/ -v - Запрос: «Как внедрить 5S?» - Бот выдает последовательность шагов с пояснениями. -### **12. Полнотекстовый поиск по точным фрагментам и поиск инструкций (HOW TO)** +### **17. Полнотекстовый поиск по точным фрагментам и поиск инструкций (HOW TO)** **Что делает**: При обнаружении номеров пунктов (1.1, 3.2.1), фраз в кавычках или ключевых слов «как», «инструкция», «алгоритм», «порядок», «последовательность», «этапы», «методика», «процедура», «регламент», «правила», «способ», «метод» – бот переключается с гибридного RAG на **точный подстроковый поиск** в Qdrant (MatchText). Это гарантирует попадание в нужный раздел документа, а не просто семантически похожий фрагмент. @@ -928,7 +1218,7 @@ pytest tests/ -v - Запрос: «Порядок расчета OEE по методике из приложения 2» - Находит точный раздел и выдает инструкцию. -### **13. Расширение запроса (query expansion)** +### **18. Расширение запроса (query expansion)** **Что делает**: Добавляет синонимы, аббревиатуры и связанные термины к исходному запросу для увеличения полноты поиска. Использует GigaChat для генерации до 10 дополнительных ключевых слов. Результаты кэшируются на 5 минут. @@ -950,7 +1240,7 @@ pytest tests/ -v | «выработка на человека» | «выработка на человека производительность труда выработка на одного сотрудника ПТ» | | «расчет такта» | «расчет такта тактовое время Takt time формула такта время выпуска единицы» | -### **14. Переранжирование контекста (кросс-энкодер)** +### **19. Переранжирование контекста (кросс-энкодер)** **Что делает**: После получения фрагментов из Qdrant, специализированная модель (кросс-энкодер) ранжирует их по релевантности запросу, отбрасывая шум. Используется локальная модель `intfloat/multilingual-e5-reranker`, что исключает затраты на токены и снижает задержку. @@ -967,7 +1257,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби ## 7.5. Функции автоматизации и интеграции -### **15. Автоматическая индексация файлов в комнатах (без `!learn`)** +### **20. Автоматическая индексация файлов в комнатах (без `!learn`)** **Что делает**: Любой файл (DOCX, PDF, XLSX, PPTX, изображение, аудио, архив), отправленный в групповой чат, автоматически индексируется в базу знаний комнаты. Не требуется включать режим обучения (`!learn`). Это работает «из коробки» для всех участников комнаты. @@ -988,7 +1278,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби 4. Если файл является архивом (ZIP, 7z), бот распаковывает его и индексирует все поддерживаемые форматы внутри. -### **16. Веб-скрапинг с рекурсивным обходом** +### **21. Веб-скрапинг с рекурсивным обходом** **Что делает**: Бот может загрузить сайт по ссылке, рекурсивно обойти страницы (с ограничением глубины и количества) и проиндексировать их в базу знаний. Поддерживаются HTML-страницы и PDF-документы по ссылкам. @@ -1020,7 +1310,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби 5. **Ограничения** – глубина по умолчанию 1, максимум страниц 5 (настраивается в конфиге). Это предотвращает перегрузку системы. -### **17. Поддержка голосовых сообщений (распознавание через SaluteSpeech)** +### **22. Поддержка голосовых сообщений (распознавание через SaluteSpeech)** **Что делает**: Аудиофайлы (.ogg, .wav, .mp3, .amr, .m4a) транскрибируются в текст через SaluteSpeech API. Полученный текст затем обрабатывается как обычный запрос (классификация, поиск, генерация ответа). Ответ отправляется текстом в чат. @@ -1041,7 +1331,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби 4. Поддерживаются длинные сообщения – транскрипция работает с учетом лимитов API. -### **18. Административные команды (`!stats`, `!status`, `!clean`)** +### **23. Административные команды (`!stats`, `!status`, `!clean`)** **Что делает**: - `!stats` – показывает статистику работы бота: uptime, количество обработанных сообщений, AI-запросов, файлов, ошибок, документов в БЗ. @@ -1299,12 +1589,12 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби ### 4.1. Уже реализованные улучшения (доступны сейчас) -В текущей версии платформы уже реализованы следующие ключевые возможности: +В текущей версии платформы уже реализованы следующие ключевые возможности (дополнены): - **Цепочка рассуждений (Chain-of-Thought)** – для расчетов и инструкций модель показывает пошаговое решение. - **Кэширование классификации и расширения запроса** – результаты кэшируются на 5 минут, что ускоряет повторные запросы. - **Переранжирование через локальный кросс-энкодер** – вместо дорогого вызова LLM используется легкая модель `intfloat/multilingual-e5-reranker`. -- **Обрезка истории диалога по токенам** – точный подсчет через `tiktoken`, эффективное использование контекстного окна. +- **Обрезка истории диалога по токенам** – точный подсчет через `tiktoken`, эффективное использование контекстного окна. Добавлена пагинация и обрезка сообщений до лимита. - **Единое RAG-ядро с HTTP API** – все клиенты (XMPP, Telegram, веб) подключаются к одному серверу. - **Генерация коробочных решений по шаблону** – команды `!create`, `!template_save`, `!template_list`, `!template_delete`. - **Автоматическая индексация файлов в комнатах** – файлы индексируются без команды `!learn`. @@ -1313,26 +1603,38 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби - **Конфигурация на Pydantic** – вместо ручной загрузки используется `AppConfig` с валидацией и автодополнением. - **Аутентификация через API-ключ** – все эндпоинты RAG-сервера защищены заголовком `X-API-Key` (кроме `/health`). - **Автоматическая документация OpenAPI** – доступны Swagger UI (`/docs`) и ReDoc (`/redoc`), а также сырая спецификация (`/openapi.json`). -- **Генерация API-ключа** – в `.env` добавлена переменная `RAG_API_KEY`, которую можно сгенерировать командой `python3 -c "import secrets; print(secrets.token_urlsafe(32))"`. +- **Генерация 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. Планируемые улучшения -- **Интеграция с системами документооборота (СЭД)** – бот сможет подписывать документы ЭЦП, отправлять их на регистрацию, отслеживать статусы. В новой архитектуре это делается через расширение API RAG-сервера. +- **Интеграция с системами документооборота (СЭД)** – бот сможет подписывать документы ЭЦП, отправлять их на регистрацию, отслеживать статусы. - **Прогнозная аналитика командировок** – бот будет предлагать оптимальные маршруты, экономить на билетах за счет предварительного бронирования. -- **Агент-индексатор сетевых папок (SMB)** – бот сам сканирует общие каталоги и обновляет базу знаний, отправляя файлы на индексацию в RAG-сервер. -- **Кэширование результатов генерации** – для одинаковых запросов (с использованием хеша запроса и контекста) планируется внедрение кэширования (in-memory или Redis) на уровне RAG-сервера для снижения нагрузки и ускорения ответа. -- **Сбор обратной связи** – команда `!feedback` для оценки качества ответов (лайки/дизлайки) и хранение оценок в БД для последующего анализа. -- **A/B-тестирование промптов** – возможность разделять пользователей на группы и применять разные версии промптов для сравнения эффективности. +- **Агент-индексатор сетевых папок (SMB)** – бот сам сканирует общие каталоги и обновляет базу знаний. +- **Кэширование результатов генерации** – для одинаковых запросов (с использованием хеша запроса и контекста) планируется внедрение кэширования (Redis) на уровне RAG-сервера. +- **Сбор обратной связи** – команда `!feedback` для оценки качества ответов (лайки/дизлайки) и хранение оценок в БД. +- **A/B-тестирование промптов** – возможность разделять пользователей на группы и применять разные версии промптов. - **Гибкие промты** – автоматический выбор краткой или расширенной версии промпта в зависимости от длины доступного контекстного окна. -- **Команда `!style`** – изменение стиля ответов (кратко/подробно/по умолчанию) по желанию пользователя. -- **Подключение дополнительных клиентов** – благодаря HTTP API RAG-сервера можно легко добавить Telegram-бота, Mastodon-бота, веб-интерфейс или интеграцию с системами документооборота без изменения ядра. +- **Команда `!style`** – изменение стиля ответов (кратко/подробно/по умолчанию). +- **Подключение дополнительных клиентов** – Telegram, МАХ, без изменения ядра. --- # III. Описание модулей -Платформа Эфцекабот построена по принципу **«тонкий клиент – толстый сервер»**. Вся RAG-логика вынесена в отдельный HTTP-сервис – **RAG-сервер**, который обслуживает все клиенты (XMPP-боты, Telegram-боты, веб-интерфейсы и т.д.). Клиенты отправляют запросы на RAG-сервер через HTTP и не содержат RAG-логики. +Платформа Эфцекабот построена по принципу **«тонкий клиент – толстый сервер»**. Вся RAG-логика вынесена в отдельный HTTP-сервис – **RAG-сервер**, который обслуживает все клиенты. Клиенты отправляют запросы на RAG-сервер через HTTP и не содержат RAG-логики. Все модули, описанные ниже, расположены в каталоге `rag/`. Часть из них работает на RAG-сервере, часть – в клиентах, часть является общими утилитами. @@ -1345,7 +1647,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби - `QueryProcessor` – обычный RAG-пайплайн (поиск, генерация, критика). - `IndexingManager` – индексация документов с предварительным сжатием. -**Место в архитектуре:** запускается внутри RAG-сервера при обработке HTTP-запроса `/rag/query`. Не зависит от XMPP или других протоколов – может быть использован в любом клиенте через HTTP API. +**Добавлены новые параметры:** `tool_handler` для передачи реальных обработчиков инструментов в `QueryProcessor`. **Ключевые методы:** @@ -1357,12 +1659,15 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби - Не содержит состояния, использует переданные сервисы и промпты. - Поддерживает специализированные намерения: `METRICS`, `SUMMARY`, `CONTRADICTION`, `TEMPLATE_FILL`, `SPELLCHECK`, `SURGICAL`, `GREETING`. - Добавляет цепочку рассуждений (Chain-of-Thought) для `CALCULATION` и `PROCEDURE`. +- Включает интеграцию SOMA, ReAct, планирования и агентов через `QueryProcessor`. + + ## 2. Модуль `rag_server.py` – HTTP-сервер (FastAPI) **Назначение:** предоставляет REST API для всех клиентов. Является точкой входа в платформу. -**Эндпоинты**: +**Эндпоинты** (добавлены новые): | Метод | Эндпоинт | Назначение | Требует аутентификации | |-------|----------|------------|------------------------| @@ -1370,10 +1675,22 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби | POST | `/rag/index` | Проиндексировать документ | Да | | POST | `/rag/vision` | Распознать текст на изображении (OCR) | Да | | POST | `/rag/transcribe` | Транскрибировать аудио (SaluteSpeech) | Да | -| GET | `/health` | Проверка состояния сервера | Нет | -| GET | `/docs` | Swagger UI (интерактивная документация) | Нет | -| GET | `/redoc` | ReDoc (альтернативная документация) | Нет | -| GET | `/openapi.json` | OpenAPI-спецификация | Нет | +| 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`. @@ -1385,10 +1702,18 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби - Эндпоинты `/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-клиент для ботов -**Назначение:** используется тонкими клиентами (XMPP-ботами, Telegram-ботами) для отправки запросов к RAG-серверу. +**Назначение:** используется тонкими клиентами для отправки запросов к RAG-серверу. **Методы:** @@ -1397,14 +1722,20 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби - `vision(file_path)` – отправляет изображение на `/rag/vision`. - `transcribe(file_path)` – отправляет аудио на `/rag/transcribe`. - `health_check()` – проверяет доступность сервера. - -**Место в архитектуре:** встраивается в клиентские приложения вместо локального вызова RAG-логики. +- `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` с API-ключом. +- Автоматически добавляет заголовок `X-API-Key`. - Не содержит бизнес-логики – только HTTP-вызовы. ## 4. Модуль `rag_api.py` – локальный API-интерфейс @@ -1437,9 +1768,20 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби **Место в архитектуре:** используется в `QueryProcessor` при синтезе ответа. +**Добавлена санитизация пользовательских данных (`_sanitize`) для защиты от инъекций ChatML.** + ## 6. Модули функций (каталог `functions/`) -Все функции являются **чистыми, без состояния** и вызываются из `RAGOrchestrator` на сервере. Они не зависят от XMPP и используют переданные промпты и конфигурацию. +Все функции являются чистыми, без состояния. Добавлены новые: + +- **`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` – классификация намерений @@ -1560,17 +1902,26 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби | Файл | Назначение | |------|------------| -| `postgres_service.py` | Пул соединений с PostgreSQL. CRUD для документов, истории диалогов, комнат, шаблонов, прав доступа. | -| `qdrant_service.py` | Векторная БД. Создание коллекции, гибридный поиск (dense + sparse), полнотекстовый поиск, удаление по doc_id. | -| `embedding_service.py` | Эмбеддинги GigaChat. Одиночные/пакетные запросы, кэширование (`lru_cache`), обрезка текста до 800 символов. | +| `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()` – без бизнес-логики. | -| `reranker_service.py` | Кросс-энкодер для переранжирования (локально). Ленивая загрузка модели. | +| `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-сервер. +Эти модули работают только на стороне **тонких клиентов** (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/`) @@ -1619,6 +1970,9 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби | `web_utils.py` | Веб-скрапинг (`fetch_any_url`, `crawl_url`). | | `arg_parser.py` | Парсинг аргументов команд (--flag value). | +- **`logger.py`** – добавлена поддержка JSON-логирования (параметр `json_format`). +- **`web_utils.py`** – ограничение размера загружаемого контента. + ## 10. Тесты (каталог `tests/`) Покрывают критически важные функции: @@ -1634,6 +1988,9 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби Тесты используют `pytest` и `pytest-asyncio`, не требуют реального подключения к внешним сервисам (используются моки). Запуск: `pytest tests/ -v`. +- **Unit-тесты** – без изменений. +- **Интеграционные тесты** – добавлены `test_endpoints.py` и `test_commands.py` для проверки новых эндпоинтов и команд. + ## 11. Конфигурационные файлы Платформа использует два основных конфигурационных файла: @@ -1645,61 +2002,56 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби ## 12. Схема базы данных (PostgreSQL) -Схема создается автоматически через `schema.sql` и включает таблицы: +Схема управляется через Alembic. Таблицы: -- **`documents`** – метаданные документов (источник, владелец, глобальный/комнатный флаг, хеш, коллекция Qdrant). Добавлена колонка `indexed BOOLEAN DEFAULT FALSE` для транзакционности индексации. -- **`document_access`** – права доступа к личным документам. -- **`history`** – история диалогов (личных и комнатных). -- **`rooms`** – список MUC-комнат, в которых бот должен состоять. -- **`room_templates`** – шаблоны коробочных решений, сохраненные в комнатах. +- **`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` при каждом запросе (кроме `/health`). Ключ должен быть уникальным и сложным. +Для защиты RAG-сервера используется API-ключ в заголовке `X-API-Key`. Сгенерировать ключ: -**Сгенерировать ключ можно одним из способов:** - - -### Способ 1 – через Python (рекомендуется) - -``` +```bash python3 -c "import secrets; print(secrets.token_urlsafe(32))" ``` -### Способ 2 – через openssl - -``` -openssl rand -base64 32 -``` - -### Способ 3 – через /dev/urandom (Linux/FreeBSD) - -``` -cat /dev/urandom | tr -dc 'a-zA-Z0-9' | head -c 32; echo -``` - -Пример сгенерированного ключа: - -``` -vK9pQz5RfT7mX2wY4nB8cD6gH3jF1aE5sL0oU9iP2qR7tY6wX4zA -``` - ## 2. Прописать ключ в переменные окружения -В файл `.env` (в корне проекта) добавьте строку: +В `.env` добавьте: ```env -RAG_API_KEY=вставьте_сгенерированный_ключ_сюда +RAG_API_KEY=ваш_ключ ``` -## 3. Использование в Swagger UI (документация) +## 3. Использование в Swagger UI -После запуска RAG-сервера откройте в браузере `http://localhost:8080/docs`. Нажмите кнопку **"Authorize"** (замочек) в правом верхнем углу, введите сгенерированный ключ в поле `APIKeyHeader`, нажмите **"Authorize"**. Теперь можно выполнять запросы прямо из интерфейса. +Откройте `http://localhost:8080/docs`, нажмите **Authorize**, введите ключ. ## 4. Использование в боте -В `bots/xmpp/client.py` при создании `RAGClient` автоматически передается `api_key=config.rag_api_key`. В `rag_client.py` ключ добавляется в заголовок `X-API-Key` при каждом запросе. +В `client.py` `RAGClient` автоматически использует `config.rag_api_key`. + +## 5. Миграции Alembic + +Для управления схемой БД используйте Alembic. Установите переменную окружения `FCKBOT_PROFILE_DIR` с путём к профилю бота, затем: + +```bash +alembic upgrade head +``` + +Для создания новой миграции: + +```bash +alembic revision --autogenerate -m "описание" +``` \ No newline at end of file