ha-text-ai/README_RU.md

# 🤖 HA Text AI для Home Assistant

<div align="center"> 

![GitHub release](https://img.shields.io/github/release/smkrv/ha-text-ai.svg?style=flat-square) ![GitHub downloads](https://img.shields.io/github/downloads/smkrv/ha-text-ai/total.svg?style=flat-square) ![GitHub stars](https://img.shields.io/github/stars/smkrv/ha-text-ai.svg?style=social) ![GitHub last commit](https://img.shields.io/github/last-commit/smkrv/ha-text-ai.svg?style=flat-square) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT) [![hacs_badge](https://img.shields.io/badge/HACS-Custom-41BDF5.svg?style=flat-square)](https://github.com/hacs/integration) ![English](https://img.shields.io/badge/language-Russian-red) ![Russian](https://img.shields.io/badge/language-English-red) ![Deutch](https://img.shields.io/badge/language-Deutch-red)

<img src="https://github.com/smkrv/ha-text-ai/blob/3e3ec45b195c92989434fde40ae110027f4ea124/misc/icons/icon.png" alt="HA Text AI" width="140"/>

### Расширенная AI-интеграция для Home Assistant с поддержкой нескольких провайдеров
</div>

<p align="center">
Преобразите свой умный дом с мощной AI-поддержкой от множества провайдеров, включая модели OpenAI GPT и Anthropic Claude. Получайте интеллектуальные ответы, автоматизируйте сложные сценарии и улучшайте домашнюю автоматизацию с помощью передовой обработки естественного языка.

</p>

---

> [!IMPORTANT]
> 🚧 АЛЬФА-ВЕРСИЯ 🚧  
> Ожидайте: возможные ошибки, частые изменения, незавершенные функции.  
> 🤝 Разработка силами сообщества  
>
>  <a href="https://community.home-assistant.io/t/ha-text-ai-transforming-home-automation-with-multi-provider-language-models/799741"><img src="https://img.shields.io/badge/Сообщество-blue?style=for-the-badge&logo=homeassistant&logoColor=white&color=03a9f4"/></a>

## 🌟 Возможности

- 🧠 **Мультипровайдерная AI-интеграция**:
  - Поддержка моделей OpenAI GPT
  - Интеграция с Anthropic Claude
  - Пользовательские API-эндпоинты
  - Гибкий выбор модели

- 💬 **Расширенная обработка языка**:
  - Контекстно-зависимые ответы
  - Многоступенчатые диалоги
  - Пользовательские системные инструкции
  - Естественный поток общения

- 📝 **Улучшенное управление памятью**:
  - Постоянная история диалогов
  - Контекстно-осознанные ответы
  - Настраиваемые лимиты истории
  - Фильтрация для конкретных моделей

- ⚡ **Оптимизация производительности**:
  - Эффективное использование токенов
  - Интеллектуальное ограничение скорости
  - Кэширование ответов
  - Контроль интервалов запросов

- 🎯 **Расширенная настройка**:
  - Выбор модели для каждого запроса
  - Настраиваемые параметры
  - Пользовательские системные промпты
  - Контроль температуры

- 🔒 **Повышенная безопасность**:
  - Защищенное хранение API-ключей
  - Защита от превышения лимитов
  - Обработка ошибок
  - Мониторинг использования

- 🎨 **Улучшенный пользовательский интерфейс**:
  - Интуитивная конфигурация
  - Подробные атрибуты сенсоров
  - Расширенный сервисный интерфейс
  - UI выбора модели

- 🔄 **Интеграция с автоматизацией**:
  - Реакции на события
  - Поддержка условной логики
  - Совместимость с шаблонами
  - Автоматизация для конкретных моделей

## 📋 Предварительные требования

- Home Assistant 2024.11 или новее
- Активный API-ключ от:
  - OpenAI ([Получить ключ](https://platform.openai.com/account/api-keys))
  - Anthropic ([Получить ключ](https://console.anthropic.com/))
  - OpenRouter ([Получить ключ](https://openrouter.ai/keys))
- Python 3.9 или новее
- Стабильное интернет-соединение

### Параметры конфигурации
- Провайдер API (OpenAI/Anthropic)
- API-ключ (специфичный для провайдера)
- Выбор модели (гибкий, модели от провайдера)
- Температура (управление креативностью, 0.0-2.0)
- Максимальные токены (Ограничение длины ответа)
- Интервал запросов (Регулировка вызовов API)
- Пользовательская конечная точка API (опционально)

#### ⓘ Потенциально совместимые провайдеры
Интеграция разработана гибко и может работать с провайдерами, предлагающими API, совместимые с OpenAI:
- Groq
- Together AI
- Perplexity AI
- Mistral AI
- Google AI
- Локальные AI-серверы (например, Ollama)
- Пользовательские эндпоинты, совместимые с OpenAI

#### Дополнительные замечания
- Не все провайдеры гарантируют полную совместимость
- Производительность может различаться
- Проверяйте документацию каждого провайдера
- Убедитесь, что у вашего API-ключа достаточно кредитов/квоты

#### Требования к совместимости провайдеров
Для совместимости провайдер должен поддерживать:
- REST API-структуру, похожую на OpenAI
- JSON-формат запросов/ответов
- Стандартный метод аутентификации
- Схожую обработку параметров модели

## ⚡ Установка

### Установка через HACS (Рекомендуется)
<a href="https://my.home-assistant.io/redirect/hacs_repository/?owner=smkrv&repository=ha-text-ai&category=Integration"><img src="https://my.home-assistant.io/badges/hacs_repository.svg" width="170" height="auto"></a>
1\. Откройте HACS в Home Assistant
2\. Нажмите "Интеграции"
3\. Нажмите "..." в правом верхнем углу  
4\. Выберите "Пользовательские репозитории"
5\. Добавьте URL репозитория: `https://github.com/smkrv/ha-text-ai`
6\. Выберите категорию "Интеграция"
7\. Нажмите "Загрузить"
8\. Перезапустите Home Assistant

### Самостоятельная установка
1\. Скачайте последний релиз  
2\. Извлеките и скопируйте `custom_components/ha_text_ai` в вашу директорию `custom_components`  
3\. Перезапустите Home Assistant  
4\. Добавьте конфигурацию через UI или YAML  

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

### Через UI (Рекомендуется)  
1\. Перейдите в Настройки → Устройства и сервисы   
2\. Нажмите "Добавить интеграцию"  
3\. Найдите "HA Text AI"  
4\. Следуйте шагам конфигурации   

### Через YAML
```yaml
ha_text_ai:
  api_provider: openai  # или anthropic
  api_key: !secret ai_api_key
  model: gpt-4o-mini
  temperature: 0.7
  max_tokens: 1000
  request_interval: 1.0
  api_endpoint: https://api.openai.com/v1  # опционально, для пользовательских эндпоинтов
  system_prompt: |
    Вы - эксперт по домашней автоматизации.
    Фокусируйтесь на практичных и эффективных решениях.
```

## 🛠️ Доступные сервисы

### ask_question
```yaml
service: ha_text_ai.ask_question
data:
  question: "Какая оптимальная температура для сна?"
  model: "claude-3-sonnet"  # опционально
  temperature: 0.5  # опционально
  max_tokens: 500  # опционально
  context_messages: 10  # опционально, количество предыдущих сообщений в контексте, по умолчанию: 5
  system_prompt: "Вы эксперт по оптимизации сна"  # опционально
```

### set_system_prompt
```yaml
service: ha_text_ai.set_system_prompt
data:
  prompt: |
    Вы эксперт по домашней автоматизации, сосредоточенный на:
    1. Энергоэффективности
    2. Оптимизации комфорта
    3. Вопросах безопасности
    Предоставляйте практичные, выполнимые советы.
```

### clear_history
```yaml
service: ha_text_ai.clear_history
```

### get_history
```yaml
service: ha_text_ai.get_history
data:
  limit: 5  # опционально
  filter_model: "gpt-4o"  # опционально
```

### 🏷️ Соглашение по именованию сенсоров HA Text AI

#### Структура имени сенсора
```yaml
# Всегда начинается с 'sensor.ha_text_ai_'
# Вы определяете только часть после подчеркивания
sensor.ha_text_ai_ВАШЕ_УНИКАЛЬНОЕ_ОКОНЧАНИЕ

# Примеры:
sensor.ha_text_ai_gpt      # Сенсор на базе GPT
sensor.ha_text_ai_claude   # Сенсор на базе Claude
sensor.ha_text_ai_gpt      # Пользовательское окончание
```

#### Получение ответа
```yaml
# Используйте имя вашего конкретного сенсора
{{ state_attr('sensor.ha_text_ai_gpt', 'response') }}
```

#### Практическое использование
```yaml
automation:
  - alias: "AI-ответ с пользовательским сенсором"
    action:
      - service: ha_text_ai.ask_question
        data:
          question: "Совет по домашней автоматизации"
      - service: notify.mobile
        data:
          message: >
            Совет ИИ:
            {{ state_attr('sensor.ha_text_ai_gpt', 'response') }}
```

### 💡 Правила именования
- Префикс всегда `sensor.ha_text_ai_`
- Добавьте уникальный идентификатор после подчеркивания
- Используйте lowercase
- Пробелы не допускаются
- Сохраняйте описательность и краткость

### 🔍 Атрибуты сенсора HA Text AI

#### Информация о модели и провайдере
```yaml
# Название текущей используемой AI-модели
{{ state_attr('sensor.ha_text_ai_gpt', 'Model') }}           # gpt-4o

# Провайдер сервиса (определяет эндпоинт API и аутентификацию)
{{ state_attr('sensor.ha_text_ai_gpt', 'Api provider') }}    # openai

# Предыдущая или альтернативная конфигурация модели
{{ state_attr('sensor.ha_text_ai_gpt', 'Last model') }}      # gpt-4o
```

#### Системный статус
```yaml
# Текущая готовность сервиса AI API
{{ state_attr('sensor.ha_text_ai_gpt', 'Api status') }}      # готов

# Указывает, выполняется ли в данный момент запрос
{{ state_attr('sensor.ha_text_ai_gpt', 'Is processing') }}   # false

# Показывает, достигнут ли лимит запросов API
{{ state_attr('sensor.ha_text_ai_gpt', 'Is rate limited') }} # false

# Статус конкретного используемого эндпоинта
{{ state_attr('sensor.ha_text_ai_gpt', 'Endpoint status') }} # готов
```

#### Метрики производительности
```yaml
# Общее количество успешно выполненных API-запросов
{{ state_attr('sensor.ha_text_ai_gpt', 'Successful requests') }}   # 0

# Количество API-запросов с ошибками
{{ state_attr('sensor.ha_text_ai_gpt', 'Failed requests') }}       # 0

# Среднее время получения ответа от сервиса AI
{{ state_attr('sensor.ha_text_ai_gpt', 'Average latency') }}       # 0

# Максимальное время для одного цикла запрос-ответ
{{ state_attr('sensor.ha_text_ai_gpt', 'Max latency') }}           # 0
```

#### Использование диалога и токенов
```yaml
# Количество предыдущих взаимодействий, сохраненных в контексте
{{ state_attr('sensor.ha_text_ai_gpt', 'History size') }}          # 0

# Общее количество использованных токенов
{{ state_attr('sensor.ha_text_ai_gpt', 'Total tokens') }}          # 0

# Токены, использованные во входных промптах
{{ state_attr('sensor.ha_text_ai_gpt', 'Prompt tokens') }}         # 0

# Токены, использованные в ответах AI
{{ state_attr('sensor.ha_text_ai_gpt', 'Completion tokens') }}     # 0
```

#### Детали последнего взаимодействия
```yaml
# Самый последний полный ответ, сгенерированный сервисом AI
{{ state_attr('sensor.ha_text_ai_gpt', 'Response') }}        # Последний AI-ответ

# Последний обработанный пользовательский запрос
{{ state_attr('sensor.ha_text_ai_gpt', 'Question') }}        # Последний заданный вопрос

# Точный момент последнего взаимодействия
{{ state_attr('sensor.ha_text_ai_gpt', 'Last timestamp') }}  # Временная метка
```

#### Системное здоровье
```yaml
# Суммарное количество всех ошибок при взаимодействии с сервисом AI
{{ state_attr('sensor.ha_text_ai_gpt', 'Total errors') }}    # 0

# Указывает, проводится ли плановое или аварийное обслуживание
{{ state_attr('sensor.ha_text_ai_gpt', 'Is maintenance') }}  # false

# Общее время непрерывной работы сервиса AI (в часах или днях)
{{ state_attr('sensor.ha_text_ai_gpt', 'Uptime') }}          # 547,58
```

### 💡 Профессиональные советы
- Всегда проверяйте наличие атрибутов
- Используйте эти атрибуты для мониторинга и автоматизации
- Некоторые значения могут быть изначально равны 0 или быть пустыми

## 📘 Часто задаваемые вопросы

**В: Какие AI-провайдеры поддерживаются?**
О: В настоящее время поддерживаются OpenAI (модели GPT) и Anthropic (модели Claude), планируется расширение списка провайдеров.

**В: Как уменьшить расходы на API?**
О: Используйте GPT-3.5-Turbo или Claude-3-Sonnet для большинства запросов, внедрите кэширование и оптимизируйте использование токенов.

**В: Есть ли ограничения на количество запросов?**
О: Зависит от тарифного плана вашего API-провайдера. Рекомендуется отслеживать использование и реализовать ограничение запросов через параметр `request_interval`.

**В: Можно ли использовать пользовательские модели?**
О: Да, вы можете настроить пользовательские эндпоинты и использовать любую совместимую модель, указав её в конфигурации.

**В: Как переключаться между различными AI-провайдерами?**
О: Просто измените параметр модели в вашей конфигурации или при вызове сервиса для использования нужной модели провайдера.

**В: Насколько безопасны мои данные?**
О: Ваши данные в безопасности. Система работает полностью на вашем локальном компьютере, сохраняя контроль над данными. API-ключи хранятся защищённо, все внешние коммуникации используют зашифрованные соединения.

**В: Как работают контекстные сообщения?**
О: Контекстные сообщения позволяют AI помнить и ссылаться на предыдущую историю диалога. По умолчанию включаются 5 предыдущих сообщений, но вы можете настроить от 1 до 20 сообщений для контроля глубины разговора и использования токенов.

## 🤝 Участие в разработке

Мы всегда рады вашему вкладу! Пожалуйста, ознакомьтесь с [Руководством по участию](CONTRIBUTING.md).

1\. Создайте fork репозитория  
2\. Создайте ветку для функции (`git checkout -b feature/Улучшение`)  
3\. Зафиксируйте изменения (`git commit -m 'Добавить улучшение'`)  
4\. Отправьте ветку (`git push origin feature/Улучшение`)  
5\. Откройте Pull Request  

## 📝 Лицензия

MIT License - подробности в файле [LICENSE](LICENSE).

## 💡 Поддержите проект

Лучшая поддержка - это:
- Делитесь обратной связью
- Предлагайте идеи
- Рекомендуйте друзьям
- Сообщайте о проблемах
- Поставьте звезду репозиторию

Если хотите финансово поблагодарить, можете отправить небольшой токен признательности в USDT:

**USDT Кошелек (TRC10/TRC20):**
`TXC9zYHYPfWUGi4Sv4R1ctTBGScXXQk5HZ`

*Open-source создается страстью сообщества!* 🚀

---

<div align="center">

Создано с ❤️ и Claude 3.5 Sonnet для сообщества Home Assistant

[Сообщить об ошибке](https://github.com/smkrv/ha-text-ai/issues) · [Предложить функцию](https://github.com/smkrv/ha-text-ai/issues)

</div>