From 6602a3d7d6a83f4c6709d401c254528a30dbfac0 Mon Sep 17 00:00:00 2001 From: Markov Andrey Date: Tue, 30 Jun 2026 20:03:45 +0000 Subject: [PATCH] =?UTF-8?q?=D0=A0=D0=B5=D0=B4=D0=B0=D0=BA=D1=82=D0=B8?= =?UTF-8?q?=D1=80=D0=BE=D0=B2=D0=B0=D1=82=D1=8C=20README.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 543 +++++++++++++++++++++++++++--------------------------- 1 file changed, 276 insertions(+), 267 deletions(-) diff --git a/README.md b/README.md index e3c56e4..ffb520a 100644 --- a/README.md +++ b/README.md @@ -2,43 +2,45 @@ ## 1. Рабочее название -**Эфцекабот** — (_fckbot, производное от ФЦК БОТ_) корпоративная платформа для интеллектуальной обработки документов и диалогов, реализующая гибридный RAG (Retrieval-Augmented Generation) на базе GigaChat. Платформа включает единое RAG-ядро и несколько специализированных ботов-клиентов (методолог, коробочник, персональный ассистент), работающих в корпоративном мессенджере (XMPP). Ориентирована на поддержку бережливого производства, производительности труда, нормативной документации, ИИ-метрик, разработки лучших практик и коробочных решений, а также других функций. +**Эфцекабот** — (_fckbot_, производное от _ФЦК БОТ_) — корпоративная платформа для интеллектуальной обработки документов и диалогов, реализующая гибридный RAG (Retrieval-Augmented Generation) на базе GigaChat. Платформа включает единое RAG-ядро и несколько специализированных ботов-клиентов (методолог, коробочник, персональный ассистент), работающих в корпоративном мессенджере (XMPP). Ориентирована на поддержку бережливого производства, производительности труда, нормативной документации, ИИ-метрик, разработки лучших практик и коробочных решений, а также других функций. ## 2. Подход к построению -**Архитектура**: платформа состоит из трех основных слоев: +**Архитектура**: платформа состоит из трех основных слоев. -1. **RAG-ядро (HTTP-сервис)** — центральный компонент, выполняющий все этапы обработки запросов: классификацию намерений, расширение запроса, гибридный поиск (dense + sparse) в Qdrant, переранжирование через локальный кросс-энкодер, синтез ответа через GigaChat, самокритику и перегенерацию. Ядро также управляет индексацией документов и хранением истории диалогов в PostgreSQL. RAG-ядро реализовано как отдельный HTTP-сервер (FastAPI + Uvicorn), что позволяет использовать его для любых клиентов (XMPP, Telegram, Mastodon, веб-интерфейс, системы аналитики). RAG-сервер также предоставляет эндпоинты `/rag/vision` для распознавания текста на изображениях (OCR) и `/rag/transcribe` для транскрибации аудио, что централизует обработку медиафайлов. +1. **RAG-ядро (HTTP-сервис)** — центральный компонент, выполняющий все этапы обработки запросов: классификацию намерений, расширение запроса, гибридный поиск (dense + sparse) в Qdrant, переранжирование через локальный кросс-энкодер, синтез ответа через GigaChat, самокритику и перегенерацию. Ядро также управляет индексацией документов и хранением истории диалогов в PostgreSQL. RAG-ядро реализовано как отдельный HTTP-сервер (FastAPI + Uvicorn), что позволяет использовать его для любых клиентов (XMPP, Telegram, Mastodon, веб-интерфейс, системы аналитики). RAG-сервер также предоставляет эндпоинты `/rag/vision` для распознавания текста на изображениях (OCR) и `/rag/transcribe` для транскрибации аудио, что централизует обработку медиафайлов. 2. **Тонкие XMPP-боты-клиенты** — каждый профиль (методолог, коробочник, персональный ассистент) представляет собой отдельный XMPP-клиент, который подключается к ejabberd, обрабатывает команды, принимает файлы и пересылает запросы пользователей в RAG-ядро по HTTP. Боты не содержат RAG-логики, не имеют локальной БД или Qdrant, а только загружают свои промпты и передают их в запросах. Это делает их легковесными и независимыми. Вся обработка изображений и аудио выполняется на RAG-сервере, что дополнительно упрощает клиентов. 3. **Внешние системы хранения и API**: - - **ejabberd** — XMPP-сервер (сообщения, MUC-комнаты, HTTP Upload). - - **PostgreSQL** — централизованное хранилище метаданных документов, истории диалогов, прав доступа, списка комнат, шаблонов и оценок обратной связи. - - **Qdrant** — векторная БД с двумя полями (dense, sparse) для гибридного поиска. Доступна только RAG-ядру. - - **GigaChat API** — генерация текста и эмбеддингов. Вызовы осуществляются только из RAG-ядра, что позволяет централизованно управлять кэшированием и лимитами. +- **Ejabberd** — XMPP-сервер (сообщения, MUC-комнаты, HTTP Upload); +- **PostgreSQL** — централизованное хранилище метаданных документов, истории диалогов, прав доступа, списка комнат, шаблонов и оценок обратной связи; +- **Qdrant** — векторная БД с двумя полями (dense, sparse) для гибридного поиска. Доступна только RAG-ядру; +- **GigaChat API** — генерация текста и эмбеддингов. Вызовы осуществляются только из RAG-ядра, что позволяет централизованно управлять кэшированием и лимитами. **Философия**: - Каждый документ принадлежит контексту (личный, комнатный, глобальный). -- Боты-клиенты не имеют собственных знаний – они только передают запросы в RAG-ядро, которое отвечает строго по загруженным материалам (строгий RAG). +- Боты-клиенты не имеют собственных знаний — они только передают запросы в RAG-ядро, которое отвечает строго по загруженным материалам (строгий RAG). - Единая история диалога для каждого пользователя/комнаты хранится на сервере, что обеспечивает непрерывность контекста независимо от того, через какой интерфейс (XMPP, Telegram, веб) пользователь общается с системой. -- Встроен интеллектуальный маршрутизатор запросов (классификация намерений), экспертная подсистема (метрики, суммаризация, проверка противоречий, хирургическая замена) и самокритика ответов – все это реализовано в RAG-ядре и доступно всем клиентам. +- Встроен интеллектуальный маршрутизатор запросов (классификация намерений), экспертная подсистема (метрики, суммаризация, проверка противоречий, хирургическая замена) и самокритика ответов — все это реализовано в RAG-ядре и доступно всем клиентам. -**Сервисы распределены по jails FreeBSD/Linux**: +**Сервисы распределены по джейлам FreeBSD/Linux**: - `rag-server` (Python 3.11/3.12) — HTTP-сервис RAG-ядра. - `metabot`, `korobot`, `persobot` — отдельные XMPP-клиенты (также на Python), которые общаются с RAG-ядром через HTTP. -- `ejabberd`, `PostgreSQL`, `Qdrant` — внешние системы. +- `Ejabberd`, `PostgreSQL`, `Qdrant` — внешние системы. + +Инфраструктура развернута на **FreeBSD** с использованием **джейлов** (изолированных окружений), **ZFS** (файловая система с поддержкой снэпшотов и сжатия) и **10-гигабитной** внутренней сети между сервисами. Балансировщик **HAProxy** обеспечивает маршрутизацию внешних запросов и, при необходимости, горизонтальное масштабирование. Автоматические снэпшоты ZFS настроены через `zfs-auto-snapshot` для надежного резервного копирования. ## 3. Уникальность решения -1. **Гибридный RAG (dense + sparse) с самокритикой и централизованным ядром** — не используется в корпоративных ботах массово. Коммерческие решения часто ограничиваются простым семантическим поиском без переранжирования и самокритики. Вынесение RAG-логики в отдельный HTTP-сервис позволяет легко масштабировать и подключать любые клиентские интерфейсы. +1. **Гибридный RAG (dense + sparse) с самокритикой и централизованным ядром** — не используется в корпоративных ботах массово. Коммерческие решения часто ограничиваются простым семантическим поиском без переранжирования и самокритики. Вынесение RAG-логики в отдельный HTTP-сервис позволяет легко масштабировать и подключать любые клиентские интерфейсы. 2. **Персональный ассистент как часть экосистемы** — типичные персональные ассистенты не имеют доступа к внутренней базе знаний и не умеют отвечать на сложные вопросы по документам. Эфцекабот объединяет общие и персональные функции в едином RAG-ядре, при этом каждый бот-профиль использует свои промпты, что позволяет гибко настраивать поведение под конкретные задачи. -3. **Единая чат-среда и единый RAG-бэкенд для всех коммуникаций** — не требуется переключаться между десятками каналов (чат-боты в Telegram, веб-формы, почта). Весь документооборот, командировки, экспертные вопросы — в одном интерфейсе (корпоративном мессенджере), а при необходимости те же функции доступны через Telegram, или веб-интерфейс благодаря универсальному HTTP API RAG-ядра. +3. **Единая чат-среда и единый RAG-бэкенд для всех коммуникаций** — не требуется переключаться между десятками каналов (чат-боты в Telegram, веб-формы, почта). Весь документооборот, командировки, экспертные вопросы — в одном интерфейсе (корпоративном мессенджере), а при необходимости те же функции доступны через Telegram или веб-интерфейс благодаря универсальному HTTP API RAG-ядра. 4. **Полный контроль над данными** — все компоненты развернуты внутри компании. Никакие документы или переписка не покидают периметр. История и документы хранятся только на серверах компании. @@ -48,40 +50,42 @@ ## 4. Преимущества и недостатки работы бота в чате -#### Преимущества: +#### Преимущества + - **Единое корпоративное окно** — пользователь не переключается между приложениями, получает экспертные ответы прямо в рабочем чате. -- **Мгновенный обмен файлами** — встроен HTTP Upload, бот автоматически отправляет файлы в RAG-ядро для индексации (в т.ч. в групповых комнатах). +- **Мгновенный обмен файлами** — встроен HTTP Upload, бот автоматически отправляет файлы в RAG-ядро для индексации (в том числе в групповых комнатах). - **Учет контекста беседы** — история диалога хранится централизованно в RAG-ядре, что обеспечивает единый контекст для всех клиентов (XMPP, Telegram, веб). - **Поддержка комнат (MUC)** — документы, загруженные в комнату, видны всем участникам, а переписка в комнате служит общим контекстом. - **Легковесные клиенты** — боты не содержат сложной RAG-логики, что упрощает их обновление и развертывание; все изменения в RAG вносятся в одном месте — RAG-ядре. -- **Не требует установки уникального клиентского ПО** — достаточно любого XMPP-клиента (Fluux, Conversations, Gajim, Pidgin) или работать через web-интерфейс (который также может использовать RAG-ядро). +- **Не требует установки уникального клиентского ПО** — достаточно любого XMPP-клиента (Fluux, Conversations, Gajim, Pidgin) или работы через веб-интерфейс (который также может использовать RAG-ядро). - **Полный контроль данных** — развертывание внутри периметра, никаких облачных сервисов. - **Поддерживаемые форматы**: DOCX, PDF, XLSX, PPTX, TXT, CSV, JSON, изображения (OCR), аудио (SaluteSpeech), архивы ZIP/7z. - **Размер загружаемого файла**: до 1 Гб. -#### Недостатки: +#### Недостатки + - **Задержка** — добавлен сетевой вызов от бота к RAG-ядру (1–2 мс внутри сети) и несколько вызовов GigaChat (3–10 секунд). Однако благодаря кэшированию (классификация, расширение, эмбеддинги) и локальному кросс-энкодеру итоговое время ответа в большинстве случаев составляет 3–7 секунд, что приемлемо для экспертной системы. - **Сложность отладки** — распределенная система (RAG-ядро, боты-клиенты, ejabberd, PostgreSQL, Qdrant) усложняет трассировку ошибок, но централизованное логирование и единая точка входа (RAG-ядро) упрощают мониторинг. ## 5. Как чат-бот влияет на работу с GigaChat -| Аспект | Влияние | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **Скорость** | GigaChat – облачный API, задержка ~1–2 секунды на вызов. В текущей архитектуре все вызовы GigaChat происходят только из RAG-ядра (не из ботов). Пайплайн может делать 2–4 вызова на запрос (классификация, расширение, генерация, критика). Благодаря общему кэшированию (TTL 5 минут) для классификации и расширения, а также локальному кросс-энкодеру для переранжирования, количество вызовов GigaChat сокращено до минимума, что снижает итоговую задержку до 3–7 секунд. | -| **Экономия токенов** | Переранжирование и гибридный поиск (sparse + dense) уменьшают объём контекста. История диалога обрезается точно по токенам (через tiktoken) на стороне RAG-ядра, что позволяет эффективнее использовать контекстное окно. Дополнительно внедрено иерархическое резюмирование для сжатия длинных диалогов и документов, что ещё больше экономит токены. Централизация также позволяет агрегировать кэши и общие эмбеддинги, снижая общие затраты на токены. | -| **Качество ответа** | GigaChat хорошо понимает русский язык, отлично справляется с деловой и технической терминологией. Но без точного промпта и контекста возможны галлюцинации – самокритика и перегенерация, выполняемые в RAG-ядре, частично нивелируют это. Единые промпты для всех клиентов упрощают тонкую настройку качества. Иерархическое резюмирование помогает сохранить ключевую информацию в длинных документах. | -| **Надежность** | GigaChat имеет лимиты и может выдавать ошибки. RAG-ядро делает несколько попыток при эмбеддингах и генерации, а при отказе API возвращает сообщение о недоступности. Централизация позволяет реализовать единые политики повторных попыток и fallback. RAGClient устойчив к сетевым ошибкам (ClientConnectorError и др.) | +| Аспект | Влияние | +| ------ | ------- | +| **Скорость** | GigaChat — облачный API, задержка ~1–2 секунды на вызов. В текущей архитектуре все вызовы GigaChat происходят только из RAG-ядра (не из ботов). Пайплайн может делать 2–4 вызова на запрос (классификация, расширение, генерация, критика). Благодаря общему кэшированию (TTL 5 минут) для классификации и расширения, а также локальному кросс-энкодеру для переранжирования, количество вызовов GigaChat сокращено до минимума, что снижает итоговую задержку до 3–7 секунд. | +| **Экономия токенов** | Переранжирование и гибридный поиск (sparse + dense) уменьшают объем контекста. История диалога обрезается точно по токенам (через tiktoken) на стороне RAG-ядра, что позволяет эффективнее использовать контекстное окно. Дополнительно внедрено иерархическое резюмирование для сжатия длинных диалогов и документов, что еще больше экономит токены. Централизация также позволяет агрегировать кэши и общие эмбеддинги, снижая общие затраты на токены. | +| **Качество ответа** | GigaChat хорошо понимает русский язык, отлично справляется с деловой и технической терминологией. Но без точного промпта и контекста возможны галлюцинации — самокритика и перегенерация, выполняемые в RAG-ядре, частично нивелируют это. Единые промпты для всех клиентов упрощают тонкую настройку качества. Иерархическое резюмирование помогает сохранить ключевую информацию в длинных документах. | +| **Надежность** | GigaChat имеет лимиты и может выдавать ошибки. RAG-ядро делает несколько попыток при эмбеддингах и генерации, а при отказе API возвращает сообщение о недоступности. Централизация позволяет реализовать единые политики повторных попыток и fallback. RAGClient устойчив к сетевым ошибкам (ClientConnectorError и др.). | | **Гибридные векторы** | GigaChat генерирует только dense-эмбеддинги, sparse-векторы вычисляются через FastEmbed (`Qdrant/bm25`) локально на сервере RAG-ядра. Это разгружает GigaChat и не требует дополнительных API, а также позволяет использовать общий кэш эмбеддингов для всех клиентов. | ## 6. Архитектура проекта ### 6.1. Общая архитектура -Платформа состоит из трех основных логических слоев: +Платформа состоит из трех основных логических слоев. ``` ┌──────────────────────────────────────────────────────────────────────┐ -│ ВНЕШНИЕ КЛИЕНТЫ (пользователи) │ +│ ВНеНИЕ КЛИЕНТЫ (пользователи) │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ XMPP-боты │ │ Telegram │ │ Mastodon │ │ Веб-интерф. │ │ │ │ (тонкие) │ │ (клиент) │ │ (клиент) │ │ (клиент) │ │ @@ -91,7 +95,7 @@ │ │ │ │ │ ▼ ▼ │ │ ┌────────────────────────────────────────────────────────────────┐ │ -│ │ RAG-СЕРВЕР (HTTP API) │ │ +│ │ RAG-Сервер (HTTP API) │ │ │ │ POST /rag/query – выполнить RAG-запрос │ │ │ │ POST /rag/index – проиндексировать документ │ │ │ │ POST /rag/vision – распознать текст на изображении (OCR) │ │ @@ -113,10 +117,10 @@ │ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │ │ │ └────────────────────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────────────────┘ - ``` -**Ключевые компоненты:** +**Ключевые компоненты**: + - **RAG-сервер** — единая точка входа для всех RAG-запросов. Содержит всю бизнес-логику (поиск, генерацию, самокритику, индексацию). Запускается как отдельный HTTP-сервис. - **Тонкие клиенты** — боты-профили (XMPP, Telegram, Mastodon и т.д.), которые только передают запросы в RAG-сервер и не содержат RAG-логики. - **Внешние системы** — PostgreSQL, Qdrant, GigaChat API — доступны только RAG-серверу. @@ -126,124 +130,117 @@ Проект организован по принципу разделения ответственности: RAG-сервер и боты-клиенты имеют свои независимые каталоги. Тесты вынесены в корень проекта. ``` -/usr/local/etc/fckbot/ # КОРЕНЬ ПРОЕКТА -│ -├── rag/ # RAG-СЕРВЕР (HTTP-ядро) -│ ├── .env.example # Шаблон переменных окружения (пароли, ключи API) -│ ├── auth.py # Аутентификация (проверка API-ключа) -│ ├── config_models.py # Pydantic-модели для конфигурации (AppConfig) -│ ├── create_qdrant_collection.py # Скрипт создания коллекции в Qdrant -│ ├── history_manager.py # Менеджер истории диалогов (сжатие, сохранение) -│ ├── indexing_manager.py # Менеджер индексации документов (сжатие, вызов KBService) -│ ├── intent_router.py # Маршрутизатор специализированных намерений -│ ├── prompt_builder.py # Построитель промтов (динамические few-shot, сэндвич) -│ ├── query_processor.py # Обработчик обычных RAG-запросов (поиск, синтез, критика) -│ ├── rag_api.py # Локальный API-интерфейс (facade) для вызова RAG-логики без HTTP -│ ├── rag.conf # Конфиг RAG-сервера (YAML): БД, Qdrant, GigaChat, чанкинг, RAG, HTTP-сервер -│ ├── rag_orchestrator.py # Оркестратор RAG-пайплайна: фасад, координирующий менеджеры -│ ├── rag_server.py # HTTP-сервер на FastAPI + Uvicorn (точка входа RAG-ядра) -│ ├── README.md # Документация RAG-сервера (этот файл) -│ ├── requirements.txt # Список зависимостей Python для всего проекта -│ ├── schema.sql # Схема PostgreSQL (единая БД для всех ботов) -│ ├── functions/ # Чистые функции (без состояния) -│ │ ├── check_consistency.py # Проверка логических/числовых/терминологических противоречий между фрагментами -│ │ ├── check_spelling.py # Проверка орфографии и пунктуации с сохранением форматирования -│ │ ├── critique_answer.py # Самокритика ответа по 5 критериям -│ │ ├── expand_query.py # Расширение запроса (синонимы, аббревиатуры) -│ │ ├── extract_metrics.py # Извлечение числовых показателей (KPI) в JSON -│ │ ├── file_processor.py # Отправка файлов через HTTP Upload и обработка тегов [SURGICAL_REPLACE], [REWRITE], [FILE] -│ │ ├── generate_document.py # Генерация документа по шаблону (заполнение плейсхолдеров {{...}}) -│ │ ├── hierarchical_summarize.py # Иерархическое резюмирование -│ │ ├── intent_classify.py # Классификация намерений пользователя (FACT, PROCEDURE, METRICS и др.) -│ │ ├── rerank_context.py # Переранжирование контекста через локальный кросс-энкодер -│ │ └── summarize_document.py # Суммаризация документа (краткий пересказ ≤30%) -│ ├── services/ # Сервисы (долгоживущие компоненты) -│ │ ├── embedding_service.py # Эмбеддинги GigaChat (одиночные/пакетные запросы с кэшированием) -│ │ ├── file_service.py # Извлечение текста из файлов (DOCX, PDF, XLSX, PPTX, изображения, аудио, архивы) -│ │ ├── giga_client.py # Клиент GigaChat (chat, upload_file) – без бизнес-логики -│ │ ├── kb_service.py # База знаний (индексация, поиск, управление доступом) -│ │ ├── postgres_service.py # Пул соединений с PostgreSQL (CRUD для документов, истории, комнат, шаблонов) -│ │ ├── qdrant_service.py # Векторная БД (создание коллекции, гибридный поиск, удаление) -│ │ └── reranker_service.py # Кросс-энкодер для переранжирования (локально, модель intfloat/multilingual-e5-reranker) -│ └── utils/ # Утилиты (без бизнес-логики) -│ ├── arg_parser.py # Парсинг аргументов командной строки (--flag value) -│ ├── config_loader.py # Загрузка rag.conf и bot.conf, слияние, чтение .env, создание AppConfig -│ ├── logger.py # Настройка логирования (уровни, вывод в файл и консоль) -│ ├── text_utils.py # Разбиение текста на чанки (tiktoken + razdel), подсчёт токенов -│ └── web_utils.py # Веб-скрапинг (fetch_any_url, crawl_url) -│ -├── bots/ # ОБЩИЙ КОД БОТОВ-КЛИЕНТОВ -│ ├── bot.py # Точка входа для запуска XMPP-бота (принимает --profile-dir) -│ ├── rag_client.py # HTTP-клиент для связи с RAG-сервером (асинхронный, с повторными попытками) -│ ├── commands/ # Команды ботов (XMPP-интерфейс) -│ │ ├── base.py # Базовый класс Command (алиасы, права доступа, кэширование) -│ │ ├── create.py # !create – генерация документа по шаблону -│ │ ├── expert.py # !summary, !metrics – экспертные функции -│ │ ├── global_remove.py # !global_remove – удаление глобального документа (админ) -│ │ ├── help.py # !help – подробная справка по командам -│ │ ├── info.py # !info – краткая справка -│ │ ├── kb.py # !clear, !global_clear, !kb – управление базой знаний -│ │ ├── learn.py # !learn, !stop_learn, !global_learn – режим обучения -│ │ ├── other.py # !reset – сброс истории -│ │ ├── registry.py # Регистрация команд, алиасы, подсказки при опечатке -│ │ ├── stats.py # !stats, !status, !clean – администрирование -│ │ └── template.py # !template_save, !template_list, !template_delete – шаблоны -│ ├── handlers/ # Обработчики XMPP событий -│ │ ├── file_handler.py # Скачивание файлов и постановка в очередь индексации -│ │ ├── health_handler.py # Очистка временных файлов, healthcheck БД/Qdrant (для клиентов) -│ │ ├── message_handler.py # Маршрутизация входящих сообщений (команды, файлы, AI-запросы) – использует RAGClient -│ │ ├── metrics_handler.py # Счётчики (сообщения, файлы, AI-запросы, ошибки) -│ │ ├── room_handler.py # MUC комнаты (приглашения, вход, переподключение) -│ │ └── subscription_handler.py # Подписки (roster subscription) -│ ├── workers/ # Фоновые воркеры -│ │ └── indexing_worker.py # Индексация файлов и URL (отправляет на RAG-сервер через RAGClient) -│ └── xmpp/ # XMPP-клиент -│ └── client.py # Основной класс Bot (наследует slixmpp.ClientXMPP) -│ -├── template_bot_profile/ # ШАБЛОН ПРОФИЛЯ (для создания новых ботов) -│ ├── bot.conf.sample # Пример конфига бота-клиента (копируется в bot.conf) -│ ├── data/ # Каталог для постоянных копий файлов -│ │ └── fewshot_examples.json # Примеры few-shot (можно редактировать) -│ ├── prompts/ # Пример промптов (копируются в профиль) -│ │ ├── consistency_check.txt # Проверка противоречий между фрагментами -│ │ ├── expand.txt # Расширение запроса (синонимы, аббревиатуры) -│ │ ├── generate_document.txt # Генерация документа по шаблону -│ │ ├── hierarchical_summary.txt # Иерархическое резюмирование -│ │ ├── intent_classify.txt # Классификация намерений -│ │ ├── metrics_extract.txt # Извлечение KPI в JSON -│ │ ├── quality_criteria.txt # Дополнительные критерии качества ответа -│ │ ├── self_critique.txt # Самокритика ответа -│ │ ├── smart_summary.txt # Суммаризация документа -│ │ ├── spellcheck.txt # Проверка орфографии и пунктуации -│ │ ├── synthesis.txt # Шаблон синтеза ответа -│ │ └── system.txt # Системный промпт (роль, стиль, правила) -│ └── temp/ # Пустой каталог для временных файлов -│ -├── tests/ # ЮНИТ-ТЕСТЫ (общие для всего проекта) -│ ├── conftest.py # Фикстуры и моки для pytest -│ ├── test_check_spelling.py # Тесты проверки орфографии -│ ├── test_consistency.py # Тесты проверки противоречий -│ ├── test_critique.py # Тесты самокритики -│ ├── test_expand_query.py # Тесты расширения запроса -│ ├── test_extract_metrics.py # Тесты извлечения метрик -│ ├── test_hierarchical_summary.txt # Тесты иерархического резюмирования -│ ├── test_intent_classify.py # Тесты классификации намерений -│ └── test_summarize.py # Тесты суммаризации -│ -├── venv/ # ВИРТУАЛЬНОЕ ОКРУЖЕНИЕ Python -│ ├── bin/ # Исполняемые файлы (python, pip, activate) -│ ├── lib/ # Установленные библиотеки +/usr/local/etc/fckbot/ # КОРЕНЬ ПРОЕКТА +├── rag/ # RAG-СеВе (HTTP-ядро) +│ ├── auth.py # Аутентификация (проверка API-ключа) +│ ├── config_models.py # Pydantic-модели для конфигурации (AppConfig) +│ ├── create_qdrant_collection.py # Скрипт создания коллекции в Qdrant +│ ├── history_manager.py # Менеджер истории диалогов (сжатие, сохранение) +│ ├── indexing_manager.py # Менеджер индексации документов (сжатие, вызов KBService) +│ ├── intent_router.py # Маршрутизатор специализированных намерений +│ ├── prompt_builder.py # Построитель промтов (динамические few-shot, сэндвич) +│ ├── query_processor.py # Обработчик обычных RAG-запросов (поиск, синтез, критика) +│ ├── rag_api.py # Локальный API-интерфейс (facade) для вызова RAG-логики без HTTP +│ ├── rag.conf # Конфиг RAG-сервера (YAML): БД, Qdrant, GigaChat, чанкинг, RAG, HTTP +│ ├── rag_orchestrator.py # Оркестратор RAG-пайплайна: фасад, координирующий менеджеры +│ ├── rag_server.py # HTTP-сервер на FastAPI + Uvicorn (точка входа RAG-ядра) +│ ├── README.md # Документация RAG-сервера (этот файл) +│ ├── requirements.txt # Список зависимостей Python для всего проекта +│ ├── schema.sql # Схема PostgreSQL (единая БД для всех ботов) +│ ├── functions/ # Чистые функции (без состояния) +│ │ ├── check_consistency.py # Проверка логических/числовых/терминологических противоречий +│ │ ├── check_spelling.py # Проверка орфографии и пунктуации с сохранением форматирования +│ │ ├── critique_answer.py # Самокритика ответа по 5 критериям +│ │ ├── expand_query.py # Расширение запроса (синонимы, аббревиатуры) +│ │ ├── extract_metrics.py # Извлечение числовых показателей (KPI) в JSON +│ │ ├── file_processor.py # Отправка файлов через HTTP Upload и обработка тегов [SURGICAL_REPLACE], [REWRITE], [FILE] +│ │ ├── generate_document.py # Генерация документа по шаблону (заполнение плейсхолдеров {{...}}) +│ │ ├── hierarchical_summarize.py # Иерархическое резюмирование +│ │ ├── intent_classify.py # Классификация намерений пользователя (FACT, PROCEDURE, METRICS и др.) +│ │ ├── rerank_context.py # Переранжирование контекста через локальный кросс-энкодер +│ │ └── summarize_document.py # Суммаризация документа (краткий пересказ ≤30%) +│ ├── services/ # Сервисы (долгоживущие компоненты) +│ │ ├── embedding_service.py # Эмбеддинги GigaChat (одиночные/пакетные запросы с кэшированием) +│ │ ├── file_service.py # Извлечение текста из файлов (DOCX, PDF, XLSX, PPTX, изображения, аудио, архивы) +│ │ ├── giga_client.py # Клиент GigaChat (chat, upload_file) – без бизнес-логики +│ │ ├── kb_service.py # База знаний (индексация, поиск, управление доступом) +│ │ ├── postgres_service.py # Пул соединений с PostgreSQL (CRUD для документов, истории, комнат, шаблонов) +│ │ ├── qdrant_service.py # Векторная БД (создание коллекции, гибридный поиск, удаление) +│ │ └── reranker_service.py # Кросс-энкодер для переранжирования (локально, модель intfloat/multilingual-e5-reranker) +│ └── utils/ # Утилиты (без бизнес-логики) +│ ├── arg_parser.py # Парсинг аргументов командной строки (--flag value) +│ ├── config_loader.py # Загрузка rag.conf и bot.conf, слияние, чтение .env, создание AppConfig +│ ├── logger.py # Настройка логирования (уровни, вывод в файл и консоль) +│ ├── text_utils.py # Разбиение текста на чанки (tiktoken + razdel), подсчет токенов +│ └── web_utils.py # Веб-скрапинг (fetch_any_url, crawl_url) +├── bots/ # ОБЩИЙ КОД БОТОВ-КЛИЕНТОВ +│ ├── bot.py # Точка входа для запуска XMPP-бота (принимает --profile-dir) +│ ├── rag_client.py # HTTP-клиент для связи с RAG-сервером (асинхронный, с повторными попытками) +│ ├── commands/ # Команды ботов (XMPP-интерфейс) +│ │ ├── base.py # Базовый класс Command (алиасы, права доступа, кэширование) +│ │ ├── create.py # !create – генерация документа по шаблону +│ │ ├── expert.py # !summary, !metrics – экспертные функции +│ │ ├── global_remove.py # !global_remove – удаление глобального документа (админ) +│ │ ├── help.py # !help – подробная справка по командам +│ │ ├── info.py # !info – краткая справка +│ │ ├── kb.py # !clear, !global_clear, !kb – управление базой знаний +│ │ ├── learn.py # !learn, !stop_learn, !global_learn – режим обучения +│ │ ├── other.py # !reset – сброс истории +│ │ ├── registry.py # Регистрация команд, алиасы, подсказки при опечатке +│ │ ├── stats.py # !stats, !status, !clean – администрирование +│ │ └── template.py # !template_save, !template_list, !template_delete – шаблоны +│ ├── handlers/ # Обработчики XMPP событий +│ │ ├── file_handler.py # Скачивание файлов и постановка в очередь индексации +│ │ ├── health_handler.py # Очистка временных файлов, healthcheck БД/Qdrant (для клиентов) +│ │ ├── message_handler.py # Маршрутизация входящих сообщений (команды, файлы, AI-запросы) – использует RAGClient +│ │ ├── metrics_handler.py # Счетчики (сообщения, файлы, AI-запросы, ошибки) +│ │ ├── room_handler.py # MUC комнаты (приглашения, вход, переподключение) +│ │ └── subscription_handler.py # Подписки (roster subscription) +│ ├── workers/ # Фоновые воркеры +│ │ └── indexing_worker.py # Индексация файлов и URL (отправляет на RAG-сервер через RAGClient) +│ └── xmpp/ # XMPP-клиент +│ └── client.py # Основной класс Bot (наследует slixmpp.ClientXMPP) +├── template_bot_profile/ # ШАБЛОН ПРОФИЛЯ (для создания новых ботов) +│ ├── bot.conf.sample # Пример конфига бота-клиента (копируется в bot.conf) +│ ├── data/ # Каталог для постоянных копий файлов +│ │ └── fewshot_examples.json # Примеры few-shot (можно редактировать) +│ ├── prompts/ # Пример промптов (копируются в профиль) +│ │ ├── consistency_check.txt # Проверка противоречий между фрагментами +│ │ ├── expand.txt # Расширение запроса (синонимы, аббревиатуры) +│ │ ├── generate_document.txt # Генерация документа по шаблону +│ │ ├── hierarchical_summary.txt # Иерархическое резюмирование +│ │ ├── intent_classify.txt # Классификация намерений +│ │ ├── metrics_extract.txt # Извлечение KPI в JSON +│ │ ├── quality_criteria.txt # Дополнительные критерии качества ответа +│ │ ├── self_critique.txt # Самокритика ответа +│ │ ├── smart_summary.txt # Суммаризация документа +│ │ ├── spellcheck.txt # Проверка орфографии и пунктуации +│ │ ├── synthesis.txt # Шаблон синтеза ответа +│ │ └── system.txt # Системный промпт (роль, стиль, правила) +│ └── temp/ # Пустой каталог для временных файлов +├── tests/ # ЮНИТ-ТеТЫ (общие для всего проекта) +│ ├── conftest.py # Фикстуры и моки для pytest +│ ├── test_check_spelling.py # Тесты проверки орфографии +│ ├── test_consistency.py # Тесты проверки противоречий +│ ├── test_critique.py # Тесты самокритики +│ ├── test_expand_query.py # Тесты расширения запроса +│ ├── test_extract_metrics.py # Тесты извлечения метрик +│ ├── test_hierarchical_summary.txt # Тесты иерархического резюмирования +│ ├── test_intent_classify.py # Тесты классификации намерений +│ └── test_summarize.py # Тесты суммаризации +├── venv/ # ВИРТУАЛЬНОЕ ОКРУЖЕНИЕ Python +│ ├── bin/ # Исполняемые файлы (python, pip, activate) +│ ├── lib/ # Установленные библиотеки │ └── ... -│ -└── .env # ПЕРЕМЕННЫЕ ОКРУЖЕНИЯ - ├── XMPP_PASSWORD=... # Пароль для XMPP-аккаунта бота - ├── DB_PASSWORD=... # Пароль для PostgreSQL - ├── GIGACHAT_API_KEY=... # API-ключ GigaChat - ├── SALUTE_SPEECH_AUTH=... # Авторизация для SaluteSpeech (голосовые сообщения) - └── RAG_API_KEY=... # API-ключ для доступа к RAG-серверу (защита эндпоинтов) +└── .env.example # ШАБЛОН ПЕРЕМЕННЫХ ОКРУЖЕНИЯ + ├── XMPP_PASSWORD=... # Пароль для XMPP-аккаунта бота + ├── DB_PASSWORD=... # Пароль для PostgreSQL + ├── GIGACHAT_API_KEY=... # API-ключ GigaChat + ├── SALUTE_SPEECH_AUTH=... # Авторизация для SaluteSpeech (голосовые сообщения) + └── RAG_API_KEY=... # API-ключ для доступа к RAG-серверу (защита эндпоинтов) ``` -**Важные примечания:** +**Важные примечания**: - Реальные профили ботов (например, `metabot/`, `korobot/`, `persobot/`) создаются администратором вручную путем копирования `template_bot_profile/` и размещаются **вне репозитория** (например, в `/usr/local/etc/fckbot/profiles/`). - Все юнит-тесты находятся в корневом каталоге `tests/`, что упрощает их запуск и поддержку. @@ -274,7 +271,7 @@ └─────────────┘ └─────────────┘ ``` -**Поток данных:** +**Поток данных**: 1. **Запрос пользователя** → XMPP-бот (ejabberd) → HTTP → RAG-сервер. 2. RAG-сервер получает историю из PostgreSQL, ищет в Qdrant, генерирует ответ через GigaChat, выполняет самокритику. @@ -286,18 +283,18 @@ Проект покрыт unit-тестами с использованием `pytest` и `pytest-asyncio`. Тесты находятся в корневом каталоге `tests/` и проверяют критически важные функции: -- классификацию намерений (`test_intent_classify.py`), -- расширение запроса (`test_expand_query.py`), -- извлечение метрик (`test_extract_metrics.py`), -- суммаризацию (`test_summarize.py`), -- проверку противоречий (`test_consistency.py`), -- самокритику (`test_critique.py`), -- проверку орфографии (`test_check_spelling.py`), +- классификацию намерений (`test_intent_classify.py`); +- расширение запроса (`test_expand_query.py`); +- извлечение метрик (`test_extract_metrics.py`); +- суммаризацию (`test_summarize.py`); +- проверку противоречий (`test_consistency.py`); +- самокритику (`test_critique.py`); +- проверку орфографии (`test_check_spelling.py`); - иерархическое резюмирование (`test_hierarchical_summarize.py`). -**Запуск всех тестов:** +**Запуск всех тестов**: -``` +```bash cd /usr/local/etc/fckbot source venv/bin/activate pytest tests/ -v @@ -313,24 +310,24 @@ pytest tests/ -v - **`rerank.min_length`** — порог длины контекста (в символах) для запуска переранжирования (по умолчанию 5000). Если контекст короче, переранжирование не выполняется, что экономит ресурсы. - **`rag_server_url`** — URL RAG-сервера (используется ботами-клиентами). Пример: `"http://localhost:8080"`. - **`mention_keyword`** — ключевое слово, на которое бот реагирует в групповых чатах (в дополнение к упоминанию по JID и нику). Если параметр не указан, используется имя бота. Пример: `mention_keyword: "методолог"`. -- **`fewshot`** – настройки динамических few-shot примеров: - - `max_examples`: 3 – максимальное количество примеров, включаемых в промт. - - `examples_file`: "`data/fewshot_examples.json`" – путь к файлу с примерами (относительно профиля). +- **`fewshot`** — настройки динамических few-shot примеров: + - `max_examples`: 3 — максимальное количество примеров, включаемых в промт. + - `examples_file`: "`data/fewshot_examples.json`" — путь к файлу с примерами (относительно профиля). Эти параметры позволяют настраивать поведение без изменения кода. Переопределение параметров из `rag.conf` в `bot.conf` дает гибкость для разных профилей. ### 6.6. Основные слои (что есть что) -| Слой | Назначение | -| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Слой | Назначение | +| ---- | ---------- | | **RAG-сервер** (`rag_server.py`) | HTTP-сервис, обрабатывающий все RAG-запросы. Содержит оркестратор (`RAGOrchestrator`), который выполняет классификацию, поиск, генерацию и самокритику. Также предоставляет эндпоинты для OCR и транскрибации. Запускается как отдельный процесс. Доступен по HTTP всем клиентам. | | **RAG-оркестратор** (`rag_orchestrator.py`) | Фасад, координирующий работу менеджеров: `HistoryManager`, `IntentRouter`, `QueryProcessor`, `IndexingManager`. Не зависит от XMPP. | -| **Менеджер истории** (`history_manager.py`) | Отвечает за получение истории из БД, её сжатие (иерархическое резюмирование) и сохранение новых сообщений. | +| **Менеджер истории** (`history_manager.py`) | Отвечает за получение истории из БД, ее сжатие (иерархическое резюмирование) и сохранение новых сообщений. | | **Маршрутизатор намерений** (`intent_router.py`) | Обрабатывает специализированные намерения (METRICS, SUMMARY, CONTRADICTION, TEMPLATE_FILL, SURGICAL, GREETING, SPELLCHECK) и возвращает готовый ответ. | | **Процессор запросов** (`query_processor.py`) | Выполняет обычный RAG-пайплайн (расширение, поиск, переранжирование, синтез, критика) для GENERAL, FACT, PROCEDURE, COMPARISON, CALCULATION. | | **Построитель промтов** (`prompt_builder.py`) | Динамический подбор few-shot примеров и формирование промта по принципу «сэндвича» (важное в начале и в конце). | | **Менеджер индексации** (`indexing_manager.py`) | Сжимает большие документы перед индексацией и вызывает `KBService`. | -| **HTTP-клиент** (`rag_client.py`) | Используется ботами-клиентами для отправки запросов в RAG-сервер. Асинхронный, с повторными попытками. Содержит методы vision() и transcribe(). | +| **HTTP-клиент** (`rag_client.py`) | Используется ботами-клиентами для отправки запросов в RAG-сервер. Асинхронный, с повторными попытками. Содержит методы `vision()` и `transcribe()`. | | **Сервисы** (`services/`) | Долгоживущие компоненты, предоставляющие API для работы с внешними системами (PostgreSQL, Qdrant, GigaChat, файлы). Используются только RAG-сервером и оркестратором. Не содержат бизнес-логики. | | **Функции** (`functions/`) | Независимые чистые функции, каждая решает одну конкретную задачу: классификация, расширение, суммаризация, проверка противоречий, самокритика, иерархическое резюмирование и т.д. Не имеют состояния, вызываются из оркестратора. | | **XMPP-боты-клиенты** (`xmpp/client.py`) | Тонкие клиенты, подключающиеся к ejabberd. Содержат только XMPP-логику, команды и загрузку промптов. Все RAG-запросы отправляют в RAG-сервер через `rag_client.py`. | @@ -347,28 +344,28 @@ pytest tests/ -v | Место | Функция | Обоснование | | ----- | ------- | ----------- | -| **🥇 1** | Генерация по шаблону | Основной инструмент для создания коробочных решений — автоматизирует производство документов | -| **🥈 2** | Гибридный RAG | Без него бот не может отвечать по документам — фундамент системы | -| **🥉 3** | Комнатные/глобальные БЗ | Обеспечивают коллективную работу над коробочными решениями | -| **4** | Хирургическая замена | Ускоряет доработку документов, критично для подготовки финальных версий | -| **5** | Проверка орфографии | Повышает качество исходящих документов | -| **6** | Суммаризация | Ускоряет анализ больших объемов информации | -| **7** | Самокритика | Повышает надежность ответов в критических областях | -| **8** | Извлечение метрик | Автоматизирует сбор KPI | -| **9** | Проверка противоречий | Исключает ошибки в документации | -| **10** | Классификация намерений | Обеспечивает интеллектуальную маршрутизацию | -| **11** | Цепочка рассуждений | Повышает точность расчетов и инструкций | -| **12** | Полнотекстовый поиск | Гарантирует юридическую точность и поиск инструкций | -| **13** | Расширение запроса | Улучшает полноту поиска | -| **14** | Переранжирование | Экономит токены и повышает точность | -| **15** | Автоиндексация | Упрощает коллективную работу | -| **16** | Веб-скрапинг | Интегрирует внешние источники | -| **17** | Голосовые сообщения | Удобство для мобильных пользователей | -| **18** | Администрирование | Оперативный контроль без доступа к серверу | +| **1** | Генерация по шаблону | Основной инструмент для создания коробочных решений — автоматизирует производство документов. | +| **2** | Гибридный RAG | Без него бот не может отвечать по документам — фундамент системы. | +| **3** | Комнатные/глобальные БЗ | Обеспечивают коллективную работу над коробочными решениями. | +| **4** | Хирургическая замена | Ускоряет доработку документов, критично для подготовки финальных версий. | +| **5** | Проверка орфографии | Повышает качество исходящих документов. | +| **6** | Суммаризация | Ускоряет анализ больших объемов информации. | +| **7** | Самокритика | Повышает надежность ответов в критических областях. | +| **8** | Извлечение метрик | Автоматизирует сбор KPI. | +| **9** | Проверка противоречий | Исключает ошибки в документации. | +| **10** | Классификация намерений | Обеспечивает интеллектуальную маршрутизацию. | +| **11** | Цепочка рассуждений | Повышает точность расчетов и инструкций. | +| **12** | Полнотекстовый поиск | Гарантирует юридическую точность и поиск инструкций. | +| **13** | Расширение запроса | Улучшает полноту поиска. | +| **14** | Переранжирование | Экономит токены и повышает точность. | +| **15** | Автоиндексация | Упрощает коллективную работу. | +| **16** | Веб-скрапинг | Интегрирует внешние источники. | +| **17** | Голосовые сообщения | Удобство для мобильных пользователей. | +| **18** | Администрирование | Оперативный контроль без доступа к серверу. | ## 7.1. Ключевые функции для создания документов (коробочных решений) -### 🥇 **1. Генерация коробочных решений по шаблону** +### **1. Генерация коробочных решений по шаблону** **Что делает**: По команде `!create "Коробочное решение"` бот генерирует готовый коробочный документ на основе шаблона, заполняя все плейсхолдеры `{{...}}` данными из базы знаний комнаты. Шаблон содержит следующие разделы (соответствует файлу `Шаблон коробочного решения.docx`): @@ -387,7 +384,7 @@ pytest tests/ -v Превращает бота из информатора в **инструмент производства готовых коробочных решений**. Достаточно один раз настроить шаблон, и бот будет генерировать документы на основе актуальных данных из базы знаний. Все, что требуется от пользователя — загрузить в комнату документы-источники (регламенты, отчеты, методики, ГОСТы, аналитические записки). **Польза**: -Автоматизация подготовки коробочных решений, сокращение времени на создание документов с 1-2 недель до 10-30 минут, исключение ошибок ручного ввода, единообразие документов, возможность быстрого масштабирования на любые типы организаций. +Автоматизация подготовки коробочных решений, сокращение времени на создание документов с 1–2 недель до 10–30 минут, исключение ошибок ручного ввода, единообразие документов, возможность быстрого масштабирования на любые типы организаций. **Примеры использования (все возможные сценарии)**: @@ -503,16 +500,15 @@ pytest tests/ -v **Пример**: плейсхолдер `{{KPI_NAME}}` – бот найдет в английских документах «Overall Equipment Effectiveness» и переведет как «Общая эффективность оборудования» (или оставит аббревиатуру OEE, если так указано в документах). -### 🥈 **2. Гибридный RAG с самокритикой** +### **2. Гибридный RAG с самокритикой** **Что делает**: Это ядро системы, которое используется для поиска данных для каждого плейсхолдера шаблона. Бот выполняет: - -- Семантический поиск (dense-эмбеддинги от GigaChat). -- Ключевой поиск (sparse-векторы BM25 от FastEmbed). -- Объединение через Reciprocal Rank Fusion (RRF). -- Генерацию ответа через GigaChat. -- Проверку через самокритику (оценка по 5 критериям). +- Семантический поиск (dense-эмбеддинги от GigaChat); +- Ключевой поиск (sparse-векторы BM25 от FastEmbed); +- Объединение через Reciprocal Rank Fusion (RRF); +- Генерацию ответа через GigaChat; +- Проверку через самокритику (оценка по 5 критериям); - Перегенерацию при необходимости. **Уникальность**: @@ -568,7 +564,7 @@ pytest tests/ -v 4. **Поиск постановки задач**: - Для `{{TASK_1}}` бот находит в стратегических документах перечень задач: «разработать стандарт», «обучить персонал», «внедрить систему мониторинга». -### 🥉 **3. Комнатные и глобальные базы знаний** +### **3. Комнатные и глобальные базы знаний** **Что делает**: Документы могут быть трех типов: @@ -651,7 +647,7 @@ pytest tests/ -v Пользователь загружает DOCX, затем пишет «Проверь орфографию» или «Найди ошибки». Бот разбивает текст на чанки (учитывая токены), отправляет каждый чанк в GigaChat с промптом на исправление ошибок. Исправления применяются с сохранением форматирования. Возвращает исправленный файл и список изменений в виде «было → стало». **Уникальность**: -Автоматическое исправление ошибок в готовых документах без ручной правки. Поддерживает сложные случаи русского языка (благодаря использованию `razdel` для разбиения на предложения). +Автоматическое исправление ошибок в готовых документов без ручной правки. Поддерживает сложные случаи русского языка (благодаря использованию `razdel` для разбиения на предложения). **Польза**: Экономия времени на вычитку, повышение грамотности исходящих документов. Незаменимо при подготовке коробочных решений и официальных документов. @@ -809,10 +805,10 @@ pytest tests/ -v **Польза**: Экономия токенов, времени и повышение точности ответов за счет выбора специализированной стратегии. -**Примеры работы (как классификатор определяет тип запроса):** +**Примеры работы (как классификатор определяет тип запроса)**: | Запрос пользователя | Распознанное намерение | -||| +|----------------------|-------------------------| | «Какое тактовое время установлено на линии?» | `FACT` | | «Как рассчитать OEE?» | `PROCEDURE` | | «Сравни показатели производительности до и после кайдзен» | `COMPARISON` | @@ -825,7 +821,7 @@ pytest tests/ -v | «Проверь орфографию» | `SPELLCHECK` | | «О чем этот документ?» | `GENERAL` | -### **11. Цепочка рассуждений (Chain-of-Thought)** +### **11. Цепочка рассуждений (Chain‑of‑Thought)** **Что делает**: Для запросов с намерениями `CALCULATION` (расчет) и `PROCEDURE` (инструкция/алгоритм) бот автоматически добавляет в промпт инструкцию, требующую пошагового решения перед итоговым ответом. Модель генерирует ответ с последовательным описанием шагов, а затем итоговым результатом. @@ -863,12 +859,12 @@ pytest tests/ -v **Ключевая особенность**: Если запрос содержит вопрос «как сделать Х», бот не просто находит фрагмент с упоминанием Х, а **извлекает всю инструкцию или процедуру**, даже если она не оформлена как маркированный список, а просто описана в тексте. Для этого используется дополнительный промпт, который заставляет LLM выделить и структурировать последовательность действий. -**Уникальность**: +**Уникальность**: - Гарантирует юридически значимые цитаты и ссылки на пункты нормативных актов. - Может находить и выдавать пошаговые инструкции из неструктурированного текста. - Объединяет точный поиск с **цепочкой рассуждений (CoT)**, если инструкция требует расчетов или последовательных действий. -**Польза**: +**Польза**: - Позволяет получать готовые алгоритмы и процедуры без необходимости читать весь документ. - Быстрое освоение новых процессов – достаточно спросить «как сделать Х», и бот найдет инструкцию в документах. - Снижение времени на поиск регламентов и стандартов. @@ -1047,8 +1043,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби ### **18. Административные команды (`!stats`, `!status`, `!clean`)** -**Что делает**: - +**Что делает**: - `!stats` – показывает статистику работы бота: uptime, количество обработанных сообщений, AI-запросов, файлов, ошибок, документов в БЗ. - `!status` – проверяет доступность внешних сервисов: PostgreSQL, Qdrant, GigaChat, а также состояние дискового пространства. - `!clean` – очищает временную директорию (удаляет все временные файлы). @@ -1188,8 +1183,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби !create "Коробочное решение_Музеи" ``` ----- - +--- # II. Перспективы развития Эфцекабот @@ -1199,17 +1193,17 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби ### 1.1. Общие боты -| Тип бота | Отдел | Примеры запросов | -|-----|------|------| -| **Методолог (стандарты)** | Методология, бизнес‑аналитика, внутренний контроль | «Найди требования к описанию бизнес‑процесса» | -| **Писатель коробочных решений** | Методология | «Напиши коробочное решение по образцу» | -| **Юрист‑эксперт** | Юридический | «Составь претензию по шаблону» | -| **Финансовый аналитик** | Финансы, управленческий учет | «Рассчитай OEE по проекту X» | -| **HR‑помощник** | Отдел персонала | «Образец служебной записки или бизнес‑процесса» | -| **Менеджер проектов** | Проектный офис | «Сформируй выжимку по проекту за месяц» | -| **ИТ‑архитектор** | IT‑департамент | «Сравни конфигурации серверов из ТЗ» | -| **Комплаенс‑контроль** | Служба безопасности | «Проверь отчет на соответствие регламенту» | -| **Executive‑бот** | Топ‑менеджмент | «Сводка KPI по всем проектам» | +| Тип бота | Отдел | Примеры запросов | +|----------|-------|------------------| +| **Методолог (стандарты)** | Методология, бизнес-аналитика, внутренний контроль | «Найди требования к описанию бизнес-процесса» | +| **Писатель коробочных решений** | Методология | «Напиши коробочное решение по образцу» | +| **Юрист-эксперт** | Юридический | «Составь претензию по шаблону» | +| **Финансовый аналитик** | Финансы, управленческий учет | «Рассчитай OEE по проекту X» | +| **HR-помощник** | Отдел персонала | «Образец служебной записки или бизнес-процесса» | +| **Менеджер проектов** | Проектный офис | «Сформируй выжимку по проекту за месяц» | +| **ИТ-архитектор** | IT-департамент | «Сравни конфигурации серверов из ТЗ» | +| **Комплаенс-контроль** | Служба безопасности | «Проверь отчет на соответствие регламенту» | +| **Executive-бот** | Топ-менеджмент | «Сводка KPI по всем проектам» | Каждый из этих ботов может быть реализован как отдельный XMPP-клиент (или другой клиент), подключающийся к общему RAG-ядру. Благодаря единому ядру, все боты используют одни и те же документы и историю, но могут иметь свои промпты, что позволяет настраивать стиль и глубину ответов под конкретную задачу. @@ -1219,18 +1213,18 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби В новой архитектуре персональные настройки хранятся в общей БД и доступны всем клиентам. Пользователь может начать диалог в XMPP, а продолжить в Telegram – история и контекст сохраняются. -**Ключевые сценарии персонального ассистента:** +**Ключевые сценарии персонального ассистента**: -| Сценарий | Пример запроса | Автоматизация | -|-----|------|------| -| **Планирование командировки** | «Запланируй командировку в Нижний Новгород на 10–12 мая» | Бот через агента‑тревел подбирает билеты, отель, создает задачу на согласование руководителю, резервирует | -| **Поиск и бронирование билетов** | «Найди ближайший рейс до Екатеринбурга на завтра утро» | Интеграция с корпоративным тревел‑агентом (API), выдача вариантов, бронирование по команде | -| **Бронирование гостиницы** | «Подбери гостиницу рядом с офисом клиента в Казани, бюджет до 5000 ₽/ночь» | Агент‑отельер возвращает список, пользователь выбирает – бронь автоматически | -| **Оформление командировочного удостоверения** | «Сформируй командировочное удостоверение по поездке №45» | Бот заполняет шаблон данными из бронирования, высылает PDF | -| **Авансовый отчет по командировке** | «Сделай авансовый отчет за поездку в Уфу» | Бот предзаполняет даты, маршрут, суммы билетов и отеля; сотрудник добавляет фото чеков → OCR распознает и вносит суммы | -| **Согласование отчета** | «Отправь отчет руководителю на подпись» | Бот пересылает отчет в личный чат руководителя, тот ставит «OK» кнопкой | -| **Календарь командировок** | «Добавь поездку в мой календарь на 15–17 мая» | Синхронизация с корпоративным календарем (Exchange/Google) | -| **Статус командировок** | «Какие у меня утвержденные командировки на следующую неделю?» | Бот извлекает из базы данных (или внешней системы) и отвечает | +| Сценарий | Пример запроса | Автоматизация | +|----------|----------------|---------------| +| **Планирование командировки** | «Запланируй командировку в Нижний Новгород на 10–12 мая» | Бот через агента-тревел подбирает билеты, отель, создает задачу на согласование руководителю, резервирует | +| **Поиск и бронирование билетов** | «Найди ближайший рейс до Екатеринбурга на завтра утро» | Интеграция с корпоративным тревел-агентом (API), выдача вариантов, бронирование по команде | +| **Бронирование гостиницы** | «Подбери гостиницу рядом с офисом клиента в Казани, бюджет до 5000 ₽/ночь» | Агент-отельер возвращает список, пользователь выбирает – бронь автоматически | +| **Оформление командировочного удостоверения** | «Сформируй командировочное удостоверение по поездке №45» | Бот заполняет шаблон данными из бронирования, высылает PDF | +| **Авансовый отчет по командировке** | «Сделай авансовый отчет за поездку в Уфу» | Бот предзаполняет даты, маршрут, суммы билетов и отеля; сотрудник добавляет фото чеков → OCR распознает и вносит суммы | +| **Согласование отчета** | «Отправь отчет руководителю на подпись» | Бот пересылает отчет в личный чат руководителя, тот ставит «OK» кнопкой | +| **Календарь командировок** | «Добавь поездку в мой календарь на 15–17 мая» | Синхронизация с корпоративным календарем (Exchange/Google) | +| **Статус командировок** | «Какие у меня утвержденные командировки на следующую неделю?» | Бот извлекает из базы данных (или внешней системы) и отвечает | ## 2. Как бот «вызывает» агентов – архитектура оркестрации @@ -1241,12 +1235,12 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби 3. Если запрос требует внешнего действия (бронирование, расчет, генерация отчета, OCR), RAG-сервер возвращает структурированную команду (например, в формате `[SURGICAL_REPLACE]`, `[REWRITE]`, или через теги для вызова агента). 4. Клиент (или отдельный агент-оркестратор) выполняет эту команду через API внешних систем и возвращает результат в RAG-сервер для финальной обработки. -| Запрос пользователя | Намерение (intent) | Вызываемый агент | Действие агента | Результат | -|----|----|----|----|----| -| «Найди билеты Москва‑Питер на 15 мая» | `BOOKING` | Агент‑тревел | Запрос к API билетной системы | Список рейсов с ценами | -| «Подбери гостиницу рядом с вокзалом» | `BOOKING` | Агент‑отельер | Поиск по API Booking.com / Ostrovok | Варианты отелей, кнопка бронирования | -| «Сделай авансовый отчет по командировке #123» | `REPORT` | Агент‑генератор DOCX | Заполняет шаблон из данных бронирования и чеков | Готовый отчет в чат | -| «Проверь этот чек» | `OCR` | Агент‑распознаватель (OCR) | Извлекает сумму, дату, назначение | Структурированные данные, которые бот вставляет в отчет | +| Запрос пользователя | Намерение (intent) | Вызываемый агент | Действие агента | Результат | +|---------------------|---------------------|------------------|-----------------|-----------| +| «Найди билеты Москва-Питер на 15 мая» | `BOOKING` | Агент-тревел | Запрос к API билетной системы | Список рейсов с ценами | +| «Подбери гостиницу рядом с вокзалом» | `BOOKING` | Агент-отельер | Поиск по API Booking.com / Ostrovok | Варианты отелей, кнопка бронирования | +| «Сделай авансовый отчет по командировке #123» | `REPORT` | Агент-генератор DOCX | Заполняет шаблон из данных бронирования и чеков | Готовый отчет в чат | +| «Проверь этот чек» | `OCR` | Агент-распознаватель (OCR) | Извлекает сумму, дату, назначение | Структурированные данные, которые бот вставляет в отчет | **Вывод:** RAG-сервер – это «мозг», а агенты – «руки». Без RAG-сервера агенты разрозненны; с ним они работают как единая система, управляемая естественным языком через единый HTTP API. @@ -1268,7 +1262,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби **Допущения:** - Количество командировок в год: 200 чел. × 44 недели = **8 800 командировок**. - Без автоматизации затраты времени на одну командировку (поиск билетов, бронирование отеля, оформление заявки, составление авансового отчета, согласование) – **2 часа** (суммарно). -- С ботом (интеграция с тревел‑агентом, автоматическое заполнение форм, OCR чеков, «однонажательное» согласование) – **0,4 часа** (24 минуты). Экономия = 1,6 часа на командировку. +- С ботом (интеграция с тревел-агентом, автоматическое заполнение форм, OCR чеков, «однонажательное» согласование) – **0,4 часа** (24 минуты). Экономия = 1,6 часа на командировку. **Экономия в часах:** 8 800 × 1,6 = **14 080 часов**. @@ -1282,24 +1276,24 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби ### 3.4. Итоговая годовая экономия -| Статья | Часы | -| - | - | -| Поиск информации (RAG) | 40 755 | -| Командировки (бронирование + отчетность) | 14 080 | -| Снижение ошибок в документообороте | 1 600 | -| **Итого прямая экономия времени** | **56 435** | +| Статья | Часы | +|--------|------| +| Поиск информации (RAG) | 40 755 | +| Командировки (бронирование + отчетность) | 14 080 | +| Снижение ошибок в документообороте | 1 600 | +| **Итого прямая экономия времени** | **56 435** | *Не учтены косвенные эффекты: ускорение согласования, повышение мотивации, снижение текучки.* ### 3.5. Затраты на внедрение и обслуживание -| Статья | Стоимость | -| | | -| Развертывание инфраструктуры (серверы, настройка) | 1 млн руб. (разово) | -| Разработка интеграций (агенты, тревел‑API, 1С, календарь) | 2 млн руб. (разово, можно тиражировать) | -| Обслуживание, обновление БЗ, поддержка | 1 млн руб./год | -| **Итого первый год** | **4 млн руб.** | -| **Итого последующие годы** | **1 млн руб./год** | +| Статья | Стоимость | +|--------|-----------| +| Развертывание инфраструктуры (серверы, настройка) | 1 млн руб. (разово) | +| Разработка интеграций (агенты, тревел-API, 1С, календарь) | 2 млн руб. (разово, можно тиражировать) | +| Обслуживание, обновление БЗ, поддержка | 1 млн руб./год | +| **Итого первый год** | **4 млн руб.** | +| **Итого последующие годы** | **1 млн руб./год** | ## 4. Перспективы развития (12–24 месяца) @@ -1326,7 +1320,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби - **Интеграция с системами документооборота (СЭД)** – бот сможет подписывать документы ЭЦП, отправлять их на регистрацию, отслеживать статусы. В новой архитектуре это делается через расширение API RAG-сервера. - **Прогнозная аналитика командировок** – бот будет предлагать оптимальные маршруты, экономить на билетах за счет предварительного бронирования. -- **Агент‑индексатор сетевых папок (SMB)** – бот сам сканирует общие каталоги и обновляет базу знаний, отправляя файлы на индексацию в RAG-сервер. +- **Агент-индексатор сетевых папок (SMB)** – бот сам сканирует общие каталоги и обновляет базу знаний, отправляя файлы на индексацию в RAG-сервер. - **Кэширование результатов генерации** – для одинаковых запросов (с использованием хеша запроса и контекста) планируется внедрение кэширования (in-memory или Redis) на уровне RAG-сервера для снижения нагрузки и ускорения ответа. - **Сбор обратной связи** – команда `!feedback` для оценки качества ответов (лайки/дизлайки) и хранение оценок в БД для последующего анализа. - **A/B-тестирование промптов** – возможность разделять пользователей на группы и применять разные версии промптов для сравнения эффективности. @@ -1334,6 +1328,8 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби - **Команда `!style`** – изменение стиля ответов (кратко/подробно/по умолчанию) по желанию пользователя. - **Подключение дополнительных клиентов** – благодаря HTTP API RAG-сервера можно легко добавить Telegram-бота, Mastodon-бота, веб-интерфейс или интеграцию с системами документооборота без изменения ядра. +--- + # III. Описание модулей Платформа Эфцекабот построена по принципу **«тонкий клиент – толстый сервер»**. Вся RAG-логика вынесена в отдельный HTTP-сервис – **RAG-сервер**, который обслуживает все клиенты (XMPP-боты, Telegram-боты, веб-интерфейсы и т.д.). Клиенты отправляют запросы на RAG-сервер через HTTP и не содержат RAG-логики. @@ -1343,6 +1339,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби ## 1. Модуль `rag_orchestrator.py` – оркестратор RAG-пайплайна **Назначение:** это **сердце платформы**. Модуль координирует все этапы обработки запроса через менеджеры: + - `HistoryManager` – получение и сжатие истории. - `IntentRouter` – обработка специализированных намерений. - `QueryProcessor` – обычный RAG-пайплайн (поиск, генерация, критика). @@ -1351,10 +1348,12 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби **Место в архитектуре:** запускается внутри RAG-сервера при обработке HTTP-запроса `/rag/query`. Не зависит от XMPP или других протоколов – может быть использован в любом клиенте через HTTP API. **Ключевые методы:** + - `process_query()` – основной метод, выполняет полный цикл обработки запроса. - `index_document()` – индексация документа (вызывается из `/rag/index`). Перед индексацией применяет иерархическое резюмирование, если документ слишком большой. **Особенности:** + - Не содержит состояния, использует переданные сервисы и промпты. - Поддерживает специализированные намерения: `METRICS`, `SUMMARY`, `CONTRADICTION`, `TEMPLATE_FILL`, `SPELLCHECK`, `SURGICAL`, `GREETING`. - Добавляет цепочку рассуждений (Chain-of-Thought) для `CALCULATION` и `PROCEDURE`. @@ -1363,10 +1362,10 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби **Назначение:** предоставляет REST API для всех клиентов. Является точкой входа в платформу. -**Эндпоинты:** +**Эндпоинты**: | Метод | Эндпоинт | Назначение | Требует аутентификации | -|-|-|-|-| +|-------|----------|------------|------------------------| | POST | `/rag/query` | Выполнить RAG-запрос (история берется из БД) | Да | | POST | `/rag/index` | Проиндексировать документ | Да | | POST | `/rag/vision` | Распознать текст на изображении (OCR) | Да | @@ -1379,6 +1378,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби **Место в архитектуре:** запускается как отдельный процесс (с помощью Uvicorn). Обслуживает все клиенты. Инициализирует все сервисы (БД, Qdrant, GigaChat) и создает экземпляр `RAGOrchestrator`. **Особенности:** + - Использует Pydantic для валидации запросов и ответов. - Поддерживает CORS для возможности запросов с других доменов. - Имеет встроенный healthcheck для мониторинга. @@ -1391,6 +1391,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби **Назначение:** используется тонкими клиентами (XMPP-ботами, Telegram-ботами) для отправки запросов к RAG-серверу. **Методы:** + - `query()` – отправляет запрос на `/rag/query`. - `index_document()` – отправляет запрос на `/rag/index`. - `vision(file_path)` – отправляет изображение на `/rag/vision`. @@ -1400,6 +1401,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби **Место в архитектуре:** встраивается в клиентские приложения вместо локального вызова RAG-логики. **Особенности:** + - Асинхронный (aiohttp). - Поддерживает повторные попытки (retry) при сетевых ошибках. - Автоматически добавляет заголовок `X-API-Key` с API-ключом. @@ -1411,13 +1413,13 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби **Место в архитектуре:** может использоваться для тестирования или в случае, если RAG-ядро запущено в том же процессе, что и клиент. -## 5. Модуль prompt_builder.py – построитель промтов (новое) +## 5. Модуль `prompt_builder.py` – построитель промтов -**Назначение:** динамически подбирает релевантные few-shot примеры из файла data/fewshot_examples.json (или использует статические) и формирует промт по структуре «сэндвич» (важное в начале и в конце). Это улучшает качество ответов, особенно для сложных запросов. +**Назначение:** динамически подбирает релевантные few-shot примеры из файла `data/fewshot_examples.json` (или использует статические) и формирует промт по структуре «сэндвич» (важное в начале и в конце). Это улучшает качество ответов, особенно для сложных запросов. **Формат файла** `fewshot_examples.json`: -``` +```json [ { "keywords": ["OEE", "эффективность"], @@ -1433,7 +1435,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби - `question` – вопрос пользователя. - `answer` – эталонный ответ. -**Место в архитектуре:** используется в QueryProcessor при синтезе ответа. +**Место в архитектуре:** используется в `QueryProcessor` при синтезе ответа. ## 6. Модули функций (каталог `functions/`) @@ -1483,18 +1485,18 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби **Вход:** текст, название, промпт, конфиг. **Выход:** строка с кратким изложением. -### 6.5. hierarchical_summarize.py – иерархическое резюмирование (новое) +### 6.5. `hierarchical_summarize.py` – иерархическое резюмирование **Назначение:** сжимает очень большие тексты (документы, историю диалога) с помощью рекурсивного резюмирования блоков. Разбивает текст на блоки по предложениям, резюмирует каждый блок через GigaChat, объединяет результаты, и при необходимости повторяет процесс рекурсивно до достижения целевой длины. -**Место в архитектуре:** вызывается из RAGOrchestrator: +**Место в архитектуре:** вызывается из `RAGOrchestrator`: - В `process_query` – для сжатия длинной истории диалога. - В `index_document` – для сжатия больших документов перед индексацией (через метод `_compress_document_if_needed`). -**Как работает:** использует промпт (hierarchical_summary.txt) для каждого блока. +**Как работает:** использует промпт (`hierarchical_summary.txt`) для каждого блока. -**Вход:** текст, целевой размер в токенах, размер блока, глубина. +**Вход:** текст, целевой размер в токенах, размер блока, глубина. **Выход:** сжатый текст. ### 6.6. `check_consistency.py` – проверка противоречий @@ -1557,7 +1559,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби Долгоживущие компоненты, которые инициализируются один раз при старте RAG-сервера и предоставляют API для работы с внешними системами. | Файл | Назначение | -|-----|------| +|------|------------| | `postgres_service.py` | Пул соединений с PostgreSQL. CRUD для документов, истории диалогов, комнат, шаблонов, прав доступа. | | `qdrant_service.py` | Векторная БД. Создание коллекции, гибридный поиск (dense + sparse), полнотекстовый поиск, удаление по doc_id. | | `embedding_service.py` | Эмбеддинги GigaChat. Одиночные/пакетные запросы, кэширование (`lru_cache`), обрезка текста до 800 символов. | @@ -1573,10 +1575,10 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби ### 8.1. Обработчики (`handlers/`) | Файл | Назначение | -|-----|------| +|------|------------| | `metrics_handler.py` | Счетчики (сообщения, файлы, AI-запросы, ошибки). | | `message_handler.py` | Маршрутизация входящих сообщений (использует `RAGClient`). | -| `file_handler.py` | Скачивание файлов и постановка в очередь индексации. Убраны прямые вызовы GigaChat – теперь всё через RAGClient. | +| `file_handler.py` | Скачивание файлов и постановка в очередь индексации. Убраны прямые вызовы GigaChat – теперь все через RAGClient. | | `room_handler.py` | MUC комнаты (приглашения, вход, переподключение). | | `subscription_handler.py` | Подписки (roster subscription). | | `health_handler.py` | Очистка файлов, healthcheck БД/Qdrant (для клиентов). | @@ -1584,7 +1586,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби ### 8.2. Команды (`commands/`) | Файл | Назначение | -|-----|------| +|------|------------| | `base.py` | Базовый класс `Command`. | | `registry.py` | Регистрация команд, алиасы, подсказки. | | `info.py` | `!info` – краткая справка. | @@ -1601,7 +1603,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби ### 8.3. Воркеры (`workers/`) | Файл | Назначение | -|-----|------| +|------|------------| | `indexing_worker.py` | Фоновый воркер, который обрабатывает очередь индексации файлов и URL, отправляя их на RAG-сервер через `RAGClient`. Обработка изображений и аудио теперь через RAG-сервер. | ## 9. Утилиты (каталог `utils/`) @@ -1609,7 +1611,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби Вспомогательные функции, используемые как сервером, так и клиентами: | Файл | Назначение | -|-----|------| +|------|------------| | `config_loader.py` | Загрузка `rag.conf` и `bot.conf`, слияние, чтение `.env`, создание `AppConfig` с помощью Pydantic. | | `logger.py` | Настройка логирования (уровни, вывод в файл и консоль). | | `layout_converter.py` | Конвертер раскладки клавиатуры (русская ↔ английская). | @@ -1636,7 +1638,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби Платформа использует два основных конфигурационных файла: -- **`rag.conf`** – общие настройки для всех ботов: параметры подключения к БД, Qdrant, GigaChat, настройки чанкинга, RAG, веб-скрапера, очистки, логирования. Добавлены параметры управления токенами и секция summarization. +- **`rag.conf`** – общие настройки для всех ботов: параметры подключения к БД, Qdrant, GigaChat, настройки чанкинга, RAG, веб-скрапера, очистки, логирования. Добавлены параметры управления токенами и секция `summarization`. - **`bot.conf`** – настройки конкретного профиля бота (методолог, коробочник, персональный ассистент): JID, пароль, промпты, пути к данным, ключевые слова, администраторы, параметры функций (температура, лимиты). Переменные окружения (пароли, ключи API) хранятся в `.env`. Примеры конфигурации предоставлены в файлах `rag.conf.example`, `bot.conf.sample`, `env.example`. @@ -1645,7 +1647,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби Схема создается автоматически через `schema.sql` и включает таблицы: -- **`documents`** – метаданные документов (источник, владелец, глобальный/комнатный флаг, хеш, коллекция Qdrant). Добавлена колонка indexed `BOOLEAN DEFAULT FALSE` для транзакционности индексации. +- **`documents`** – метаданные документов (источник, владелец, глобальный/комнатный флаг, хеш, коллекция Qdrant). Добавлена колонка `indexed BOOLEAN DEFAULT FALSE` для транзакционности индексации. - **`document_access`** – права доступа к личным документам. - **`history`** – история диалогов (личных и комнатных). - **`rooms`** – список MUC-комнат, в которых бот должен состоять. @@ -1657,22 +1659,31 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби ## 1. Генерация API-ключа -Для защиты RAG-сервера используется API-ключ, который передаётся в заголовке `X-API-Key` при каждом запросе (кроме `/health`). Ключ должен быть уникальным и сложным. +Для защиты RAG-сервера используется API-ключ, который передается в заголовке `X-API-Key` при каждом запросе (кроме `/health`). Ключ должен быть уникальным и сложным. **Сгенерировать ключ можно одним из способов:** -```bash -# Способ 1 – через Python (рекомендуется) + +### Способ 1 – через Python (рекомендуется) + +``` python3 -c "import secrets; print(secrets.token_urlsafe(32))" +``` -# Способ 2 – через openssl +### Способ 2 – через openssl + +``` openssl rand -base64 32 +``` -# Способ 3 – через /dev/urandom (Linux/FreeBSD) +### Способ 3 – через /dev/urandom (Linux/FreeBSD) + +``` cat /dev/urandom | tr -dc 'a-zA-Z0-9' | head -c 32; echo ``` Пример сгенерированного ключа: + ``` vK9pQz5RfT7mX2wY4nB8cD6gH3jF1aE5sL0oU9iP2qR7tY6wX4zA ``` @@ -1691,6 +1702,4 @@ RAG_API_KEY=вставьте_сгенерированный_ключ_сюда ## 4. Использование в боте -В `bots/xmpp/client.py` при создании `RAGClient` автоматически передаётся `api_key=config.rag_api_key`. В `rag_client.py` ключ добавляется в заголовок `X-API-Key` при каждом запросе. - ---- \ No newline at end of file +В `bots/xmpp/client.py` при создании `RAGClient` автоматически передается `api_key=config.rag_api_key`. В `rag_client.py` ключ добавляется в заголовок `X-API-Key` при каждом запросе.