This commit is contained in:
Leonid Pershin
449
docs/configuration.md
Normal file
449
docs/configuration.md
Normal file
@@ -0,0 +1,449 @@
|
||||
# ⚙️ Конфигурация
|
||||
|
||||
Полное руководство по настройке ChatBot.
|
||||
|
||||
## 📝 Иерархия конфигурации
|
||||
|
||||
Настройки загружаются в следующем порядке (последующие переопределяют предыдущие):
|
||||
|
||||
1. `appsettings.json` - Базовые настройки
|
||||
2. `appsettings.Development.json` - Настройки для разработки
|
||||
3. User Secrets - Секреты для разработки
|
||||
4. Переменные окружения - Production настройки
|
||||
5. `.env` файл - Локальные переменные
|
||||
|
||||
## 🔐 Переменные окружения
|
||||
|
||||
### Telegram Bot
|
||||
|
||||
```env
|
||||
# Обязательно
|
||||
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
|
||||
```
|
||||
|
||||
### Ollama
|
||||
|
||||
```env
|
||||
# URL сервера Ollama
|
||||
OLLAMA_URL=http://localhost:11434
|
||||
|
||||
# Модель по умолчанию
|
||||
OLLAMA_DEFAULT_MODEL=gemma2:2b
|
||||
```
|
||||
|
||||
### База данных
|
||||
|
||||
```env
|
||||
# Подключение к PostgreSQL
|
||||
DB_HOST=localhost
|
||||
DB_PORT=5432
|
||||
DB_NAME=chatbot
|
||||
DB_USER=postgres
|
||||
DB_PASSWORD=your_secure_password
|
||||
```
|
||||
|
||||
## 📄 appsettings.json
|
||||
|
||||
### Полная структура
|
||||
|
||||
```json
|
||||
{
|
||||
"Serilog": {
|
||||
"MinimumLevel": {
|
||||
"Default": "Information",
|
||||
"Override": {
|
||||
"Microsoft": "Warning",
|
||||
"System": "Warning"
|
||||
}
|
||||
},
|
||||
"WriteTo": [
|
||||
{
|
||||
"Name": "Console",
|
||||
"Args": {
|
||||
"outputTemplate": "[{Timestamp:HH:mm:ss}] [{Level}] {Message}{NewLine}{Exception}"
|
||||
}
|
||||
},
|
||||
{
|
||||
"Name": "File",
|
||||
"Args": {
|
||||
"path": "logs/telegram-bot-.log",
|
||||
"rollingInterval": "Day",
|
||||
"retainedFileCountLimit": 7
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"TelegramBot": {
|
||||
"BotToken": ""
|
||||
},
|
||||
"Ollama": {
|
||||
"Url": "",
|
||||
"DefaultModel": ""
|
||||
},
|
||||
"AI": {
|
||||
"Temperature": 0.9,
|
||||
"SystemPromptPath": "Prompts/system-prompt.txt",
|
||||
"MaxRetryAttempts": 3,
|
||||
"RetryDelayMs": 1000,
|
||||
"RequestTimeoutSeconds": 180,
|
||||
"EnableHistoryCompression": true,
|
||||
"CompressionThreshold": 20,
|
||||
"CompressionTarget": 10,
|
||||
"MinMessageLengthForSummarization": 50,
|
||||
"MaxSummarizedMessageLength": 200,
|
||||
"EnableExponentialBackoff": true,
|
||||
"MaxRetryDelayMs": 30000,
|
||||
"CompressionTimeoutSeconds": 30,
|
||||
"StatusCheckTimeoutSeconds": 10
|
||||
},
|
||||
"Database": {
|
||||
"ConnectionString": "",
|
||||
"EnableSensitiveDataLogging": false,
|
||||
"CommandTimeout": 30
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🎯 Секции конфигурации
|
||||
|
||||
### TelegramBot
|
||||
|
||||
| Параметр | Тип | Описание | По умолчанию |
|
||||
|----------|-----|----------|--------------|
|
||||
| `BotToken` | string | Токен бота от @BotFather | - |
|
||||
|
||||
**Валидация:**
|
||||
- Токен не может быть пустым
|
||||
- Минимальная длина: 10 символов
|
||||
|
||||
**Пример:**
|
||||
```json
|
||||
{
|
||||
"TelegramBot": {
|
||||
"BotToken": "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Ollama
|
||||
|
||||
| Параметр | Тип | Описание | По умолчанию |
|
||||
|----------|-----|----------|--------------|
|
||||
| `Url` | string | URL Ollama сервера | http://localhost:11434 |
|
||||
| `DefaultModel` | string | Модель по умолчанию | gemma2:2b |
|
||||
|
||||
**Валидация:**
|
||||
- URL должен быть валидным HTTP/HTTPS адресом
|
||||
- Модель не может быть пустой
|
||||
|
||||
**Пример:**
|
||||
```json
|
||||
{
|
||||
"Ollama": {
|
||||
"Url": "http://localhost:11434",
|
||||
"DefaultModel": "gemma2:2b"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Доступные модели:**
|
||||
- `gemma2:2b` - Быстрая, легкая (2GB RAM)
|
||||
- `llama3.2` - Средняя (4GB RAM)
|
||||
- `mistral` - Продвинутая (8GB RAM)
|
||||
- `phi3` - Компактная (2.5GB RAM)
|
||||
|
||||
### AI
|
||||
|
||||
| Параметр | Тип | Описание | По умолчанию |
|
||||
|----------|-----|----------|--------------|
|
||||
| `Temperature` | double | Креативность ответов (0.0-2.0) | 0.9 |
|
||||
| `SystemPromptPath` | string | Путь к системному промпту | Prompts/system-prompt.txt |
|
||||
| `MaxRetryAttempts` | int | Макс. попыток повтора | 3 |
|
||||
| `RetryDelayMs` | int | Задержка между попытками (мс) | 1000 |
|
||||
| `RequestTimeoutSeconds` | int | Таймаут запроса (сек) | 180 |
|
||||
| `EnableHistoryCompression` | bool | Включить сжатие истории | true |
|
||||
| `CompressionThreshold` | int | Порог для сжатия (кол-во сообщений) | 20 |
|
||||
| `CompressionTarget` | int | Целевое кол-во после сжатия | 10 |
|
||||
| `MinMessageLengthForSummarization` | int | Мин. длина для суммаризации | 50 |
|
||||
| `MaxSummarizedMessageLength` | int | Макс. длина суммаризации | 200 |
|
||||
| `EnableExponentialBackoff` | bool | Экспоненциальный backoff | true |
|
||||
| `MaxRetryDelayMs` | int | Макс. задержка повтора (мс) | 30000 |
|
||||
| `CompressionTimeoutSeconds` | int | Таймаут сжатия (сек) | 30 |
|
||||
| `StatusCheckTimeoutSeconds` | int | Таймаут проверки статуса (сек) | 10 |
|
||||
|
||||
**Валидация:**
|
||||
- `Temperature`: 0.0 ≤ x ≤ 2.0
|
||||
- `MaxRetryAttempts`: 1 ≤ x ≤ 10
|
||||
- `RetryDelayMs`: 100 ≤ x ≤ 60000
|
||||
- `RequestTimeoutSeconds`: 10 ≤ x ≤ 600
|
||||
|
||||
**Пример:**
|
||||
```json
|
||||
{
|
||||
"AI": {
|
||||
"Temperature": 0.9,
|
||||
"MaxRetryAttempts": 3,
|
||||
"EnableHistoryCompression": true,
|
||||
"CompressionThreshold": 20
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Temperature (Температура)
|
||||
|
||||
Определяет "креативность" ответов AI:
|
||||
|
||||
- **0.0-0.3**: Детерминированные, предсказуемые ответы
|
||||
- **0.4-0.7**: Сбалансированные ответы
|
||||
- **0.8-1.2**: Креативные, разнообразные ответы (рекомендуется)
|
||||
- **1.3-2.0**: Очень креативные, иногда непредсказуемые
|
||||
|
||||
#### History Compression
|
||||
|
||||
Автоматическое сжатие истории диалога для оптимизации:
|
||||
|
||||
```
|
||||
История: 20+ сообщений
|
||||
↓ (сжатие)
|
||||
Результат: 10 сообщений (суммаризация старых)
|
||||
```
|
||||
|
||||
**Алгоритм:**
|
||||
1. Сохранить системный промпт
|
||||
2. Сохранить последние N сообщений
|
||||
3. Старые сообщения суммаризировать
|
||||
|
||||
### Database
|
||||
|
||||
| Параметр | Тип | Описание | По умолчанию |
|
||||
|----------|-----|----------|--------------|
|
||||
| `ConnectionString` | string | Строка подключения PostgreSQL | - |
|
||||
| `EnableSensitiveDataLogging` | bool | Логировать SQL запросы | false |
|
||||
| `CommandTimeout` | int | Таймаут команд (сек) | 30 |
|
||||
|
||||
**Валидация:**
|
||||
- Connection string не может быть пустой
|
||||
- `CommandTimeout`: 5 ≤ x ≤ 300
|
||||
|
||||
**Пример:**
|
||||
```json
|
||||
{
|
||||
"Database": {
|
||||
"ConnectionString": "Host=localhost;Port=5432;Database=chatbot;Username=chatbot;Password=password",
|
||||
"EnableSensitiveDataLogging": false,
|
||||
"CommandTimeout": 30
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Connection String формат:**
|
||||
```
|
||||
Host={host};Port={port};Database={name};Username={user};Password={password}
|
||||
```
|
||||
|
||||
### Serilog (Логирование)
|
||||
|
||||
| Параметр | Тип | Описание |
|
||||
|----------|-----|----------|
|
||||
| `MinimumLevel.Default` | string | Минимальный уровень логов |
|
||||
| `WriteTo` | array | Sink'и для записи |
|
||||
|
||||
**Уровни логирования:**
|
||||
- `Verbose` - Все детали (разработка)
|
||||
- `Debug` - Отладочная информация
|
||||
- `Information` - Общая информация (по умолчанию)
|
||||
- `Warning` - Предупреждения
|
||||
- `Error` - Ошибки
|
||||
- `Fatal` - Критические ошибки
|
||||
|
||||
**Пример:**
|
||||
```json
|
||||
{
|
||||
"Serilog": {
|
||||
"MinimumLevel": {
|
||||
"Default": "Information",
|
||||
"Override": {
|
||||
"Microsoft.EntityFrameworkCore": "Warning"
|
||||
}
|
||||
},
|
||||
"WriteTo": [
|
||||
{
|
||||
"Name": "Console"
|
||||
},
|
||||
{
|
||||
"Name": "File",
|
||||
"Args": {
|
||||
"path": "logs/app-.log",
|
||||
"rollingInterval": "Day"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🔧 Настройка системного промпта
|
||||
|
||||
Файл: `ChatBot/Prompts/system-prompt.txt`
|
||||
|
||||
Этот файл определяет личность и стиль общения бота.
|
||||
|
||||
### Структура промпта
|
||||
|
||||
```
|
||||
[Персонаж]
|
||||
- Имя, возраст, локация
|
||||
- Интересы, хобби
|
||||
- Стиль общения
|
||||
|
||||
[Правила ответов]
|
||||
- Естественность
|
||||
- Обработка {empty}
|
||||
- Реакция на провокации
|
||||
|
||||
[Примеры]
|
||||
- Корректные ответы
|
||||
- Примеры {empty}
|
||||
```
|
||||
|
||||
### Специальные маркеры
|
||||
|
||||
**{empty}** - Бот игнорирует сообщение
|
||||
|
||||
Используется когда:
|
||||
- Сообщение адресовано другому человеку
|
||||
- Контекст не требует ответа
|
||||
- Провокационные вопросы о боте
|
||||
|
||||
### Кастомизация промпта
|
||||
|
||||
1. Откройте `Prompts/system-prompt.txt`
|
||||
2. Отредактируйте под свои нужды
|
||||
3. Сохраните файл
|
||||
4. Перезапустите бота
|
||||
|
||||
## 🔄 Переключение режимов
|
||||
|
||||
### In-Memory Storage (для тестов)
|
||||
|
||||
В `Program.cs`:
|
||||
```csharp
|
||||
// Заменить
|
||||
builder.Services.AddScoped<ISessionStorage, DatabaseSessionStorage>();
|
||||
|
||||
// На
|
||||
builder.Services.AddScoped<ISessionStorage, InMemorySessionStorage>();
|
||||
```
|
||||
|
||||
### Отключение сжатия истории
|
||||
|
||||
В `appsettings.json`:
|
||||
```json
|
||||
{
|
||||
"AI": {
|
||||
"EnableHistoryCompression": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Изменение уровня логирования
|
||||
|
||||
```json
|
||||
{
|
||||
"Serilog": {
|
||||
"MinimumLevel": {
|
||||
"Default": "Debug" // или Verbose
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 📊 Примеры конфигураций
|
||||
|
||||
### Development (разработка)
|
||||
|
||||
```json
|
||||
{
|
||||
"AI": {
|
||||
"Temperature": 0.7,
|
||||
"EnableHistoryCompression": false,
|
||||
"MaxRetryAttempts": 2
|
||||
},
|
||||
"Database": {
|
||||
"EnableSensitiveDataLogging": true
|
||||
},
|
||||
"Serilog": {
|
||||
"MinimumLevel": {
|
||||
"Default": "Debug"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Production (production)
|
||||
|
||||
```json
|
||||
{
|
||||
"AI": {
|
||||
"Temperature": 0.9,
|
||||
"EnableHistoryCompression": true,
|
||||
"MaxRetryAttempts": 3
|
||||
},
|
||||
"Database": {
|
||||
"EnableSensitiveDataLogging": false
|
||||
},
|
||||
"Serilog": {
|
||||
"MinimumLevel": {
|
||||
"Default": "Information"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### High Performance (производительность)
|
||||
|
||||
```json
|
||||
{
|
||||
"AI": {
|
||||
"Temperature": 0.8,
|
||||
"RequestTimeoutSeconds": 120,
|
||||
"EnableHistoryCompression": true,
|
||||
"CompressionThreshold": 15,
|
||||
"CompressionTarget": 8
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 🔍 Проверка конфигурации
|
||||
|
||||
### Валидация при старте
|
||||
|
||||
Приложение автоматически валидирует конфигурацию при запуске.
|
||||
|
||||
**Ошибки валидации:**
|
||||
```
|
||||
Options validation failed for 'TelegramBotSettings' with errors:
|
||||
- BotToken cannot be empty
|
||||
```
|
||||
|
||||
### Просмотр текущей конфигурации
|
||||
|
||||
Используйте команду бота:
|
||||
```
|
||||
/settings
|
||||
```
|
||||
|
||||
Ответ:
|
||||
```
|
||||
⚙️ Текущие настройки:
|
||||
🤖 Модель: gemma2:2b
|
||||
🌡️ Temperature: 0.9
|
||||
📝 Сообщений в истории: 5/30
|
||||
🗜️ Сжатие истории: Включено
|
||||
```
|
||||
|
||||
## 📚 См. также
|
||||
|
||||
- [Установка](./installation.md)
|
||||
- [Быстрый старт](./quickstart.md)
|
||||
- [Development](./development/project-structure.md)
|
||||
Reference in New Issue
Block a user