# AI-ассистент

> ИИ-ассистент SecureBaseline Cloud - диагностика CIS-сканирования через YandexGPT, OpenAI, Anthropic, AWS Bedrock или Google Vertex AI

Source: https://opennix.org/docs/haas/ai-assistant/


## Обзор

AI-ассистент использует LLM-провайдеры для интеллектуальной помощи по эталонным тестам CIS, сканированию соответствия и устранению неполадок харденинга. SecureBaseline Cloud поддерживает 7 провайдеров и любой OpenAI-совместимый эндпоинт.

## Поддерживаемые провайдеры

| Провайдер | Протокол | Аутентификация | Применение |
|-----------|----------|----------------|------------|
| YandexGPT | OpenAI-совместимый | API-ключ или IAM-токен + ID каталога | Развертывания в Yandex Cloud |
| OpenAI | OpenAI API | API-ключ | GPT-4o, GPT-4-turbo |
| Azure OpenAI | OpenAI-совместимый | API-ключ + URL эндпоинта | Корпоративные развертывания Azure |
| Anthropic | Messages API | API-ключ | Claude Sonnet, Opus |
| AWS Bedrock | Converse API (SigV4) | ACCESS_KEY_ID:SECRET_ACCESS_KEY или IAM Role | Развертывания в AWS |
| Google Vertex AI | Express Mode или Full Mode | API-ключ (Express) или OAuth2 (Full) | Развертывания в GCP, Gemini |
| Custom | OpenAI-совместимый | API-ключ (опционально) | Ollama, Mistral, vLLM, LiteLLM |

## Навигация

**Меню**: AI Tools > LLM Settings

## Разделы страницы

Страница LLM Settings имеет две вкладки:

### Вкладка Configs

Управление конфигурациями LLM.

| Элемент | Описание |
|---------|----------|
| Add Config | Создать новую конфигурацию LLM |
| Таблица конфигураций | Список всех конфигураций с действиями |

### Вкладка Usage

Статистика использования:
- **Total Requests** - количество вызовов AI API
- **Input Tokens** - общее количество отправленных токенов
- **Output Tokens** - общее количество полученных токенов
- **Разбивка по провайдерам** - таблица с запросами и токенами по провайдеру/модели

## Управление конфигурациями

### Столбцы таблицы конфигураций

| Столбец | Описание |
|---------|----------|
| Name | Название конфигурации с тегом Default |
| Provider | Провайдер LLM (цветовая метка) |
| Model | Название модели |
| Default Config | Переключатель для установки/снятия конфигурации по умолчанию |
| Auth | Индикаторы наличия API Key и/или IAM Token |
| Status | Active (зеленый) или Inactive (серый) |
| Actions | Кнопки Test, Edit, Delete |

### Добавление конфигурации

1. Нажмите **Add Config**
2. Выберите провайдера - поля формы меняются в зависимости от выбора
3. Заполните обязательные поля (см. разделы по провайдерам ниже)
4. Нажмите **Test** для проверки подключения перед сохранением
5. Нажмите **Create**

### Общие поля (все провайдеры)

| Поле | Описание | Обязательно |
|------|----------|-------------|
| Name | Название конфигурации (напр., "Production Claude") | Да |
| Provider | Провайдер LLM из выпадающего списка | Да |
| Model | Название модели (вводится вручную) | Да |
| Temperature | 0 (детерминированный) до 1 (креативный), по умолчанию 0.3 | Нет |
| Max Tokens | Максимальная длина ответа, 100-8000, по умолчанию 2000 | Нет |
| Active | Включить/выключить конфигурацию | Нет |
| Default | Установить как конфигурацию по умолчанию | Нет |

### Поля для каждого провайдера

#### YandexGPT

| Поле | Описание | Обязательно |
|------|----------|-------------|
| Yandex Cloud Folder ID | ID каталога, где включен YandexGPT | Да |
| API Key | API-ключ Yandex Cloud | Нет* |
| IAM Token | Альтернатива API-ключу (истекает через 12ч) | Нет* |

*Необходим либо API Key, либо IAM Token. Модели: `yandexgpt-5-lite`, `yandexgpt-5`.

#### OpenAI

| Поле | Описание | Обязательно |
|------|----------|-------------|
| API Key | API-ключ OpenAI (sk-...) | Да |
| Base URL | Пользовательский эндпоинт (по умолчанию: api.openai.com) | Нет |

Модели: `gpt-4o`, `gpt-4-turbo`, `gpt-3.5-turbo`.

#### Azure OpenAI

| Поле | Описание | Обязательно |
|------|----------|-------------|
| Base URL | Эндпоинт ресурса Azure (https://your-resource.openai.azure.com) | Да |
| API Key | API-ключ Azure OpenAI | Да |

Модели: название вашей развернутой модели.

#### Anthropic

| Поле | Описание | Обязательно |
|------|----------|-------------|
| API Key | API-ключ Anthropic (sk-ant-...) | Да |

Модели: `claude-sonnet-4-20250514`, `claude-opus-4-20250514`, `claude-haiku-4-5-20251001`.

#### AWS Bedrock

| Поле | Описание | Обязательно |
|------|----------|-------------|
| AWS Region | Регион, где включен Bedrock (напр., us-east-1) | Да |
| AWS Credentials | ACCESS_KEY_ID:SECRET_ACCESS_KEY (через двоеточие) | Нет |

Оставьте учетные данные пустыми для использования IAM Role на EC2. Модели: `us.anthropic.claude-sonnet-4-5-20250929-v1:0`, `amazon.titan-text-premier-v1:0`.

#### Google Vertex AI

Два режима:

**Express Mode** (рекомендуется для Gemini):
- Оставьте Project ID:Region пустым
- Введите API-ключ в поле Access Token
- Проект и регион не нужны

**Full Mode** (для Claude на Vertex):
- Введите `project-id:region` в поле Project ID:Region
- Введите OAuth2 токен в поле Access Token

| Поле | Описание | Обязательно |
|------|----------|-------------|
| Project ID:Region | GCP project:region для Full Mode (пусто для Express) | Нет |
| Access Token | API-ключ (Express) или OAuth2 токен (Full) | Нет |

Модели: `gemini-2.5-flash-lite`, `gemini-2.5-pro`, `claude-sonnet-4-5@20250929`.

#### Custom (OpenAI-совместимый)

Для self-hosted моделей: Ollama, Mistral, vLLM, LiteLLM, LocalAI.

| Поле | Описание | Обязательно |
|------|----------|-------------|
| Base URL | URL эндпоинта (напр., http://localhost:11434/v1) | Да |
| API Key | API-ключ, если требуется эндпоинтом | Нет |

Модели: зависят от вашего развертывания (напр., `llama3.1`, `mistral`, `codestral`).

### Редактирование конфигурации

1. Нажмите **Edit** на строке конфигурации
2. Измените поля - API-ключ/учетные данные можно оставить пустыми для сохранения текущего значения
3. Нажмите **Update**

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

### Тестирование конфигурации

Два способа тестирования:

**Из таблицы** (сохраненные конфигурации):
1. Нажмите **Test** на строке конфигурации
2. Использует сохраненные учетные данные

**Из формы** (перед сохранением):
1. Заполните форму конфигурации
2. Нажмите **Test** в форме
3. При редактировании без новых учетных данных тест использует сохраненные

Результат теста показывает:
- Текст ответа от LLM
- Количество входных/выходных токенов
- Длительность в миллисекундах
- Подробности ошибки при неудаче

### Конфигурация по умолчанию

Одна конфигурация должна быть отмечена как default. Она используется когда конкретная конфигурация не выбрана в чате или при вызове AI-функций с других страниц.

Если default не установлен:
- Появляется предупреждение: "No default config set!"
- Система использует любую активную конфигурацию
- В ответах AI включается предупреждение

Переключите **Default Config** в таблице для установки/снятия.

### Удаление конфигурации

1. Нажмите **Delete** на строке конфигурации
2. Подтвердите удаление - вся связанная история использования также удаляется

## Чат-интерфейс

### Начало разговора

1. Перейдите в **AI Tools > AI Assistant**
2. Опционально выберите конфигурацию из выпадающего списка
3. Введите вопрос в поле ввода
4. Нажмите Enter или **Send**

### Язык

AI-ассистент отвечает на языке, выбранном в интерфейсе (русский или английский), независимо от языка вашего вопроса.

### Возможности чата

- **Поддержка Markdown** - ответы AI форматируются с заголовками, списками и блоками кода
- **Выбор конфигурации** - выбор LLM-конфигурации для каждого разговора
- **Автопрокрутка** - чат прокручивается к новым сообщениям
- **Предупреждение о лимите токенов** - уведомление при достижении max tokens

### Примеры вопросов

- "Что такое правило CIS 1.1.1.1?"
- "Как исправить проблемы с SSH-конфигурацией?"
- "Какой профиль выбрать для веб-сервера на Ubuntu 24.04?"
- "В чем разница между Level 1 и Level 2?"
- "Почему харденинг может отключить мое приложение?"

## AI-функции на других страницах

### Объяснение правил (страница Compliance)

Когда LLM настроен, кнопка **Explain** появляется в результатах сканирования:

1. Просмотрите результаты завершенного сканирования
2. Нажмите **Explain** на строке правила
3. Модальное окно показывает объяснение от AI:
   - Что проверяет правило
   - Почему это важно для безопасности
   - Риски несоответствия
   - Как исправить простыми шагами

Объяснение генерируется на языке интерфейса (русский или английский).

### Диагностика ошибок (страница Jobs)

Когда задача харденинга завершается с ошибкой:

1. Перейдите на страницу Jobs
2. Нажмите **Diagnose with AI** на неудачной задаче
3. AI анализирует вывод Ansible и предоставляет:
   - Анализ корневой причины
   - Шаги исправления
   - Советы по предотвращению
   - Оценку критичности

## Безопасность учетных данных

Все API-ключи, IAM-токены и учетные данные шифруются при хранении с использованием AES-256-GCM. Они никогда не возвращаются в ответах API - отображается только булевый индикатор наличия.

## Лучшие практики

### Конфигурация

- Установите одну конфигурацию как **default**
- Используйте низкую temperature (0.3) для фактических ответов о CIS-правилах
- Используйте высокую temperature (0.7) для креативного устранения неполадок
- Установите разумный max_tokens (2000 - хорошее значение по умолчанию)

### Контроль расходов

- Отключите неиспользуемые конфигурации
- Мониторьте использование по провайдерам на вкладке Usage
- Используйте быстрые модели для рутинных запросов
- Очищайте чат для уменьшения длины контекста

### Self-hosted модели

Для изолированных или экономичных развертываний:
1. Разверните Ollama с моделью (напр., `ollama pull llama3.1`)
2. Создайте конфигурацию Custom с Base URL `http://ollama-host:11434/v1`
3. API-ключ не нужен для локального Ollama

## Устранение неполадок

### Нет ответа от AI

1. Проверьте, что конфигурация активна и установлена как default
2. Протестируйте конфигурацию кнопкой Test
3. Проверьте, что API-ключ действителен

### "Configure an LLM provider first"

Нет активной LLM-конфигурации:
1. Перейдите в LLM Settings
2. Создайте конфигурацию для вашего провайдера
3. Отметьте как Active и Default

### Тест конфигурации не проходит

1. Проверьте правильность API-ключа/учетных данных
2. Для Bedrock: убедитесь, что модель включена в вашем регионе AWS
3. Для Vertex AI Express: убедитесь, что API-ключ включен для Vertex AI API в GCP Console
4. Для Custom: проверьте доступность URL эндпоинта

### Неправильный язык ответов

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

## Инструкции по настройке провайдеров

### YandexGPT

1. Перейдите в Yandex Cloud Console > IAM > API Keys
2. Создайте новый API-ключ, скопируйте секрет
3. Получите ID каталога со страницы каталога
4. Создайте конфигурацию: Provider=YandexGPT, Model=yandexgpt-5-lite, Folder ID, API Key

### Anthropic

1. Перейдите на console.anthropic.com > API Keys
2. Создайте ключ, скопируйте его
3. Создайте конфигурацию: Provider=Anthropic, Model=claude-sonnet-4-20250514, API Key

### AWS Bedrock

1. Включите доступ к модели в AWS Console > Bedrock > Model access
2. Создайте IAM-пользователя с разрешением `bedrock:InvokeModel`
3. Создайте конфигурацию: Provider=AWS Bedrock, Region=us-east-1, Credentials=ACCESS_KEY:SECRET_KEY
4. Или оставьте учетные данные пустыми на EC2 с привязанной IAM Role

### Google Vertex AI (Express Mode)

1. Включите Vertex AI API в GCP Console
2. Создайте API-ключ на странице Credentials
3. Создайте конфигурацию: Provider=Google Vertex AI, Model=gemini-2.5-flash-lite, Access Token=ваш-api-ключ
4. Оставьте Project ID:Region пустым для Express Mode

### Ollama

**Локальная установка:**
1. Установите Ollama: `curl -fsSL https://ollama.com/install.sh | sh`
2. Скачайте модель: `ollama pull llama3.1`
3. Создайте конфигурацию: Provider=Custom, Model=llama3.1, Base URL=http://localhost:11434/v1

**Ollama Cloud:**
1. Получите API-ключ в вашем аккаунте Ollama Cloud
2. Создайте конфигурацию: Provider=Custom, Model=llama3.1, Base URL=https://ollama.com/v1, API Key=ваш-ключ

## Связанные разделы

- [Сканирование соответствия](/docs/haas/compliance-scanning/) - AI-объяснение правил в результатах сканирования
- [Настройки](/docs/haas/settings/) - общие настройки платформы
- [Устранение неполадок](/docs/haas/troubleshooting/) - диагностика платформы и инструмент must-gather