init

6_генерация_эмбеддингов/embed_input_spec.txt

@@ -0,0 +1,103 @@
+# Спецификация входа для генерации эмбеддинга главы
+
+Текст, который передаётся в модель эмбеддингов (по умолчанию BAAI/bge-m3), строится из **валидированного анализа главы**. Источник полей — JSON анализа по схеме из ARCHITECTURE_SUMMARY.md (блоки framework, insights, application). Цель — сохранить смысл для семантического поиска: по вектору ищут главы по смыслу (принципы, инсайты, техники), а не по сырому тексту.
+
+---
+
+## ЧТО ВКЛЮЧАТЬ
+
+В текст для эмбеддинга входят **только** блоки анализа:
+
+1. **Framework (каркас):** принципы (title, description, example), terms (термин → краткое пояснение), при необходимости — ключевые цепочки cause–mechanism–result (кратко).
+
+2. **Insights (инсайты):** title, description (и при необходимости example) по каждому инсайту. Без лишних метаполей.
+
+3. **Application (применение):** техники — name, goal, steps (кратко или полный список), при необходимости context_example. То, по чему будет искаться «как это применить».
+
+**Не включать:**
+- Оригинальный текст главы.
+- Limitations — по умолчанию не включать (опционально через конфиг).
+- Теги — хранятся в payload Qdrant, в вектор не входят.
+
+---
+
+## ПОРЯДОК И ФОРМАТ СЕРИАЛИЗАЦИИ
+
+**Язык текста:** тот же, что и язык главы (или основной язык книги). Для мультиязычных коллекций — зафиксировать в конфиге (например, всегда русский / всегда язык главы).
+
+**Порядок секций** (приоритет при truncation — сверху вниз):
+
+```
+FRAMEWORK
+{framework}
+
+INSIGHTS
+{insights}
+
+APPLICATION
+{application}
+```
+
+**Разделители:**
+- Между секциями: заголовок секции (FRAMEWORK, INSIGHTS, APPLICATION) + пустая строка.
+- Внутри секции: элементы разделять переносом строки или маркером «—»; не склеивать в один абзац. Пример: каждый принцип — с новой строки; каждый инсайт — с новой строки; каждая техника — с новой строки.
+
+**Формат полей:** читаемый текст с подписями («Принцип: …», «Инсайт: …», «Техника: …») или компактный структурированный текст. Избегать сырого JSON без подписей; предпочитать человекочитаемую склейку.
+
+**Подстановки при сборке:**
+- `{framework}` — строка из JSON блока framework (принципы, terms; chains при необходимости).
+- `{insights}` — строка из JSON блока insights.
+- `{application}` — строка из JSON блока application.
+
+**Пример сериализации (фрагмент):**
+
+```
+FRAMEWORK
+
+Принцип: Правило двух минут. Описание: Если действие занимает меньше двух минут — сделай его сразу. Пример: ответ на короткий email, вынести мусор.
+Термины: атомная привычка — сверхмалое действие, повторяемое ежедневно.
+
+INSIGHTS
+
+Инсайт: Привычки формируют идентичность. Мы меняемся не через цели, а через системы и повторяющиеся действия.
+
+APPLICATION
+
+Техника: Снижение барьера входа. Цель: начать действие без откладывания. Шаги: сформулировать версию привычки «на 2 минуты»; выполнять её в одно и то же время; после закрепления — расширять.
+```
+
+**Нормализация перед подачей в модель:** схлопнуть множественные пробелы и переносы в один; обрезать пробелы по краям строк и в начале/конце итогового текста. Это уменьшает разброс из‑за форматирования.
+
+---
+
+## ЛИМИТ МОДЕЛИ И СТРАТЕГИЯ ПРЕВЫШЕНИЯ
+
+- **Лимит (bge-m3):** 8192 токенов на вход. Полный анализ главы обычно укладывается. Для других моделей — лимит указывать в конфиге.
+
+- **Если текст укладывается в лимит:** передать один сконкатенированный текст (FRAMEWORK + INSIGHTS + APPLICATION) в один вызов модели.
+
+- **Если текст длиннее лимита** — выбрать одну из стратегий (зафиксировать в конфиге):
+
+  1. **truncate_priority:** обрезать текст до лимита. Сохранять в порядке приоритета: сначала APPLICATION (техники важны для поиска), затем INSIGHTS, затем FRAMEWORK. Отбрасывать с конца не поместившегося блока.
+
+  2. **truncate_per_section:** обрезать до лимита, сохраняя начало каждой секции. Сначала поместить начало FRAMEWORK, затем начало INSIGHTS, затем начало APPLICATION, пока не исчерпается лимит.
+
+  3. **chunk_aggregate:** разбить текст **последовательно** (с начала к концу) на чанки по лимиту; получить вектор для каждого чанка; усреднить векторы (или другой способ агрегации) и сохранить один итоговый вектор. Способ агрегации — в конфиге.
+
+---
+
+## ВЫХОД
+
+- Один вектор фиксированной размерности. Для bge-m3 — **1024**. При смене модели размерность меняется; коллекции Qdrant создавать с соответствующим size.
+- Вектор сохраняется в Qdrant в коллекции `chapter_analyses`. Payload — по схеме из ARCHITECTURE_SUMMARY.md: bookId, chapterId, chapterNumber, chapterTitle, validationScore, tags и др. Текст анализа в payload при необходимости хранить отдельно или не хранить (по политике системы).
+
+---
+
+## КОНФИГУРАЦИЯ
+
+- Модель эмбеддингов: env/конфиг (по умолчанию EMBED_MODEL=bge-m3).
+- Лимит токенов модели: конфиг (для bge-m3: EMBED_MAX_TOKENS=8192).
+- Размерность вектора: для bge-m3 — 1024; при смене модели задавать в конфиге и пересоздавать коллекции Qdrant.
+- Стратегия при превышении: конфиг (truncate_priority | truncate_per_section | chunk_aggregate).
+- Включение limitations в текст: опционально, конфиг (по умолчанию false).
+- Язык сериализации (при мультиязычности): опционально, конфиг (например, chapter_lang | book_lang | fixed:ru).