AI-ассистент

AI-ассистент — встроенный в веб-интерфейс чат, который помогает разобраться в состоянии кластера, ресурсах и документации. Он опционален и включается наличием Kubernetes-секрета assistant в неймспейсе d8-console.

Экспериментальная функция. Ассистент передаёт данные из кластера (манифесты ресурсов, логи, очередь Deckhouse и т. п.) в указанную вами LLM. Подключайте только те модели и провайдеров, которым вы доверяете эти данные.

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

• Сервис ассистента и его MCP-сервер деплоятся только при наличии секрета assistant в неймспейсе d8-console.
• Креды LLM ассистент читает из этого же секрета и общается с моделью по OpenAI-совместимому API (/v1/chat/completions, streaming).
• Кнопка чата (✨) появляется в верхней панели, когда ассистент включён, либо когда у вас есть права создавать и изменять секреты в неймспейсе d8-console (тогда вместо чата открывается форма настройки).

Endpoint модели должен быть OpenAI-совместимым и поддерживать tool/function calling — ассистент вызывает инструменты (работа с кластером, поиск по документации) через function calling.

Настройка через интерфейс

Откройте чат кнопкой ✨ и заполните форму (или нажмите шестерёнку «Настройки ассистента», если чат уже настроен):

• Адрес API (base URL) — базовый URL OpenAI-совместимого API, включая суффикс версии (обычно /v1).
• Модель — имя модели, как его ожидает endpoint (например, gpt-4o).
• API-ключ — ключ/токен авторизации. Для модели без авторизации укажите любую непустую строку. В режиме редактирования можно оставить поле пустым — текущий ключ сохранится.
• Лимит токенов — лимит на ответ модели (max_completion_tokens).
• Размер контекста (токены) — полный размер контекстного окна модели; нужен для индикатора расхода токенов. Можно оставить пустым.
• Бюджет контекста (токены) — порог, при превышении которого старый вывод инструментов обрезается, чтобы не упереться в лимит модели. 0 отключает.

Параметры сохраняются в секрет; передеплой не требуется при изменении уже существующего секрета.

Изменения в кластере

По умолчанию ассистент работает только на чтение: просматривает ресурсы, логи, документацию, очередь Deckhouse и т. п. Создание, изменение и удаление ресурсов Kubernetes отключены.

Под полем ввода в чате есть переключатель «Разрешить изменения». Если включить его перед отправкой запроса, ассистент сможет создавать, изменять и удалять ресурсы в кластере. Запрет и разрешение проверяются на сервере, а не только в подсказке модели.

Права доступа. Все операции ассистента в кластере выполняются от имени текущего пользователя — с тем же токеном сессии, что и остальные запросы Console. Ассистент не получает дополнительных привилегий: если у вас нет права создать или изменить ресурс в интерфейсе, ассистент тоже не сможет это сделать.

При включённых изменениях ассистент сначала выполняет пробный запуск (dry run) и просит явного подтверждения перед реальным применением.

Схема секрета assistant

Тип секрета — Opaque. Ключи:

Пример: внешняя модель (OpenAI GPT-4o)

kubectl -n d8-console create secret generic assistant \
  --from-literal=api_key='sk-proj-...' \
  --from-literal=base_url='https://api.openai.com/v1' \
  --from-literal=model='gpt-4o' \
  --from-literal=context_window='128000'

Внешний endpoint должен быть доступен из пода ассистента (egress в интернет).

Пример: внутренняя модель в кластере

Если в кластере развёрнут OpenAI-совместимый сервинг (vLLM, Ollama и т. п.), укажите его in-cluster Service URL:

kubectl -n d8-console create secret generic assistant \
  --from-literal=api_key='not-needed' \
  --from-literal=base_url='http://<service>.<model-namespace>.svc.cluster.local:8000/v1' \
  --from-literal=model='<served-model-name>'

• model — имя модели так, как его отдаёт сервинг (для vLLM — --served-model-name).
• api_key — если сервинг не требует авторизации, всё равно укажите любую непустую строку.

Управление размером контекста

История диалога живёт на стороне браузера и целиком отправляется в модель на каждый запрос. Инструменты работы с кластером (например, список ресурсов) могут возвращать очень объёмные данные, которые накапливаются в контексте и быстро упираются в лимит контекстного окна модели (ошибка вида 400 … maximum context length). Чтобы этого избежать, ассистент применяет несколько оптимизаций.

Слимминг вывода Kubernetes

Из результатов k8s_list_resources и k8s_get_resource удаляются самые объёмные и малополезные для модели поля:

• metadata.managedFields — служебная история server-side apply;
• аннотация kubectl.kubernetes.io/last-applied-configuration — дубликат манифеста.

Полезные spec/status и остальные метаданные сохраняются. Если ответ не является объектом Kubernetes, он передаётся без изменений.

Потолок на один результат инструмента

Любой результат инструмента обрезается примерно до 50 000 символов. В конце добавляется пометка об усечении с подсказкой сузить запрос фильтрами (namespace / label_selector / field_selector / limit), чтобы модель сама переспросила более точечно.

Страж контекста (max_context_tokens)

Перед каждым обращением к модели ассистент оценивает суммарный размер промпта. Если он превышает max_context_tokens (по умолчанию 300000), старый вывод инструментов заменяется заглушкой — начиная с самых ранних, при этом результаты текущего шага диалога сохраняются. Так контекст сжимается без потери последнего полезного результата.

Страж включён по умолчанию; задайте max_context_tokens: 0, чтобы отключить его (например, если модель сама умеет обрезать контекст).

Индикатор расхода токенов

После каждого раунда модель сообщает фактический расход токенов. Если задан context_window (например, 128000 для gpt-4o), над полем ввода появляется тонкая шкала «использовано / доступно» с цветовой индикацией (зелёная → жёлтая → красная) и подсказкой по наведении. Без context_window показывается только счётчик использованных токенов.