.. _py_online_llm:

17. 连接在线大语言模型
=========================

在本课中，我们将学习如何将您的 PiCrawler（或 Raspberry Pi）连接到不同的
**在线大语言模型（LLM）**\ 。
每个提供商都需要 API 密钥，并提供不同的模型供您选择。

我们将涵盖以下内容：

* 创建并安全保存您的 API 密钥。
* 选择适合您需求的模型。
* 运行我们的示例代码与模型对话。

让我们逐个提供商逐步进行。

----

准备工作
--------

请确保已完成：

* :ref:`install_all_modules` — 安装 ``robot-hat``、``vilib``、
  ``picrawler`` 模块，然后运行脚本 ``i2samp.sh``。


OpenAI
----------

OpenAI 提供强大的模型，如 **GPT-4o** 和 **GPT-4.1**，可用于文本和视觉任务。

设置方法如下：

**获取并保存您的 API 密钥**

#. 前往 |link_openai_platform| 并登录。在 **API keys** 页面，点击
   **Create new secret key**\ 。

   .. image:: img/llm_openai_create.png

#. 填写详细信息（Owner、Name、Project 和权限），然后点击
   **Create secret key**\ 。

   .. image:: img/llm_openai_create_confirm.png

#. 密钥创建后请立即复制 — 您将无法再次查看。如果丢失，需要生成新的。

   .. image:: img/llm_openai_copy.png

#. 在项目文件夹中（例如：``/picrawler/examples``），创建 ``secret.py``：

   .. code-block:: bash

       cd ~/picrawler/examples
       sudo nano secret.py

#. 将密钥粘贴到文件中：

   .. code-block:: python

       # secret.py
       # 在此存储密钥。切勿将此文件提交到 Git。
       OPENAI_API_KEY = "sk-xxx"

**启用计费并查看模型**

#. 使用密钥前，前往 OpenAI 账户的 **Billing** 页面，添加付款信息并充值少量额度。

   .. image:: img/llm_openai_billing.png

#. 然后前往 **Limits** 页面，查看账户可用的模型，并复制模型 ID 用于代码中。

   .. image:: img/llm_openai_models.png

**使用示例代码测试**

#. 打开示例代码：

   .. code-block:: bash

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

#. 将内容替换为以下代码，并将 ``model="xxx"`` 更新为所需模型（如 ``gpt-4o``）：

   .. code-block:: python

       from picrawler.llm import OpenAI
       from secret import OPENAI_API_KEY

       INSTRUCTIONS = "你是一个有帮助的助手。"
       WELCOME = "你好，我是一个有帮助的助手。有什么可以帮助你的吗？"

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

   保存并退出（``Ctrl+X``，然后 ``Y``，然后 ``Enter``）。

#. 最后，运行测试：

   .. code-block:: bash

       sudo python3 18.online_llm_test.py


----

Gemini
----------

Gemini 是 Google 的 AI 模型家族。它速度快，非常适合通用任务。

**获取并保存您的 API 密钥**

#. 登录 |link_google_ai|，然后前往 API Keys 页面。

   .. image:: img/llm_gemini_get.png

#. 点击右上角的 **Create API key** 按钮。

   .. image:: img/llm_gemini_create.png

#. 您可以为现有项目或新项目创建密钥。

   .. image:: img/llm_gemini_choose.png

#. 复制生成的 API 密钥。

   .. image:: img/llm_gemini_copy.png

#. 在项目文件夹中：

   .. code-block:: bash

       cd ~/picrawler/examples
       sudo nano secret.py

#. 粘贴密钥：

   .. code-block:: python

        # secret.py
        # 在此存储密钥。切勿将此文件提交到 Git。
       GEMINI_API_KEY = "AIxxx"

**查看可用模型**

前往官方 |link_gemini_model| 页面，查看模型列表、API ID 及优化用途。

   .. image:: img/llm_gemini_model.png

**使用示例代码测试**

#. 打开测试文件：

   .. code-block:: bash

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

#. 替换内容并更新 ``model="xxx"``\ （如 ``gemini-2.5-flash``\ ）：

   .. code-block:: python

       from picrawler.llm import Gemini
       from secret import GEMINI_API_KEY

       INSTRUCTIONS = "你是一个有帮助的助手。"
       WELCOME = "你好，我是一个有帮助的助手。"

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

#. 保存并运行：

   .. code-block:: bash

       sudo python3 18.online_llm_test.py

----

Qwen（通义千问）
--------------------

Qwen 是阿里云提供的大语言模型和多模态模型家族。
这些模型支持文本生成、推理和多模态理解（如图像分析）。

**获取 API 密钥**

* **国际用户**

  #. 前往 **阿里云** 上的 |link_qwen_inter| 官方页面。
  #. 登录或创建 **阿里云** 账户。
  #. 进入 **Model Studio**\ （选择新加坡或北京区域）。

      * 如果页面顶部出现"立即激活"提示，点击激活 Model Studio 并领取免费额度（仅新加坡）。
      * 激活免费 — 免费额度用完后才会计费。
      * 如果没有激活提示，说明服务已激活。

  #. 前往 **Key Management** 页面。在 **API Key** 选项卡，点击 **Create API Key**\ 。
  #. 创建后复制您的 API 密钥并妥善保存。

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

* **中国大陆用户**

  #. 登录 |link_aliyun|\ （百炼控制台）。
  #. 选择 **Create API Key**\ 。如果提示模型服务未开通，点击 **Activate**，
     同意条款并领取免费额度。激活后按钮将变为可用。

     .. image:: img/llm_qwen_aliyun_create.png

  #. 再次点击 **Create API Key**\ ，验证后点击 **Confirm**\ 。

     .. image:: img/llm_qwen_aliyun_confirm.png

  #. 创建后复制您的 API 密钥。

     .. image:: img/llm_qwen_aliyun_copy.png

**保存 API 密钥**

.. code-block:: bash

    cd ~/picrawler/examples
    sudo nano secret.py

.. code-block:: python

    QWEN_API_KEY = "sk-xxx"

**测试**

.. code-block:: bash

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

.. code-block:: python

   from picrawler.llm import Qwen
   from secret import QWEN_API_KEY

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

.. code-block:: bash

    sudo python3 18.online_llm_test.py

Grok (xAI)
--------------

Grok 是 xAI（Elon Musk 团队）的对话式 AI。

**获取 API 密钥**

#. 注册账户：|link_grok_ai|。先充值 — 否则 API 无法使用。
#. 前往 API Keys 页面，点击 **Create API key**\ 。

   .. image:: img/llm_grok_create.png

#. 输入名称，点击 **Create API key**\ 。

   .. image:: img/llm_grok_name.png

#. 复制密钥并保存。

   .. image:: img/llm_grok_copy.png

#. 在项目文件夹中保存到 ``secret.py``：

   .. code-block:: python

      GROK_API_KEY = "xai-xxx"

**查看模型** — 前往 xAI 控制台的 Models 页面查看可用模型及其 API ID。

   .. image:: img/llm_grok_model.png

**测试**

.. code-block:: python

   from picrawler.llm import Grok
   from secret import GROK_API_KEY

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

.. code-block:: bash

   sudo python3 18.online_llm_test.py

----

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

DeepSeek 是中国 LLM 提供商，提供经济实惠且功能强大的模型。

**获取 API 密钥**

#. 登录 |link_deepseek|。
#. 右上角菜单选择 **API Keys → Create API Key**。

   .. image:: img/llm_deepseek_create.png

#. 输入名称，点击 **Create**\ ，复制密钥。

   .. image:: img/llm_deepseek_copy.png

#. 保存到 ``secret.py``：

   .. code-block:: python

      DEEPSEEK_API_KEY = "sk-xxx"

**启用计费** — 需先充值（如 ¥10）。

   .. image:: img/llm_deepseek_chognzhi.png

**可用模型**\ ：``deepseek-chat``、``deepseek-reasoner``

**测试**

.. code-block:: python

   from picrawler.llm import Deepseek
   from secret import DEEPSEEK_API_KEY

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

.. code-block:: bash

   sudo python3 18.online_llm_test.py

----

Doubao（豆包）
----------------

Doubao 是字节跳动（火山引擎 Ark）的 AI 模型平台。

**获取 API 密钥**

#. 登录 |link_doubao|。
#. 左侧菜单 **API Key Management → Create API Key**。

   .. image:: img/llm_doubao_create.png

#. 选择名称并点击 **Create**。

   .. image:: img/llm_doubao_name.png

#. 点击 **Show API Key** 图标并复制。

   .. image:: img/llm_doubao_copy.png

#. 保存到 ``secret.py``：``DOUBAO_API_KEY = "xxx"``

**选择模型**

#. 前往模型市场选择模型。

   .. image:: img/llm_doubao_model_select.png

#. 例如选择 **Doubao-seed-1.6**\ ，点击 **API 接入**\ 。

   .. image:: img/llm_doubao_model.png

#. 选择 API Key 并点击 **Use API**\ 。

   .. image:: img/llm_doubao_use_api.png

#. 点击 **Enable Model**\ 。

   .. image:: img/llm_doubao_kaitong.png

#. 悬停在模型 ID 上复制。

   .. image:: img/llm_doubao_copy_id.png

**测试**

.. code-block:: python

   from picrawler.llm import Doubao
   from secret import DOUBAO_API_KEY

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

.. code-block:: bash

   sudo python3 18.online_llm_test.py


通用
------

本项目支持通过统一接口连接多个 LLM 平台。内置兼容：

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

此外，您可以连接**任何兼容 OpenAI API 格式的 LLM 服务**\ 。

**获取并保存 API 密钥**

.. code-block:: bash

   cd ~/picrawler/examples
   nano secret.py

.. code-block:: python

   API_KEY = "your_api_key_here"

.. warning::

   请妥善保管您的 API 密钥。不要将 ``secret.py`` 上传到公共仓库。

**使用示例代码测试**

.. code-block:: bash

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

.. note::

   关于 ``base_url``：我们支持 **OpenAI API 格式**\ ，以及与它\ **兼容**\ 的任何 API。
   每个提供商有自己的 ``base_url``。请查阅其文档。

.. code-block:: python

   from picrawler.llm import LLM
   from secret import API_KEY

   llm = LLM(
       base_url="https://api.example.com/v1",  // 填入提供商的 base_url
       api_key=API_KEY,
       model="your-model-name-here",
   )

.. code-block:: bash

   python3 18.online_llm_test.py