.. _py_voice_active_gpt:

18. 与 GPT 进行语音对话
============================

本示例结合了 :ref:`py_stt`、:ref:`py_tts` 和一个基于 GPT 的 LLM，
创建了一个完全语音交互的机器人。PiCrawler 监听唤醒词，理解您的语音，
以 AI 生成的对话回复，并根据上下文执行物理动作。

.. note::

    本项目依赖 **VoiceActiveCrawler** 类。请确保 ``voice_active_crawler.py``
    文件存在于 examples 目录中。同时创建包含 ``OPENAI_API_KEY`` 的
    ``secret.py`` 文件。如果尚未获取 API 密钥，请参阅 :ref:`py_online_llm`
    （OpenAI 部分）了解详细步骤。

**运行代码**

.. raw:: html

    <run></run>

.. code-block::

    cd ~/picrawler/examples
    sudo python3 18_voice_active_crawler_gpt.py

运行后，机器人初始化：

- STT 引擎用于语音识别
- TTS 引擎（Piper）用于语音回复
- LLM 客户端（GPT-4o-mini）用于 AI 对话
- 唤醒词检测器

机器人会用欢迎消息问候您。说出唤醒词（例如 "Hey Buddy"）开始对话。
按 **Ctrl+C** 退出。

**代码**

.. note::
    您可以**修改/重置/复制/运行/停止**\ 以下代码。但在此之前，您需要进入源代码
    路径，如 ``picrawler\examples``。修改代码后，可以直接运行以查看效果。

.. raw:: html

    <run></run>

.. code-block:: python

    from picrawler.llm import OpenAI as LLM
    from secret import OPENAI_API_KEY as API_KEY

    from voice_active_crawler import VoiceActiveCrawler

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

    # 机器人名称
    NAME = "Buddy"

    # 启用图像（需要多模态模型）
    WITH_IMAGE = True

    # 设置模型和语言
    TTS_MODEL = "en_US-ryan-low"
    STT_LANGUAGE = "en-us"

    # 启用键盘输入
    KEYBOARD_ENABLE = True

    # 启用唤醒词
    WAKE_ENABLE = True
    WAKE_WORD = ["hey buddy"]
    ANSWER_ON_WAKE = "Hi there"

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

    INSTRUCTIONS = """
    You are a Raspberry Pi-based robotic spider developed by SunFounder, named Picrawler...
    ## Actions You Can Perform:
    ["forward", "backward", "turn left", "turn right", "sit", "stand", "wave", "push up", "dance", "look left", "look right", "look up", "look down"]
    """

    vad = VoiceActiveCrawler(
        llm, name=NAME, with_image=WITH_IMAGE,
        stt_language=STT_LANGUAGE, tts_model=TTS_MODEL,
        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__':
        vad.run()


**工作原理**

#. VoiceActiveCrawler 是什么？

   ``VoiceActiveCrawler`` 是一个高级类，将四个子系统整合到一个语音交互管道中：

   - **STT** — 语音识别（听取您的语音）
   - **LLM** — AI 对话（GPT 处理您说的话）
   - **TTS** — 语音合成（朗读 AI 回复）
   - **动作** — 物理运动（机器人执行命令）

#. 使用唤醒词作为触发器

   .. code-block:: python

      WAKE_ENABLE = True
      WAKE_WORD = ["hey buddy"]

   启用后，机器人持续监听唤醒词。只有检测到唤醒词后，机器人才会开始对话。
   这避免了对背景噪音的响应。

#. 连接 LLM

   .. code-block:: python

      from picrawler.llm import OpenAI as LLM
      from secret import OPENAI_API_KEY as API_KEY

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

   ``picrawler.llm`` 模块提供 OpenAI 兼容的客户端。推荐使用 ``gpt-4o-mini``：
   快速、实惠，支持多模态输入（文本+图像）。

#. 多模态模型的视觉功能

   .. code-block:: python

      WITH_IMAGE = True

   启用后，机器人会从摄像头拍照并与语音问题一起发送。LLM 可以"看见"机器人
   所见的景象。

#. 用指令设置机器人个性

   ``INSTRUCTIONS`` 字符串是发送给 LLM 的\ **系统提示**\ ，定义了机器人的身份、
   个性、可用动作列表和回复格式。

#. 管道概览

   1. 机器人监听唤醒词
   2. 通过 STT 录制语音
   3. 识别的文本发送给 LLM（可选带摄像头图像）
   4. LLM 返回文本回复和动作列表
   5. 机器人通过 TTS 朗读回复并执行动作
   6. 循环回到监听状态

#. 三种 LLM 后端

   相同的 ``VoiceActiveCrawler`` 管道支持不同 LLM 后端：

   .. list-table::
      :header-rows: 1

      * - 特性
        - GPT (18)
        - Doubao (19)
        - Ollama (20)
      * - 运行环境
        - 云端
        - 云端
        - 本地
      * - API 密钥
        - 需要
        - 需要
        - 不需要
      * - 语言
        - 英语
        - 中文
        - 英语
      * - 视觉
        - 支持
        - 支持
        - 较少

   - :ref:`py_voice_doubao` — 相同云端方案，适配中文，使用字节跳动的豆包模型。
   - :ref:`py_voice_ollama` — 完全在本地硬件运行，无需网络或 API 密钥。