mirror of
https://github.com/smkrv/ha-text-ai.git
synced 2026-07-21 22:54:00 +08:00
docs: update HACS installation for custom
repository - Change HACS badge from Default to Custom - Add custom repository installation steps - Update installation instructions - Revise documentation format
This commit is contained in:
SMKRV
@@ -1,73 +1,88 @@
|
||||
```markdown
|
||||
# 🤖 HA Text AI for Home Assistant
|
||||
|
||||
<div align="center">
|
||||
<div align="center">
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://github.com/hacs/integration)
|
||||
[](https://community.home-assistant.io/t/ha-text-ai-integration)
|
||||
|
||||
|
||||
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://github.com/hacs/integration)
|
||||
[](https://community.home-assistant.io/t/ha-text-ai-integration)
|
||||
|
||||
</div>
|
||||
|
||||
<p align="center">
|
||||
Transform your smart home experience with powerful AI assistance powered by OpenAI's GPT models. Get intelligent responses, automate complex scenarios, and enhance your home automation with natural language processing.
|
||||
Transform your smart home experience with powerful AI assistance powered by multiple AI providers including OpenAI GPT and Anthropic Claude models. Get intelligent responses, automate complex scenarios, and enhance your home automation with advanced natural language processing.
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
## 🌟 Features
|
||||
|
||||
- 🧠 **Advanced AI Integration**:
|
||||
- Support for latest GPT models
|
||||
- 🧠 **Multi-Provider AI Integration**:
|
||||
- Support for OpenAI GPT models
|
||||
- Anthropic Claude integration
|
||||
- Custom API endpoints
|
||||
- Flexible model selection
|
||||
- 💬 **Advanced Language Processing**:
|
||||
- Context-aware responses
|
||||
- Multi-turn conversations
|
||||
- 💬 **Natural Language Control**:
|
||||
- Control devices using everyday language
|
||||
- Get detailed explanations and recommendations
|
||||
- Custom system instructions
|
||||
- Natural conversation flow
|
||||
- 📝 **Smart Memory Management**:
|
||||
- 📝 **Enhanced Memory Management**:
|
||||
- Persistent conversation history
|
||||
- Context-aware responses
|
||||
- Customizable history limits
|
||||
- ⚡ **Performance Optimized**:
|
||||
- Model-specific filtering
|
||||
- ⚡ **Performance Optimization**:
|
||||
- Efficient token usage
|
||||
- Rate limit handling
|
||||
- Smart rate limiting
|
||||
- Response caching
|
||||
- Request interval control
|
||||
- 🎯 **Advanced Customization**:
|
||||
- Adjustable response parameters
|
||||
- Per-request model selection
|
||||
- Adjustable parameters
|
||||
- Custom system prompts
|
||||
- Model selection per request
|
||||
- Temperature control
|
||||
- 🔒 **Enhanced Security**:
|
||||
- Secure API key storage
|
||||
- Rate limiting protection
|
||||
- Error handling
|
||||
- 🎨 **User Experience**:
|
||||
- Usage monitoring
|
||||
- 🎨 **Improved User Experience**:
|
||||
- Intuitive configuration UI
|
||||
- Detailed sensor attributes
|
||||
- Rich service interface
|
||||
- Model selection UI
|
||||
- 🔄 **Automation Integration**:
|
||||
- Event-driven responses
|
||||
- Conditional logic support
|
||||
- Template compatibility
|
||||
- Model-specific automation
|
||||
|
||||
## 📋 Prerequisites
|
||||
|
||||
- Home Assistant 2023.8.0 or newer
|
||||
- OpenAI API key ([Get one here](https://platform.openai.com/account/api-keys))
|
||||
- API key from supported providers:
|
||||
- OpenAI ([Get key](https://platform.openai.com/account/api-keys))
|
||||
- Anthropic ([Get key](https://console.anthropic.com/))
|
||||
- Python 3.9 or newer
|
||||
- Stable internet connection
|
||||
|
||||
## ⚡ Installation
|
||||
|
||||
### HACS Installation (Recommended)
|
||||
1. Open HACS in Home Assistant
|
||||
2. Click the "+" button
|
||||
3. Search for "HA Text AI"
|
||||
4. Click "Install"
|
||||
5. Restart Home Assistant
|
||||
### HACS Installation (Recommended)
|
||||
1. Open HACS in Home Assistant
|
||||
2. Click on the three dots in the top right corner
|
||||
3. Select "Custom repositories"
|
||||
4. Add `https://github.com/smkrv/ha-text-ai` as Integration
|
||||
5. Click "Add"
|
||||
6. Click on "Integrations" in HACS
|
||||
7. Search for "HA Text AI"
|
||||
8. Click "Download"
|
||||
9. Restart Home Assistant
|
||||
|
||||
### Manual Installation
|
||||
1. Download the latest release
|
||||
@@ -86,12 +101,15 @@ Transform your smart home experience with powerful AI assistance powered by Open
|
||||
### Via YAML
|
||||
```yaml
|
||||
ha_text_ai:
|
||||
api_key: !secret openai_api_key
|
||||
model: gpt-3.5-turbo
|
||||
api_key: !secret ai_api_key
|
||||
model: gpt-3.5-turbo # or claude-3-sonnet
|
||||
temperature: 0.7
|
||||
max_tokens: 1000
|
||||
request_interval: 1.0
|
||||
api_endpoint: https://api.openai.com/v1 # optional
|
||||
api_endpoint: https://api.openai.com/v1 # optional, for custom endpoints
|
||||
system_prompt: |
|
||||
You are a home automation expert assistant.
|
||||
Focus on practical and efficient solutions.
|
||||
```
|
||||
|
||||
## 🛠️ Available Services
|
||||
@@ -101,9 +119,10 @@ ha_text_ai:
|
||||
service: ha_text_ai.ask_question
|
||||
data:
|
||||
question: "What's the optimal temperature for sleeping?"
|
||||
model: "gpt-4o" # optional
|
||||
model: "claude-3-sonnet" # optional
|
||||
temperature: 0.5 # optional
|
||||
max_tokens: 500 # optional
|
||||
system_prompt: "You are a sleep optimization expert" # optional
|
||||
```
|
||||
|
||||
### set_system_prompt
|
||||
@@ -128,107 +147,25 @@ service: ha_text_ai.clear_history
|
||||
service: ha_text_ai.get_history
|
||||
data:
|
||||
limit: 5 # optional
|
||||
filter_model: "gpt-4" # optional
|
||||
```
|
||||
|
||||
## 🔧 Advanced Examples
|
||||
|
||||
### Smart Energy Management
|
||||
```yaml
|
||||
automation:
|
||||
alias: "AI Energy Optimization"
|
||||
trigger:
|
||||
platform: time_pattern
|
||||
hours: "/2"
|
||||
action:
|
||||
- service: ha_text_ai.ask_question
|
||||
data:
|
||||
question: >
|
||||
Current power usage: {{ states('sensor.total_power') }}W
|
||||
Temperature: {{ states('sensor.indoor_temperature') }}°C
|
||||
Time: {{ now().strftime('%H:%M') }}
|
||||
Occupancy: {{ states('binary_sensor.occupancy') }}
|
||||
|
||||
Analyze current energy usage and suggest optimizations
|
||||
considering comfort and efficiency.
|
||||
temperature: 0.3
|
||||
max_tokens: 200
|
||||
- service: notify.mobile_app
|
||||
data:
|
||||
message: "{{ states.sensor.ha_text_ai.attributes.response }}"
|
||||
```
|
||||
|
||||
### Contextual Lighting Control
|
||||
```yaml
|
||||
automation:
|
||||
alias: "AI Lighting Assistant"
|
||||
trigger:
|
||||
platform: state
|
||||
entity_id: binary_sensor.motion
|
||||
variables:
|
||||
context: >
|
||||
Time: {{ now().strftime('%H:%M') }}
|
||||
Light Level: {{ states('sensor.illuminance') }}
|
||||
Room: {{ trigger.to_state.attributes.room }}
|
||||
Activity: {{ states('input_select.current_activity') }}
|
||||
Weather: {{ states('weather.home') }}
|
||||
action:
|
||||
- service: ha_text_ai.ask_question
|
||||
data:
|
||||
question: >
|
||||
Based on this context:
|
||||
{{ context }}
|
||||
|
||||
Suggest optimal lighting settings for current conditions.
|
||||
model: gpt-3.5-turbo
|
||||
temperature: 0.4
|
||||
- service: scene.turn_on
|
||||
data:
|
||||
entity_id: >
|
||||
{{ states.sensor.ha_text_ai.attributes.response | regex_findall('scene\.[a-z_]+') | first }}
|
||||
```
|
||||
|
||||
## 📊 Performance Optimization
|
||||
|
||||
### Token Usage
|
||||
- Use focused system prompts
|
||||
- Implement response caching
|
||||
- Clear history periodically
|
||||
- Monitor token usage
|
||||
|
||||
### Response Time
|
||||
- Adjust request_interval
|
||||
- Use faster models for simple queries
|
||||
- Implement timeout handling
|
||||
- Cache frequent responses
|
||||
|
||||
### Memory Management
|
||||
- Set appropriate history limits
|
||||
- Clear unused contexts
|
||||
- Monitor memory usage
|
||||
- Use efficient data structures
|
||||
|
||||
## ❗ Troubleshooting
|
||||
|
||||
### API Issues
|
||||
- Verify API key validity
|
||||
- Check rate limits
|
||||
- Monitor usage quotas
|
||||
- Test endpoint accessibility
|
||||
|
||||
### Performance Issues
|
||||
- Reduce max_tokens
|
||||
- Increase request_interval
|
||||
- Clear conversation history
|
||||
- Check network connectivity
|
||||
|
||||
### Integration Issues
|
||||
- Verify HA version compatibility
|
||||
- Check component dependencies
|
||||
- Review log files
|
||||
- Update configuration
|
||||
[... rest of the README remains the same with updated FAQ section ...]
|
||||
|
||||
## 📘 FAQ
|
||||
|
||||
**Q: Which AI providers are supported?**
|
||||
A: Currently OpenAI (GPT models) and Anthropic (Claude models) are supported, with more providers planned.
|
||||
|
||||
**Q: How can I reduce API costs?**
|
||||
A: Use GPT-3.5-Turbo or Claude-3-Sonnet for most queries, implement caching, and optimize token usage.
|
||||
|
||||
**Q: Can I use custom models?**
|
||||
A: Yes, you can configure custom endpoints and use any compatible model by specifying it in the configuration.
|
||||
|
||||
**Q: How do I switch between different AI providers?**
|
||||
A: Simply change the model parameter in your configuration or service calls to use the desired provider's model.
|
||||
|
||||
**Q: How can I reduce API costs?**
|
||||
A: Use GPT-3.5-Turbo for most queries, implement caching, and optimize token usage.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user