7. AI 语音助手

本课程将把您的 Pironman 5 Pro MAX 打造成一个 以语音为核心的 AI 助手。 通过提供的代码，机器人将能够：等待唤醒词、使用 Vosk 识别语音并转写为文本、将内容发送到 OpenAI LLM，并通过 Piper TTS 语音回复。

开始之前

请确保您已完成以下准备：

  • 1. 测试 Piper — Piper 语音功能正常（例如可以播放 “Hello”）。

  • 测试 Vosk — Vosk 语音识别在您的语言环境中可正常使用（例如 en-us）。

  • 5. 连接在线 LLM — 您的 OpenAI API key 已保存在 secret.py 中，变量名为 OPENAI_API_KEY。

  • Pironman 5 Pro MAX 已连接并可正常使用 麦克风 和 扬声器。

  • 具备稳定的 网络连接 （LLM 为在线服务）。

运行示例

cd ~/sunfounder-voice-assistant/examples/
sudo python3 voice_assistant.py

代码使用的配置：

  • LLM：OpenAI （gpt-4o-mini）

  • TTS：Piper （en_US-ryan-low）

  • STT：Vosk （en-us）

  • 唤醒词： "hey buddy"

  • 键盘输入：已启用 （可选的手动输入方式）

  • 图像模式：已启用 （WITH_IMAGE=True）—— 如果未来需要使用图像功能，需要支持多模态的 LLM

运行流程：

  1. 助手启动后，会显示包含唤醒词的欢迎信息。

  2. 系统持续监听 “hey buddy” 唤醒词。

  3. 被唤醒后，您的语音将被转写为文本（Vosk → text）。

  4. 文本被发送到 OpenAI（gpt-4o-mini） 生成回复。

  5. 回复内容通过 Piper （en_US-ryan-low）转换为语音并播放。

示例交互

You: Hey Buddy
Robot: Hi there!

You: What’s the capital of Italy?
Robot: The capital of Italy is Rome.

示例代码

from sunfounder_voice_assistant.voice_assistant import VoiceAssistant
from sunfounder_voice_assistant.llm import OpenAI as LLM
from secret import OPENAI_API_KEY as API_KEY

llm = LLM(
    api_key=API_KEY,
    model="gpt-4o-mini",
)

# Robot name
NAME = "Buddy"

# Enable image, need to set up a multimodal language model
WITH_IMAGE = True

# Set models and languages
LLM_MODEL = "gpt-4o-mini"
TTS_MODEL = "en_US-ryan-low"
STT_LANGUAGE = "en-us"

# Enable keyboard input
KEYBOARD_ENABLE = True

# Enable wake word
WAKE_ENABLE = True
WAKE_WORD = [f"hey {NAME.lower()}"]
# Set wake word answer, set empty to disable
ANSWER_ON_WAKE = "Hi there"

# Welcome message
WELCOME = f"Hi, I'm {NAME}. Wake me up with: " + ", ".join(WAKE_WORD)

# Set instructions
INSTRUCTIONS = f"""
You are a helpful assistant, named {NAME}.
"""

va = VoiceAssistant(
    llm,
    name=NAME,
    with_image=WITH_IMAGE,
    tts_model=TTS_MODEL,
    stt_language=STT_LANGUAGE,
    keyboard_enable=KEYBOARD_ENABLE,
    wake_enable=WAKE_ENABLE,
    wake_word=WAKE_WORD,
    answer_on_wake=ANSWER_ON_WAKE,
    welcome=WELCOME,
    instructions=INSTRUCTIONS,
)

if __name__ == "__main__":
    va.run()

代码说明：

  • OpenAI(..., model="gpt-4o-mini") — 本课程中仅使用 OpenAI 作为 LLM。

  • NAME / WAKE_WORD — 用于自定义助手名称和唤醒词（例如 “Buddy” 和 “hey buddy”）。

  • WITH_IMAGE=True — 为助手启用图像模式（此处未包含图像输入/输出逻辑）。

  • TTS_MODEL="en_US-ryan-low" — 指定回复所使用的 Piper 语音模型。

  • STT_LANGUAGE="en-us" — 指定 Vosk 语音识别所使用的语言。

  • KEYBOARD_ENABLE=True — 允许在调试过程中通过键盘手动输入文本。

  • WELCOME / INSTRUCTIONS — 启动欢迎语以及助手的人设/System Prompt。

  • va.run() — 启动主循环：唤醒 → 监听 → LLM 处理 → 语音播报。

切换到其他 LLM 或 TTS

只需进行少量修改，您就可以轻松切换到其他 LLM、TTS 或 STT 语言：

  • 支持的 LLM：

    • OpenAI

    • Doubao

    • Deepseek

    • Gemini

    • Qwen

    • Grok

  • 1. 测试 Piper — 查看 Piper TTS 支持的语言。

  • 测试 Vosk — 查看 Vosk STT 支持的语言。

如需切换，只需修改代码中的初始化部分：

from sunfounder_voice_assistant.llm import Gemini as LLM
llm = LLM(api_key="YOUR_KEY", model="gemini-pro")

# Set models and languages
TTS_MODEL = "en_US-ryan-low"
STT_LANGUAGE = "en-us"

故障排查

  • 机器人无法响应唤醒词

    • 检查麦克风是否工作正常。

    • 确认 WAKE_ENABLE = True。

    • 根据您的发音调整唤醒词。

    • 尽量减少背景噪音，并清晰发音。

  • 扬声器没有声音输出

    • 检查 TTS 模型名称是否正确（例如 en_US-ryan-low）。

    • 手动测试 Piper 或 Espeak 是否可正常工作。

    • 检查扬声器连接和音量设置。

  • API key 报错或请求超时

    • 检查 secret.py 中配置的 key 是否正确。

    • 确保网络连接稳定。

    • 确认所使用的 LLM 模型受支持（例如 gpt-4o-mini）。

  • 唤醒词可用，但没有回复

    • 检查 STT 语言是否与您的口音匹配。

    • 确认模型已正确下载。

    • 尝试输出调试日志，以确认 STT 是否正在正常运行。

  • TTS 正常，但 LLM 没有回复

    • 检查 API key 是否有效。

    • 确认模型名称和 LLM 配置是否正确。

    • 确保设备已连接互联网。