Add Function Calling Demo Documentation

Author: juncaipeng

README.md

@@ -139,7 +139,6 @@ import erniebot
 erniebot.api_type = "yinian"
 erniebot.access_token = "<access-token-for-yinian>"
 
-
 response = erniebot.Image.create(
     model="ernie-vilg-v2",
     prompt="雨后的桃花，8k，辛烷值渲染",

docs/README.md

@@ -130,7 +130,6 @@ import erniebot
 erniebot.api_type = "yinian"
 erniebot.access_token = "<access-token-for-yinian>"
 
-
 response = erniebot.Image.create(
     model="ernie-vilg-v2",
     prompt="雨后的桃花，8k，辛烷值渲染",
@@ -143,7 +142,6 @@ print(response)
 
 <img width="512" alt="image" src="https://github.com/PaddlePaddle/ERNIE-Bot-SDK/assets/1371212/73911c97-ef42-4803-8dc6-d385486c128c">
 
-
 我们推荐两个撰写文生图Prompt提示词的文档，大家可以组合使用，创作出更加精美的图片。
 * [AI作画-基础版使用指南](https://ai.baidu.com/ai-doc/NLP/qlakgh129)
 * [AI作画-高级版使用指南](https://ai.baidu.com/ai-doc/NLP/4libyluzs)

docs/api_reference/embedding.md

@@ -17,7 +17,6 @@ erniebot.Embedding.create(**kwargs: Any)
 | input | list[string] | 是 | 输入的文本列表。服务可以支持计算多段文本的向量，列表中每个元素即为一段单独的文本。注意， <br>(1) 列表长度不得超过16； <br>(2) 服务在计算向量时，每段文本只支持最多384个token，超长报错（服务采用`汉字数 + 单词数 * 1.3`估算token数量）； <br>(3) 文本内容不能为空。 |
 | user_id | string | 否 | 表示最终用户的唯一标识符，可以监视和检测滥用行为，防止接口恶意调用。 |
 
-
 ## 返回结果
 
 接口返回`erniebot.response.EBResponse`对象。

docs/authentication.md

@@ -1,5 +1,7 @@
 # 认证鉴权
+
 调用文心大模型是一项收费服务，所以大家使用ERNIE Bot SDK需要进行认证鉴权。
+
 认证鉴权主要包括两步：申请用户凭证，设置鉴权参数。
 
 ERNIE Bot SDK支持多个后端来调用文心大模型（如下表格），大家可以根据实际情况选择。不同后端支持的模型、认证鉴权方式存在差异，下面我们分别介绍。
@@ -16,13 +18,10 @@ ERNIE Bot SDK支持多个后端来调用文心大模型（如下表格），大
 
 在[AI Studio星河社区](https://aistudio.baidu.com/index)注册并登录账号，可以在个人中心的[访问令牌页面](https://aistudio.baidu.com/usercenter/token)获取用户凭证access token。
 
-
 <div align="center">
-<img src="https://user-images.githubusercontent.com/52520497/268609784-8476269e-5cdb-4dfc-9841-983b5a766226.png"  width = "800" />  
+<img src="https://user-images.githubusercontent.com/52520497/268609784-8476269e-5cdb-4dfc-9841-983b5a766226.png" width="800">  
 </div>
 
-
-
 注意事项：
 
 * AI Studio每个账户的access token，有100万token的免费额度，可以用于ERNIE Bot SDK调用文心一言大模型。AI Studio近期将会开通付费购买的渠道。
@@ -33,6 +32,7 @@ ERNIE Bot SDK支持多个后端来调用文心大模型（如下表格），大
 AI Studio后端可以使用access token进行鉴权，支持如下三种方法来设置鉴权参数。
 
 (1) 使用环境变量：
+
 ```shell
 export EB_API_TYPE="aistudio"
 export EB_ACCESS_TOKEN="<access-token-for-aistudio>"
@@ -75,19 +75,20 @@ response = erniebot.ChatCompletion.create(
 * 进入百度云 - [千帆大模型平台](https://cloud.baidu.com/product/wenxinworkshop)，提交申请体验。通常几个小时后会通知申请通过。
 * 登录[千帆大模型平台](https://cloud.baidu.com/product/wenxinworkshop)，进入[控制台](https://console.bce.baidu.com/qianfan/ais/console/applicationConsole/application)创建千帆应用，可以拿到AK/SK（如下图）。
 * 进入[计费管理](https://console.bce.baidu.com/qianfan/chargemanage/list)，选择服务并开通付费，包括：`ERNIE-Bot大模型公有云在线调用服务`、`ERNIE-Bot-turbo大模型公有云在线调用服务`和`Embedding-V1公有云在线调用服务`。
-* 参考access token[获取教程](https://cloud.baidu.com/doc/WENXINWORKSHOP/s/Ilkkrb0i5)，使用AK/SK获取access token。
+* 参考[access token获取教程](https://cloud.baidu.com/doc/WENXINWORKSHOP/s/Ilkkrb0i5)，使用AK/SK获取access token。
 
 <div align="center">
-<img src="https://user-images.githubusercontent.com/52520497/264009567-46f88a38-df70-4a79-affb-ddbf797855b1.jpeg"  width = "800" />  
+<img src="https://user-images.githubusercontent.com/52520497/264009567-46f88a38-df70-4a79-affb-ddbf797855b1.jpeg" width="800">  
 </div>
 
 注意事项：
-* 千帆的AK/SK是一直有效，而access token默认有效期是30天，失效后需要重新获取access token。
+* 千帆的AK/SK是一直有效，而access token的默认有效期是30天，失效后需要重新获取access token。
 
 ### 2.2 设置鉴权参数
 
 千帆后端也可以使用access token进行鉴权，设置鉴权参数的三种方法和AI Studio后端类似，举例如下。
-请注意替换后端参数为`qianfan`，并且使用千帆平台申请的`access_token`。
+
+请注意设置后端参数为`'qianfan'`，并且使用千帆平台申请的access token。
 
 ```shell
 export EB_API_TYPE="qianfan"
@@ -101,7 +102,7 @@ erniebot.api_type = "qianfan"
 erniebot.access_token = "<access-token-for-qianfan>"
 ```
 
-此外，千帆后端还可以使用AK/SK进行鉴权，同样支持三种方法，环境变量对应是`EB_AK`和`EB_SK`，代码变量对应是`ak`和`sk`，举例如下。
+此外，千帆后端还可以使用AK/SK进行鉴权，同样支持三种方法，环境变量对应是`EB_AK`和`EB_SK`，Python变量对应是`ak`和`sk`，举例如下。
 
 ```shell
 export EB_API_TYPE="qianfan"
@@ -125,19 +126,19 @@ erniebot.sk = "<secret-access-key-for-qianfan>"
 
 * 进入[百度云](https://cloud.baidu.com/)，完成注册。
 * 进入百度云 - [智能创作平台](https://console.bce.baidu.com/ai/#/ai/intelligentwriting/app/list)，创建应用，可以拿到AK/SK（如下图）。
-* 参考access token[获取教程](https://cloud.baidu.com/doc/WENXINWORKSHOP/s/Ilkkrb0i5)，使用AK和SK获取access token。
+* 参考[access token获取教程](https://cloud.baidu.com/doc/WENXINWORKSHOP/s/Ilkkrb0i5)，使用AK和SK获取access token。
 
 <div align="center">
-<img src="https://user-images.githubusercontent.com/52520497/264009612-17658684-c066-44e5-8814-178214aa8155.jpeg"  width = "800" />  
+<img src="https://user-images.githubusercontent.com/52520497/264009612-17658684-c066-44e5-8814-178214aa8155.jpeg" width="800">  
 </div>
 
-
 智能创作平台的完整介绍，请参考[使用文档](https://ai.baidu.com/ai-doc/NLP/Uk53wndcb)；费用、充值相关的问题，请参考[计费简介](https://ai.baidu.com/ai-doc/NLP/qla2beec2)。
 
 ### 3.2 设置鉴权参数
 
 智能创作平台后端设置鉴权参数的方法，和千帆后端完全一致，都支持access toke或者AK/SK参数，举例如下。
-请注意替换后端参数为`yinian`，并且使用智能创作平台申请的`access_token`、`AK/SK`。
+
+请注意设置后端参数为`'yinian'`，并且使用智能创作平台申请的access_token、AK/SK。
 
 ```shell
 export EB_API_TYPE="yinian"

docs/guides/image.md

@@ -35,11 +35,11 @@ print(img_url)
 文本提示是`请帮我画一只可爱的大猫咪`时，生成的图片如下。
 
 <div align="center">
-<img src="https://user-images.githubusercontent.com/52520497/263970054-abf68cb8-3ad3-48cb-942f-1fc3075d5452.png"  width = "400" />  
+<img src="https://user-images.githubusercontent.com/52520497/263970054-abf68cb8-3ad3-48cb-942f-1fc3075d5452.png" width="400">  
 </div>
 
 文本提示是`请帮我画一个开心的袋熊`时，生成的图片如下。
 
 <div align="center">
-<img src="https://user-images.githubusercontent.com/52520497/263970013-53eef22c-5ad0-4d60-835b-5f7b699fb3ef.png"  width = "400" />  
+<img src="https://user-images.githubusercontent.com/52520497/263970013-53eef22c-5ad0-4d60-835b-5f7b699fb3ef.png" width="400">  
 </div>

examples/function_calling/README.md

@@ -23,8 +23,63 @@ python function_calling_demo.py --port 8188
 
 ### 界面介绍
 
+应用的整体界面如下图所示：
+
+![overview](https://user-images.githubusercontent.com/21275753/268629662-454d756d-e8b0-49fa-98a5-35444ffd4bfe.png)
+
+界面可分为参数配置区、对话区、函数调用区以及日志区。对各分区的介绍如下：
+
+**参数配置区**
+
+在此分区可以设置后端类型、鉴权参数以及要使用的模型类型等。此外，在“高级配置”中可以设定`top_p`与`temperature`等参数以调节模型响应内容的随机程度。
+
+**对话区**
+
+在该分区与大模型进行对话。在文本框中输入消息后敲击回车键或者点击“发送消息”即可完成消息的发送。除基本对话功能外，支持重置对话、撤回消息以及重新生成最新的一条回复。
+
+**函数调用区**
+
+在该分区中可以管理和调用函数。在分区左侧查看应用预置的函数定义与描述，也可以编写自定义函数并为其添加描述。在右侧可以执行函数的具体调用，只需给定函数名称和请求参数即可。得到函数响应参数后，可以通过点击“发送调用结果”将响应参数回传给模型。此外，可以选择将哪些函数作为供模型参考的备选函数，模型将会综合对话上下文决定是否建议调用备选函数中的一个或几个。
+
+**日志区**
+
+记录最近10条消息的原始数据，便于调试。
+
 ### 典型使用流程
 
-使用前，请参考[认证鉴权文档](../../docs/authentication.md#%E7%94%B3%E8%AF%B7%E5%8D%83%E5%B8%86%E5%A4%A7%E6%A8%A1%E5%9E%8B%E5%B9%B3%E5%8F%B0%E7%9A%84aksk)申请千帆平台的AK/SK用于服务调用鉴权。
+使用前，请参考[认证鉴权文档](../../docs/authentication.md)获取要使用的后端的鉴权参数。
+
+(1) 在参数配置区选择后端类型，并配置鉴权参数。
+
+(2) 点击展开“函数调用”面板，浏览其中的函数定义与描述。在“备选函数”复选框组中勾选想要使用的函数。
+
+(3) 在对话区的文本框中输入需求，例如“请问李小明的邮箱地址是什么？”。敲击回车键或者点击“发送信息”，然后等待模型给出回复。
+
+(4) 如果模型认为应当执行一个函数调用，则在对话记录中提示的消息将会以“**【函数调用】**”开头，后续紧跟着模型的思考过程以及它建议调用的函数名称与参数。在这种情况下，“函数调用”面板将自动展开（如果之前是被折叠状态的话），并自动在其中的“函数名称”文本框与“请求参数”编辑器中分别填入模型建议调用的函数名称以及JSON格式的请求参数。模型给出的建议不一定是准确的，大家可以根据实际情况修改函数名称与请求参数。**调用的函数必须是备选函数之一**。
+
+(5) 确认函数名称与请求参数无误后，点击“调用函数”，得到函数的响应参数，如下图所示：
+
+![call_a_function](https://user-images.githubusercontent.com/21275753/268624448-e0fd4c28-3ecf-45cc-b2d8-2f5b66f1f73d.jpg)
+
+(6) 点击“发送调用结果”，将函数响应参数回传给模型。此时，应用会自动生成一条以“**【函数调用】**”开头的对话记录，其中给出调用的函数名称以及响应参数，作为用户发送的消息。
+
+(7) 模型将会根据函数响应参数，建议我们调用下一个函数，或者对我们在步骤(3)中提出的问题进行回复（更新在对话区的对话记录中）。如果函数建议我们继续调用函数，则仍然遵循步骤(4)-(6)的处理方式。
 
 ### 添加自定义函数
+
+除了使用预置的函数外，应用也支持添加**1个**用户自定义函数。将“函数调用”面板展开后，可以找到“自定义函数”选项卡，界面如下所示：
+
+![custom_function](https://user-images.githubusercontent.com/21275753/268624469-a6666d32-92f9-463c-9f6c-994d8c406e94.jpg)
+
+在“定义”编辑器中，可以编写自定义函数的定义。需注意如下几点：
+
+* 函数以Python语言定义，需遵循Python语言的语法规则。
+* 函数的名称必须为`custom_function`，当前禁止修改，否则将触发错误。
+* 出于安全考虑，当前不支持在自定义函数中使用Python内置对象。这意味着`import`语句以及Python标准库在自定义函数中均无法被使用。
+
+在“描述”编辑器中，可以编写对自定义函数的描述。点击“更新描述”按钮可以从函数定义自动生成或更新函数描述，但该功能只限于生成初版的描述，为了使模型得到更充分的提示，描述中的`description`、参数`type`等信息仍需要手工完善。编写描述时请注意如下几点：
+
+* 描述以**JSON**格式编写，注意与Python字典的区分。
+* 函数的`name`必须为`"custom_function"`。
+
+编写完成函数的定义与描述后，需要勾选上方的`custom_function`复选框才可以将自定义函数加入到备选函数中。当自定义函数的定义或是描述中存在语法错误时，`custom_function`复选框将无法被选中，页面右上角会提示具体的错误原因。当“定义”或“描述”编辑器中的内容发生变动时，`custom_function`复选框将被自动取消选中。