Разбор протокола расчёта (ИИ)

Возможности

• Получить разбор протокола словами: общий вывод, причины по важности, что сделать по каждой.
• Перейти к объекту причины: значок объекта приближает карту и открывает карточку; кнопка «Исправить: …» ведёт туда, где правится причина (параметры расчёта, узел с заданным напором, температурный график, расчётная схема, карточка объекта).
• Увидеть таблицу регуляторов, не удержавших уставку: вид (РД, РР, РПД), задано и получено, отклонение, расход, «недобор напора» или «перебор напора».
• Получить совет к следующему запуску: какие флаги расчёта попробовать и зачем.
• Прочитать замечания к данным, которые модель заметила в протоколе.
• Открыть сохранённый разбор без повторного обращения к модели; построить разбор заново — кнопкой обновления.

Как это работает

Что считает код, а что модель. Протокол уже разобран сервером на записи: уровень, категория, объекты. Таблицу регуляторов код строит сам из строк «Задано … м, получено … м, расход … т/ч»: отклонение = задано − получено; плюс — недобор напора, минус — перебор. Модель получает сводку по категориям и пишет причины, действия и советы.

Что уходит в модель (ai/calc_protocol.py): по каждой категории — до 8 сообщений целиком (каждое до 400 символов, до 4 объектов), остальные — счётчиком «и ещё N сообщ.». Флаги для следующего запуска модель выбирает только из списка: -Tn, -iter, -no_kv, -rd_old, -rr_old, -ok_old, -tg, -leto, -dross_yes, -mag_fragment. Объекты в ответе сверяются с протоколом: объект, которого в протоколе нет, отбрасывается.

Протокол без ошибок и предупреждений модель не вызывает: ответ сразу — «В протоколе нет ошибок и предупреждений — расчёт прошёл без замечаний».

Кеш. Разбор сохраняется в первой записи протокола (calculation_protocol.ai_summary) отдельно для русского, английского и казахского. Повторное «Объяснить» на том же языке отвечает из кеша мгновенно — в заголовке панели пометка «из кеша». Кнопка обновления спрашивает модель заново и перезаписывает разбор этого языка. Расчёт по списку объясняется одним разбором на все фрагменты (общий номер запроса).

Язык. Разбор пишется на языке интерфейса. Подписи объектов, коды и флаги остаются как в протоколе. Состояние регулятора окно подписывает само по знаку отклонения.

Что нужно для работы

• Протокол с записями: последний расчёт сеанса или сохранённый из «Истории».
• Право «Запуск расчётов» и помощник ИИ, включённый на сервере. Без них кнопки «Объяснить» нет, протокол работает как обычно.

Шаги

1. Нажмите «Протокол» в верхней строке — откроется протокол последнего расчёта.

   

2. Нажмите «Объяснить». Кнопка есть, когда в протоколе есть записи и включён ИИ.

   

3. Через несколько секунд появится разбор: причины по важности и ссылки на объекты. Ссылка показывает объект на карте и открывает карточку. Разбор запоминается: повторное открытие того же протокола на том же языке ответ не пересчитывает; кнопка обновления строит разбор заново.

   

Примеры

Сценарий «Перспектива 2035» (копия Алматы, протокол 15, расчёт 715). Разбор на трёх языках уже в кеше: ответ сервера — за 0,08 с, пометка «из кеша».

• Вывод: расчёт завершился со статусом success, но результат ненадёжен — 2 ошибки и 12 предупреждений.
• 5 причин, первые — «Два узла с заданным напором в одной подсети» (кнопка «Исправить» ведёт к узлу с заданным напором) и неуточнённые коды РС у источников АТЭЦ1 и АТЭЦ2.
• Регуляторов с отклонением — 4. Например, РД «(6-8 УР2ЧАП) М2 1КЗ-22А О - М2 1КЗ-22Б О»: задано 59,0 м, получено 51,19 м, отклонение 7,81 м, расход 0,16 т/ч — недобор напора.
• Совет к следующему запуску: -rd_old — сравнить со старым алгоритмом регуляторов, если отклонения останутся после исправления узлов.

Если не получается

• «Помощник ИИ не ответил: …» — модель недоступна (лимит запросов, нет связи, ИИ выключен); протокол остаётся доступным без разбора.
• Кнопки «Объяснить» нет — протокол пуст (сначала выполните расчёт) или ИИ выключен.
• «Помощник ИИ не ответил: Ошибка на сервере: …» — после двоеточия причина от сервера: «Превышен лимит запросов к ИИ, повторите позже», «Нет связи с Claude API», «Ошибка Claude API (…)», «Ответ ИИ не уместился в лимит токенов». ИИ выключен на сервере — «Помощник ИИ не ответил: Помощник ИИ выключен на сервере — обратитесь к администратору.»
• «Запрос к ИИ слишком длинный (… символов, предел …)» — протокол огромный; разбирайте расчёты фрагментов по отдельности.
• Пометка «из кеша», а данные уже исправлены — нажмите кнопку обновления: она спросит модель заново.

Для администратора

• Флаги: AI_ENABLED, ANTHROPIC_API_KEY, AI_MODEL, AI_MAX_INPUT_CHARS, AI_MAX_OUTPUT_TOKENS, AI_TIMEOUT_S. Разбор протокола идёт с самым высоким уровнем рассуждения (effort high) — это самый дорогой из инструментов ИИ; кеш снимает повторные расходы.
• Кеш — колонка calculation_protocol.ai_summary (и ai_summary_at); её добавляет сам API при обновлении схемы города. Без права на UPDATE разбор работает, но не кешируется.
• Каждый вызов модели — запись «AI» в журнале действий (tool=calc_protocol, токены, номера протоколов).

Для разработчика

• API: POST /api/v1/ai/calc-protocol/explain (protocol_id, calculation_id или request_id; refresh) → regulators, explanation (summary, root_causes, regulators_note, next_run, data_quality), cached, locale.
• Сервер: routers/ai.py, ai/calc_protocol.py (regulators_from_entries, build_user_input, cached_answer, merge_cache), промпт ai/prompts/calc_protocol.md.
• Веб: components/CalculationProtocol.vue (explainWithAi), components/ai/AiAnswerPanel.vue, services/aiService.ts.
• Тесты: tests/components/AiAnswerPanel.spec.ts, tests/services/aiService.spec.ts; API — tests/test_ai_calc_protocol.py; e2e — e2e/functions/ai.spec.ts.