From 05f9620e8ed6fc726bdedf970b4399b5cb70fef8 Mon Sep 17 00:00:00 2001 From: Markov Andrey Date: Tue, 30 Jun 2026 15:30:31 +0000 Subject: [PATCH] Update 2 files - /README.md - /template_bot_profile/bot.conf.sample --- README.md | 73 ++++++++++++++++++++-------- template_bot_profile/bot.conf.sample | 7 ++- 2 files changed, 58 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 1843176..2bdbbeb 100644 --- a/README.md +++ b/README.md @@ -140,6 +140,7 @@ │ ├── 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-сервер @@ -205,7 +206,8 @@ │ ├── template_bot_profile/ # ШАБЛОН ПРОФИЛЯ (для создания новых ботов) │ ├── bot.conf.sample # Пример конфига бота-клиента (копируется в bot.conf) -│ ├── data/ # Пустой каталог для постоянных копий файлов +│ ├── data/ # Каталог для постоянных копий файлов +│ │ └── fewshot_examples.json # Примеры few-shot (можно редактировать) │ ├── prompts/ # Пример промптов (копируются в профиль) │ │ ├── consistency_check.txt # Проверка противоречий между фрагментами │ │ ├── expand.txt # Расширение запроса (синонимы, аббревиатуры) @@ -315,6 +317,9 @@ 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`" – путь к файлу с примерами (относительно профиля). Эти параметры позволяют настраивать поведение без изменения кода. Переопределение параметров из `rag.conf` в `bot.conf` дает гибкость для разных профилей. @@ -327,6 +332,7 @@ pytest tests/ -v | **Менеджер истории** (`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-сервером и оркестратором. Не содержат бизнес-логики. | @@ -1318,6 +1324,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби - **Аутентификация через 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))"`. +- **Динамические few-shot примеры** – подбор релевантных примеров на основе запроса и построение промта по структуре «сэндвич». ### 4.2. Планируемые улучшения @@ -1408,11 +1415,35 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби **Место в архитектуре:** может использоваться для тестирования или в случае, если RAG-ядро запущено в том же процессе, что и клиент. -## 5. Модули функций (каталог `functions/`) +## 5. Модуль prompt_builder.py – построитель промтов (новое) + +**Назначение:** динамически подбирает релевантные few-shot примеры из файла data/fewshot_examples.json (или использует статические) и формирует промт по структуре «сэндвич» (важное в начале и в конце). Это улучшает качество ответов, особенно для сложных запросов. + +**Формат файла** `fewshot_examples.json`: + +``` +[ + { + "keywords": ["OEE", "эффективность"], + "intents": ["PROCEDURE", "CALCULATION"], + "question": "Как рассчитать OEE?", + "answer": "OEE = Доступность × Производительность × Качество." + } +] +``` + +- `keywords` – список ключевых слов для поиска релевантности. +- `intents` – список намерений, для которых применим пример. +- `question` – вопрос пользователя. +- `answer` – эталонный ответ. + +**Место в архитектуре:** используется в QueryProcessor при синтезе ответа. + +## 6. Модули функций (каталог `functions/`) Все функции являются **чистыми, без состояния** и вызываются из `RAGOrchestrator` на сервере. Они не зависят от XMPP и используют переданные промпты и конфигурацию. -### 5.1. `intent_classify.py` – классификация намерений +### 6.1. `intent_classify.py` – классификация намерений **Назначение:** определяет тип запроса пользователя (FACT, PROCEDURE, METRICS, SUMMARY, CONTRADICTION, SURGICAL, GREETING, GENERAL, SPELLCHECK, TEMPLATE_FILL) по тексту запроса. **Примеры в промпте перемешаны для уменьшения эффекта якорения.** @@ -1423,7 +1454,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби **Вход:** текст запроса, промпт, конфиг. **Выход:** код намерения (str) или `"GENERAL"`. -### 5.2. `expand_query.py` – расширение запроса +### 6.2. `expand_query.py` – расширение запроса **Назначение:** добавляет синонимы, аббревиатуры и связанные термины к исходному запросу для увеличения полноты поиска. @@ -1434,7 +1465,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби **Вход:** текст запроса, промпт, конфиг. **Выход:** расширенный запрос (строка) или исходный, если расширение не удалось. -### 5.3. `extract_metrics.py` – извлечение метрик +### 6.3. `extract_metrics.py` – извлечение метрик **Назначение:** извлекает числовые показатели (KPI, OEE, такт, выработку, проценты) из текста в структурированном виде (JSON). @@ -1445,7 +1476,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби **Вход:** контекст (текст), промпт, конфиг. **Выход:** список словарей с полями `metric_name`, `value`, `unit`, `period`, `source_fragment`. -### 5.4. `summarize_document.py` – суммаризация документа +### 6.4. `summarize_document.py` – суммаризация документа **Назначение:** создает краткий пересказ документа (≤30% от оригинала) с выделением целей, выводов и ключевых цифр. @@ -1456,7 +1487,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби **Вход:** текст, название, промпт, конфиг. **Выход:** строка с кратким изложением. -### 5.5. hierarchical_summarize.py – иерархическое резюмирование (новое) +### 6.5. hierarchical_summarize.py – иерархическое резюмирование (новое) **Назначение:** сжимает очень большие тексты (документы, историю диалога) с помощью рекурсивного резюмирования блоков. Разбивает текст на блоки по предложениям, резюмирует каждый блок через GigaChat, объединяет результаты, и при необходимости повторяет процесс рекурсивно до достижения целевой длины. @@ -1470,7 +1501,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби **Вход:** текст, целевой размер в токенах, размер блока, глубина. **Выход:** сжатый текст. -### 5.6. `check_consistency.py` – проверка противоречий +### 6.6. `check_consistency.py` – проверка противоречий **Назначение:** находит логические, числовые или терминологические расхождения в разных фрагментах текста. @@ -1481,7 +1512,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби **Вход:** список фрагментов, запрос, промпт, конфиг. **Выход:** строка с результатом проверки. -### 5.7. `critique_answer.py` – самокритика ответа +### 6.7. `critique_answer.py` – самокритика ответа **Назначение:** оценивает качество сгенерированного ответа по пяти критериям (соответствие источнику, отсутствие галлюцинаций, стиль, логика, запрет внешних знаний). @@ -1492,7 +1523,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби **Вход:** запрос, контекст, ответ, промпт, конфиг. **Выход:** `True` (ответ хороший) или `False` (есть замечания). -### 5.8. `rerank_context.py` – переранжирование контекста +### 6.8. `rerank_context.py` – переранжирование контекста **Назначение:** отбирает только релевантные фрагменты из результатов поиска, отбрасывая шум. Использует локальный кросс-энкодер вместо LLM. @@ -1503,7 +1534,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби **Вход:** запрос, контекст, конфиг. **Выход:** отфильтрованный контекст (строка). -### 5.9. `file_processor.py` – обработка файлов +### 6.9. `file_processor.py` – обработка файлов **Назначение:** отправка файлов пользователю через HTTP Upload (XEP-0363) и обработка тегов `[SURGICAL_REPLACE]`, `[REWRITE]`, `[FILE]` из ответа AI. @@ -1514,7 +1545,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби **Вход:** ответ AI, JID пользователя, путь к файлу. **Выход:** отправленный файл или сообщение об ошибке. -### 5.10. `generate_document.py` – генерация по шаблону +### 6.10. `generate_document.py` – генерация по шаблону **Назначение:** заполняет плейсхолдеры `{{название}}` в шаблоне документа на основе данных из базы знаний. @@ -1525,7 +1556,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби **Вход:** шаблон (DOCX), запрос пользователя, конфиг. **Выход:** готовый DOCX-файл. -## 6. Сервисы (каталог `services/`) +## 7. Сервисы (каталог `services/`) Долгоживущие компоненты, которые инициализируются один раз при старте RAG-сервера и предоставляют API для работы с внешними системами. @@ -1539,11 +1570,11 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби | `giga_client.py` | Клиент GigaChat. Методы `chat()` и `upload_file()` – без бизнес-логики. | | `reranker_service.py` | Кросс-энкодер для переранжирования (локально). Ленивая загрузка модели. | -## 7. Обработчики, команды, воркеры (для XMPP-клиентов) +## 8. Обработчики, команды, воркеры (для XMPP-клиентов) Эти модули работают только на стороне **тонких клиентов** (XMPP-ботов) и не входят в RAG-сервер. -### 7.1. Обработчики (`handlers/`) +### 8.1. Обработчики (`handlers/`) | Файл | Назначение | |-----|------| @@ -1554,7 +1585,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби | `subscription_handler.py` | Подписки (roster subscription). | | `health_handler.py` | Очистка файлов, healthcheck БД/Qdrant (для клиентов). | -### 7.2. Команды (`commands/`) +### 8.2. Команды (`commands/`) | Файл | Назначение | |-----|------| @@ -1571,13 +1602,13 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби | `create.py` | `!create` – генерация документа по шаблону. | | `global_remove.py` | `!global_remove` – удаление глобального документа (админ). | -### 7.3. Воркеры (`workers/`) +### 8.3. Воркеры (`workers/`) | Файл | Назначение | |-----|------| | `indexing_worker.py` | Фоновый воркер, который обрабатывает очередь индексации файлов и URL, отправляя их на RAG-сервер через `RAGClient`. Обработка изображений и аудио теперь через RAG-сервер. | -## 8. Утилиты (каталог `utils/`) +## 9. Утилиты (каталог `utils/`) Вспомогательные функции, используемые как сервером, так и клиентами: @@ -1590,7 +1621,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби | `web_utils.py` | Веб-скрапинг (`fetch_any_url`, `crawl_url`). | | `arg_parser.py` | Парсинг аргументов команд (--flag value). | -## 9. Тесты (каталог `tests/`) +## 10. Тесты (каталог `tests/`) Покрывают критически важные функции: @@ -1605,7 +1636,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби Тесты используют `pytest` и `pytest-asyncio`, не требуют реального подключения к внешним сервисам (используются моки). Запуск: `pytest tests/ -v`. -## 10. Конфигурационные файлы +## 11. Конфигурационные файлы Платформа использует два основных конфигурационных файла: @@ -1614,7 +1645,7 @@ Qdrant вернул 30 фрагментов. Кросс-энкодер отби Переменные окружения (пароли, ключи API) хранятся в `.env`. Примеры конфигурации предоставлены в файлах `rag.conf.example`, `bot.conf.sample`, `env.example`. -## 11. Схема базы данных (PostgreSQL) +## 12. Схема базы данных (PostgreSQL) Схема создается автоматически через `schema.sql` и включает таблицы: diff --git a/template_bot_profile/bot.conf.sample b/template_bot_profile/bot.conf.sample index 84f5e5b..669ac86 100644 --- a/template_bot_profile/bot.conf.sample +++ b/template_bot_profile/bot.conf.sample @@ -39,4 +39,9 @@ features: ocr: true enable_intent_classification: true enable_self_critique: true - mention_keyword: "методолог" \ No newline at end of file + mention_keyword: "методолог" + +# Настройки динамических примеров (few-shot) +fewshot: + max_examples: 5 # для бота-методолога можно больше + examples_file: "data/fewshot_examples.json" \ No newline at end of file