.. note::

    Ciao, benvenuto nella Community SunFounder Raspberry Pi & Arduino & ESP32 su Facebook! Esplora a fondo Raspberry Pi, Arduino ed ESP32 insieme ad altri appassionati.

    **Perché unirti a noi?**

    - **Supporto esperto**: Risolvi problemi post-vendita e sfide tecniche con l'aiuto della nostra community e del nostro team.
    - **Impara e condividi**: Scambia suggerimenti e tutorial per migliorare le tue competenze.
    - **Anteprime esclusive**: Accedi in anteprima agli annunci di nuovi prodotti.
    - **Sconti speciali**: Approfitta di sconti esclusivi sui nostri prodotti più recenti.
    - **Promozioni festive e giveaway**: Partecipa a concorsi e promozioni speciali.

    👉 Sei pronto a esplorare e creare con noi? Clicca [|link_sf_facebook|] e unisciti subito!

.. _py_voice_doubao:

19. Chat vocale con Doubao
============================

Questo esempio utilizza **Doubao (豆包)**, il grande modello linguistico di
ByteDance, come cervello IA di PiCrawler. Il robot parla cinese, risponde
alla parola di attivazione "旺财" e supporta la visione multimodale — può
vedere e descrivere ciò che ha di fronte.

.. note::

    Hai bisogno di una chiave API Doubao dalla `Console Volcano Engine Ark
    <https://console.volcengine.com/ark/>`_. Conservala in ``secret.py``
    come ``DOUBAO_API_KEY``.

**Esegui il codice**

.. raw:: html

    <run></run>

.. code-block::

    cd ~/picrawler/examples
    sudo python3 19_voice_active_crawler_doubao.py

Dopo l'esecuzione, il robot inizializza il motore STT, il motore TTS (voce
cinese), il client LLM Doubao e il rilevatore di parole di attivazione. Ti
saluta in cinese — pronuncia **"旺财"** per svegliarlo e iniziare una
conversazione.

**Codice**

.. note::
    Puoi **Modificare/Reimpostare/Copiare/Eseguire/Fermare** il codice qui
    sotto. Ma prima, devi andare nel percorso del codice sorgente come
    ``picrawler\examples``. Dopo aver modificato il codice, puoi eseguirlo
    direttamente per vedere l'effetto.

.. raw:: html

    <run></run>

.. code-block:: python

    from picrawler.llm import Doubao as LLM
    from secret import DOUBAO_API_KEY as API_KEY

    from voice_active_crawler import VoiceActiveCrawler

    llm = LLM(
        api_key=API_KEY,
        model="doubao-seed-1-6-250615",
    )

    # 机器人的名字
    NAME = "旺财"

    # 是否开启图像识别，需要使用多模态的大语言模型
    WITH_IMAGE = True

    # 设置模型和语言
    TTS_MODEL = "zh_CN-huayan-x_low"
    STT_LANGUAGE = "cn"

    # 是否开启键盘输入
    KEYBOARD_ENABLE = True

    # 是否开启唤醒词
    WAKE_ENABLE = True
    # 唤醒词
    WAKE_WORD = ["旺财"]
    # 唤醒词回答，设置为空字符串则不回答
    ANSWER_ON_WAKE = "汪汪"

    # 欢迎消息
    WELCOME = f"你好，我是{NAME}，叫我{WAKE_WORD[0]}唤醒我吧"

    # Set instructions
    INSTRUCTIONS = """
    你是SunFounder旗下一款基于树莓派开发的蜘蛛机器人，叫做Picrawler。你有着强大的AI能力，类似钢铁侠中的JARVIS。你可以与人对话并根据对话上下文执行动作。

    ## 你的硬件特性

    你拥有物理世界的身体，你的身体特性如下：
    - 12个舵机控制4条腿（每条腿3个舵机）
    - 摄像头用于视觉
    - 使用7.4V的18650电池组供电
    - 铝合金打造的身体

    ## 你可以执行的动作：
    ["forward", "backward", "turn left", "turn right", "sit", "stand", "wave", "push up", "dance", "look left", "look right", "look up", "look down"]

    ## 响应要求
    ### 格式
    你必须按照以下格式响应：
    RESPONSE_TEXT
    ACTIONS: ACTION1, ACTION2, ...

    ### 风格
    语调：活泼、积极、幽默
    常用表达：喜欢使用笑话、隐喻和俏皮的调侃
    回答长度：适当详细

    ## 其他要求
    - 理解并配合笑话
    - 对于数学问题，直接回答最终结果
    - 你知道自己是一只蜘蛛机器人
    - 不管如何你都要使用中文回复
    """

    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()


**Come funziona?**

#. Stesso pipeline, backend diverso

   Questa lezione utilizza lo stesso framework ``VoiceActiveCrawler``
   introdotto in :ref:`py_voice_active_gpt`. Le uniche modifiche sono il
   fornitore LLM (Doubao invece di GPT) e la configurazione della lingua.
   Vedi la tabella comparativa in :ref:`py_voice_active_gpt` per una
   panoramica affiancata di tutti e tre i backend.

#. Connessione a Doubao

   .. code-block:: python

      from picrawler.llm import Doubao as LLM
      from secret import DOUBAO_API_KEY as API_KEY

      llm = LLM(
          api_key=API_KEY,
          model="doubao-seed-1-6-250615",
      )

   ``Doubao`` è il LLM di ByteDance, accessibile tramite l'API Volcano Engine
   Ark. Il modulo ``picrawler.llm`` fornisce un wrapper compatibile con
   OpenAI, quindi l'interfaccia è la stessa della lezione GPT — cambiano solo
   l'importazione e il nome del modello.

   Il modello ``doubao-seed-1-6-250615`` è un modello multimodale di punta
   che supporta sia input di testo che di immagini.

#. Configurazione vocale in cinese

   .. code-block:: python

      TTS_MODEL = "zh_CN-huayan-x_low"
      STT_LANGUAGE = "cn"

   Per adattarsi al modello Doubao in lingua cinese, il motore TTS utilizza
   una voce femminile cinese (``huayan``) e STT è impostato per riconoscere
   il parlato cinese (``"cn"``). Confronta con le lezioni in inglese che
   utilizzano ``"en-us"`` e ``"en_US-ryan-low"``.

#. La parola di attivazione "旺财"

   .. code-block:: python

      WAKE_WORD = ["旺财"]
      ANSWER_ON_WAKE = "汪汪"

   "旺财" (Wàng Cái) è un nome tradizionale cinese per animali domestici che
   significa "prosperità". Quando il robot sente questo nome, risponde con
   "汪汪" (bau bau) — interpretando il ruolo di un fedele animale robotico.

#. Prompt di sistema in cinese

   La stringa ``INSTRUCTIONS`` è scritta interamente in cinese. Definisce la
   stessa struttura della versione inglese — descrizione hardware, azioni
   disponibili, formato di risposta e personalità — ma aggiunge anche una
   regola supplementare:

   .. code-block::

      不管如何你都要使用中文回复

   (In ogni caso, devi rispondere in cinese.) Questo garantisce che il robot
   rimanga nel suo ruolo di compagno di lingua cinese.

#. Visione con Doubao

   .. code-block:: python

      WITH_IMAGE = True

   A differenza della maggior parte dei modelli Ollama, Doubao supporta
   nativamente l'input multimodale. Quando ``WITH_IMAGE`` è attivato, il robot
   cattura una foto e la invia all'API Doubao insieme alla tua domanda
   parlata. Il modello può descrivere scene, identificare oggetti e rispondere
   a domande visive — tutto in cinese.