方案简介

GPT Home 是一个在 Raspberry Pi 上自建语音家庭助手的开源项目，目标是做出比 Google Nest Hub 或 Amazon Alexa 更好的家庭助手。项目基于 LiteLLM 和 LangGraph 构建，通过 Docker 容器化部署，理论上可运行在任何 Linux 系统上。它集成了 OpenAI、Spotify、Philips Hue、OpenWeatherMap、Open-Meteo、CalDAV 日历等服务，支持天气查询、闹钟、提醒、日历、待办、通用知识问答、翻译、音乐、灯光控制和趣味游戏等用例，还支持持久记忆和屏幕显示。适合喜欢动手 DIY、注重隐私、想拥有可自定义语音助手并持有树莓派等硬件的玩家。

亮点与能力

• 接入 LiteLLM，支持 100+ 模型提供商（OpenAI、Anthropic、Google、Cohere 等）
• 集成 Spotify 音乐控制
• 集成 Philips Hue 灯光控制
• 集成 OpenWeatherMap / Open-Meteo 天气查询
• 闹钟、提醒、CalDAV 日历与待办清单
• 持久记忆（Persistent Memory）
• 显示屏支持（I2C / SPI / HDMI 触摸屏）
• 通过 Web 界面 gpt-home.local/settings 配置 API Key

前置要求

硬件要求（规格表）：

| | Minimum | Recommended |
|---|---|---|
| Board | Raspberry Pi Zero 2 W | Raspberry Pi 4B / 5 |
| CPU | Quad-core ARM Cortex-A53 @ 1GHz | Quad-core ARM Cortex-A72 @ 1.5GHz+ |
| RAM | 512MB | 1GB+ |
| Storage | 16GB microSD | 32GB+ microSD |
| OS | Raspberry Pi OS Lite (64-bit) | Ubuntu Server (64-bit) |

作者使用的核心配件：Raspberry Pi 4B、Mini Speaker、USB 2.0 Mini Microphone、microSD 卡。也可使用 Whisplay HAT、RaspiAudio Ultra++ 等音频扩展板，以及可选的 I2C/SPI/HDMI 显示屏和 UPS 电源。

注意：不要把电池直接接在树莓派上，应使用带电池的 UPS 或电源，否则电压波动可能损坏主板。

实施步骤

1. 运行安装脚本（生产环境，树莓派）

bash
curl -s https://raw.githubusercontent.com/judahpaul16/gpt-home/main/contrib/setup.sh | \
bash -s -- --no-build

脚本会自动安装 Docker、时间同步等全部系统依赖。

2. 配置 API Key（必需）

bash
cd ~/gpt-home
cp .env.example .env
sed -i 's/^LITELLM_API_KEY=$/LITELLM_API_KEY=your-api-key-here/' .env
docker compose down && docker compose up -d

3. 查看日志验证运行（可选）

bash
docker compose logs -f

开发环境（任意机器）

bash
git clone https://github.com/judahpaul16/gpt-home.git
cd gpt-home
cp .env.example .env

Edit .env with your API keys

nano .env

Start dev environment with hot reload

COMPOSE_PROFILES=dev docker compose up

or

docker compose --profile dev up

访问 http://localhost（nginx 将流量路由到前端和 API）。

使用与配置要点

• 生产环境启动后，可通过 Web 界面 gpt-home.local/settings 设置 API Key
• 查看支持的模型提供商列表参考 LiteLLM 文档 docs.litellm.ai/docs/providers
• 用 docker compose logs -f 验证助手是否正常运行
• 集成服务（Spotify、Philips Hue、天气、日历等）按需在配置中启用对应 API Key
• 3.5" PiScreen 显示屏（SPI, ILI9486）会被安装脚本自动检测

注意事项与常见问题

• ⚠️ 电池切勿直接连接树莓派，必须使用 UPS 或带电池的电源，否则电压波动可能损坏板子；接线前确认极性正确，改动前断开电源
• 兼容性：理论上任何 Linux 均可运行（得益于 Docker），但作者只对兼容性表中列出的版本作担保
• Wi-Fi 若不通过以太网连接，可用项目自带的 Wi-Fi 配置脚本，它会配置 wpa_supplicant + systemd-networkd、禁用 NetworkManager、设置 DNS 并关闭 Wi-Fi 省电：

bash
curl -s https://raw.githubusercontent.com/judahpaul16/gpt-home/main/contrib/wifi-setup.sh | \
sudo WIFI_SSID="your-ssid" WIFI_PSK="your-password" bash

• 也可交互式运行（提示输入 SSID 和密码），可按需设置 WIFI_IFACE（默认 wlan0）和 WIFI_COUNTRY（默认 US）
• 深入的架构与 API 文档见项目 Wiki

优缺点

• ✓ 支持 100+ 模型提供商
• ✓ 任意 Linux 可跑，部署简单
• ✕ 依赖云端 API 密钥
• ✕ 仅验证过部分硬件版本

出处

本方案挖掘自开源项目 judahpaul16/gpt-home，方案内容与实施命令均来自其 README 原文。