feat(sprint6c+sprint7): терминология, сверка примеров с кодом, мульти-RAG (часть A)
Спринт 6c — терминология и сверка документации с реальным кодом:
- Словарь терминов в static/docs.html: «маршрутизатор» вместо «роутер»,
«защитное условие» вместо «guard», «пошаговая ветка» вместо «многошаговая».
Разделены концепты «намерение» (intent) и «ветка» (branch) с пометкой,
что в коде они хранятся как одна сущность 1:1.
- Песочница: «Решение маршрутизатора» виден всегда (зелёный/жёлтый),
счётчик переключений «N из 3» отдельной плашкой, бейджи под словарь.
- Настройки: «Условия перехода» → «Защитные условия (guards, JSON)».
- GRAPH_ARCHITECTURE_v4.md: имена полей thread_state и слоты приведены
к реальной БД (db/models/thread_state.py) и таксономии промптов шагов
(prompts/intents/new_booking/steps/). Ссылки на *_v2 примеры. На v3
поставлена шапка «устарело».
- 4 примера переписаны как *_v2: реальные current_intent_code/
current_step_code/slots_json, реальные allowed_next без двойных переходов,
реальная таксономия слотов name/reason/specialist/preferred_time/confirmed.
Удалены вымышленные CRM tool calls и слоты, которых нет в коде.
- static/example.html — параметризованная страница с навигацией между
4 примерами; роут GET /api/docs/examples/{name} в main.py отдаёт
markdown без дублирования файлов.
- Редактирование документов в Отладке: GET/PUT /documents/{id}/raw,
textarea с переразметкой и обновлением Chroma при сохранении.
Спринт 7, часть A — мульти-RAG через подписку ветка↔документы:
- Миграция: таблица intent_documents (M:N), модель IntentDocument,
индекс по document_id для обратного поиска.
- API: GET/PUT /intents/{code}/documents и GET/PUT /documents/{id}/intents
с PUT-семантикой «полный список», атомарно. Сервис
services/intent_document_service.py.
- Retrieval-фильтр в chat_service: подтягивает document_ids активной
ветки и передаёт в vectorstore.query(). Дефолт пустой подписки —
document_ids=[] (= 0 чанков), не «вся коллекция»: пустая подписка
означает «ветка не настроена», подмешивать случайное хуже, чем
ничего. vectorstore.query() различает None (нет фильтра) и [] (0).
- UI Настроек: блок «Документы базы знаний» в правом сайдбаре,
всегда видим независимо от вкладки, сортировка по имени, счётчик
«N из M», PUT при сохранении.
- UI Отладки: третья кнопка «привязка» рядом с «удалить» —
раскрывашка со списком веток (галочки), быстрая привязка прямо
на странице загрузки.
- Песочница: блок «Срез RAG» с подпиской/найдено, ворнинг при пустой
подписке. Поле rag_subscription в QueryResponse и ChatResponse.
- Системный промпт страницы Отладки переехал в обычную ветку _debug
(«Страница отладки»). Удалён prompts/system_prompt.md и логика
DEFAULT_SYSTEM_PROMPT в llm_client. routers/query.py подтягивает
активный конфиг ветки _debug и её подписки. Дефолт пустой подписки
для _debug — None (вся коллекция), не [] как для пациентских — чтобы
Отладка работала «из коробки». На странице Отладки info-bar показывает
активную версию и счётчик подписок, ссылка → Настройки.
- Тест-блок «Тест-вопрос» в центре Настроек: расширил /query
параметрами intent_code (default _debug), system_prompt (override
для теста черновика из textarea), disable_rag (для _router).
Редактор промпта обёрнут в <details open> — можно свернуть до
одной строки. Под ним — три колонки результата (RAG / промпт /
ответ). Для _router показывается подсказка про отсутствие RAG.
Документы:
- data/datasets/*.md — наработки по 6 веткам (рабочие материалы оператора).
- docs/BRANCH_MAP_AND_PROMPTS_v1.md, docs/OPTIMIZATION_CONVERSION_v1.md,
docs/guides/state_machine_and_slots.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
AR 15 M4
@@ -0,0 +1,129 @@
|
||||
# Машина состояний и слоты — на пальцах
|
||||
|
||||
Шпаргалка для настройщика мультиагента. Без жаргона: всё через примеры из реальной ветки `new_booking` (см. [`../architecture/GRAPH_ARCHITECTURE_v3.md`](../architecture/GRAPH_ARCHITECTURE_v3.md), раздел 3).
|
||||
|
||||
Терминология та же, что в архитектурном документе: при первом упоминании даётся русский термин и английский эквивалент в скобках, дальше — что удобнее по контексту.
|
||||
|
||||
---
|
||||
|
||||
## 1. Машина состояний (state machine) — это «карта разговора» внутри одной ветки
|
||||
|
||||
Когда роутер (router) определил намерение (intent) пациента и передал диалог в ветку (branch), внутри этой ветки начинается мини-сценарий. Если сценарий — линейный «спросил-ответил», промпт справится сам. Если шагов несколько и порядок важен — нужна **машина состояний**: явная карта того, на каком шаге (step) сейчас разговор и куда он может пойти дальше.
|
||||
|
||||
В нашем проекте каноничный пример — ветка `new_booking`, у неё шесть шагов:
|
||||
|
||||
```
|
||||
intro → qualify → present → offer_time → book → close
|
||||
│
|
||||
└─ guard: пациент-ребёнок → собрать законного представителя
|
||||
└─ guard: запрос конкретного врача → рукав «лист ожидания»
|
||||
```
|
||||
|
||||
**Шаг (step)** — это одна осмысленная задача в разговоре («квалифицировать пациента», «предложить время»). У шага должна быть одна цель и понятное условие, по которому можно идти дальше.
|
||||
|
||||
**Защитное условие (guard)** — это правило, которое блокирует обычный переход и уводит разговор в сторону до тех пор, пока не выполнено условие. Например, на `qualify` нельзя уйти в `present`, пока для ребёнка не собраны ФИО и телефон законного представителя — это юридическое требование.
|
||||
|
||||
### Что важно при настройке ветки
|
||||
|
||||
- У каждого шага должно быть **понятное имя** в `step` и **одна цель**.
|
||||
- Должно быть **условие выхода** (exit condition) — когда разговор уходит из этой ветки целиком (например, пациент упомянул операцию → handoff в `escalate_human` с `reason=surgery`). См. раздел 4 архитектурного документа.
|
||||
- Должен быть **финальный шаг** (у `new_booking` — `close`), иначе разговор «зависнет».
|
||||
- Все нелинейные ветвления оформлять через **условные переходы** (conditional transitions), а не через под-состояния — так проще тестировать.
|
||||
|
||||
---
|
||||
|
||||
## 2. Слоты (slots) — это «поля анкеты», которые заполняются по ходу разговора
|
||||
|
||||
Внутри шагов помощник собирает у пациента данные. Каждая такая «графа» — **слот**. Все слоты текущего треда хранятся в `thread_state.slots` (JSON-колонка).
|
||||
|
||||
Реальный фрагмент состояния треда (thread state) на середине записи:
|
||||
|
||||
```json
|
||||
{
|
||||
"intent": "new_booking",
|
||||
"step": "offer_time",
|
||||
"slots": {
|
||||
"patient_name": "Анна",
|
||||
"is_child": false,
|
||||
"service": "первичный ЛОР",
|
||||
"doctor": "Сушков М. Г.",
|
||||
"time_candidates": ["2026-04-24 10:00", "2026-04-24 15:00"],
|
||||
"time_chosen": null
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Помощник на каждом ходу видит: *«я на шаге `offer_time`, `time_candidates` заполнен, `time_chosen` пуст — значит следующая реплика должна получить выбор времени, а не представляться заново»*.
|
||||
|
||||
### Главные свойства слота
|
||||
|
||||
| Свойство | Что это | Пример |
|
||||
|----------|---------|--------|
|
||||
| Имя (`name`) | Идентификатор в `slots` | `time_chosen` |
|
||||
| Тип (`type`) | Что туда кладётся | дата, строка, булево, список |
|
||||
| Вопрос (`prompt`) | Что говорит помощник, если слот пуст | «Подскажите, какое время удобнее — утром или вечером?» |
|
||||
| Проверка (`validation`) | Когда значение считается валидным | `time_chosen ∈ time_candidates` |
|
||||
| Обязательность | Можно ли уйти с шага без слота | `time_chosen` — да, `is_child` — да, `insurance` — нет |
|
||||
| Источник | Откуда модель может взять значение | реплика пациента, инструмент `crm.get_slots`, RAG-срез |
|
||||
|
||||
---
|
||||
|
||||
## 3. Как состояния и слоты работают вместе
|
||||
|
||||
Простыми словами:
|
||||
|
||||
> **Шаг** говорит, *о чём сейчас разговор внутри ветки*.
|
||||
> **Слоты** говорят, *что именно должно быть собрано к концу шага*.
|
||||
|
||||
Связка работает через **структурированный ответ** (structured output) модели:
|
||||
|
||||
```json
|
||||
{
|
||||
"reply": "Записала вас на четверг, 10:00...",
|
||||
"state_after": "close",
|
||||
"slots_updated": { "time_chosen": "2026-04-24 10:00" }
|
||||
}
|
||||
```
|
||||
|
||||
Код-валидатор (см. 3.3 архитектурного документа):
|
||||
|
||||
1. Проверяет, что переход `offer_time → close` легален.
|
||||
2. Применяет `slots_updated` к `thread_state`.
|
||||
3. Если модель вернула несуществующее `state_after` — состояние не меняется, в лог пишется предупреждение.
|
||||
|
||||
Модель рассуждает содержательно, код защищает механически. Поэтому при настройке ветки **списка шагов и таблицы легальных переходов между ними достаточно**, чтобы прикрутить валидатор — отдельной логики не нужно.
|
||||
|
||||
---
|
||||
|
||||
## 4. Что делает настройщик мультиагента
|
||||
|
||||
1. **Описать карту шагов ветки.** Перечислить шаги, разрешённые переходы, финальный шаг и условия выхода (exit conditions). Если ветка простая (`reschedule`, `general_info`) — одного-двух шагов достаточно. Если сложная (`new_booking`) — выписать все шесть и guard'ы к ним.
|
||||
2. **Описать слоты на каждом шаге.** Какие обязательные, какие опциональные, какой тип, какой вопрос помощника, какая проверка. Помнить про **RAG-срезы по шагам** (см. 3.4 архитектурного документа): на разных шагах нужны разные куски базы знаний.
|
||||
3. **Прогнать сценарии вживую** на стенде. Минимум:
|
||||
- **happy path** — пациент сразу даёт всё (несколько слотов из одной фразы);
|
||||
- **по кусочкам** — пациент отвечает на каждый вопрос отдельно;
|
||||
- **боковой вопрос** — посреди записи пациент спрашивает про цену/адрес → должна сработать **мягкая вставка** (soft insertion), `step` не меняется (см. 4.2);
|
||||
- **смена темы** — пациент посреди записи говорит «нет, я хочу перенести существующую» → должен сработать **жёсткий переход** (hard handoff) в `reschedule`;
|
||||
- **guard** — для `new_booking`: пациент-ребёнок (см. `../examples/03_child_patient_guard.md`);
|
||||
- **отмена/перезапуск** — пациент говорит «отмени всё, начнём заново» → корректный сброс состояния.
|
||||
4. **Записать замечания** в формате: ветка → шаг → слот → что пошло не так → ожидаемое поведение. Это сильно ускоряет правки на стороне разработки и даёт готовый материал для регрессионных тестов.
|
||||
|
||||
---
|
||||
|
||||
## 5. Мини-словарь
|
||||
|
||||
- **Тред / сессия (thread / session)** — один разговор с одним пациентом от приветствия до закрытия.
|
||||
- **Намерение (intent)** — категория запроса, которую вернул роутер: `new_booking`, `reschedule`, `price_question`, `medical_question`, `general_info`, `escalate_human`.
|
||||
- **Ветка (branch)** — изолированный промпт, обслуживающий одно намерение.
|
||||
- **Шаг (step)** — текущая стадия разговора внутри ветки, поле `step` в `thread_state`.
|
||||
- **Переход (transition)** — правило перехода с шага на шаг; **условный переход** (conditional transition) — переход, зависящий от значения слота.
|
||||
- **Слот (slot)** — поле в `thread_state.slots`.
|
||||
- **Защитное условие (guard)** — правило, которое блокирует переход, пока не выполнено.
|
||||
- **Условие выхода (exit condition)** — правило выхода из ветки целиком (триггер handoff'а к роутеру).
|
||||
- **Мягкая вставка (soft insertion)** — короткий ответ на боковой вопрос без смены `step`.
|
||||
- **Жёсткий переход (hard handoff)** — выход из ветки с сохранением `suspended_intent` + `resumable_step` + `resumable_slots`.
|
||||
- **Структурированный ответ (structured output)** — JSON, который модель возвращает вместо чистого текста: `reply`, `state_after`, `slots_updated`.
|
||||
|
||||
---
|
||||
|
||||
*По любым неясностям — комментарий прямо в этом файле либо тикет с пометкой ветки и шага, дополним.*
|
||||
Reference in New Issue
Block a user