examples/function_calling/README.md

# 函数调用功能演示应用

函数调用功能演示应用支持基础的对话补全功能，同时，模型可能在对话中要求发起函数调用，这些函数可以是应用预先提供的，也可以是用户自定义的。该应用可供大家体验ERNIE Bot SDK的函数调用功能，也可以用于调试本地代码、以进一步优化函数调用效果。

## 安装依赖

首先，请确保Python版本>=3.8。然后执行如下命令：

```shell
cd examples/function_calling
pip install -r requirements.txt
```

## 运行应用

执行如下命令：

```shell
python gradio_demo.py
```

然后，使用本地浏览器打开[http://localhost:8073](http://localhost:8073)。

可以通过`--port`指定端口号，例如`python gradio_demo.py --port 8188`指定8188端口作为启动Gradio服务的端口。默认端口为8073。

### 界面介绍

应用的整体界面如下图所示：

![Overview](https://user-images.githubusercontent.com/21275753/268629662-454d756d-e8b0-49fa-98a5-35444ffd4bfe.png)

界面可分为参数配置区、对话区、函数调用区以及日志区。对各分区的介绍如下：

**参数配置区**

在此分区可以设置后端类型、鉴权参数以及要使用的模型类型等。此外，在“高级配置”中可以设定`top_p`与`temperature`等参数以调节模型响应内容的随机程度。

**对话区**

在该分区与大模型进行对话。在文本框中输入消息后敲击回车键或者点击“发送消息”即可完成消息的发送。除基本对话功能外，支持重置对话、撤回消息以及重新生成最新的一条回复。

**函数调用区**

在该分区中可以管理和调用函数。在分区左侧查看应用预置的函数定义与描述，也可以编写自定义函数并为其添加描述。在右侧可以执行函数的具体调用，只需给定函数名称和请求参数即可。得到函数响应参数后，可以通过点击“发送调用结果”将响应参数回传给模型。此外，可以选择将哪些函数作为供模型参考的备选函数，模型将会综合对话上下文决定是否建议调用备选函数中的一个或几个。

**日志区**

记录最近10条消息的原始数据，便于调试。

### 典型使用流程

使用前，请参考[认证鉴权文档](../../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`复选框将被自动取消选中。