.. 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_ollama:

20. Chat vocale locale con Ollama
==================================================

Questo esempio sostituisce l'API GPT basata su cloud con un LLM **Ollama**
eseguito localmente. Tutta l'elaborazione IA rimane sulla tua macchina —
nessuna connessione internet richiesta, nessuna chiave API da gestire. È un
robot interattivo a voce completamente offline.

**Esegui il codice**

.. raw:: html

    <run></run>

.. code-block::

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

**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 Ollama as LLM

   from voice_active_crawler import VoiceActiveCrawler

   # Se Ollama è in esecuzione sullo stesso Raspberry Pi, usa "localhost".
   # Se è in esecuzione su un altro computer nella tua LAN, sostituisci con l'IP.
   llm = LLM(
      ip="localhost",
      model="llama3.2:3b"   // puoi usare qualsiasi modello
   )

   # Nome del robot
   NAME = "Buddy"

   # Attiva immagine (richiede modello multimodale)
   WITH_IMAGE = False

   # Imposta modelli e lingue
   TTS_MODEL = "en_US-ryan-low"
   STT_LANGUAGE = "en-us"

   # Attiva input da tastiera
   KEYBOARD_ENABLE = True

   # Attiva parola di attivazione
   WAKE_ENABLE = True
   WAKE_WORD = ["hey buddy"]
   # Risposta alla parola di attivazione, imposta vuoto per disattivare
   ANSWER_ON_WAKE = "Hi there"

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

   # Imposta istruzioni
   INSTRUCTIONS = """
   You are a Raspberry Pi-based robotic spider developed by SunFounder, named Picrawler. You possess powerful AI capabilities similar to JARVIS from Iron Man. You can have conversations with people and perform actions based on the context of the conversation.

   ## Your Hardware Features

   You have a physical body with the following features:
   - 12 servos controlling 4 legs (3 servos per leg)
   - A camera for vision
   - Powered by a 7.4V 18650 battery pack
   - Aluminum alloy body

   ## Actions You Can Perform:
   ["forward", "backward", "turn left", "turn right", "sit", "stand", "wave", "push up", "dance", "look left", "look right", "look up", "look down"]

   ## Response Requirements
   ### Format
   You must respond in the following format:
   RESPONSE_TEXT
   ACTIONS: ACTION1, ACTION2, ...

   ### Style
   Tone: lively, positive, humorous
   Common expressions: likes to use jokes, metaphors, and playful teasing
   Answer length: appropriately detailed

   ## Other Requirements
   - Understand and go along with jokes
   - For math problems, answer directly with the final result
   - You know you're a spider robot
   """

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


**Come funziona?**

#. Cos'è Ollama?

   `Ollama <https://ollama.com/>`_ è uno strumento per eseguire grandi modelli
   linguistici localmente sul tuo hardware. A differenza della lezione GPT che
   chiama un'API cloud, questo esempio esegue tutto sul dispositivo — le tue
   conversazioni non lasciano mai il Raspberry Pi (o la tua rete locale).

   .. code-block::

      # Installa Ollama, poi scarica un modello:
      ollama pull llama3.2:3b

#. Connessione LLM locale

   .. code-block:: python

      from picrawler.llm import Ollama as LLM

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

   La classe ``Ollama`` si connette a un server Ollama tramite la sua API
   compatibile con OpenAI. Differenze chiave rispetto alla configurazione
   cloud GPT:

   - **Nessuna chiave API** — l'autenticazione non è necessaria per un server
     locale.
   - **Indirizzo IP** — usa ``"localhost"`` se Ollama è in esecuzione sullo
     stesso Pi, o un IP LAN come ``"192.168.1.100"`` se è in esecuzione su un
     altro computer.
   - **Modello** — qualsiasi modello scaricato in Ollama funziona
     (``llama3.2:3b``, ``qwen2.5:7b``, ``mistral``, ecc.).

#. Disattivazione della visione

   .. code-block:: python

      WITH_IMAGE = False

   La maggior parte dei modelli Ollama non supporta l'input multimodale
   (immagini). Impostare ``WITH_IMAGE`` su ``False`` salta il passaggio di
   cattura della fotocamera. Se scarichi un modello compatibile con la visione
   (es. ``llava``), puoi impostarlo su ``True``.

#. Disattivazione di Think

   .. code-block:: python

      vad = VoiceActiveCrawler(
          ...
          disable_think=True,
      )

   Alcuni modelli Ollama (in particolare i modelli di ragionamento come
   ``qwen2.5``) emettono tag ``<think>`` nel loro output. Impostare
   ``disable_think=True`` dice a ``VoiceActiveCrawler`` di rimuovere questi
   tag in modo che il robot pronunci solo la risposta finale.

#. Lo stesso pipeline, offline

   Il pipeline di conversazione è identico a :ref:`py_voice_active_gpt`:

   1. Il rilevamento della parola di attivazione avvia un turno.
   2. STT converte la tua voce in testo.
   3. Il testo viene inviato al LLM Ollama locale.
   4. Il LLM restituisce una risposta e azioni opzionali.
   5. TTS pronuncia la risposta e il robot esegue le azioni.

   La differenza critica: **il passaggio 3 viene eseguito sul tuo hardware**,
   senza dipendenza dal cloud, senza limiti di velocità e con privacy totale.

#. Considerazioni hardware

   Eseguire un LLM localmente è dispendioso in termini di risorse. Su un
   Raspberry Pi:

   - **Modelli piccoli** (3B parametri, come ``llama3.2:3b``) funzionano
     lentamente ma funzionano; aspettati diversi secondi di elaborazione per
     risposta.
   - **Modelli grandi** (7B+) saranno troppo lenti per un uso interattivo su
     un Pi.
   - Per prestazioni migliori, esegui Ollama su un computer separato nella
     tua LAN e punta il parametro ``ip`` verso di esso.