.. note::

    Hola, bienvenido a la comunidad de entusiastas de SunFounder Raspberry Pi & Arduino & ESP32 en Facebook. ¡Explora más a fondo Raspberry Pi, Arduino y ESP32 con otros entusiastas!

    **¿Por qué unirse?**

    - **Soporte experto**: Resuelve problemas postventa y desafíos técnicos con la ayuda de nuestra comunidad y equipo.
    - **Aprende y comparte**: Intercambia consejos y tutoriales para mejorar tus habilidades.
    - **Avances exclusivos**: Obtén acceso anticipado a anuncios de nuevos productos y vistas previas.
    - **Descuentos especiales**: Disfruta de descuentos exclusivos en nuestros productos más recientes.
    - **Promociones festivas y sorteos**: Participa en sorteos y promociones de temporada.

    👉 ¿Listo para explorar y crear con nosotros? Haz clic en [|link_sf_facebook|] y únete hoy mismo.

.. _py_online_llm:

17. Conexión a LLMs en línea
===============================

En esta lección, aprenderemos a conectar su PiCrawler (o Raspberry Pi) a
diferentes **grandes modelos de lenguaje (LLMs) en línea**.
Cada proveedor requiere una clave API y ofrece diferentes modelos entre los
que puede elegir.

Cubriremos cómo:

* Crear y guardar sus claves API de forma segura.
* Elegir un modelo que se ajuste a sus necesidades.
* Ejecutar nuestro código de ejemplo para chatear con los modelos.

Vamos paso a paso para cada proveedor.

----

Antes de comenzar
------------------

Asegúrese de haber completado:

* :ref:`install_all_modules` — Instale los módulos ``robot-hat``,
  ``vilib``, ``picrawler``, luego ejecute el script ``i2samp.sh``.


OpenAI
----------

OpenAI proporciona modelos potentes como **GPT-4o** y **GPT-4.1** que pueden
usarse tanto para tareas de texto como de visión.

Así se configura:

**Obtener y guardar su clave API**

#. Vaya a |link_openai_platform| e inicie sesión. En la página **API keys**,
   haga clic en **Create new secret key**.

   .. image:: img/llm_openai_create.png

#. Complete los detalles (Owner, Name, Project y permisos si es necesario),
   luego haga clic en **Create secret key**.

   .. image:: img/llm_openai_create_confirm.png

#. Una vez creada la clave, cópiela inmediatamente — no podrá verla de nuevo.
   Si la pierde, deberá generar una nueva.

   .. image:: img/llm_openai_copy.png

#. En su carpeta de proyecto (por ejemplo: ``/picrawler/examples``), cree un
   archivo llamado ``secret.py``:

   .. code-block:: bash

       cd ~/picrawler/examples
       sudo nano secret.py

#. Pegue su clave en el archivo así:

   .. code-block:: python

       # secret.py
       # Almacene secretos aquí. Nunca haga commit de este archivo en Git.
       OPENAI_API_KEY = "sk-xxx"

**Activar facturación y verificar modelos**

#. Antes de usar la clave, vaya a la página **Billing** en su cuenta de
   OpenAI, agregue sus datos de pago y recargue un pequeño monto de créditos.

   .. image:: img/llm_openai_billing.png

#. Luego vaya a la página **Limits** para verificar qué modelos están
   disponibles para su cuenta y copie el ID exacto del modelo para usar en
   su código.

   .. image:: img/llm_openai_models.png

**Probar con código de ejemplo**

#. Abra el código de ejemplo:

   .. code-block:: bash

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

#. Reemplace el contenido con el código siguiente y actualice ``model="xxx"``
   al modelo deseado (por ejemplo, ``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",
       )

   Guarde y salga (``Ctrl+X``, luego ``Y``, luego ``Enter``).

#. Finalmente, ejecute la prueba:

   .. code-block:: bash

       sudo python3 18.online_llm_test.py


----

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

Gemini es la familia de modelos de IA de Google. Es rápido y excelente para
tareas de propósito general.

**Obtener y guardar su clave API**

#. Inicie sesión en |link_google_ai|, luego vaya a la página API Keys.

   .. image:: img/llm_gemini_get.png

#. Haga clic en el botón **Create API key** en la esquina superior derecha.

   .. image:: img/llm_gemini_create.png

#. Puede crear una clave para un proyecto existente o uno nuevo.

   .. image:: img/llm_gemini_choose.png

#. Copie la clave API generada.

   .. image:: img/llm_gemini_copy.png

#. En su carpeta de proyecto:

   .. code-block:: bash

       cd ~/picrawler/examples
       sudo nano secret.py

#. Pegue la clave:

   .. code-block:: python

        # secret.py
        # Almacene secretos aquí. Nunca haga commit de este archivo en Git.
       GEMINI_API_KEY = "AIxxx"

**Verificar modelos disponibles**

Vaya a la página oficial |link_gemini_model|, aquí verá la lista de modelos,
sus ID de API exactos y para qué caso de uso está optimizado cada uno.

   .. image:: img/llm_gemini_model.png

**Probar con código de ejemplo**

#. Abra el archivo de prueba:

   .. code-block:: bash

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

#. Reemplace el contenido con el código siguiente y actualice ``model="xxx"``
   al modelo deseado (por ejemplo, ``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",
       )

#. Guarde y ejecute:

   .. code-block:: bash

       sudo python3 18.online_llm_test.py

----

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

Qwen es una familia de grandes modelos de lenguaje y multimodales
proporcionados por Alibaba Cloud.
Estos modelos admiten generación de texto, razonamiento y comprensión
multimodal (como análisis de imágenes).

**Obtener una clave API**

Para llamar a los modelos Qwen, necesita una **clave API**.
La mayoría de los usuarios internacionales deben usar la consola
**DashScope International (Model Studio)**.
Los usuarios de China continental pueden usar la consola **Bailian (百炼)**.

* **Para usuarios internacionales**

  #. Vaya a la página oficial |link_qwen_inter| en **Alibaba Cloud**.
  #. Inicie sesión o cree una cuenta de **Alibaba Cloud**.
  #. Navegue a **Model Studio** (elija la región Singapur o Beijing).

      * Si aparece un aviso "Activate Now" en la parte superior de la página,
        haga clic para activar Model Studio y recibir la cuota gratuita
        (solo Singapur).
      * La activación es gratuita — solo se le cobrará después de agotar su
        cuota gratuita.
      * Si no aparece ningún aviso de activación, el servicio ya está activo.

  #. Vaya a la página **Key Management**. En la pestaña **API Key**, haga
     clic en **Create API Key**.
  #. Después de la creación, copie su clave API y consérvela segura.

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

  .. note::
     Los usuarios de Hong Kong, Macao y Taiwán también deben elegir la opción
     **International (Model Studio)**.

* **Para usuarios de China continental**

  Si está en China continental, puede usar la consola **Alibaba Cloud
  Bailian (百炼)** en su lugar:

  #. Inicie sesión en |link_aliyun| (consola Bailian) y complete la
     verificación de cuenta.
  #. Seleccione **Create API Key**. Si se le solicita que los servicios de
     modelo no están activados, haga clic en **Activate**, acepte los términos
     y reclame su cuota gratuita. Después de la activación, el botón
     **Create API Key** estará habilitado.

     .. image:: img/llm_qwen_aliyun_create.png

  #. Haga clic en **Create API Key** nuevamente, verifique su cuenta y luego
     haga clic en **Confirm**.

     .. image:: img/llm_qwen_aliyun_confirm.png

  #. Una vez creada, copie su clave API.

     .. image:: img/llm_qwen_aliyun_copy.png

**Guardar su clave API**

#. En su carpeta de proyecto:

   .. code-block:: bash

       cd ~/picrawler/examples
       sudo nano secret.py

#. Pegue su clave así:

   .. code-block:: python

        # secret.py
        # Almacene secretos aquí. Nunca haga commit de este archivo en Git.

        QWEN_API_KEY = "sk-xxx"

**Probar con código de ejemplo**

#. Abra el archivo de prueba:

   .. code-block:: bash

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

#. Reemplace el contenido con el código siguiente y actualice ``model="xxx"``
   al modelo deseado (por ejemplo, ``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",
      )

#. Ejecute con:

   .. code-block:: bash

       sudo python3 18.online_llm_test.py

Grok (xAI)
------------------
Grok es la IA conversacional de xAI, creada por el equipo de Elon Musk. Puede
conectarse a través de la API de xAI.

**Obtener y guardar su clave API**

#. Regístrese para una cuenta aquí: |link_grok_ai|. Añada algunos créditos a
   su cuenta primero — de lo contrario, la API no funcionará.

#. Vaya a la página API Keys, haga clic en **Create API key**.

   .. image:: img/llm_grok_create.png

#. Ingrese un nombre para la clave, luego haga clic en **Create API key**.

   .. image:: img/llm_grok_name.png

#. Copie la clave generada y consérvela segura.

   .. image:: img/llm_grok_copy.png

#. En su carpeta de proyecto:

   .. code-block:: bash

       cd ~/picrawler/examples
       sudo nano secret.py

#. Pegue su clave así:

   .. code-block:: python

        # secret.py
        # Almacene secretos aquí. Nunca haga commit de este archivo en Git.

        GROK_API_KEY = "xai-xxx"

**Verificar modelos disponibles**

Vaya a la página Models en la consola xAI. Aquí puede ver todos los modelos
disponibles para su equipo, junto con sus ID de API exactos — use estos ID
en su código.

   .. image:: img/llm_grok_model.png

**Probar con código de ejemplo**

#. Abra el archivo de prueba:

   .. code-block:: bash

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

#. Reemplace el contenido con el código siguiente y actualice ``model="xxx"``
   al modelo deseado (por ejemplo, ``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",
       )

#. Ejecute con:

   .. code-block:: bash

       sudo python3 18.online_llm_test.py

----

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

DeepSeek es un proveedor chino de LLM que ofrece modelos asequibles y capaces.

**Obtener y guardar su clave API**

#. Inicie sesión en |link_deepseek|.

#. En el menú superior derecho, seleccione **API Keys → Create API Key**.

   .. image:: img/llm_deepseek_create.png

#. Ingrese un nombre, haga clic en **Create**, luego copie la clave.

   .. image:: img/llm_deepseek_copy.png

#. En su carpeta de proyecto:

   .. code-block:: bash

       cd ~/picrawler/examples
       sudo nano secret.py

#. Agregue su clave:

   .. code-block:: python

       # secret.py
       DEEPSEEK_API_KEY = "sk-xxx"

**Activar facturación**

Necesitará recargar su cuenta primero. Comience con un monto pequeño (como
¥10 RMB).

   .. image:: img/llm_deepseek_chognzhi.png

**Modelos disponibles**

Al momento de escribir esto (2025-09-12), DeepSeek ofrece:

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

**Probar con código de ejemplo**

#. Abra el archivo de prueba:

   .. code-block:: bash

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

#. Reemplace el contenido con el código siguiente y actualice ``model="xxx"``
   al modelo deseado (por ejemplo, ``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,
       )

#. Ejecute:

   .. code-block:: bash

       sudo python3 18.online_llm_test.py

----

Doubao
------------------
Doubao es la plataforma de modelos de IA de ByteDance (Volcengine Ark).

**Obtener y guardar su clave API**

#. Inicie sesión en |link_doubao|.

#. En el menú izquierdo, desplácese hasta **API Key Management → Create API Key**.

   .. image:: img/llm_doubao_create.png

#. Elija un nombre y haga clic en **Create**.

   .. image:: img/llm_doubao_name.png

#. Haga clic en el icono **Show API Key** y cópiela.

   .. image:: img/llm_doubao_copy.png

#. En su carpeta de proyecto:

   .. code-block:: bash

       cd ~/picrawler/examples
       sudo nano secret.py

#. Agregue su clave:

   .. code-block:: python

       # secret.py
       DOUBAO_API_KEY = "xxx"

**Elegir un modelo**

#. Vaya al mercado de modelos y elija un modelo.

   .. image:: img/llm_doubao_model_select.png

#. Por ejemplo, elija **Doubao-seed-1.6**, luego haga clic en **API 接入**.

   .. image:: img/llm_doubao_model.png

#. Seleccione su clave API y haga clic en **Use API**.

   .. image:: img/llm_doubao_use_api.png

#. Haga clic en **Enable Model**.

   .. image:: img/llm_doubao_kaitong.png

#. Pase el cursor sobre el ID del modelo para copiarlo.

   .. image:: img/llm_doubao_copy_id.png

**Probar con código de ejemplo**

#. Abra el archivo de prueba:

   .. code-block:: bash

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

#. Reemplace el contenido con el código siguiente y actualice ``model="xxx"``
   al modelo deseado (por ejemplo, ``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",
       )

#. Ejecute con:

   .. code-block:: bash

       sudo python3 18.online_llm_test.py


General
--------------

Este proyecto admite la conexión a múltiples plataformas LLM a través de una
interfaz unificada.
Tenemos compatibilidad integrada con:

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

Además, puede conectarse a **cualquier otro servicio LLM que sea compatible
con el formato de API de OpenAI**.
Para esas plataformas, necesitará obtener manualmente su **clave API** y la
**base_url** correcta.

**Obtener y guardar su clave API**

#. Obtenga una **clave API** de la plataforma que desee usar. (Consulte la
   consola oficial de cada plataforma para más detalles.)

#. En su carpeta de proyecto, cree un nuevo archivo:

   .. code-block:: bash

      cd ~/picrawler/examples
      nano secret.py

#. Agregue su clave en ``secret.py``:

   .. code-block:: python

      # secret.py
      API_KEY = "your_api_key_here"

.. warning::

   Mantenga su clave API privada. No suba ``secret.py`` a repositorios
   públicos.

**Probar con código de ejemplo**

#. Abra el archivo de prueba:

   .. code-block:: bash

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

#. Reemplace el contenido de un archivo Python con el siguiente ejemplo y
   complete la ``base_url`` y el ``model`` correctos para su plataforma:

   .. note::

      Acerca de ``base_url``:
      Soportamos el **formato de API de OpenAI**, así como cualquier API que
      sea **compatible** con él.
      Cada proveedor tiene su propia ``base_url``. Consulte su documentación.

   .. 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",  // complete la base_url de su proveedor
          api_key=API_KEY,
          model="your-model-name-here",           // elija un modelo de su proveedor
      )


#. Ejecute el programa:

   .. code-block:: bash

      python3 18.online_llm_test.py