DeepSeek Home Assistant Integration

A community Home Assistant integration that brings the DeepSeek API to your smart home — conversation agent plus a deepseek.generate service for automations. Not affiliated with DeepSeek.

Features

• 🤖 Conversation Agent: Use DeepSeek as your Home Assistant voice/chat assistant
• 🔧 Config Flow: Easy UI-based setup - no YAML required
• 🎯 Multiple Models: Support for deepseek-chat, deepseek-reasoner, deepseek-coder
• 💭 Reasoning Support: Optional reasoning display with deepseek-reasoner model
• 🌐 Multi-language: Support for all languages DeepSeek understands
• ⚡ Fast & Efficient: Async implementation with proper error handling
• 🔌 OpenAI-Compatible: Uses DeepSeek's OpenAI-compatible API

Installation

HACS (Recommended)

1. Open HACS in Home Assistant
2. Click "Integrations"
3. Click the "+" button (Explore & Add Repositories)
4. Search for "DeepSeek"
5. Click "Install"
6. Restart Home Assistant

Manual Installation

1. Copy the custom_components/deepseek folder to your Home Assistant custom_components directory
2. Restart Home Assistant
3. Go to Settings → Devices & Services → Add Integration
4. Search for "DeepSeek"

Configuration

Getting an API Key

1. Visit DeepSeek Platform
2. Sign up or log in
3. Go to API Keys section
4. Create a new API key
5. Copy the key (you'll only see it once!)

Setup Steps

1. Add Integration: Go to Settings → Devices & Services → Add Integration → Search "DeepSeek"
2. Enter API Key: Paste your DeepSeek API key
3. Configure Options (optional):
   • Model: Choose between deepseek-chat, deepseek-reasoner, or deepseek-coder
   • Max Tokens: Response length limit (default: 2048)
   • Temperature: Creativity level (0.0-2.0, default: 0.7)
   • Show Reasoning: Display reasoning steps (only for deepseek-reasoner)
4. Complete: The integration is now ready!

Usage

As a Conversation Agent

Once installed, DeepSeek becomes available as a conversation agent:

• Voice Commands: "Hey Assistant, ask DeepSeek what's the weather forecast"
• Chat Interface: Use the chat feature in Home Assistant
• Automations: Trigger DeepSeek responses in automations

AI Task entity (recommended)

The integration registers a Home Assistant AI Task entity so it can be selected from the AI-Task picker in the visual automation editor and used with the standard ai_task.generate_data action. This is the recommended way to integrate DeepSeek into modern automations.

Plain-text generation

- action: ai_task.generate_data
  data:
    task_name: weather_summary
    instructions: >-
      Today's forecast: {{ states('weather.home') }},
      high {{ state_attr('weather.home', 'temperature') }}°C.
      Summarise it in one short sentence.
    entity_id: ai_task.deepseek
  response_variable: result
- action: notify.mobile_app
  data:
    message: "{{ result.data }}"

Structured (JSON) output

Pass a structure: schema and the integration will set DeepSeek's response_format=json_object, so the model replies with parseable JSON, which the framework returns as a dict in result.data.

- action: ai_task.generate_data
  data:
    task_name: forecast_extract
    instructions: >-
      From this forecast — {{ states('weather.home') }} — produce
      structured data.
    entity_id: ai_task.deepseek
    structure:
      summary:
        selector:
          text:
      high_c:
        selector:
          number:
      rain_chance_percent:
        selector:
          number:
  response_variable: result
- action: persistent_notification.create
  data:
    message: "{{ result.data.summary }} (rain {{ result.data.rain_chance_percent }}%)"

If DeepSeek returns something that isn't valid JSON for a structured task, the automation step fails with a clear DeepSeek returned a non-JSON response for a structured task error rather than silently mis-parsing.

Service: deepseek.generate (legacy alternative)

For one-off prompts or when you don't want a target entity, the deepseek.generate action is still available and unchanged. The AI Task entity above is the recommended path going forward.

Use DeepSeek as a building block in automations, scripts, and other integrations. The service takes a prompt and returns the model's reply, which you can capture into a variable with response_variable and use in subsequent steps.

Fields

Field	Type	Required	Description
prompt	string	yes	The user message sent to the model.
system_prompt	string	no	Optional system instructions placed before the prompt.
model	string	no	Override the model configured for this entry (deepseek-v4-flash, etc.).
max_tokens	int	no	Maximum tokens to generate (1–8192).
temperature	float	no	Sampling temperature (0–2).
top_p	float	no	Nucleus sampling threshold (0–1).
config_entry	string	no	Specific DeepSeek entry to use, when more than one is configured.

Response

text: "The model's reply..."
model: "deepseek-v4-flash"
finish_reason: "stop"
usage:
  prompt_tokens: 24
  completion_tokens: 86
  total_tokens: 110

Example: morning weather summary

automation:
  - alias: Morning weather summary
    trigger:
      - platform: time
        at: "07:00:00"
    action:
      - service: deepseek.generate
        data:
          system_prompt: >-
            You are a concise weather presenter. Reply in one short sentence.
          prompt: >-
            Today's forecast: {{ states('weather.home') }},
            high {{ state_attr('weather.home', 'temperature') }}°C,
            wind {{ state_attr('weather.home', 'wind_speed') }} km/h.
        response_variable: weather_reply
      - service: notify.mobile_app
        data:
          message: "{{ weather_reply.text }}"

Example: smart device-status update

script:
  living_room_status:
    sequence:
      - service: deepseek.generate
        data:
          model: deepseek-v4-pro
          temperature: 0.3
          prompt: >-
            Lights: {{ states('light.living_room') }}.
            Temperature: {{ states('sensor.living_room_temperature') }}°C.
            Write a friendly one-line status update for the living room.
        response_variable: status
      - service: tts.cloud_say
        data:
          entity_id: media_player.living_room
          message: "{{ status.text }}"

You can also call the service directly from Developer Tools → Actions to test prompts and see the full response object.

Models

Available Models

1. deepseek-chat (Default)
   • DeepSeek-V3-class model in non-thinking mode — works cleanly with this integration's plain chat-completions API.
   • Recommended for everyday conversations and Assist tool calling.
2. deepseek-reasoner
   • DeepSeek-R1-class model in non-thinking mode.
   • Reasonable choice for harder questions where you want the larger model.
3. deepseek-v4-flash (advanced — opt-in, see caveat below)
4. deepseek-v4-pro (advanced — opt-in, see caveat below)

Caveat for the deepseek-v4-* models: these run in DeepSeek's thinking mode by default and stream a reasoning_content field that must be re-fed on every follow-up turn. This integration does not yet round-trip that field, so multi-turn conversations with a v4 model fail with 400 — reasoning_content in the thinking mode must be passed back to the API. Stick to deepseek-chat / deepseek-reasoner until v4 thinking-mode support lands.

Model selection tips

• General use / Assist: deepseek-chat
• Complex reasoning: deepseek-reasoner
• Creative tasks: higher temperature (0.8–1.2)
• Precise / factual tasks: lower temperature (0.2–0.5)

Troubleshooting

Common Issues

"Invalid API key"

• Ensure you copied the key correctly
• Check if the key has expired
• Verify you have API access on DeepSeek Platform

"Cannot connect"

• Check your internet connection
• Verify DeepSeek API status at status.deepseek.com
• Ensure your firewall allows connections to api.deepseek.com

"No response"

• Check the logs for detailed errors
• Verify the model is available in your region
• Ensure you have sufficient API credits

Logs

Enable debug logging for detailed information:

logger:
  default: info
  logs:
    custom_components.deepseek: debug

Development

Project Structure

custom_components/deepseek/
├── __init__.py              # Main integration setup
├── manifest.json           # Integration metadata
├── config_flow.py          # UI configuration
├── const.py               # Constants
├── conversation.py        # Conversation agent
├── strings.json           # UI strings
├── translations/          # Translations
│   └── en.json
├── services.yaml          # Service definitions
└── README.md             # This file

Testing

# Run validation
hassfest validate

# Test with Home Assistant dev container
hass --script ensure_config

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run validation tests
5. Submit a pull request

Privacy & Security

• API Keys: Stored securely in Home Assistant's config
• Data: Conversations are sent to DeepSeek's API
• No Local Storage: No conversation data is stored locally
• Rate Limiting: Built-in rate limit handling

Refer to DeepSeek's Privacy Policy for more information.

Support

• GitHub Issues: Report bugs or request features
• Documentation: DeepSeek API Docs
• Community: Home Assistant Community

License

MIT License - see LICENSE file for details.

Acknowledgments

• Community-built integration, not affiliated with DeepSeek.
• Uses the OpenAI Python client against the DeepSeek-compatible API at https://api.deepseek.com.
• Thanks to all contributors and testers.

---

DeepSeek: Making AI accessible for everyone's smart home. 🏠✨