Русский перевод README

2026-07-21 22:54:00 +08:00 · 2024-11-26 15:30:07 +03:00
parent d618feffff
commit c61c4570b0
1 changed files with 390 additions and 0 deletions
@@ -0,0 +1,390 @@
+# 🤖 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>