AMD迷你主机搭建Home Assistant本地AI语音助手完整指南

先说结论：一台 AMD 迷你主机完全可以作为 Home Assistant 的本地 AI 语音中枢。这里的“AI 语音助手”不是接云端大模型的那种，而是把语音识别、语义理解、语音合成三个环节全部落在局域网内，用 Wyoming 协议把 faster-whisper、Piper、Ollama 串起来，最后通过 Home Assistant 的 Assist Pipeline 做统一调用。它的核心价值是离线可用、数据不上云、组件可替换，而且不需要独立显卡。本文就是一套完整的实操记录，从 AMD 迷你主机的选型和环境准备开始，到 Docker Compose 部署、语音助手管道配置、功能验证、API 批量调用和问题排查，读者跟着走一遍，能得到一套可以长期跑的本地语音助手底座。

这套方案并不是一个“开箱即用的大一统项目”，而是把几类成熟的本地组件组合起来。最值得关注的几个点：整条语音链路在无公网环境下可用；AMD 迷你主机没必要追求高端显卡，CPU 和内存才是关键；所有服务都用 Docker Compose 管理，重启后能自动拉起；Home Assistant 自带 REST API，可以和自动化、脚本、通知联动；后续还能加 openWakeWord 唤醒词和 ESP32 语音卫星。配置较好的 AMD 迷你主机用户，比如 16GB 内存、256GB NVMe 的型号，会非常从容；只有 8GB 内存也能跑，但建议先跑 tiny 级别模型，不要同时开大语言模型和大型 Whisper 模型。

如果你正在纠结“要不要为了跑 Home Assistant 单独上一台迷你主机”，或者“本地语音助手是不是必须靠 NVIDIA 显卡”，这篇文章可以给你一个明确答案。下面按实际部署顺序来写：环境准备、服务编排、语音管道配置、功能测试、接口批量、资源观测、常见问题、最佳实践。

1. 核心能力速览

先看这套方案的整体规格：

这里需要说明一点：最终的显存、内存在不同主机上差异较大，尤其是 Ollama 加载不同尺寸的模型时差距很明显。上面的内存建议是通用判断，不是某个型号的固定参数。首次部署时可以先跑 tiny/int8 模型验证全链路，再根据实际负载升级模型。

2. 适用场景与使用边界

这套方案最适合的场景是“家庭内网里的私密语音助手”。智能家居控制、日历提醒、天气播报、定时任务、灯和空调开关，这些操作完全可以在本地完成。好处非常直接：录音、文本、对话历史都不需要传到外部服务，家里断网时语音链路依然可用。对于比较在意隐私的人，这是云端语音助手给不了的。

它不适合的场景也很明确：如果你要求中文语音识别准确率达到商业云端水平，或者要求语音助手能流畅回答复杂知识问答，本地小模型的表现会明显弱于云端大模型。faster-whisper 的 tiny/base 模型在嘈杂环境下会出错，Piper 的中文音色有限，Ollama 上的 1.5B 小模型也不适合做复杂推理。这套方案的定位是“可靠的家居自动化入口”，不是“万能聊天机器人”。

使用边界方面需要特别强调合规。如果你在家里部署语音采集设备，必须提前告知共同居住的家人，避免在卧室、卫生间等私密空间布置常驻麦克风。不要采集、保存或转发与当前任务无关的语音内容。涉及家庭成员声音、人脸、车牌等敏感信息时，必须获得明确授权。批量生成语音内容时，也要注意音色授权和内容版权，不能拿侵权素材做商业发布。

3. 环境准备与 AMD 迷你主机选型

3.1 硬件选型建议

AMD 迷你主机跑 Home Assistant 非常合适，因为 HA 本身就是 Python + 容器化的负载，吃的是单核性能和内存容量，对显卡完全无感。选购时可以重点关注以下几点：

• 内存：8GB 是底线，建议直接买 16GB，方便同时跑 HA、Whisper、Piper、Ollama。
• 存储：至少 64GB NVMe。HA 数据库和容器镜像会慢慢涨，128GB 更稳。
• 网口：千兆网口必备，双网口对未来做软路由或 VLAN 会更灵活。
• 功耗：迷你主机整体功耗低于传统台式机，但具体待机功耗要看型号，不能一概而论。
• 风扇噪音：放在客厅或卧室的设备，静音比性能更重要，预算内优先选被动散热或低转速风扇型号。

新一代 AMD 移动平台带 NPU，但 Home Assistant 不会默认调用 NPU，本地语音链路主要还是吃 CPU 和内存。为了 NPU 特意加预算，目前不太值得，先把 CPU 推理链路跑通再说。

3.2 系统版本与基础依赖

本文的部署环境以 Debian 12 / Ubuntu 22.04 为例。系统安装完成后，建议先做三件事：更新 apt 源、确认内核架构、确认磁盘空闲空间。

bash复制sudo apt update && sudo apt upgrade -y
uname -m
free -h
df -h

uname -m 输出 x86_64 即可确认是 64 位架构。Home Assistant 官方镜像、Wyoming 组件、Ollama 都有 x86_64 版本，AMD 迷你主机不存在架构兼容问题。

接着安装 Docker 和 Docker Compose 插件：

bash复制sudo apt install -y docker.io docker-compose-plugin
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

安装完先退出重新登录一次，让用户组生效。验证 Docker 是否可用：

bash复制docker --version
docker compose version

如果当前用户不在 docker 组里，后面所有命令都要加 sudo，比较容易出错。这一步建议先处理干净。

3.3 端口规划

本次方案主要用到这些端口，提前规划避免冲突：

如果主机上已经跑了其他服务，比如 8123 被占，可以在 Compose 文件里改映射端口，但需要同步调整 HA 的访问地址和集成配置。建议先执行 ss -lntp 检查端口占用。

4. Docker Compose 部署 Home Assistant 与语音组件

4.1 为什么不用 HAOS 镜像而是 Container

Home Assistant 有 HAOS 和 Docker Container 两种常见安装方式。HAOS 的好处是自带加载项商店，更新链路完整；坏处是它像一个专用系统，想在这台机器上同时跑 Ollama、其他自己写的服务，会比较受限。Container 部署则直接把 HA 当作一个普通容器，和 Whisper、Piper、Ollama 放在同一个 Compose 文件里，扩展和迁移都很方便。本次部署选择 Container 方式。

4.2 编写 docker-compose.yml

先建好目录结构：

bash复制mkdir -p ~/ha-stack && cd ~/ha-stack
touch docker-compose.yml

编辑 docker-compose.yml：

yaml复制services:
  homeassistant:
    container_name: homeassistant
    image: ghcr.io/home-assistant/home-assistant:stable
    restart: unless-stopped
    network_mode: host
    privileged: true
    volumes:
      - ./ha_config:/config
      - /etc/localtime:/etc/localtime:ro

  wyoming-whisper:
    container_name: wyoming-whisper
    image: ghcr.io/rhasspy/wyoming-faster-whisper:latest
    restart: unless-stopped
    network_mode: host
    command: --model tiny-int8 --language zh --device cpu
    volumes:
      - ./whisper-data:/data

  wyoming-piper:
    container_name: wyoming-piper
    image: ghcr.io/rhasspy/wyoming-piper:latest
    restart: unless-stopped
    network_mode: host
    command: --voice zh_CN-huayan-medium
    volumes:
      - ./piper-data:/data

  ollama:
    container_name: ollama
    image: ollama/ollama:latest
    restart: unless-stopped
    network_mode: host
    volumes:
      - ./ollama-data:/root/.ollama

这里采用了 network_mode: host，在 Linux 下配置最简单，多个容器直接共享宿主机网络，彼此通过 127.0.0.1 访问。如果你更习惯 bridge 网络，也可以不用 host 模式，但后面在 HA 里添加 Wyoming 集成和 Ollama 集成时，要填写宿主机局域网 IP，不能填 127.0.0.1，否则容器内部只会访问到自己。

privileged: true 不是 Home Assistant 的最小运行要求，但后面如果你要接入 USB 蓝牙适配器、Zigbee 设备或音频采集设备，保留这个配置可以少踩很多权限坑。只用纯局域网语音测试的话，去掉也能跑。

4.3 启动并检查日志

bash复制sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs -f homeassistant

首次启动时，Home Assistant 会拉取镜像并初始化数据库，日志会持续滚动。看到类似 Home Assistant initialized in ... 后，说明服务已经起来了。Wyoming 组件和 Ollama 也会同时启动，可以用 docker compose logs -f wyoming-whisper 单独观察模型下载进度。

faster-whisper 在第一次启动时会下载语音识别模型，Piper 会下载中文语音模型，Ollama 要等我们手动拉取模型。这些下载过程长短取决于网络环境，耐心等就行，中途不要直接删除容器。

4.4 拉取对话模型

Ollama 镜像启动后，先拉一个适合本地 CPU 推理的中文小模型。这里以 qwen2.5:1.5b 为例，大小在 1GB 级别，对迷你主机比较友好：

bash复制ollama pull qwen2.5:1.5b
ollama list

如果你用的是 Docker 启动的 Ollama，也可以直接进入容器执行。确认模型列表里有 qwen2.5:1.5b 后，后面在 Home Assistant 里添加 Ollama 集成时就能选到这个模型。

5. Home Assistant 初始化与语音助手配置

5.1 首次访问与账号创建

浏览器访问 http://你的迷你主机IP:8123，进入 Home Assistant 初始化页面。第一次会要求创建管理员账号、设置家庭名称和地理位置。这一步按实际环境填写即可，如果你不想上报位置信息，可以不启用相关功能。

初始化完成后，建议先在“设置 -> 系统 -> 重启”里重启一次，确认容器重启后 HA 能正常拉起。后面所有集成配置都在 Web UI 里完成，不需要手动改配置文件。

5.2 添加 Wyoming 集成

打开“设置 -> 设备与服务 -> 添加集成”，搜索 Wyoming Protocol。这里需要添加两次，一次指向 faster-whisper，一次指向 Piper。

第一次添加：服务器地址填 127.0.0.1，端口填 10300，端口类型是“语音转文本”，也就是 faster-whisper。添加成功后，Home Assistant 会把该服务识别为语音助手管道里的 STT 引擎。

第二次添加：同样选择 Wyoming Protocol，服务器地址还是 127.0.0.1，端口填 10200，端口类型是“文本转语音”，也就是 Piper。添加成功后，它会被识别为 TTS 引擎。

如果你把管道里的组件跑在另一台机器上，这里的地址必须改成那台机器的局域网 IP。确认端口能通，可以用以下命令从宿主机侧检查：

bash复制nc -zv 127.0.0.1 10300
nc -zv 127.0.0.1 10200

5.3 添加 Ollama 对话代理

继续在“设备与服务 -> 添加集成”里搜索 Ollama，填写服务地址 http://127.0.0.1:11434，模型选 qwen2.5:1.5b。这个集成会被 Home Assistant 当作“对话代理”，也就是 Assist Pipeline 里的 LLM 大脑。

添加完成后，可以先用对话框单独测试 Ollama，不涉及语音。直接在对话输入框里问“现在几点”，看它能否正确调用 HA 的实体状态。如果 Ollama 回复正常，说明对话链路已经通了一半。

5.4 创建 Assist 语音助手管道

打开“设置 -> 语音助手 -> 语音助手”，点“添加”。管道名称随意，关键是下面几个选项：

• 语音转文本：选择刚添加的 faster-whisper
• 文本转语音：选择刚添加的 Piper
• 对话代理：选择刚添加的 Ollama
• 唤醒词：可以先选择“无”，用点击按钮方式触发

保存后，这个管道就成为 Home Assistant 默认的语音助手。你可以在前端页面右下角找到 Assist 图标，点击后进入语音对话界面。此时只差最后的端到端测试。

6. 功能测试与效果验证

6.1 测试 Piper 文本转语音

最容易验证的是 TTS。在 Assist 对话框里输入一句话，让系统用语音播报，比如“你好，这是本地语音合成测试”。如果配置正确，Piper 会生成一段中文语音，并在浏览器或手机 App 上播放。

如果完全没有声音，先检查媒体播放器设备。Home Assistant 播放 TTS 需要有一个可用的 media player，比如浏览器内建播放、DLNA 音箱或 Chromecast。可以在“设置 -> 设备与服务”里确认有没有可用的媒体播放器实体。

6.2 测试 faster-whisper 语音转文字

在 Assist 对话框里点击麦克风按钮，对着麦克风说一句中文，比如“打开客厅灯”。此时 Home Assistant 会把音频发送给 faster-whisper，由它转成文字。成功时，对话框会显示识别出的文本，然后再交给 LLM 处理。

如果识别结果为空或者乱码，优先检查 faster-whisper 启动参数里的语言设置。command: --model tiny-int8 --language zh 里的 zh 就是中文语言指定。如果模型语言没有写对，英文模型会把中文强行识别成错误文本。

6.3 测试 Ollama 对话链路

不启用麦克风，直接在 Assist 对话框里输入中文文本，观察 Ollama 的回答能力。建议先用一个简单的状态查询测试，比如“客厅温度是多少”，让 HA 通过 Ollama 读取实体状态并组织回答。如果它答非所问，说明 Ollama 集成的对话代理没有正确获取 HA 上下文，可以在 Ollama 集成的系统提示词里补充一句“你是家庭智能助手，优先调用 Home Assistant 实体状态回答问题”。

6.4 完整语音链路测试

完整链路建议按以下顺序验证：

• 点击麦克风，说出“现在几点”
• 观察 Whisper 是否正确识别中文
• 观察 Ollama 是否返回文本回复
• 观察 Piper 是否合成语音并播放

四步都能完成，说明这条本地 AI 语音链路已经打通。如果中间某一步卡住，不要继续组合排查，先单独测试对应组件。语音链路最忌讳把 STT、TTS、LLM 三个问题混在一起定位。

6.5 判断链路是否成功的标准

一个比较客观的判断方法是看 Home Assistant 日志。打开“设置 -> 系统 -> 日志”，如果 Assistant Pipeline 执行过程中出现错误，日志里会明确记录是 STT 失败、TTS 失败还是对话代理失败。比如 Error rendering TTS audio 说明问题在 Piper，No wake word detected 说明问题在唤醒词阶段。日志比听感判断更准确。

7. 接口 API 与批量任务扩展

7.1 Home Assistant REST API 调用语音助手

Home Assistant 自带长期访问令牌，生成位置在“个人资料 -> 安全 -> 长期访问令牌”。拿到令牌后，可以通过 REST API 直接调用对话服务，效果等同于在 Assist 对话框里输入文本：

bash复制curl -X POST http://127.0.0.1:8123/api/services/conversation/process \
  -H "Authorization: Bearer 替换成你的长期访问令牌" \
  -H "Content-Type: application/json" \
  -d '{"text":"现在几点了"}'

返回内容会包含对话代理给出的回答。这个接口的意义在于，你可以把语音助手能力接入到自己的脚本、定时任务或者外部小程序里，而不一定非要在 HA 界面上操作。

7.2 Ollama API 批量文本处理

Ollama 的 /api/chat 接口可以直接用于批量文本处理，比如把一批日志文本、新闻摘要或待办事项交给本地模型整理。下面是一个 Python 调用模板：

python复制import requests
import json

url = "http://127.0.0.1:11434/api/chat"
payload = {
    "model": "qwen2.5:1.5b",
    "messages": [
        {"role": "system", "content": "你是文本整理助手，输出简洁摘要。"},
        {"role": "user", "content": "请把下面两条记录整理成待办项：买牛奶、取快递。"}
    ],
    "stream": False
}

response = requests.post(url, json=payload, timeout=120)
print(json.loads(response.text)["message"]["content"])

批量处理时要注意控制并发和超时时间。AMD 迷你主机用 CPU 推理小模型，同时跑多个请求会把 CPU 打满，反而拖慢整体速度。更稳妥的做法是循环串行处理，或者一次只放两到三个并发请求。

7.3 批量转写音频与批量生成 TTS

语音链路里同样能拆出批量任务。如果你有一段会议录音或者一批语音备忘录，可以用 faster-whisper 的 Python 脚本批量转写。下面是一个通用的目录遍历示例：

python复制from faster_whisper import WhisperModel

model = WhisperModel("tiny-int8", device="cpu", compute_type="int8")

import glob
for audio_file in glob.glob("/path/to/audio/*.wav"):
    segments, info = model.transcribe(audio_file, language="zh")
    text = " ".join(segment.text for segment in segments)
    print(f"{audio_file}: {text}")

Piper 也支持命令行批量生成语音。在容器内确认 piper 命令可用后，可以循环把多行文本合成到对应 wav 文件。需要注意，不同镜像里模型文件路径和命令参数可能不一样，建议先执行 docker exec -it wyoming-piper bash 进入容器，运行 piper --help 看一下实际参数。

bash复制echo "第一条通知内容" | piper --model zh_CN-huayan-medium --output_file /data/1.wav
echo "第二条通知内容" | piper --model zh_CN-huayan-medium --output_file /data/2.wav

批量任务建议遵循三个原则：输出文件按日期分目录；每条任务记录成功失败状态；失败后重试或标记，不要静默跳过。

8. 资源占用与性能观察

8.1 用 docker stats 观察容器负载

部署完成后，最直接的资源观测方式是：

bash复制docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}"

以一台 16GB 内存的 AMD 迷你主机为例，Home Assistant 基础容器、Piper、faster-whisper tiny 模型同时运行时，内存占用通常在一个可控范围内。但具体占用会因 HA 自动化数量、设备集成数量、模型大小和并发任务数而明显变化，因此这里不写死数字。你需要自己观察基线，比如服务刚启动后记录一轮 docker stats，再在跑完一条语音指令后记录一轮，两者对比就能看出哪个组件吃资源。

8.2 Ollama 模型内存占用观察

Ollama 提供了专门的模型占用查询命令：

bash复制ollama ps

输出会列出当前加载到内存中的模型、大小和进程。qwen2.5:1.5b 这类小模型对现代 AMD 迷你主机压力不大，但如果同时加载了 7B 甚至更大的模型，8GB 内存的主机会比较勉强。判断标准以 ollama ps 显示的实际占用为准，不要只凭模型文件大小猜。

8.3 CPU 推理与并发的关系

本地语音链路对 CPU 的消耗集中在两个场景：faster-whisper 推理录音片段，Ollama 推理对话文本。faster-whisper 的 tiny-int8 模型在迷你主机上很快，但 small、medium 模型会明显变慢。Ollama 这边，模型的参数量越大，每条回复等待时间越长。如果既想保留识别准确率，又想控制等待时间，可以把 Whisper 提升到 base-int8，LLM 保持 1.5B 级别，这是资源占用和体验比较均衡的组合。

8.4 降低资源占用的手段

• 语音识别模型先用 tiny-int8，后续根据准确率逐步升级。
• Piper 只加载一个中文音色，不要同时挂多个语音。
• Ollama 设置 OLLAMA_KEEP_ALIVE 较短，避免长期把模型驻留内存。
• HA 的历史数据定期清理，避免 SQLite 数据库无限膨胀。
• 不用的集成尽量关闭，每多几十个实体都会影响启动时间和内存占用。

9. 常见问题与排查方法

如果你是第一次部署，遇到问题后先做一件事：看日志。docker compose logs -f homeassistant 和 docker compose logs -f wyoming-whisper 基本能覆盖 90% 的问题。不要反复重启容器但不看输出，那样会漏掉真正的报错信息。

10. 最佳实践与使用建议

10.1 目录与配置管理

建议把所有配置文件收敛到一个目录下，比如 ~/ha-stack，里面分成 ha_config、whisper-data、piper-data、ollama-data 子目录。这样迁移主机时，只打包这个目录就能带走整套服务。HA 的配置会在 ha_config 下生成 configuration.yaml，建议把它纳入 Git 管理，每次改动后有可回滚版本。

10.2 版本锁定的取舍

容器镜像建议先用 latest 跑通全链路，之后再根据实际体验锁定版本。Home Assistant 更新频率较高，固定一个大版本可以减少重启风险。Ollama、Wyoming 组件同样如此。生产环境不要盲目每天升级，升级前先看 changelog 和社区反馈。

10.3 安全与隐私

默认情况下，Home Assistant 会绑定所有网卡，局域网内其他设备都能访问 8123。如果你想限制访问，可以在 HA 前面加一层反向代理，并用防火墙只放行必要端口。不要把 8123 端口直接暴露到公网。语音数据建议保留在本地磁盘，录音文件定期清理。涉及家人的语音和图像素材，必须确认知情同意。

10.4 性能与体验优化路径

先跑通最小链路，再逐步优化：第一次部署全部开默认参数，验证语音识别、TTS、对话代理三条基础能力都通；之后根据实际效果把 Whisper 从 tiny 换到 base；再给 Assist Pipeline 开 openWakeWord 唤醒词；最后考虑用 ESP32 做分布式语音卫星，放到不同房间。这样每一步改动都能定位到具体变化，不会出现“全部升级完反而不能用了”的情况。

10.5 自动化联动建议

本地语音助手的最终价值要和自动化绑定。比如设置一条自动化：用户说“晚安”，语音助手调用 Ollama 理解语义后，由 HA 关闭客厅灯、锁门、播报明日天气，再播放助眠音乐。这样多步骤场景比单纯一问一答更有家用价值。建议先用 HA 自带的自动化编辑器搭一个简单场景，再逐步增加实体判断和条件分支。

11. 总结与下一步

这次在 AMD 迷你主机上搭建 Home Assistant 本地 AI 语音助手，最有价值的点就是整条语音链路完全可控、离线可用，所有关键组件都跑在自家局域网里。最先值得验证的功能不是复杂对话，而是 TTS 和 STT 这两条基础链路，因为它们决定“听不听得见、听不听得准”。最容易踩坑的也是中文语音模型和容器网络模式：模型语言设置不对会识别乱码，集成地址填错会导致服务找不到。

建议按“最小配置跑通、后面逐步升级”的顺序来做。先用 tiny-int8 Whisper、Piper 中文音色、qwen2.5:1.5b 跑通一条完整指令，再考虑更大的模型和唤醒词。后续可以扩展的方向包括 openWakeWord 本地点名唤醒、ESP32 语音卫星、多房间媒体播放器联动、更可靠的中文 TTS 音色，以及把更多 HA 自动化场景接入对话代理。整套部署流程不算复杂，但对目录结构、端口、模型语言和日志检查这四个点要求比较高。有了一台 AMD 迷你主机之后，这套本地智能语音方案值得作为长期项目慢慢打磨。建议收藏备用，方便下次重建时直接对照。