树莓派语音助手 PI-Assistant

🗺️ 更新日志

[2026/1/30]

• 添加火山引擎（豆包）语音识别及语音合成方案，支持流式
• 添加豆包对话大模型接口
• 重新整理了项目结构

[2025/3/14]

• 添加跨平台的语音唤醒方案 Porcupine ，识别效果更佳
• 不涉及硬件的功能均可在Windows上运行，运行环境Python3.9(64bit)及以上

💡 功能列表

• 多模型接入：可选DeepSeek/OpenAi/豆包大模型等，支持聊天上下文
• 可选流式生成：模型流式输出内容，TTS音频流式传输
• 支持多种唤醒方式：语音唤醒，局域网消息唤醒，外设模块唤醒，远程唤醒
• 语音端点检测：自动检测语音截止点
• 语音识别：支持在线与离线双模式
• 文字转语音：舒适的人声
• 接续对话：完成交互对话全程只需唤醒一次
• 支持对话中断：可在任意时刻打断对话，重新提问
• 聊天记忆：在程序结束后保存聊天内容，重新运行时自动加载
• 通知播报：手机上接收的消息（熄屏时）以自定义格式播报
• 音乐播放：获取QQ音乐个性推荐，支持调整音量，切换，暂停
• 音频闪避：在聊天交互/通知播报时自动减小音乐音量
• 日程设定：支持设定闹钟/倒计时，以及提醒事项
• WebUI调参：可通过电脑和手机登录网页调参
• 外设控制：支持接入自定义设备（MQTT协议），配置相关文件可实现自动化
• 自动化智能家居：传入自定义状态，支持自定义场景触发自定义动作
• 远程控制：支持广域网MQTT设备控制
• HomeAssistant：支持通过API控制HA下的设备
• 模型调度：支持向模型输入状态（模糊）控制设备，配合HA完成智能家居控制

🎁 安装

Python模块安装

pip install azure-cognitiveservices-speech loguru requests arcade RPi.GPIO pydub numpy sounddevice pymysql cn2an duckduckgo_search flask SpeechRecognition openai pyaudio websocket-client paho-mqtt 'volcengine-python-sdk[ark]'

具体库版本可参考requirements.txt文件

Azure认知服务&&豆包语音服务

为了使用语音识别以及文字转语音，选择注册微软Azure/豆包，获取APIkey

硅基流动云服务/GPT服务/星火API/豆包

为了生成对话文本，需要注册硅基流动/OpenAI/讯飞星火账号/豆包（四选一），并获取APIkey

Nodejs安装(可选)

为了使用音乐播放功能，需要安装Node.js，默认qq号 1234567 ，修改 bin/config.js 为自己的QQ号 , 安装完成后可在QQMusicApi路径下运行npm start 测试结果（具体使用可参考QQMusicApi文档站以及if_music.py）

Mysql数据库安装(可选)

为了实现日程提醒功能，需要安装Mysql数据库，安装并后台运行，对应schedule.py文件，以下是一些参考命令：

show databases;
create database schedule;
use schedule;
create table main (id int(11)primary key, time int(11),content varchar(50));
alter table main modify column id int(11) AUTO_INCREMENT;
CREATE USER 'remote'@'%' IDENTIFIED BY '123456';
GRANT ALL ON schedule.* TO 'remote'@'%';

Snowboy语音唤醒配置(可选)

对于树莓派4B(64bit)的系统可能不需要额外配置，其他版本需要根据情况修改snowboy文件夹的配置文件，确保其能正常运行。（录入关键词需要修改assistxiaoxiao.pmdl文件，默认唤醒词为“助手晓晓”。）

场景、外设及自动化配置(可选)

当前实现的所有参数监听及修改都基于多线程下的循环执行（轮询），因此可以通过在 server.py 添加新的线程插入你的外设控制文件。具体步骤为：在 config.py 中添加变量，编写专用外设控制文件，在专用外设控制文件监听（轮询）变量，执行自定义动作。在任意文件中调用 config.set() 即可触发动作。

例如，在 server.py 新增一个线程用于处理控制HomeAssistant设备的消息 t7 ，在 config.py 中定义变量 "HA_light_demo": False，在 hass_light_demo.py 中处理消息和执行动作。如果要增加语音控制，在 if_devControl.py 中添加对应的语音指令和 config.set() 即可。

支持外接无线设备，作为设备的数据流转和控制中心，可达到极高的可扩展性。可在 config.py 中添加外设变量，在 dev_control.py 中定义设备类型，订阅主题和推送主题，同时，在wifi设备上（例如esp32）配置对应的主题，在任意文件中调用 config.set() 即可触发外设动作（将会发送值到预先定义的主题中，外设接收此值响应动作）。

进一步的，实现自动化，则在 Scene_conf.py 中定义状态变量并设置触发场景、配置相应的动作。调用修改状态变量函数 status_manager.set_status() 时会自动回调检查是否符合场景预设，若是则执行对应动作。（注：无线外设扩展现仅支持MQTT协议设备）

listener 1883
allow_anonymous false
password_file /etc/mosquitto/passwd

大模型调度控制设备(可选)

修改 const_config.py 中的 chat_or_standard为 False ，在 config.py 以及 Scene_conf.py 中添加设备，程序将同时发送用户消息以及输入设备的状态到大语言模型，返回一段文字以及命令，文字用于反馈用户，命令用于控制可控设备，详见prompt_and_deal.py

广域网MQTT配置(可选)

采用中国移动ONENet的MQTT服务器，实现在广域网下与家庭助手通信。

PI-Assistant共订阅三个topic：Input（实现对输入设备数据的改写）、Output（实现对输出设备的控制）、message_pi（用于消息的传递，即远程通信）

PI-Assistant会将 message_pi 传来的消息进过和本地消息几乎同样的处理，而后将返回结果发送到名为 “message_endpoint" 的主题上。

例如，在MQTT手机端Publish主题为 “Output”，内容为"dev_demo:True”的消息，即可打开设备dev_demo的Led灯。提前订阅 “message_endpoint”，向主题 message_pi 发送“你好”，稍后将会在 “message_endpoint” 上收到“你好，我是晓晓智能助手...”，具体实现参考 mqtt_wlan.py以及chat.py。

中国移动MQTT服务器的配置方法：onenet -> 开发者中心 -> 全部产品服务 -> 多协议接入 -> MQTT（旧版）-> 添加产品 -> 添加设备

📄 使用文档

常量配置

修改 const_config.py 文件夹，Openai的key，Azure认知服务的key（语音识别和tts都用到了，免费），代理端口，路径，相应功能的开启关闭等。可在 prompt_and_deal.py中修改提示词。

对于QQ音乐的Cookie，直接在网页登录，复制cookie的值粘贴到cookie.txt。

变量配置

在 config.py 编辑初始参数，如果要语音唤醒，将wakebyhw改为True。

运行

python startApi.py #音乐服务
python server.py #主程序

语音呼叫“助手晓晓”可直接唤醒，然后语音交互

在APP上配置IP后发送消息交互，也可通过http://语音助手ip:5000/command?words=''直接进行交互

连接了指定外设的情况下可通过按钮/无线模块触发，按钮GPIO7(BCM:4)高电平触发。 无线模块开源链接：https://oshwhub.com/ghgjkh/simple-wake

语音播报功能需要手机端APP配合，APP为MacroDroid，实现过程是APP端发送相应格式的消息到http://语音助手ip:5000/words?words=''，然后TTS播报出来。

具体的功能可以根据chat.py的执行逻辑以及对应文件查看使用

运行时调参

可使用网页端在程序运行时调参,地址为 http://ip:5000

文件层次结构

✏️ 待实现功能

• Docker打包项目

• 创建HA语音助手接口，使其具备轻松控制所有家具的能力

• ‘场景’控制方案重写（描述）为‘自动化’控制方案

• OpenAi/星火模型逐步转向流式输出

低功耗BLE外设硬件开发

未联网下自动切换为离线语音识别

🎉 其他

欢迎提交Issue与Pull Request