This commit is contained in:
Leonid Pershin
287
README.md
287
README.md
@@ -1,10 +1,46 @@
|
||||
# ChatBot
|
||||
# 🤖 ChatBot - AI Telegram Bot
|
||||
|
||||
## Настройка окружения
|
||||
[](https://dotnet.microsoft.com/)
|
||||
[](LICENSE.txt)
|
||||
[](https://www.postgresql.org/)
|
||||
|
||||
1. Создать `.env` файл:
|
||||
пример
|
||||
Интеллектуальный Telegram-бот на базе локальных AI моделей (Ollama), построенный на .NET 9 с использованием Clean Architecture.
|
||||
|
||||
## ✨ Основные возможности
|
||||
|
||||
- 🤖 **AI-интеграция** - Использование локальных LLM через Ollama (gemma2, llama3, mistral)
|
||||
- 💬 **Telegram Bot** - Полнофункциональный бот с поддержкой команд и групповых чатов
|
||||
- 💾 **PostgreSQL** - Надежное хранение истории диалогов и сессий
|
||||
- 🗜️ **История сжатия** - Автоматическая оптимизация длинных диалогов
|
||||
- 🔄 **Retry механизмы** - Устойчивость к сбоям с экспоненциальным backoff
|
||||
- 📊 **Health Checks** - Мониторинг состояния всех сервисов
|
||||
- 🧪 **Высокое покрытие тестами** - 50+ тестовых классов
|
||||
- 📝 **Serilog** - Структурированное логирование
|
||||
|
||||
## 🚀 Быстрый старт
|
||||
|
||||
### Требования
|
||||
|
||||
- [.NET 9.0 SDK](https://dotnet.microsoft.com/download/dotnet/9.0)
|
||||
- [PostgreSQL 14+](https://www.postgresql.org/download/)
|
||||
- [Ollama](https://ollama.ai/) с установленной моделью
|
||||
- Telegram Bot Token ([создать через @BotFather](https://t.me/botfather))
|
||||
|
||||
### Установка за 3 шага
|
||||
|
||||
#### 1. Клонирование и установка зависимостей
|
||||
|
||||
```bash
|
||||
git clone https://github.com/mrleo1nid/ChatBot.git
|
||||
cd ChatBot
|
||||
dotnet restore
|
||||
```
|
||||
|
||||
#### 2. Настройка окружения
|
||||
|
||||
Создайте файл `ChatBot/.env`:
|
||||
|
||||
```env
|
||||
# Database Configuration
|
||||
DB_HOST=localhost
|
||||
DB_PORT=5432
|
||||
@@ -16,5 +52,244 @@ DB_PASSWORD=your_secure_password
|
||||
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
|
||||
|
||||
# Ollama Configuration
|
||||
OLLAMA_URL=https://sample.api.home/
|
||||
OLLAMA_DEFAULT_MODEL=gemma3:4b
|
||||
OLLAMA_URL=http://localhost:11434
|
||||
OLLAMA_DEFAULT_MODEL=gemma2:2b
|
||||
```
|
||||
|
||||
#### 3. Запуск
|
||||
|
||||
```bash
|
||||
# Установите AI модель
|
||||
ollama pull gemma2:2b
|
||||
|
||||
# Создайте базу данных
|
||||
psql -U postgres -c "CREATE DATABASE chatbot;"
|
||||
|
||||
# Запустите бота
|
||||
cd ChatBot
|
||||
dotnet run
|
||||
```
|
||||
|
||||
🎉 **Готово!** Откройте Telegram и найдите вашего бота.
|
||||
|
||||
## 📚 Документация
|
||||
|
||||
### 🎯 Начало работы
|
||||
- [📋 Обзор проекта](docs/overview.md) - Что такое ChatBot и его возможности
|
||||
- [⚡ Быстрый старт](docs/quickstart.md) - Запуск за 5 минут
|
||||
- [🛠️ Установка и настройка](docs/installation.md) - Подробная инструкция
|
||||
- [⚙️ Конфигурация](docs/configuration.md) - Настройка параметров
|
||||
|
||||
### 🏗️ Архитектура
|
||||
- [📐 Архитектура проекта](docs/architecture/overview.md) - Общая архитектура
|
||||
- [🏛️ Слои приложения](docs/architecture/layers.md) - Детальное описание слоев
|
||||
- [📊 Модели данных](docs/architecture/data-models.md) - Структура данных
|
||||
- [🗄️ База данных](docs/architecture/database.md) - Работа с PostgreSQL
|
||||
|
||||
### 💻 Разработка
|
||||
- [📁 Структура проекта](docs/development/project-structure.md) - Организация кода
|
||||
- [🤖 Команды бота](docs/api/bot-commands.md) - Все доступные команды
|
||||
|
||||
### 📖 Полная документация
|
||||
|
||||
**👉 [Перейти к полной документации](docs/README.md)**
|
||||
|
||||
## 🎮 Использование
|
||||
|
||||
### Команды бота
|
||||
|
||||
```
|
||||
/start - Начать работу с ботом
|
||||
/help - Показать справку
|
||||
/clear - Очистить историю диалога
|
||||
/settings - Показать текущие настройки
|
||||
/status - Проверить статус бота
|
||||
```
|
||||
|
||||
### Пример диалога
|
||||
|
||||
```
|
||||
Вы: Привет!
|
||||
Бот: Привет! Как дела? 😊
|
||||
|
||||
Вы: Расскажи анекдот
|
||||
Бот: Программист ложится спать...
|
||||
Ставит рядом два стакана:
|
||||
один с водой — если захочет пить,
|
||||
другой пустой — если не захочет 😄
|
||||
```
|
||||
|
||||
## 🏗️ Технологический стек
|
||||
|
||||
### Backend
|
||||
- **Runtime:** .NET 9.0
|
||||
- **Language:** C# 13
|
||||
- **Architecture:** Clean Architecture, SOLID
|
||||
|
||||
### Основные библиотеки
|
||||
- **Telegram.Bot** 22.7.2 - Telegram Bot API
|
||||
- **OllamaSharp** 5.4.7 - Ollama клиент для AI
|
||||
- **Entity Framework Core** 9.0.10 - ORM
|
||||
- **Npgsql** 9.0.4 - PostgreSQL провайдер
|
||||
- **Serilog** 4.3.0 - Логирование
|
||||
- **FluentValidation** 12.0.0 - Валидация
|
||||
|
||||
### Тестирование
|
||||
- **xUnit** 2.9.3 - Тестовый фреймворк
|
||||
- **Moq** 4.20.72 - Моки и стабы
|
||||
- **FluentAssertions** 8.7.1 - Assertions
|
||||
- **Coverlet** 6.0.4 - Code coverage
|
||||
|
||||
## 📊 Архитектура
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ Telegram Bot Layer │
|
||||
│ (Commands, Handlers) │
|
||||
├─────────────────────────────────────┤
|
||||
│ Service Layer │
|
||||
│ (ChatService, AIService) │
|
||||
├─────────────────────────────────────┤
|
||||
│ Data Access Layer │
|
||||
│ (Repositories, DbContext) │
|
||||
├─────────────────────────────────────┤
|
||||
│ Infrastructure │
|
||||
│ (PostgreSQL, Ollama, Telegram) │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Принципы:**
|
||||
- Clean Architecture
|
||||
- SOLID принципы
|
||||
- Dependency Injection
|
||||
- Repository Pattern
|
||||
- Command Pattern для команд бота
|
||||
|
||||
## 🐳 Docker развертывание
|
||||
|
||||
```bash
|
||||
# Сборка образа
|
||||
docker build -t chatbot:latest .
|
||||
|
||||
# Запуск с docker-compose
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
## 🧪 Тестирование
|
||||
|
||||
```bash
|
||||
# Запуск всех тестов
|
||||
dotnet test
|
||||
|
||||
# С покрытием кода
|
||||
dotnet test /p:CollectCoverage=true /p:CoverletOutputFormat=opencover
|
||||
|
||||
# Запуск конкретного теста
|
||||
dotnet test --filter "FullyQualifiedName~ChatServiceTests"
|
||||
```
|
||||
|
||||
## 📈 CI/CD
|
||||
|
||||
Проект использует Gitea Actions для автоматизации:
|
||||
- ✅ Сборка проекта
|
||||
- ✅ Запуск тестов
|
||||
- ✅ Анализ кода (SonarQube)
|
||||
- ✅ Проверка покрытия
|
||||
|
||||
Конфигурация: [`.gitea/workflows/build.yml`](.gitea/workflows/build.yml)
|
||||
|
||||
## 🔧 Конфигурация
|
||||
|
||||
### Основные параметры
|
||||
|
||||
| Параметр | Описание | По умолчанию |
|
||||
|----------|----------|-------------|
|
||||
| `AI.Temperature` | Креативность ответов (0.0-2.0) | 0.9 |
|
||||
| `AI.MaxRetryAttempts` | Макс. попыток повтора | 3 |
|
||||
| `AI.EnableHistoryCompression` | Сжатие истории | true |
|
||||
| `AI.CompressionThreshold` | Порог сжатия (сообщений) | 20 |
|
||||
|
||||
**Подробнее:** [docs/configuration.md](docs/configuration.md)
|
||||
|
||||
## 🛠️ Разработка
|
||||
|
||||
### Структура проекта
|
||||
|
||||
```
|
||||
ChatBot/
|
||||
├── ChatBot/ # Основной проект
|
||||
│ ├── Services/ # Бизнес-логика
|
||||
│ ├── Data/ # Доступ к данным
|
||||
│ ├── Models/ # Модели и конфигурация
|
||||
│ └── Program.cs # Точка входа
|
||||
├── ChatBot.Tests/ # Тесты
|
||||
└── docs/ # Документация
|
||||
```
|
||||
|
||||
### Добавление новой команды
|
||||
|
||||
```csharp
|
||||
public class MyCommand : TelegramCommandBase
|
||||
{
|
||||
public override string Command => "mycommand";
|
||||
public override string Description => "Описание команды";
|
||||
|
||||
public override async Task<ReplyInfo> ExecuteAsync(TelegramCommandContext context)
|
||||
{
|
||||
return new ReplyInfo { Text = "Ответ" };
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Зарегистрируйте в `Program.cs`:
|
||||
```csharp
|
||||
builder.Services.AddScoped<ITelegramCommand, MyCommand>();
|
||||
```
|
||||
|
||||
## 🤝 Вклад в проект
|
||||
|
||||
Мы приветствуем вклад в развитие проекта!
|
||||
|
||||
### Как внести изменения
|
||||
|
||||
1. Fork репозитория
|
||||
2. Создайте feature branch (`git checkout -b feature/amazing-feature`)
|
||||
3. Commit изменения (`git commit -m 'Add amazing feature'`)
|
||||
4. Push в branch (`git push origin feature/amazing-feature`)
|
||||
5. Откройте Pull Request
|
||||
|
||||
### Guidelines
|
||||
|
||||
- Следуйте существующему стилю кода
|
||||
- Добавляйте тесты для новой функциональности
|
||||
- Обновляйте документацию
|
||||
- Убедитесь, что все тесты проходят
|
||||
|
||||
## 📝 Лицензия
|
||||
|
||||
Этот проект распространяется под лицензией MIT. См. [LICENSE.txt](LICENSE.txt) для подробностей.
|
||||
|
||||
## 🙏 Благодарности
|
||||
|
||||
- [Telegram Bot API](https://core.telegram.org/bots/api) - За отличное API
|
||||
- [Ollama](https://ollama.ai/) - За возможность использовать локальные LLM
|
||||
- [.NET Community](https://dotnet.microsoft.com/) - За мощный фреймворк
|
||||
|
||||
## 📞 Контакты и поддержка
|
||||
|
||||
- 🐛 [Сообщить о проблеме](https://github.com/mrleo1nid/ChatBot/issues)
|
||||
- 💡 [Предложить улучшение](https://github.com/mrleo1nid/ChatBot/issues)
|
||||
- 📖 [Документация](docs/README.md)
|
||||
|
||||
## 🌟 Roadmap
|
||||
|
||||
- [ ] Поддержка мультимодальных моделей (изображения)
|
||||
- [ ] Веб-интерфейс для управления ботом
|
||||
- [ ] Метрики и аналитика использования
|
||||
- [ ] Kubernetes deployment манифесты
|
||||
- [ ] Дополнительные команды (история, экспорт)
|
||||
- [ ] Плагинная система для расширений
|
||||
|
||||
---
|
||||
|
||||
**Сделано с ❤️ используя .NET 9 и Ollama**
|
||||
|
||||
Reference in New Issue
Block a user