### Расширенная AI-интеграция для Home Assistant с поддержкой нескольких провайдеров
### Расширенная AI-интеграция для Home Assistant с поддержкой нескольких провайдеров
Преобразите свой умный дом с мощной AI-поддержкой от множества провайдеров, включая модели OpenAI GPT и Anthropic Claude. Получайте интеллектуальные ответы, автоматизируйте сложные сценарии и улучшайте домашнюю автоматизацию с помощью передовой обработки естественного языка.
--- > [!IMPORTANT] > 🚧 АЛЬФА-ВЕРСИЯ 🚧 > Ожидайте: возможные ошибки, частые изменения, незавершенные функции. > 🤝 Разработка силами сообщества > >
## 🌟 Возможности
- 🧠 **Мультипровайдерная 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 (Рекомендуется)
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 создается страстью сообщества!* 🚀
---