[English](https://hb3-accelerator.com/gitea/VC-HB3-Accelerator/Docs/src/branch/main/docs.en/back-docs/setup-ai-assistant.md) | **Русский**

# Инструкция по настройке AI Ассистента с векторным поиском

## 🤖 Полное руководство по запуску интеллектуального помощника

Этот документ описывает пошаговый процесс настройки AI ассистента для решения бизнес-задач через электронные таблицы и векторный поиск.

---

## 📚 Что вы настроите

После выполнения инструкции у вас будет:

✅ Работающий AI ассистент с локальной моделью (Ollama)  
✅ База знаний для ответов клиентам (FAQ)  
✅ Автоматизация работы с поставщиками  
✅ Система обучения персонала  
✅ Векторный поиск по вашим данным  
✅ Значительная экономия времени и ресурсов  

> 💡 **Экономический эффект**: См. [ИИ-агенты DLE](../ai-assistant.md) — архитектура, примеры агентов и расчёты экономии.  

---

## ⏱️ Время настройки

- **Быстрая настройка**: 20-30 минут (базовый FAQ)
- **Полная настройка**: 1-2 часа (все возможности)

---

## Шаг 1: Установка и запуск Ollama

### 1.1 Проверка статуса Ollama

1. Перейдите в **Настройки** → вкладка **Интеграции**
2. Найдите блок **"Ollama"** и нажмите **"Подробнее"**
3. Проверьте статус подключения:
   - ✅ **"Ollama is running"** — все готово, переходите к шагу 1.3
   - ❌ **"Ollama API not responding"** — переходите к шагу 1.2

### 1.2 Запуск Ollama (если не запущен)

Если Ollama не запущен, выполните в терминале:

```bash
# Для Docker (рекомендуется)
docker-compose up -d ollama

# Или локально
ollama serve
```

Обновите страницу и проверьте статус снова.

### 1.3 Установка модели для AI

1. В разделе **Ollama** нажмите **"Установить модель"**
2. Выберите модель:
   - **qwen2.5:7b** (рекомендуется) — для русского языка, 4.7 GB
   - **llama2:7b** — для английского, 3.8 GB
   - **mistral:7b** — универсальная, 4.1 GB
3. Нажмите **"Установить"**
4. Дождитесь завершения загрузки (5-10 минут в зависимости от скорости интернета)

> 💡 **Подсказка**: Модель скачивается один раз и хранится локально

### 1.4 Установка Embedding модели

1. В том же разделе найдите **"Установить Embedding модель"**
2. Выберите модель:
   - **mxbai-embed-large:latest** (рекомендуется) — 670 MB
   - **nomic-embed-text:latest** — альтернатива, 274 MB
3. Нажмите **"Установить"**

> ⚠️ **Важно**: Embedding модель нужна для векторного поиска (RAG)

---

## Шаг 2: Создание базы знаний (электронные таблицы)

### 2.1 Создание таблицы FAQ

1. Перейдите в **Таблицы** (в главном меню)
2. Нажмите **"+ Создать таблицу"**
3. Заполните:
   - **Название**: `FAQ - Часто задаваемые вопросы`
   - **Описание**: `База знаний для AI ассистента по работе с клиентами`
4. Нажмите **"Создать"**

### 2.2 Настройка столбцов таблицы

Добавьте следующие столбцы:

#### Столбец 1: Вопрос (обязательный для RAG)

1. Нажмите **"+ Добавить столбец"**
2. Заполните:
   - **Название**: `Вопрос`
   - **Тип**: `Текст`
   - **Назначение**: Выберите `Вопрос для AI` ⭐
3. Нажмите **"Сохранить"**

> ⚠️ **Критично**: Обязательно выберите назначение "Вопрос для AI" — это поле будет индексироваться для векторного поиска

#### Столбец 2: Ответ (обязательный для RAG)

1. Нажмите **"+ Добавить столбец"**
2. Заполните:
   - **Название**: `Ответ`
   - **Тип**: `Текст`
   - **Назначение**: Выберите `Ответ AI` ⭐
3. Нажмите **"Сохранить"**

#### Столбец 3: Продукт (опционально, для фильтрации)

1. Нажмите **"+ Добавить столбец"**
2. Заполните:
   - **Название**: `Продукт`
   - **Тип**: `Множественный выбор`
   - **Варианты**: `Базовый`, `Премиум`, `Корпоративный`
   - **Назначение**: Выберите `Фильтр по продукту`
3. Нажмите **"Сохранить"**

#### Столбец 4: Теги (опционально, для категоризации)

1. Нажмите **"+ Добавить столбец"**
2. Заполните:
   - **Название**: `Теги`
   - **Тип**: `Множественный выбор`
   - **Варианты**: `Оплата`, `Доставка`, `Возврат`, `Гарантия`, `Техподдержка`
   - **Назначение**: Выберите `Теги пользователя`
3. Нажмите **"Сохранить"**

#### Столбец 5: Приоритет (опционально)

1. Нажмите **"+ Добавить столбец"**
2. Заполните:
   - **Название**: `Приоритет`
   - **Тип**: `Число`
   - **Назначение**: Выберите `Приоритет`
3. Нажмите **"Сохранить"**

> 💡 **Подсказка**: Вопросы с более высоким приоритетом будут показываться AI первыми

### 2.3 Заполнение базы знаний

Добавьте типовые вопросы и ответы:

**Пример 1: Оплата**

| Вопрос | Ответ | Продукт | Теги | Приоритет |
|--------|-------|---------|------|-----------|
| Как оплатить заказ? | Мы принимаем оплату банковской картой, через PayPal, или банковским переводом. Выберите удобный способ при оформлении заказа. | Все | Оплата | 10 |
| Можно ли оплатить частями? | Да, для заказов от 50,000₽ доступна рассрочка на 3, 6 или 12 месяцев без переплаты. | Премиум, Корпоративный | Оплата | 8 |

**Пример 2: Доставка**

| Вопрос | Ответ | Продукт | Теги | Приоритет |
|--------|-------|---------|------|-----------|
| Сколько времени занимает доставка? | Стандартная доставка: 3-5 рабочих дней по России. Экспресс-доставка: 1-2 дня в крупных городах. | Все | Доставка | 10 |
| Сколько стоит доставка? | Бесплатная доставка при заказе от 5,000₽. Для заказов менее 5,000₽ стоимость доставки 300₽. | Все | Доставка | 9 |

**Пример 3: Возврат**

| Вопрос | Ответ | Продукт | Теги | Приоритет |
|--------|-------|---------|------|-----------|
| Как вернуть товар? | Возврат возможен в течение 14 дней с момента получения. Товар должен быть в оригинальной упаковке, с сохранением товарного вида. Свяжитесь с поддержкой для оформления возврата. | Все | Возврат | 10 |
| Когда вернут деньги? | Возврат денежных средств производится в течение 5-10 рабочих дней после получения товара на наш склад. | Все | Возврат | 8 |

> 💡 **Рекомендация**: Добавьте минимум 20-30 вопросов для качественной работы AI. Чем больше вопросов, тем точнее ответы!

### 2.4 Активация таблицы как источника для AI

1. В правом верхнем углу таблицы найдите **⚙️ Настройки таблицы**
2. Включите переключатель **"Использовать как источник для AI"** ✅
3. Нажмите **"Сохранить"**

> ✅ **Готово!** Таблица теперь индексируется для векторного поиска

---

## Шаг 3: Настройка AI провайдера (Ollama)

### 3.1 Открытие настроек Ollama

1. Перейдите в **Настройки** → **Интеграции**
2. Найдите блок **"Ollama"** и нажмите **"Подробнее"**

### 3.2 Проверка Base URL

1. Проверьте поле **Base URL**:
   - Для Docker: `http://ollama:11434` ✅
   - Для локального: `http://localhost:11434`
2. Если URL неверный, исправьте и нажмите **"Сохранить"**

### 3.3 Выбор модели

1. В поле **"Модель (LLM)"** выберите установленную модель:
   - `qwen2.5:7b` (рекомендуется для русского)
2. В поле **"Embeddings-модель"** выберите:
   - `mxbai-embed-large:latest`
3. Нажмите **"Сохранить"**

---

## Шаг 4: Настройка AI Ассистента

### 4.1 Открытие настроек ассистента

1. Перейдите в **Настройки** → **Интеграции**
2. Найдите блок **"ИИ-ассистент"** и нажмите **"Подробнее"**

### 4.2 Настройка системного промта

В поле **"Системный промт"** введите инструкции для AI:

**Базовый промт (для начала)**:

```
Вы — профессиональный ассистент службы поддержки компании.

Правила:
1. Отвечайте вежливо и профессионально
2. Используйте информацию из базы знаний
3. Если информации нет — предложите связаться с оператором
4. Отвечайте кратко и по существу
5. Всегда заканчивайте вопросом "Чем еще могу помочь?"
```

**Продвинутый промт (с персонализацией)**:

```
Вы — профессиональный ассистент службы поддержки компании "Название вашей компании".

О компании:
- Мы занимаемся [краткое описание бизнеса]
- Наши ценности: качество, надежность, клиентоориентированность

Стиль общения:
- Дружелюбный, но профессиональный
- Обращайтесь к клиенту на "Вы"
- Используйте эмодзи умеренно (1-2 на сообщение)

Правила ответа:
1. ОБЯЗАТЕЛЬНО: Отвечайте ТОЛЬКО на русском языке. Все вопросы и ответы должны быть на русском языке
2. Сначала ищите ответ в базе знаний (RAG)
3. Если нашли — отвечайте на основе найденной информации
4. Если не нашли — честно скажите и предложите помощь оператора
5. Не придумывайте информацию о ценах, сроках, условиях
6. При сложных вопросах предлагайте связаться с менеджером

Всегда заканчивайте: "Чем еще могу помочь? 😊"
```

### 4.3 Выбор моделей

1. **LLM-модель**: Выберите `qwen2.5:7b (ollama)`
2. **Embedding-модель**: Выберите `mxbai-embed-large:latest (ollama)`

> 💡 **Подсказка**: Модели автоматически подтянутся из настроек Ollama

> 📊 **Размер контекстного окна**: 
> - **Qwen2.5:7b**: Базовый контекст = **32,768 токенов** (~24,000 русских слов)
> - Всего данных, отправляемых в модель:
>   - Системный промпт: ~500-2000 символов (~300-1200 токенов)
>   - История диалога: до 20 сообщений (~100-500 токенов на сообщение = ~2000-10000 токенов)
>   - RAG контекст: ~500-2000 токенов (из найденных данных)
>   - Текущий вопрос: ~50-200 токенов
>   - **Итого**: примерно 3,000-15,000 токенов (запас достаточен)
> - Если нужен больший контекст → используйте Qwen3 с YaRN (до 131K токенов)

### 4.4 Выбор RAG-таблицы

1. В поле **"Выбранные RAG-таблицы"** выберите созданную таблицу:
   - `FAQ - Часто задаваемые вопросы`
2. Нажмите **"Сохранить"**

### 4.5 Настройка правил AI (Rules)

Создайте набор правил для управления поведением AI:

1. Нажмите кнопку **"Создать"** рядом с полем "Набор правил"
2. В модальном окне заполните:

**Название**: `Гибридный режим (RAG + генерация)`

**Описание**: `AI сначала ищет в базе знаний, если не находит — генерирует ответ`

**Правила (JSON)**:
```json
{
  "checkUserTags": true,
  "searchRagFirst": true,
  "generateIfNoRag": true,
  "temperature": 0.7,
  "maxTokens": 500
}
```

3. Нажмите **"Сохранить"**
4. Выберите созданное правило в выпадающем списке

> 💡 **Что означают параметры**:
> - `checkUserTags: true` — учитывать теги пользователя при поиске
> - `searchRagFirst: true` — сначала искать в базе знаний
> - `generateIfNoRag: true` — генерировать ответ, если ничего не найдено
> - `temperature: 0.7` — баланс между точностью и креативностью (0.0-1.0)
> - `maxTokens: 500` — максимальная длина ответа

### 4.6 Настройки RAG поиска

Разверните раздел **"🔍 Настройки RAG поиска"**:

**Базовые настройки:**
1. **Метод поиска**: Выберите `Гибридный поиск` (рекомендуется)
2. **Максимальное количество результатов**: `5`
3. **Порог релевантности**: `0.1` (от 0.01 до 1.0)

**Извлечение ключевых слов:**
1. ✅ **Включить извлечение ключевых слов**
2. **Минимальная длина слова**: `3`
3. **Максимальное количество ключевых слов**: `10`
4. ✅ **Удалять стоп-слова**

**Веса поиска (для гибридного):**
1. **Семантический поиск**: `70%` (точность)
2. **Поиск по ключевым словам**: `30%` (скорость)

**Дополнительные настройки:**
1. ✅ **Нечеткий поиск** (для опечаток)
2. ✅ **Стемминг слов** (находит разные формы слова)
3. ☐ **Поиск синонимов** (пока отключен)

### 4.7 Сохранение настроек

Нажмите кнопку **"Сохранить"** внизу формы.

---

## Шаг 5: Тестирование AI Ассистента

### 5.1 Использование встроенного тестера

1. На странице настроек AI ассистента прокрутите вниз до блока **"🔍 Мониторинг системы"**
2. В разделе **"🧠 Тест RAG-функциональности"**:
   - Убедитесь, что выбрана таблица `FAQ - Часто задаваемые вопросы`
   - Введите тестовый вопрос: `Как оплатить заказ?`
   - Нажмите **"Тестировать RAG"**
3. Наблюдайте за процессом:
   - 🔍 Ищем ответ в базе знаний... (векторный поиск)
   - 🤖 Генерируем ответ с помощью ИИ... (LLM генерация)
   - ✅ Готово!
4. Проверьте результат:
   - Должен отобразиться ответ из вашей таблицы
   - Score (оценка близости): чем ближе к 0, тем лучше

> 💡 **Хороший Score**: от -300 до 0 (ответ найден)  
> ⚠️ **Плохой Score**: больше 300 (ответ не найден, AI придумает свой)

### 5.2 Тестирование через Web Chat

1. Перейдите на главную страницу приложения
2. Найдите виджет **"💬 Чат с AI"** (обычно справа внизу)
3. Нажмите на виджет, чтобы открыть чат
4. Введите вопрос: `Сколько стоит доставка?`
5. Проверьте ответ AI

**Ожидаемый результат:**
```
🤖 AI Ассистент:
Бесплатная доставка при заказе от 5,000₽. 
Для заказов менее 5,000₽ стоимость доставки 300₽.

Чем еще могу помочь? 😊
```

### 5.3 Тестирование разных сценариев

Попробуйте задать различные вопросы:

**✅ Вопрос из базы знаний:**
```
Пользователь: "Как вернуть товар?"
AI: [Ответ из таблицы FAQ]
```

**⚠️ Вопрос НЕ из базы знаний:**
```
Пользователь: "Какая погода сегодня?"
AI: "Извините, я специализируюсь на вопросах о нашей компании и продуктах. 
     По вопросам погоды обратитесь к специализированным сервисам. 
     Чем еще могу помочь?"
```

**🎯 Вопрос с опечаткой:**
```
Пользователь: "Как аплатить заказ?" (опечатка)
AI: [Найдет правильный ответ благодаря нечеткому поиску]
```

---

## Шаг 6: Расширенные возможности (опционально)

### 6.1 Создание таблицы для работы с поставщиками

#### Структура таблицы "База поставщиков"

1. Создайте новую таблицу: `База поставщиков`
2. Добавьте столбцы:

| Столбец | Тип | Описание |
|---------|-----|----------|
| Название компании | Текст | Наименование поставщика |
| Категория товаров | Множественный выбор | Электроника, Мебель, Одежда, и т.д. |
| Контактное лицо | Текст | ФИО менеджера |
| Email | Текст | Электронная почта |
| Телефон | Текст | Контактный телефон |
| Цены | Текст | Прайс-лист (краткое описание) |
| Условия оплаты | Текст | Отсрочка, предоплата, и т.д. |
| Минимальный заказ | Число | Минимальная сумма заказа |
| Срок доставки | Текст | Сроки поставки |
| Рейтинг | Число | Оценка от 1 до 10 |
| Примечания | Текст | Дополнительная информация |

3. Активируйте как источник для AI
4. Заполните данными о ваших поставщиках

#### Промт для AI закупщика

Добавьте в системный промт:

```
ДОПОЛНИТЕЛЬНО - Работа с поставщиками:

Когда пользователь спрашивает о поставщиках:
1. Ищите в базе "База поставщиков"
2. Фильтруйте по категории товаров
3. Сортируйте по рейтингу и условиям
4. Предоставьте ТОП-3 рекомендации

Формат ответа:
🏆 TOP-3 поставщика по запросу "[категория]":

1. [Название] ⭐ [Рейтинг]/10
   📧 [Email] | 📞 [Телефон]
   💰 Условия: [Условия оплаты]
   🚚 Доставка: [Срок доставки]
   📦 Минимум: [Минимальный заказ]₽

2. ...
3. ...

Рекомендую связаться с [Название первого поставщика] — лучшие условия.
```

### 6.2 Создание таблицы для обучения персонала

#### Структура таблицы "База знаний для сотрудников"

1. Создайте новую таблицу: `База знаний для сотрудников`
2. Добавьте столбцы:

| Столбец | Тип | Описание |
|---------|-----|----------|
| Вопрос | Текст | Вопрос сотрудника (назначение: Вопрос для AI) |
| Ответ | Текст | Подробный ответ (назначение: Ответ AI) |
| Категория | Множественный выбор | Продажи, HR, Финансы, IT, Маркетинг |
| Отдел | Множественный выбор | Для какого отдела актуально |
| Сложность | Число | От 1 (простой) до 5 (сложный) |
| Инструкции | Текст | Пошаговые инструкции (если есть) |
| Ссылки | Текст | Ссылки на документы/видео |
| Дата обновления | Дата | Когда информация обновлялась |

3. Примеры вопросов:

**Категория "Продажи":**
- "Как оформить возврат клиенту?"
- "Какие скидки можно давать постоянным клиентам?"
- "Как работать с корпоративными клиентами?"

**Категория "HR":**
- "Как оформить отпуск?"
- "Куда обращаться по больничному?"
- "Как происходит адаптация новых сотрудников?"

**Категория "IT":**
- "Как получить доступ к корпоративной почте?"
- "Что делать при проблемах с VPN?"
- "Как создать заявку в техподдержку?"

### 6.3 Создание связей между таблицами

#### Пример: Связь "Клиенты" → "Заказы"

1. Создайте таблицу **"Клиенты"**:
   - Название, Email, Телефон, Статус (VIP/Обычный)

2. Создайте таблицу **"Заказы"**:
   - Номер заказа, Дата, Сумма

3. В таблице "Заказы" добавьте столбец:
   - **Название**: `Клиент`
   - **Тип**: `Связь (Relation)`
   - **Связанная таблица**: выберите `Клиенты`
   - **Показывать поле**: выберите `Название`

4. Добавьте еще один столбец в "Заказы":
   - **Название**: `Email клиента`
   - **Тип**: `Lookup (Подстановка)`
   - **Связь через**: выберите столбец `Клиент`
   - **Подставлять поле**: выберите `Email`

**Результат**: При выборе клиента автоматически подставится его Email!

#### Использование AI с связанными таблицами

AI автоматически понимает связи и может отвечать на вопросы:

```
Пользователь: "Покажи все заказы клиента Иванов"
AI: [Ищет в таблице Заказы, фильтрует по клиенту Иванов]
```

---

## Шаг 7: Интеграция с Telegram и Email (опционально)

### 7.1 Настройка Telegram бота

1. Перейдите в **Настройки** → **Интеграции** → **Telegram**
2. Создайте бота через [@BotFather](https://t.me/botfather) в Telegram:
   - Отправьте `/newbot`
   - Выберите имя и username бота
   - Скопируйте **Bot Token**
3. В настройках DLE введите:
   - **Bot Token**: вставьте токен от BotFather
   - **Bot Username**: username вашего бота (например, `@mycompany_bot`)
4. Нажмите **"Сохранить"**
5. В настройках AI ассистента выберите этот Telegram бот в поле **"Telegram-бот"**

**Результат**: AI будет отвечать на сообщения в Telegram!

### 7.2 Настройка Email интеграции

1. Перейдите в **Настройки** → **Интеграции** → **Email**
2. Заполните IMAP настройки (для получения писем):
   - **IMAP Host**: `imap.gmail.com` (для Gmail)
   - **IMAP Port**: `993`
   - **IMAP User**: ваш email
   - **IMAP Password**: пароль приложения (не основной пароль!)
3. Заполните SMTP настройки (для отправки писем):
   - **SMTP Host**: `smtp.gmail.com`
   - **SMTP Port**: `587`
   - **SMTP User**: ваш email
   - **SMTP Password**: пароль приложения
   - **From Email**: email для отправки
4. Нажмите **"Тест IMAP"** и **"Тест SMTP"** для проверки
5. Нажмите **"Сохранить"**
6. В настройках AI ассистента выберите этот Email в поле **"Email для связи"**

> ⚠️ **Важно для Gmail**: Создайте "Пароль приложения" в настройках безопасности Google

**Результат**: AI будет отвечать на входящие email автоматически!

---

## Шаг 8: Мониторинг и оптимизация

### 8.1 Проверка статуса сервисов

1. Перейдите в **Настройки** → **Интеграции** → **ИИ-ассистент**
2. Прокрутите вниз до **"🔍 Мониторинг системы"**
3. Нажмите **"🔄 Обновить статус"**
4. Проверьте статусы:
   - 🟢 **Backend**: должен быть "Работает"
   - 🟢 **Postgres**: должен быть "Работает"
   - 🟢 **Ollama**: должен показывать количество моделей
   - 🟢 **Vector Search**: должен быть "Работает"

> ⚠️ Если что-то красное (🔴) — см. раздел "Решение проблем" ниже

### 8.2 Анализ качества ответов

Регулярно проверяйте качество ответов AI:

1. **Score в тестере RAG**:
   - **-300 до 0** ✅ — отличное совпадение
   - **0 до 300** ⚠️ — среднее совпадение
   - **>300** ❌ — совпадение не найдено

2. **Если Score плохой**:
   - Добавьте больше похожих вопросов в таблицу
   - Используйте разные формулировки одного вопроса
   - Увеличьте порог релевантности (например, до 0.2)

### 8.3 Оптимизация настроек RAG

Экспериментируйте с настройками для улучшения результатов:

**Для более точных ответов:**
```
Метод поиска: Семантический
Порог релевантности: 0.05 (ниже = строже)
Веса: Семантический 100% / Ключевые слова 0%
```

**Для более быстрых ответов:**
```
Метод поиска: Поиск по ключевым словам
Максимальное количество результатов: 3
```

**Для баланса (рекомендуется):**
```
Метод поиска: Гибридный
Веса: Семантический 70% / Ключевые слова 30%
Порог релевантности: 0.1
```

---

## ✅ AI Ассистент готов к работе!

### Что у вас теперь есть

✅ **Локальный AI ассистент** без зависимости от облака  
✅ **База знаний FAQ** для ответов клиентам  
✅ **Векторный поиск** для точных ответов  
✅ **Настроенные правила** поведения AI  
✅ **Система мониторинга** для контроля качества  

### Экономический эффект

При правильной настройке AI ассистента вы получите:

✅ **Автоматизацию рутинных задач** - высвобождение времени для стратегии  
✅ **Повышение качества обслуживания** - AI работает 24/7 без усталости  
✅ **Снижение операционных расходов** - меньше персонала на рутинных задачах  
✅ **Ускорение принятия решений** - мгновенный доступ к информации  

> 💡 **Подробная информация**: См. [ИИ-агенты DLE](../ai-assistant.md#экономический-эффект) — архитектура, примеры агентов и расчёты экономии.

---

## 📚 Следующие шаги

### Расширьте возможности AI

1. **Добавьте больше таблиц**:
   - База знаний для партнеров
   - Инструкции для персонала
   - Каталог продуктов
   - База контактов

2. **Создайте правила для разных сценариев**:
   - Строгий режим (только RAG) — для финансов
   - Креативный режим (больше генерации) — для маркетинга
   - Гибридный режим (баланс) — для поддержки

3. **Интегрируйте с другими системами**:
   - CRM (синхронизация клиентов)
   - Складская система (остатки товаров)
   - Бухгалтерия (счета и оплаты)

### Обучите команду

1. Покажите сотрудникам, как работает AI
2. Объясните, как добавлять новые вопросы в базу
3. Установите процесс регулярного обновления базы знаний
4. Назначьте ответственного за качество ответов AI

---

## 🆘 Решение проблем

### Проблема: Ollama не запускается

**Симптомы**: Статус "Ollama API not responding"

**Решение**:
```bash
# Проверить контейнер
docker ps | grep ollama

# Перезапустить
docker-compose restart ollama

# Проверить логи
docker-compose logs ollama
```

### Проблема: AI отвечает неточно

**Симптомы**: Ответы не соответствуют базе знаний

**Решение**:
1. Проверьте Score в тестере (должен быть < 300)
2. Добавьте больше вариантов вопросов в таблицу
3. Уменьшите порог релевантности (например, до 0.05)
4. Проверьте, что столбцы имеют правильные назначения ("Вопрос для AI", "Ответ AI")

### Проблема: Vector Search не работает

**Симптомы**: Статус Vector Search показывает ошибку

**Решение**:
1. Проверьте, установлена ли Embedding модель
2. Пересоберите индекс: на странице таблицы нажмите **"🔄 Пересобрать индекс"**
3. Проверьте, что таблица активирована как источник для AI

### Проблема: AI отвечает на неправильном языке

**Симптомы**: Ответы на английском вместо русского

**Решение**:
1. Измените системный промт, добавив в начало: `ВСЕГДА отвечай на русском языке.`
2. Используйте модель `qwen2.5:7b` вместо `llama2:7b`
3. В правилах AI установите `"language": "ru"`

### Проблема: Медленные ответы

**Симптомы**: AI отвечает дольше 5-10 секунд

**Решение**:
1. Используйте меньшую модель (`mistral:7b` вместо `qwen2.5:14b`)
2. Уменьшите `maxResults` в настройках RAG (например, до 3)
3. Отключите "Поиск синонимов" в дополнительных настройках
4. Используйте SSD для хранения моделей

---

## 📖 Дополнительная документация

### Изучите возможности AI

- 🤖 **[ИИ-агенты DLE](../ai-assistant.md)** — архитектура, примеры агентов и экономический эффект
- 📊 **[Система электронных таблиц](./tables-system.md)** - техническое описание таблиц
- ⚙️ **[Конфигурация AI](./setup-ai-assistant.md#техническая-документация-для-разработчиков)** - технические детали настройки

### Общая документация

- 🛡️ **[Безопасность](../security.md)** - как AI защищает ваши данные
- 💼 **[Блокчейн для бизнеса](../blockchain-for-business.md)** - интеграция AI с блокчейном
- 📋 **[FAQ](https://github.com/VC-HB3-Accelerator/.github/blob/main/ru/FAQ.md)** — часто задаваемые вопросы

### Поддержка

- 💬 **Чат поддержки**: https://hb3-accelerator.com/
- 📧 **Email**: info@hb3-accelerator.com
- 📚 **База знаний**: https://hb3-accelerator.com

---

## 🔧 Техническая документация (для разработчиков)

### Архитектура системы AI

```
┌───────────────────────────────────────────────────────────┐
│          Настройка AI Ассистента в DLE                   │
├───────────────────────────────────────────────────────────┤
│                                                           │
│  🤖 AI Провайдеры:                                        │
│     ├── OpenAI (GPT-4, GPT-3.5)                          │
│     ├── Anthropic (Claude)                               │
│     ├── Google (Gemini)                                  │
│     └── Ollama (локальные модели)                        │
│                                                           │
│  ⚙️  Настройки AI:                                        │
│     ├── System Prompt                                    │
│     ├── Выбор LLM модели                                 │
│     ├── Выбор Embedding модели                           │
│     ├── Выбор RAG-таблиц                                 │
│     ├── Правила (Rules)                                  │
│     └── Настройки RAG поиска                             │
│                                                           │
│  📋 Правила (Rules):                                      │
│     ├── JSON конфигурация поведения                      │
│     ├── Создание/редактирование/удаление                 │
│     └── Привязка к AI ассистенту                         │
│                                                           │
│  🔗 Интеграции:                                           │
│     ├── Email (IMAP + SMTP)                              │
│     └── Telegram Bot                                     │
│                                                           │
│  🔍 RAG:                                                  │
│     ├── Выбор таблиц для поиска                          │
│     ├── Настройки поиска (гибридный/семантический)       │
│     ├── Порог релевантности                              │
│     └── Извлечение ключевых слов                         │
│                                                           │
│  📊 Мониторинг:                                           │
│     ├── Статус сервисов (Backend, Ollama, Postgres)     │
│     ├── Тест RAG-функциональности                        │
│     └── Отслеживание прогресса                           │
│                                                           │
└───────────────────────────────────────────────────────────┘
```

### База данных

#### Таблица: `ai_providers_settings`

```sql
CREATE TABLE IF NOT EXISTS ai_providers_settings (
    id SERIAL PRIMARY KEY,
    provider_encrypted TEXT,              -- Провайдер: openai, anthropic, google, ollama
    api_key_encrypted TEXT,               -- API ключ (зашифрован)
    base_url_encrypted TEXT,              -- Base URL для API
    selected_model_encrypted TEXT,        -- Выбранная LLM модель
    embedding_model_encrypted TEXT,       -- Выбранная Embedding модель
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW()
);
```

#### Таблица: `ai_assistant_settings`

```sql
CREATE TABLE IF NOT EXISTS ai_assistant_settings (
    id SERIAL PRIMARY KEY,
    system_prompt_encrypted TEXT,         -- Системный промт
    selected_rag_tables INTEGER[],        -- Массив ID RAG-таблиц
    languages TEXT[],                     -- Массив поддерживаемых языков
    model_encrypted TEXT,                 -- Выбранная LLM модель
    embedding_model_encrypted TEXT,       -- Выбранная Embedding модель
    rules JSONB,                          -- Правила (DEPRECATED)
    rules_id INTEGER REFERENCES ai_assistant_rules(id),  -- Ссылка на правило
    telegram_settings_id INTEGER,         -- Ссылка на Telegram бота
    email_settings_id INTEGER,            -- Ссылка на Email настройки
    rag_settings JSONB,                   -- Настройки RAG поиска
    updated_at TIMESTAMP DEFAULT NOW(),
    updated_by INTEGER
);
```

#### Таблица: `ai_assistant_rules`

```sql
CREATE TABLE IF NOT EXISTS ai_assistant_rules (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL,                   -- Название набора правил
    description TEXT,                     -- Описание правила
    rules JSONB NOT NULL,                 -- JSON конфигурация
    rules_encrypted TEXT,                 -- Зашифрованная версия правил
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);
```

### Backend API

#### Настройки AI провайдеров

- **GET** `/settings/ai-settings/:provider` — Получить настройки провайдера
- **PUT** `/settings/ai-settings/:provider` — Сохранить настройки провайдера
- **DELETE** `/settings/ai-settings/:provider` — Удалить настройки провайдера
- **GET** `/settings/ai-settings/:provider/models` — Получить список моделей
- **POST** `/settings/ai-settings/:provider/verify` — Проверить API ключ

#### Настройки AI ассистента

- **GET** `/settings/ai-assistant` — Получить настройки ассистента
- **PUT** `/settings/ai-assistant` — Сохранить настройки ассистента

#### Правила AI

- **GET** `/settings/ai-assistant-rules` — Получить все правила
- **GET** `/settings/ai-assistant-rules/:id` — Получить правило по ID
- **POST** `/settings/ai-assistant-rules` — Создать правило
- **PUT** `/settings/ai-assistant-rules/:id` — Обновить правило
- **DELETE** `/settings/ai-assistant-rules/:id` — Удалить правило

#### Ollama (локальные модели)

- **GET** `/ollama/status` — Проверить статус Ollama
- **GET** `/ollama/models` — Получить список моделей
- **POST** `/ollama/install` — Установить модель
- **DELETE** `/ollama/models/:modelName` — Удалить модель

### Frontend страницы

- **`/settings/ai`** — Главная страница интеграций
- **`/settings/ai/:provider`** — Настройки AI провайдера
- **`/settings/ai/assistant`** — Настройки AI ассистента

### Процесс обработки сообщения

```
1. Пользователь → Сообщение
              ↓
2. UnifiedMessageProcessor
              ↓
3. Проверка языка (только русский)
              ↓
4. Дедупликация (хеш сообщения)
              ↓
5. Загрузка настроек (aiAssistantSettingsService)
              ↓
6. Загрузка правил (aiAssistantRulesService)
              ↓
7. RAG поиск (ragService)
   ├── Семантический поиск (vector search)
   ├── Поиск по ключевым словам
   └── Гибридный поиск
              ↓
8. Генерация ответа (generateLLMResponse)
   ├── System Prompt
   ├── История разговора
   ├── Контекст из RAG
   └── Правила
              ↓
9. Ответ → Пользователь
```

### Безопасность

- **Шифрование**: Все чувствительные поля зашифрованы с помощью AES-256
- **Права доступа**: Только администраторы могут изменять настройки
- **Валидация**: Проверка всех входных данных и API ключей

---

**© 2024-2026 Тарабанов Александр Викторович. Все права защищены.**

**Версия документа**: 1.0.0  
**Дата создания**: February 28, 2026

