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)

  <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>

---

> [!ВАЖНО]
> 🚧 АЛЬФА-ВЕРСИЯ 🚧
> Ожидайте: возможные ошибки, частые изменения, незавершенные функции.
> 🤝 Разработка силами сообщества
>
>  <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 2023.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>