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

17. Connessione agli LLM online
==================================

In questa lezione, impareremo a connettere il tuo PiCrawler (o Raspberry Pi)
a diversi **grandi modelli linguistici (LLM) online**.
Ogni fornitore richiede una chiave API e offre diversi modelli tra cui scegliere.

Tratteremo come:

* Creare e salvare le tue chiavi API in modo sicuro.
* Scegliere un modello adatto alle tue esigenze.
* Eseguire il nostro codice di esempio per dialogare con i modelli.

Procediamo passo dopo passo per ogni fornitore.

----

Prima di iniziare
------------------

Assicurati di aver completato:

* :ref:`install_all_modules` — Installa i moduli ``robot-hat``, ``vilib``,
  ``picrawler``, quindi esegui lo script ``i2samp.sh``.


OpenAI
----------

OpenAI fornisce modelli potenti come **GPT-4o** e **GPT-4.1** che possono
essere utilizzati sia per attività di testo che di visione.

Ecco come configurarlo:

**Ottieni e salva la tua chiave API**

#. Vai su |link_openai_platform| e accedi. Nella pagina **API keys**, clicca
   su **Create new secret key**.

   .. image:: img/llm_openai_create.png

#. Compila i dettagli (Owner, Name, Project e permessi se necessario), poi
   clicca su **Create secret key**.

   .. image:: img/llm_openai_create_confirm.png

#. Una volta creata la chiave, copiala immediatamente — non potrai più
   visualizzarla. Se la perdi, dovrai generarne una nuova.

   .. image:: img/llm_openai_copy.png

#. Nella cartella del progetto (ad esempio: ``/picrawler/examples``), crea un
   file chiamato ``secret.py``:

   .. code-block:: bash

       cd ~/picrawler/examples
       sudo nano secret.py

#. Incolla la tua chiave nel file in questo modo:

   .. code-block:: python

       # secret.py
       # Conserva qui i segreti. Non fare mai il commit di questo file in Git.
       OPENAI_API_KEY = "sk-xxx"

**Attiva la fatturazione e verifica i modelli**

#. Prima di usare la chiave, vai alla pagina **Billing** nel tuo account
   OpenAI, aggiungi i tuoi dati di pagamento e ricarica un piccolo importo
   di crediti.

   .. image:: img/llm_openai_billing.png

#. Poi vai alla pagina **Limits** per verificare quali modelli sono
   disponibili per il tuo account e copia l'ID esatto del modello da usare
   nel codice.

   .. image:: img/llm_openai_models.png

**Testa con il codice di esempio**

#. Apri il codice di esempio:

   .. code-block:: bash

       cd ~/picrawler/examples
       sudo nano 18.online_llm_test.py

#. Sostituisci il contenuto con il codice qui sotto e aggiorna ``model="xxx"``
   con il modello desiderato (ad esempio, ``gpt-4o``):

   .. code-block:: python

       from picrawler.llm import OpenAI
       from secret import OPENAI_API_KEY

       INSTRUCTIONS = "You are a helpful assistant."
       WELCOME = "Hello, I am a helpful assistant. How can I help you?"

       llm = OpenAI(
           api_key=OPENAI_API_KEY,
           model="gpt-4o",
       )

   Salva ed esci (``Ctrl+X``, poi ``Y``, poi ``Invio``).

#. Infine, esegui il test:

   .. code-block:: bash

       sudo python3 18.online_llm_test.py


----

Gemini
------------------

Gemini è la famiglia di modelli AI di Google. È veloce ed eccellente per
attività di uso generale.

**Ottieni e salva la tua chiave API**

#. Accedi a |link_google_ai|, poi vai alla pagina API Keys.

   .. image:: img/llm_gemini_get.png

#. Clicca sul pulsante **Create API key** nell'angolo in alto a destra.

   .. image:: img/llm_gemini_create.png

#. Puoi creare una chiave per un progetto esistente o uno nuovo.

   .. image:: img/llm_gemini_choose.png

#. Copia la chiave API generata.

   .. image:: img/llm_gemini_copy.png

#. Nella cartella del progetto:

   .. code-block:: bash

       cd ~/picrawler/examples
       sudo nano secret.py

#. Incolla la chiave:

   .. code-block:: python

        # secret.py
        # Conserva qui i segreti. Non fare mai il commit di questo file in Git.
       GEMINI_API_KEY = "AIxxx"

**Verifica i modelli disponibili**

Vai alla pagina ufficiale |link_gemini_model|, qui vedrai l'elenco dei
modelli, i loro ID API esatti e per quale caso d'uso ciascuno è ottimizzato.

   .. image:: img/llm_gemini_model.png

**Testa con il codice di esempio**

#. Apri il file di test:

   .. code-block:: bash

       cd ~/picrawler/examples
       sudo nano 18.online_llm_test.py

#. Sostituisci il contenuto con il codice qui sotto e aggiorna ``model="xxx"``
   con il modello desiderato (ad esempio, ``gemini-2.5-flash``):

   .. code-block:: python

       from picrawler.llm import Gemini
       from secret import GEMINI_API_KEY

       INSTRUCTIONS = "You are a helpful assistant."
       WELCOME = "Hello, I am a helpful assistant. How can I help you?"

       llm = Gemini(
           api_key=GEMINI_API_KEY,
           model="gemini-2.5-flash",
       )

#. Salva ed esegui:

   .. code-block:: bash

       sudo python3 18.online_llm_test.py

----

Qwen
------------------

Qwen è una famiglia di grandi modelli linguistici e multimodali forniti da
Alibaba Cloud.
Questi modelli supportano la generazione di testo, il ragionamento e la
comprensione multimodale (come l'analisi delle immagini).

**Ottieni una chiave API**

Per chiamare i modelli Qwen, hai bisogno di una **chiave API**.
La maggior parte degli utenti internazionali dovrebbe usare la console
**DashScope International (Model Studio)**.
Gli utenti della Cina continentale possono invece usare la console
**Bailian (百炼)**.

* **Per utenti internazionali**

  #. Vai alla pagina ufficiale |link_qwen_inter| su **Alibaba Cloud**.
  #. Accedi o crea un account **Alibaba Cloud**.
  #. Vai a **Model Studio** (scegli la regione Singapore o Pechino).

      * Se appare un prompt "Activate Now" nella parte superiore della pagina,
        cliccaci sopra per attivare Model Studio e ricevere la quota gratuita
        (solo Singapore).
      * L'attivazione è gratuita — ti verrà addebitato solo dopo aver esaurito
        la quota gratuita.
      * Se non appare alcun prompt di attivazione, il servizio è già attivo.

  #. Vai alla pagina **Key Management**. Nella scheda **API Key**, clicca su
     **Create API Key**.
  #. Dopo la creazione, copia la tua chiave API e conservala al sicuro.

    .. image:: img/llm_qwen_api_key.png
        :width: 800

  .. note::
     Anche gli utenti di Hong Kong, Macao e Taiwan dovrebbero scegliere
     l'opzione **International (Model Studio)**.

* **Per utenti della Cina continentale**

  Se ti trovi nella Cina continentale, puoi invece usare la console
  **Alibaba Cloud Bailian (百炼)**:

  #. Accedi a |link_aliyun| (console Bailian) e completa la verifica
     dell'account.
  #. Seleziona **Create API Key**. Se ti viene chiesto di attivare i servizi
     del modello, clicca su **Activate**, accetta i termini e richiedi la tua
     quota gratuita. Dopo l'attivazione, il pulsante **Create API Key** sarà
     abilitato.

     .. image:: img/llm_qwen_aliyun_create.png

  #. Clicca di nuovo su **Create API Key**, verifica il tuo account, poi
     clicca su **Confirm**.

     .. image:: img/llm_qwen_aliyun_confirm.png

  #. Una volta creata, copia la tua chiave API.

     .. image:: img/llm_qwen_aliyun_copy.png

**Salva la tua chiave API**

#. Nella cartella del progetto:

   .. code-block:: bash

       cd ~/picrawler/examples
       sudo nano secret.py

#. Incolla la tua chiave in questo modo:

   .. code-block:: python

        # secret.py
        # Conserva qui i segreti. Non fare mai il commit di questo file in Git.

        QWEN_API_KEY = "sk-xxx"

**Testa con il codice di esempio**

#. Apri il file di test:

   .. code-block:: bash

       cd ~/picrawler/examples
       sudo nano 18.online_llm_test.py

#. Sostituisci il contenuto con il codice qui sotto e aggiorna ``model="xxx"``
   con il modello desiderato (ad esempio, ``qwen-plus``):

   .. code-block:: python

      from picrawler.llm import Qwen
      from secret import QWEN_API_KEY

      INSTRUCTIONS = "You are a helpful assistant."
      WELCOME = "Hello, I am a helpful assistant. How can I help you?"

      llm = Qwen(
          api_key=QWEN_API_KEY,
          model="qwen-plus",
      )

#. Esegui con:

   .. code-block:: bash

       sudo python3 18.online_llm_test.py

Grok (xAI)
------------------
Grok è l'IA conversazionale di xAI, creata dal team di Elon Musk. Puoi
connetterti tramite l'API xAI.

**Ottieni e salva la tua chiave API**

#. Registrati per un account qui: |link_grok_ai|. Aggiungi prima alcuni
   crediti al tuo account — altrimenti l'API non funzionerà.

#. Vai alla pagina API Keys, clicca su **Create API key**.

   .. image:: img/llm_grok_create.png

#. Inserisci un nome per la chiave, poi clicca su **Create API key**.

   .. image:: img/llm_grok_name.png

#. Copia la chiave generata e conservala al sicuro.

   .. image:: img/llm_grok_copy.png

#. Nella cartella del progetto:

   .. code-block:: bash

       cd ~/picrawler/examples
       sudo nano secret.py

#. Incolla la tua chiave in questo modo:

   .. code-block:: python

        # secret.py
        # Conserva qui i segreti. Non fare mai il commit di questo file in Git.

        GROK_API_KEY = "xai-xxx"

**Verifica i modelli disponibili**

Vai alla pagina Models nella console xAI. Qui puoi vedere tutti i modelli
disponibili per il tuo team, con i loro ID API esatti — usa questi ID nel
tuo codice.

   .. image:: img/llm_grok_model.png

**Testa con il codice di esempio**

#. Apri il file di test:

   .. code-block:: bash

       cd ~/picrawler/examples
       sudo nano 18.online_llm_test.py

#. Sostituisci il contenuto con il codice qui sotto e aggiorna ``model="xxx"``
   con il modello desiderato (ad esempio, ``grok-4-latest``):

   .. code-block:: python

       from picrawler.llm import Grok
       from secret import GROK_API_KEY

       INSTRUCTIONS = "You are a helpful assistant."
       WELCOME = "Hello, I am a helpful assistant. How can I help you?"

       llm = Grok(
           api_key=GROK_API_KEY,
           model="grok-4-latest",
       )

#. Esegui con:

   .. code-block:: bash

       sudo python3 18.online_llm_test.py

----

DeepSeek
------------------

DeepSeek è un fornitore cinese di LLM che offre modelli convenienti e capaci.

**Ottieni e salva la tua chiave API**

#. Accedi a |link_deepseek|.

#. Nel menu in alto a destra, seleziona **API Keys → Create API Key**.

   .. image:: img/llm_deepseek_create.png

#. Inserisci un nome, clicca su **Create**, poi copia la chiave.

   .. image:: img/llm_deepseek_copy.png

#. Nella cartella del progetto:

   .. code-block:: bash

       cd ~/picrawler/examples
       sudo nano secret.py

#. Aggiungi la tua chiave:

   .. code-block:: python

       # secret.py
       DEEPSEEK_API_KEY = "sk-xxx"

**Attiva la fatturazione**

Dovrai prima ricaricare il tuo account. Inizia con un piccolo importo (come
¥10 RMB).

   .. image:: img/llm_deepseek_chognzhi.png

**Modelli disponibili**

Al momento della scrittura (2025-09-12), DeepSeek offre:

* ``deepseek-chat``
* ``deepseek-reasoner``

**Testa con il codice di esempio**

#. Apri il file di test:

   .. code-block:: bash

       cd ~/picrawler/examples
       sudo nano 18.online_llm_test.py

#. Sostituisci il contenuto con il codice qui sotto e aggiorna ``model="xxx"``
   con il modello desiderato (ad esempio, ``deepseek-chat``):

   .. code-block:: python

       from picrawler.llm import Deepseek
       from secret import DEEPSEEK_API_KEY

       INSTRUCTIONS = "You are a helpful assistant."
       WELCOME = "Hello, I am a helpful assistant. How can I help you?"

       llm = Deepseek(
           api_key=DEEPSEEK_API_KEY,
           model="deepseek-chat",
           max_messages=20,
       )

#. Esegui:

   .. code-block:: bash

       sudo python3 18.online_llm_test.py

----

Doubao
------------------
Doubao è la piattaforma di modelli AI di ByteDance (Volcengine Ark).

**Ottieni e salva la tua chiave API**

#. Accedi a |link_doubao|.

#. Nel menu a sinistra, scorri fino a **API Key Management → Create API Key**.

   .. image:: img/llm_doubao_create.png

#. Scegli un nome e clicca su **Create**.

   .. image:: img/llm_doubao_name.png

#. Clicca sull'icona **Show API Key** e copiala.

   .. image:: img/llm_doubao_copy.png

#. Nella cartella del progetto:

   .. code-block:: bash

       cd ~/picrawler/examples
       sudo nano secret.py

#. Aggiungi la tua chiave:

   .. code-block:: python

       # secret.py
       DOUBAO_API_KEY = "xxx"

**Scegli un modello**

#. Vai al marketplace dei modelli e scegli un modello.

   .. image:: img/llm_doubao_model_select.png

#. Ad esempio, scegli **Doubao-seed-1.6**, poi clicca su **API 接入**.

   .. image:: img/llm_doubao_model.png

#. Seleziona la tua chiave API e clicca su **Use API**.

   .. image:: img/llm_doubao_use_api.png

#. Clicca su **Enable Model**.

   .. image:: img/llm_doubao_kaitong.png

#. Passa il mouse sull'ID del modello per copiarlo.

   .. image:: img/llm_doubao_copy_id.png

**Testa con il codice di esempio**

#. Apri il file di test:

   .. code-block:: bash

       cd ~/picrawler/examples
       sudo nano 18.online_llm_test.py

#. Sostituisci il contenuto con il codice qui sotto e aggiorna ``model="xxx"``
   con il modello desiderato (ad esempio, ``doubao-seed-1-6-250615``):

   .. code-block:: python

       from picrawler.llm import Doubao
       from secret import DOUBAO_API_KEY

       INSTRUCTIONS = "You are a helpful assistant."
       WELCOME = "Hello, I am a helpful assistant. How can I help you?"

       llm = Doubao(
           api_key=DOUBAO_API_KEY,
           model="doubao-seed-1-6-250615",
       )

#. Esegui con:

   .. code-block:: bash

       sudo python3 18.online_llm_test.py


Generale
--------------

Questo progetto supporta la connessione a più piattaforme LLM tramite
un'interfaccia unificata.
Abbiamo compatibilità integrata con:

* **OpenAI** (ChatGPT / GPT-4o, GPT-4, GPT-3.5)
* **Gemini** (Google AI Studio / Vertex AI)
* **Grok** (xAI)
* **DeepSeek**
* **Qwen (通义千问)**
* **Doubao (豆包)**

Inoltre, puoi connetterti a **qualsiasi altro servizio LLM compatibile con il
formato API OpenAI**.
Per quelle piattaforme, dovrai ottenere manualmente la tua **chiave API** e
il **base_url** corretto.

**Ottieni e salva la tua chiave API**

#. Ottieni una **chiave API** dalla piattaforma che desideri utilizzare.
   (Consulta la console ufficiale di ciascuna piattaforma per i dettagli.)

#. Nella cartella del progetto, crea un nuovo file:

   .. code-block:: bash

      cd ~/picrawler/examples
      nano secret.py

#. Aggiungi la tua chiave in ``secret.py``:

   .. code-block:: python

      # secret.py
      API_KEY = "your_api_key_here"

.. warning::

   Mantieni la tua chiave API privata. Non caricare ``secret.py`` su
   repository pubblici.

**Testa con il codice di esempio**

#. Apri il file di test:

   .. code-block:: bash

      cd ~/picrawler/examples
      sudo nano 18.online_llm_test.py

#. Sostituisci il contenuto di un file Python con il seguente esempio e
   inserisci il ``base_url`` e il ``model`` corretti per la tua piattaforma:

   .. note::

      Informazioni su ``base_url``:
      Supportiamo il **formato API OpenAI**, così come qualsiasi API che sia
      **compatibile** con esso.
      Ogni fornitore ha il proprio ``base_url``. Consulta la loro
      documentazione.

   .. code-block:: python

      from picrawler.llm import LLM
      from secret import API_KEY

      INSTRUCTIONS = "You are a helpful assistant."
      WELCOME = "Hello, I am a helpful assistant. How can I help you?"

      llm = LLM(
          base_url="https://api.example.com/v1",  // inserisci il base_url del tuo fornitore
          api_key=API_KEY,
          model="your-model-name-here",           // scegli un modello dal tuo fornitore
      )


#. Esegui il programma:

   .. code-block:: bash

      python3 18.online_llm_test.py