Помощник ИИ

Возможности

• Спросить о сети обычными словами: длина и состав сети, откуда питается потребитель, какие задвижки закрыть при порыве, что изменилось в сценарии, где повторные отказы.
• Начать с готового вопроса: четыре примера под приветствием окна отправляются щелчком.
• Видеть ход работы: каждый вызов инструмента — строка с названием, параметрами и временем; ошибка шага — красным под строкой.
• Видеть найденное на карте: участки и узлы из ответов инструментов подсвечиваются сразу после ответа; «Оставить на карте» закрывает окно и оставляет подсветку.
• Продолжить беседу уточняющим вопросом: помощник помнит прежние вопросы и ответы этого окна. «Новая беседа» начинает с чистого листа и снимает подсветку.
• Остановить долгий ответ кнопкой «Остановить».

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

Кто отвечает. Вопрос уходит на сервер ТГИД, сервер — в модель Claude. Модель сама решает, какие инструменты вызвать, а выполняет их сервер — тем же набором, что у MCP-сервера: поиск объектов, выборка по условиям, трассировка, локализация аварии, запросы по сети, анализ режима, сводка по теме, износ, похожие аварии, места повторных отказов, качество данных, список расчётов и сценариев, сравнение сценария с основой, запуск расчёта. Запросы к базе пишет не модель, а код ТГИД.

Права — ваши. Инструменты выполняются с правами того, кто спрашивает. Нет права — шаг завершается ошибкой «Нет права «…»», и модель отвечает по тому, что удалось собрать. Персональные данные в ответах инструментов закрываются, если у вас нет права «Персональные данные потребителей полностью». Исходные данные помощник не меняет. Единственный инструмент с последствиями — запуск гидравлического расчёта: он пишет только результаты расчёта.

Пределы одного вопроса (ai/assistant.py):

Что	Предел
Вопрос	4000 символов
Прежняя беседа	20 реплик, каждая до 8000 символов; всё вместе — до AI_MAX_INPUT_CHARS (60 000 символов)
Обращений к модели	12; последнее — без инструментов, только ответ
Время	300 с, дальше модель отвечает по собранному
Ответ инструмента в модель	30 000 символов, хвост обрезается с пометкой «сузьте запрос»
Подсветка на карте	до 3000 участков и 3000 узлов
Вопросов	30 за 10 минут на пользователя
Вызовов инструментов	60 в минуту на пользователя (общий счётчик с MCP), запуск расчёта — 5 за 10 минут

Поток ответа. Сервер присылает события по мере работы: «шаг начат», «шаг выполнен» (время, ошибка), ответ. Ответ — абзацы и строки списка, жирный выделяется; HTML от модели не показывается. Под ответом — сколько объектов подсвечено, время ответа и число вызовов инструментов.

Подсветка — это ответы инструментов, а не итог. На карту попадают участки и узлы, которые инструменты вернули списком. Если модель попросила у выборки одну строку, чтобы узнать только количество, на карте будет одна линия, хотя в тексте — тысячи (см. пример).

Беседу сервер не хранит. Окно отправляет с новым вопросом прежние пары «вопрос — ответ» текстом, без результатов инструментов. Вопросы, оборванные ошибкой или остановкой, в беседу не попадают. С вопросом уходят номера фрагментов, открытых на карте (до 50), — модель берёт их, если вы не назвали фрагмент.

Язык. Запрос уходит с языком интерфейса. В английском и казахском интерфейсе модель отвечает на этом языке (или на языке вопроса), названия шагов и тексты ошибок переводит сервер. Имена объектов остаются как в базе.

Учёт расходов. Каждый вопрос — одна запись «AI» в журнале действий (tool=assistant): модель, токены всех обращений, число вызовов инструментов, код ошибки. Каждый вызов инструмента — своя запись с путём /ai/assistant/<инструмент>.

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

• Право «Запуск расчётов». Без него пункта «Помощник ИИ» нет в «Инструментах».
• Помощник ИИ включён на сервере: флаг и ключ модели. Если выключен, окно открывается с пояснением, поле вопроса неактивно.
• Для ответов о режиме — выполненные расчёты фрагментов; для похожих аварий и повторных отказов — журнал нарушений с точками на карте.

Шаги

1. Откройте «Инструменты» и наберите в поиске «Помощник ИИ» — пункт выделен рамкой.

   

2. Нажмите пункт — откроется окно.

   

3. Введите вопрос обычными словами, например «Какие источники питают участок 133? Покажи их на карте». Enter — отправить, Shift+Enter — новая строка.

   

4. Помощник покажет, какими инструментами он пользовался (здесь — трассировка сети), даст ответ и подсветит найденное на карте. «Оставить на карте» закрывает окно и оставляет подсветку; «Новая беседа» начинает разговор заново.

   

Примеры

Длина сети и крупные трубы (копия Алматы, фрагмент 74, модель claude-sonnet-5-5). Вопрос — пример из окна: «Какая длина сети и сколько участков Ду 500 и больше в открытых фрагментах?».

1. Шаг «Запросы по сети» (query: length, 360 мс).
2. Шаг «Выборка объектов по условиям» (Ду ≥ 500, limit: 1, 281 мс).
3. Ответ за 6,2 с: длина сети 394,8 км по двум трубам — 197,3 км подачи и 197,6 км обратки; участков Ду 500 и больше 2068, их длина по паспорту 245,6 км.

Числа совпадают с окном «Выборка по условиям» (Ду ≥ 500, фрагмент 74: «Найдено: 2 068 … длина по паспорту 245,61 км») и с инструментом длины сети. Под ответом — «Найдено на карте: 1 участок»: модели было нужно только количество, и выборка вернула одну строку. Расход на вопрос: 887 входных токенов, 8414 — из кеша, 356 — ответ.

Источники участка (копия Алматы, снимок шага 4). «Какие источники питают участок 133? Покажи их на карте» — один шаг «Трассировка сети» (вверх по потоку от участка 133, 8 с) и ответ: три источника — АТЭЦ1, АТЭЦ2 и НСС 18, путь к ним — 873 участка и 830 узлов, все подсвечены.

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

• «Помощник выключен на сервере или нет права «Запуск расчётов»…» — поле вопроса неактивно; обратитесь к администратору.
• «Не больше 30 вопросов за 10 минут — подождите» — лимит частоты; «Беседа слишком длинная — начните новую» — нажмите «Новая беседа».
• «Помощник выключен на сервере или нет права «Запуск расчётов»…» в окне — одно из двух; поле вопроса неактивно.
• «Помощник ИИ выключен на сервере — обратитесь к администратору.» — ИИ выключили на сервере (флаг или ключ модели), пока окно было открыто; обновите страницу.
• «Не больше 30 вопросов за 10 минут — подождите» — предел вопросов на пользователя.
• «Беседа слишком длинная — начните новую» — прежняя беседа больше 60 000 символов; нажмите «Новая беседа».
• «Превышен лимит запросов к ИИ, повторите позже», «Нет связи с Claude API», «Ключ Claude API отклонён — проверьте ANTHROPIC_API_KEY» — модель недоступна; данные ТГИД при этом работают.
• «Ответ ИИ не уместился в лимит токенов — сузьте вопрос» — назовите фрагмент, вид объектов, ограничьте список.
• «Модель отказалась отвечать на этот запрос» — переформулируйте вопрос о сети.
• «Ответ оборвался — повторите вопрос» — поток прервался до ответа (обрыв связи, перезапуск сервера).
• «Остановлено» — вы нажали «Остановить»; вопрос не попадёт в беседу.
• «Не получилось сформулировать ответ — переформулируйте вопрос.» — модель не дала текста.
• Красная строка под шагом («Нет права «…»», «Слишком часто: не больше 60 вызовов в минуту — подождите», «Неверные параметры: …») — один инструмент не выполнился; ответ строится без него.
• На карте меньше объектов, чем в ответе, — подсвечено только то, что инструменты вернули списком; полный список даст «Выборка по условиям».

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

• Включение: AI_ENABLED, ANTHROPIC_API_KEY; модель — AI_MODEL (по умолчанию в коде claude-opus-5-5), пределы — AI_MAX_INPUT_CHARS, AI_MAX_OUTPUT_TOKENS, AI_TIMEOUT_S.
• Расходы — журнал действий: действие «AI», путь /ai/assistant, в подробностях токены (input_tokens, output_tokens, cache_read_input_tokens, cache_creation_input_tokens). Вызовы инструментов — действие «MCP» с путём /ai/assistant/<инструмент>.
• Ответ идёт потоком: за nginx буферизация выключается заголовком X-Accel-Buffering: no, отдельной настройки не нужно.

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

• API: POST /api/v1/ai/assistant (question, history, fragment_ids), ответ — NDJSON (application/x-ndjson): события step, step_done, note, answer (text, model, tool_calls, tokens, highlight, geojson, duration_ms), error (code, message). Ошибки до потока: 422 (история), 413, 429, 503 ai_disabled. GET /api/v1/ai/status — включён ли ИИ и список инструментов.
• Сервер: routers/ai.py, ai/assistant.py (ручной цикл tool use, tool_choice: none на последнем шаге), промпт ai/prompts/assistant.md; инструменты — реестр tgid_mcp/tools.py (call_tool_raw, маскирование ПДн), учёт — ai/usage.py.
• Веб: components/AssistantDialog.vue, поток — services/api/assistant.ts (fetch + getReader, отмена через AbortController), разбор и история — utils/assistant.ts; доступность — authStore.canUseAi.
• Тесты: tests/utils/assistant.spec.ts; API — tests/test_ai_assistant.py; e2e — e2e/functions/ai.spec.ts (ответы модели подменены записанными).