.. _py_voice_ollama:

20. 使用 Ollama 进行本地语音对话
==========================================

本示例将基于云的 GPT API 替换为本地运行的 **Ollama** LLM。
所有 AI 处理都在您自己的机器上完成 — 无需网络，无需管理 API 密钥。
这是一个完全离线的语音交互机器人。

**运行代码**

.. raw:: html

    <run></run>

.. code-block::

    cd ~/picrawler/examples
    sudo python3 20_voice_active_crawler_ollama.py

**代码**

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

.. raw:: html

    <run></run>

.. code-block:: python

   from picrawler.llm import Ollama as LLM

   from voice_active_crawler import VoiceActiveCrawler

   # 如果 Ollama 在同一台树莓派上运行，使用 "localhost"
   # 如果在局域网其他电脑上运行，替换为那台电脑的 IP
   llm = LLM(
      ip="localhost",
      model="llama3.2:3b"   # 可以使用任何模型
   )

   NAME = "Buddy"
   WITH_IMAGE = False
   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,
      disable_think=True,
   )

   if __name__ == '__main__':
      vad.run()


**工作原理**

#. 什么是 Ollama？

   `Ollama <https://ollama.com/>`_ 是一个在本地硬件上运行大语言模型的工具。
   与调用云 API 的 GPT 课程不同，本示例在设备上运行一切 — 对话永远不会离开
   树莓派（或本地网络）。

   .. code-block::

      # 安装 Ollama，然后拉取模型：
      ollama pull llama3.2:3b

#. 本地 LLM 连接

   .. code-block:: python

      from picrawler.llm import Ollama as LLM

      llm = LLM(ip="localhost", model="llama3.2:3b")

   关键区别：

   - **无需 API 密钥** — 本地服务器不需要认证
   - **IP 地址** — 同一台 Pi 上用 ``"localhost"``，其他电脑用 LAN IP
   - **模型** — 任何已拉取的 Ollama 模型都可以使用

#. 禁用视觉

   .. code-block:: python

      WITH_IMAGE = False

   大多数 Ollama 模型不支持多模态（图像）输入。如果拉取了支持视觉的模型
   （如 ``llava``），可以将其设为 ``True``。

#. 禁用 Think

   .. code-block:: python

      disable_think=True

   某些 Ollama 模型（特别是推理模型如 ``qwen2.5``）输出 ``<think>`` 标签。
   ``disable_think=True`` 会去除这些标签，只朗读最终答案。

#. 同一个管道，离线运行

   对话管道与 :ref:`py_voice_active_gpt` 相同，但**第 3 步在您自己的硬件上
   运行**，无需云依赖、无速率限制、完全隐私。

#. 硬件注意事项

   在树莓派上本地运行 LLM：

   - **小模型**\ （3B 参数，如 ``llama3.2:3b``）较慢但可运行
   - **大模型**\ （7B+）对交互使用来说太慢
   - 建议在局域网内的独立电脑上运行 Ollama，用 ``ip`` 参数指向它