Merge pull request #106 from tackhwa/main

增加 Ernie bot SDK 调用文心一言 方式

Author: logan-zou

.env

@@ -13,6 +13,9 @@ QIANFAN_ACCESS_KEY = ""
 # 安全认证方式获取的 Secret Key
 QIANFAN_SECRET_KEY = ""
 
+# Ernie SDK 文心 API 访问密钥配置
+EB_ACCESS_TOKEN = ""
+
 # 控制台中获取的 APPID 信息
 SPARK_APPID = ""
 # 控制台中获取的 APIKey 信息
@@ -29,4 +32,4 @@ IFLYTEK_SPARK_API_KEY = ""
 IFLYTEK_SPARK_API_SECRET = ""
 
 # 智谱 API 访问密钥配置
-ZHIPUAI_API_KEY = ""
+ZHIPUAI_API_KEY = ""

docs/C2/2. 使用 LLM API.md

@@ -173,7 +173,9 @@ get_completion("你好")
 
 百度同样提供了文心一言的 API 接口，其在推出大模型的同时，也推出了 `文心千帆` 企业级大语言模型服务平台，包括了百度整套大语言模型开发工作链。对于不具备大模型实际落地能力的中小企业或传统企业，考虑文心千帆是一个可行的选择。当然，本教程仅包括通过文心千帆平台调用文心一言 API，对于其他企业级服务不予讨论。
 
-### 2.1 API 申请指引
+### 2.1 千帆 SDK
+
+#### 2.1.1 API 申请指引
 
 #### 获取密钥
 
@@ -219,7 +221,7 @@ from dotenv import load_dotenv, find_dotenv
 _ = load_dotenv(find_dotenv())
 ```
 
-### 2.2 调用文心千帆 API
+#### 2.1.2 调用文心千帆 API
 
 百度文心同样支持在传入参数的 messages 字段中配置 user、assistant 两个成员角色的 prompt，但与 OpenAI 的 prompt 格式不同的是，模型人设是通过另一个参数 system 字段传入的，而不是在 messages 字段中。
 
@@ -310,6 +312,92 @@ get_completion("你好，介绍一下你自己")
 
     · temperature，温度系数，默认 0.8，文心的 temperature 参数要求范围为 (0, 1.0]，不能设置为 0。
 
+### 2.2 ERNIE SDK
+
+#### 2.2.1 API 申请指引
+
+这里将使用 `ERNIE SDK` 中的 `ERNIE Bot` 来调用文心一言。ERNIE Bot 为开发者提供了便捷易用的接口，使其能够轻松调用文心大模型的强大功能，涵盖了文本创作、通用对话、语义向量以及AI作图等多个基础功能。`ERNIE SDK` 并不像 `千帆 SDK` 那样支持各种大语言模型， 而是只支持百度自家的文心大模型。目前 ERNIE Bot 支持的模型有：
+
+```
+ernie-3.5               文心大模型（ernie-3.5）
+ernie-lite              文心大模型（ernie-lite）
+ernie-4.0               文心大模型（ernie-4.0）
+ernie-longtext          文心大模型（ernie-longtext）
+ernie-speed             文心大模型（ernie-speed）
+ernie-speed-128k        文心大模型（ernie-speed-128k）
+ernie-tiny-8k           文心大模型（ernie-tiny-8k）
+ernie-char-8k           文心大模型（ernie-char-8k）
+ernie-text-embedding    文心百中语义模型
+ernie-vilg-v2           文心一格模型
+```
+
+在使用 ERNIE SDK 之前，需要先获取 AI Studio 后端的认证鉴权（access token），在代码中需要配置自己的密钥才能实现对模型的调用，下面我们以 [Ernie Bot](https://ernie-bot-agent.readthedocs.io/zh-cn/latest/sdk/)为例，介绍通过 ERNIE Bot 调用文心模型的流程。
+
+首先需要在[AI Studio星河社区](https://aistudio.baidu.com/index)注册并登录账号（新用户会送100万token的免费额度，为期3个月）。
+
+![](../figures/C2-2-ernie_bot_1.png)
+
+点击 `访问令牌` 获取账户的 access token，复制 access token 并且以此形式 `EB_ACCESS_TOKEN="..."` 保存到 `.env` 文件中。
+![](../figures/C2-2-ernie_bot_2.png)
+
+然后执行以下代码，将密钥加载到环境变量中。
+```python
+from dotenv import load_dotenv, find_dotenv
+
+# 读取本地/项目的环境变量。
+
+# find_dotenv() 寻找并定位 .env 文件的路径
+# load_dotenv() 读取该 .env 文件，并将其中的环境变量加载到当前的运行环境中  
+# 如果你设置的是全局的环境变量，这行代码则没有任何作用。
+_ = load_dotenv(find_dotenv())
+```
+
+#### 2.2.2 调用 Ernie Bot API
+
+```python
+import erniebot
+import os
+
+erniebot.api_type = "aistudio"
+erniebot.access_token = os.environ.get("EB_ACCESS_TOKEN")
+
+def gen_wenxin_messages(prompt):
+    '''
+    构造文心模型请求参数 messages
+
+    请求参数：
+        prompt: 对应的用户提示词
+    '''
+    messages = [{"role": "user", "content": prompt}]
+    return messages
+
+
+def get_completion(prompt, model="ernie-3.5", temperature=0.01):
+    '''
+    获取文心模型调用结果
+
+    请求参数：
+        prompt: 对应的提示词
+        model: 调用的模型
+        temperature: 模型输出的温度系数，控制输出的随机程度，取值范围是 0~1.0，且不能设置为 0。温度系数越低，输出内容越一致。
+    '''
+
+    chat_comp = erniebot.ChatCompletion()
+    message = gen_wenxin_messages(prompt)
+
+    resp = chat_comp.create(messages=message, 
+                        model=model,
+                        temperature = temperature,
+                        system="你是一名个人助理")
+
+    return resp["result"]
+```
+
+```python
+get_completion("你好，介绍一下你自己")
+```
+    '你好！我是一名个人助理，我的主要任务是帮助你完成日常任务、提供信息、解答问题，并尽力提升你的工作效率和生活质量。无论你需要什么帮助，我都会尽力提供支持。'
+
 ## 3. 使用讯飞星火
 
 讯飞星火认知大模型，由科大讯飞于 2023 年 5 月推出的中文大模型，也是国内大模型的代表产品之一。同样，受限于中文语境与算力资源，星火在使用体验上与 ChatGPT 还存在差异，但是，作为与文心不分伯仲的国内中文大模型，仍然值得期待与尝试。相较于存在显著资源、技术优势的百度，科大讯飞想要杀出重围，成为国内大模型的佼佼者，需要充分利用相对优势，至少目前来看，星火并未掉队。
@@ -652,4 +740,4 @@ get_completion("你好")
 
 - **建议您根据应用场景调整 top_p 或 temperature 参数，但不要同时调整两个参数**
 
-**注：本文对应源代码在[2. 使用 LLM API.ipynb](https://github.com/datawhalechina/llm-universe/blob/main/notebook/C2%20%E4%BD%BF%E7%94%A8%20LLM%20API%20%E5%BC%80%E5%8F%91%E5%BA%94%E7%94%A8/2.%20%E4%BD%BF%E7%94%A8%20LLM%20API.ipynb)，如需复现可下载运行源代码。**
+**注：本文对应源代码在[2. 使用 LLM API.ipynb](https://github.com/datawhalechina/llm-universe/blob/main/notebook/C2%20%E4%BD%BF%E7%94%A8%20LLM%20API%20%E5%BC%80%E5%8F%91%E5%BA%94%E7%94%A8/2.%20%E4%BD%BF%E7%94%A8%20LLM%20API.ipynb)，如需复现可下载运行源代码。**

docs/figures/C2-2-ernie_bot_1.png

@@ -290,7 +290,14 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### 2.1 API 申请指引"
+    "### 2.1 千帆 SDK"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### 2.1.1 API 申请指引"
    ]
   },
   {
@@ -360,7 +367,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### 2.2 调用文心千帆 API"
+    "#### 2.1.2 调用文心千帆 API"
    ]
   },
   {
@@ -498,6 +505,147 @@
     "    · temperature，温度系数，默认 0.8，文心的 temperature 参数要求范围为 (0, 1.0]，不能设置为 0。"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### 2.2 ERNIE SDK"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### 2.2.1 API 申请指引"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "这里将使用 `ERNIE SDK` 中的 `ERNIE Bot` 来调用文心一言。ERNIE Bot 为开发者提供了便捷易用的接口，使其能够轻松调用文心大模型的强大功能，涵盖了文本创作、通用对话、语义向量以及AI作图等多个基础功能。`ERNIE SDK` 并不像 `千帆 SDK` 那样支持各种大语言模型， 而是只支持百度自家的文心大模型。目前 ERNIE Bot 支持的模型有：\n",
+    "\n",
+    "```\n",
+    "ernie-3.5               文心大模型（ernie-3.5）\n",
+    "ernie-lite              文心大模型（ernie-lite）\n",
+    "ernie-4.0               文心大模型（ernie-4.0）\n",
+    "ernie-longtext          文心大模型（ernie-longtext）\n",
+    "ernie-speed             文心大模型（ernie-speed）\n",
+    "ernie-speed-128k        文心大模型（ernie-speed-128k）\n",
+    "ernie-tiny-8k           文心大模型（ernie-tiny-8k）\n",
+    "ernie-char-8k           文心大模型（ernie-char-8k）\n",
+    "ernie-text-embedding    文心百中语义模型\n",
+    "ernie-vilg-v2           文心一格模型\n",
+    "```\n",
+    "\n",
+    "在使用 ERNIE SDK 之前，需要先获取 AI Studio 后端的认证鉴权（access token），在代码中需要配置自己的密钥才能实现对模型的调用，下面我们以 [Ernie Bot](https://ernie-bot-agent.readthedocs.io/zh-cn/latest/sdk/) 为例，介绍通过 ERNIE Bot 调用文心模型的流程。\n",
+    "\n",
+    "首先需要在 [AI Studio星河社区](https://aistudio.baidu.com/index) 注册并登录账号（新用户会送100万token的免费额度，为期3个月）。\n",
+    "\n",
+    "![](../../figures/C2-2-ernie_bot_1.png)\n",
+    "\n",
+    "点击 `访问令牌` 获取账户的 access token，复制 access token 并且以此形式 `EB_ACCESS_TOKEN=\"...\"` 保存到 `.env` 文件中。\n",
+    "![](../../figures/C2-2-ernie_bot_2.png)\n",
+    "\n",
+    "然后执行以下代码，将密钥加载到环境变量中。"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from dotenv import load_dotenv, find_dotenv\n",
+    "\n",
+    "# 读取本地/项目的环境变量。\n",
+    "\n",
+    "# find_dotenv() 寻找并定位 .env 文件的路径\n",
+    "# load_dotenv() 读取该 .env 文件，并将其中的环境变量加载到当前的运行环境中  \n",
+    "# 如果你设置的是全局的环境变量，这行代码则没有任何作用。\n",
+    "_ = load_dotenv(find_dotenv())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "#### 2.2.2 调用 Ernie Bot API"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import erniebot\n",
+    "import os\n",
+    "\n",
+    "erniebot.api_type = \"aistudio\"\n",
+    "erniebot.access_token = os.environ.get(\"EB_ACCESS_TOKEN\")\n",
+    "\n",
+    "def gen_wenxin_messages(prompt):\n",
+    "    '''\n",
+    "    构造文心模型请求参数 messages\n",
+    "\n",
+    "    请求参数：\n",
+    "        prompt: 对应的用户提示词\n",
+    "    '''\n",
+    "    messages = [{\"role\": \"user\", \"content\": prompt}]\n",
+    "    return messages\n",
+    "\n",
+    "\n",
+    "def get_completion(prompt, model=\"ernie-3.5\", temperature=0.01):\n",
+    "    '''\n",
+    "    获取文心模型调用结果\n",
+    "\n",
+    "    请求参数：\n",
+    "        prompt: 对应的提示词\n",
+    "        model: 调用的模型\n",
+    "        temperature: 模型输出的温度系数，控制输出的随机程度，取值范围是 0~1.0，且不能设置为 0。温度系数越低，输出内容越一致。\n",
+    "    '''\n",
+    "\n",
+    "    chat_comp = erniebot.ChatCompletion()\n",
+    "    message = gen_wenxin_messages(prompt)\n",
+    "\n",
+    "    resp = chat_comp.create(messages=message, \n",
+    "                        model=model,\n",
+    "                        temperature = temperature,\n",
+    "                        system=\"你是一名个人助理\")\n",
+    "\n",
+    "    return resp[\"result\"]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "'你好！我是一名个人助理，我的主要任务是协助和支持你的日常工作和活动。我可以帮助你管理时间、安排日程、提供信息、解答问题，以及完成其他你需要的任务。如果你有任何需求或问题，请随时告诉我，我会尽力帮助你。'"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "get_completion(\"你好，介绍一下你自己\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "`Ernie Bot API` 的调用方式和参数基本和 `文心千帆 API` 一样，除了在创建 `ChatCompletion` 时使用的是 `.create()` 函数。\n",
+    "\n",
+    "所以此处并不再过多介绍接口常用参数，你可以参考 [参数介绍](https://ernie-bot-agent.readthedocs.io/zh-cn/latest/sdk/api_reference/chat_completion/) 以获取其他参数的详细信息。"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

docs/figures/C2-2-ernie_bot_2.png

@@ -22,4 +22,5 @@ pymupdf==1.24.0
 unstructured==0.12.6
 chromadb==0.4.14
 markdown==3.6
-spark-ai-python==0.3.15
+spark-ai-python==0.3.15
+erniebot==0.5.5