AI-ассистент

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

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

• Сервис ассистента и его MCP-сервер разворачиваются один раз на инсталляцию Deckhouse Commander (неймспейс d8-commander) — только при наличии секрета assistant.
• Учётные данные LLM ассистент читает из этого же секрета и общается с моделью по OpenAI-совместимому API (/v1/chat/completions, streaming).
• Кнопка чата (✨) появляется в верхней панели, когда ассистент включён.
• На кнопке — индикатор связи с моделью: синий — соединение есть, красный — модель недоступна. В подсказке к кнопке указывается причина (например, ошибка доступа / API-ключ, сеть, TLS).

Контекст рабочего пространства и кластера

• Ассистент всегда знает, в каком рабочем пространстве вы находитесь, и какой кластер выбран, если открыта страница кластера. Он использует это как цель по умолчанию для запросов к кластеру, поэтому в типичном случае не нужно называть кластер явно.
• Он умеет получать список кластеров в рабочем пространстве (по умолчанию — в текущем).
• Помимо этого ассистент умеет заходить в подчинённые кластеры рабочего пространства и работать там — читать и, если разрешено, изменять ресурсы — по тем же правилам «только чтение / разрешить изменения», что описаны ниже.

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

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

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

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

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

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

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

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

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

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

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

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

$ d8 k -n d8-commander 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'

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

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

$ d8 k -n d8-commander 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 — если сервис инференса не требует авторизации, всё равно укажите любую непустую строку.
• ca_bundle — для HTTPS-сервиса инференса с внутренним CA добавьте цепочку CA, например через --from-file=ca_bundle=./model-ca.pem.

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

История диалога хранится в браузере и целиком отправляется в модель на каждый запрос. Инструменты работы с кластером (например, список ресурсов) могут возвращать очень объёмные данные, которые накапливаются в контексте и быстро упираются в лимит контекстного окна модели (ошибка вида 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 показывается только счётчик использованных токенов.