[Docs] Add Function Calling Guide (#13)

* [Docs] Fix heading level

* Polish docs

* Add function calling docs

* Fix docs

* Fix docs

* Fix docs

* Fix docs

* Allow passign user_id when using aistudio backend

Author: Bobholamovic

README.md

@@ -48,7 +48,7 @@ response = erniebot.ChatCompletion.create(model="ernie-bot-3.5", messages=[{"rol
 print(response.result)
 ```
 
-### 命令行接口 (CLI)
+### 命令行接口（CLI）
 
 ```bash
 # List supported models
@@ -73,9 +73,9 @@ erniebot api image.create --model ernie-vilg-v2 --prompt "画一只驴肉火烧"
 
 ## 经典示例
 
-### 对话补全 (Chat Completion)
+### 对话补全（Chat Completion）
 
-ERNIE Bot SDK提供具备对话补全能力的文心一言旗舰版模型`ernie-bot-3.5`和文心一言迅捷版模型`ernie-bot-turbo`。
+ERNIE Bot SDK提供具备对话补全能力的文心一言旗舰版模型ernie-bot-3.5和文心一言迅捷版模型ernie-bot-turbo。
 旗舰版模型的效果更好，迅捷版模型的响应速度更快、推理时延更低，大家可以根据实际场景的需求选择合适的模型。
 
 以下是调用文心一言旗舰版模型进行多轮对话的示例。
@@ -104,7 +104,7 @@ response = erniebot.ChatCompletion.create(
 print(response)
 ```
 
-### 语义向量生成 (Embedding Generation)
+### 语义向量（Embedding）
 
 ERNIE Bot SDK提供用于提取语义向量的Embedding模型。
 该模型基于文心大模型，使用海量数据训练得到，为[文心百中](https://wenxin.baidu.com/baizhong/index/)系统提供关键能力。该模型可以将字符串转为384维浮点数表达的语义向量，语义向量具备极其精准的语义表达能力，可以用于度量两个字符串之间的语义相似度。
@@ -162,14 +162,13 @@ print(response)
 
 大家也可登陆[文心一格](https://yige.baidu.com/)平台，体验更多AI艺术与创意辅助的能力。
 
-## 【beta】函数调用（Function Calling）
+### 【beta】函数调用（Function Calling）
 
 ERNIE Bot SDK提供函数调用功能，即通过大模型根据对话上下文确定何时以及如何调用函数。该功能目前处于测试状态。
 
 以下是调用文心一言旗舰版模型进行函数调用的示例。
 
 ```python
-import json
 import erniebot
 
 erniebot.api_type = "qianfan"
@@ -231,13 +230,14 @@ print(response)
   * [认证鉴权](./docs/authentication.md)
   * [参数配置](./docs/configuration.md)
 * 使用指南
-  * [对话补全ChatCompletion](./docs/guide/chat_completion.md)
-  * [语义向量生成Embedding](./docs/guide/embedding.md)
-  * [文生图Image](./docs/guide/image.md)
+  * [对话补全（Chat Completion）](./docs/guides/chat_completion.md)
+  * [语义向量（Embedding）](./docs/guides/embedding.md)
+  * [文生图（Image Generation）](./docs/guides/image.md)
+  * [函数调用（Function Calling）](./docs/guides/function_calling.md)
 * API文档
-  * [对话补全ChatCompletion](./docs/api_reference/chat_completion.md)
-  * [语义向量生成Embedding](./docs/api_reference/embedding.md)
-  * [文生图Image](./docs/api_reference/image.md)
+  * [ChatCompletion](./docs/api_reference/chat_completion.md)
+  * [Embedding](./docs/api_reference/embedding.md)
+  * [Image](./docs/api_reference/image.md)
 
 ## Acknowledgement
 

docs/README.md

@@ -39,7 +39,7 @@ response = erniebot.ChatCompletion.create(model="ernie-bot-3.5", messages=[{"rol
 print(response.result)
 ```
 
-### 命令行接口 (CLI)
+### 命令行接口（CLI）
 
 ```bash
 # List supported models
@@ -64,9 +64,9 @@ erniebot api image.create --model ernie-vilg-v2 --prompt "画一只驴肉火烧"
 
 ## 经典示例
 
-### 对话补全 (Chat Completion)
+### 对话补全（Chat Completion）
 
-ERNIE Bot SDK提供具备对话补全能力的文心一言旗舰版模型`ernie-bot-3.5`和文心一言迅捷版模型`ernie-bot-turbo`。
+ERNIE Bot SDK提供具备对话补全能力的文心一言旗舰版模型ernie-bot-3.5和文心一言迅捷版模型ernie-bot-turbo。
 旗舰版模型的效果更好，迅捷版模型的响应速度更快、推理时延更低，大家可以根据实际场景的需求选择合适的模型。
 
 以下是调用文心一言旗舰版模型进行多轮对话的示例。
@@ -95,7 +95,7 @@ response = erniebot.ChatCompletion.create(
 print(response)
 ```
 
-### 语义向量生成 (Embedding Generation)
+### 语义向量（Embedding）
 
 ERNIE Bot SDK提供提取语义向量的Embedding模型。
 该模型基于文心大模型，使用海量数据训练得到，为[文心百中](https://wenxin.baidu.com/baizhong/index/)系统提供关键能力。该模型可以将字符串转为384维浮点数表达的语义向量，语义向量具备极其精准的语义表达能力，可以用于度量两个字符串之间的语义相似度。
@@ -153,14 +153,13 @@ print(response)
 
 大家也可登陆[文心一格](https://yige.baidu.com/)平台，体验更多AI艺术与创意辅助的能力。
 
-## 【beta】函数调用（Function Calling）
+### 【beta】函数调用（Function Calling）
 
 ERNIE Bot SDK提供函数调用功能，即通过大模型根据对话上下文确定何时以及如何调用函数。该功能目前处于测试状态。
 
 以下是调用文心一言旗舰版模型进行函数调用的示例。
 
 ```python
-import json
 import erniebot
 
 erniebot.api_type = "qianfan"

docs/api_reference/chat_completion.md

@@ -1,8 +1,8 @@
 # ChatCompletion
 
-给定对话文本，模型服务会响应给出新的回复，包括回复的文本以及Token统计等信息。
+给定对话文本，模型服务会响应给出新的回复，包括回复的文本以及token数量统计等信息。
 
-## 函数接口
+## Python接口
 
 ``` {.py .copy}
 erniebot.ChatCompletion.create(**kwargs: Any)
@@ -15,7 +15,7 @@ erniebot.ChatCompletion.create(**kwargs: Any)
 | :---   | :--- | :------- | :---- |
 | model  | string | 是 | 模型名称。当前支持`'ernie-bot-3.5'`和`'ernie-bot-turbo'`。 |
 | messages | list[dict] | 是 | 对话上下文信息。列表中的元素个数须为奇数。详见[`messages`](#messages)。 |
-| functions | list[dict] | 否 | 可触发函数的描述列表。详见[`functions`](#functions)。当`model='ernie-bot-turbo'`时，此参数无效。 |
+| functions | list[dict] | 否 | 可触发函数的描述列表。详见[`functions`](#functions)。`ernie-bot-turbo`模型暂不支持此参数。 |
 | top_p | float | 否 | 生成环节在概率加和为`top_p`以内的top token集合内进行采样： <br>(1) 影响输出文本的多样性，取值越大，生成文本的多样性越强； <br>(2) 默认`0.8`，取值范围为`[0, 1.0]`； <br>(3) 建议该参数和temperature只设置其中一个。 |
 | temperature | float | 否 | 采样环节的参数，用于控制随机性。 <br>(1) 较高的数值会使输出更加随机，而较低的数值会使其更加集中和确定； <br>(2) 默认`0.95`，范围为`(0, 1.0]`，不能为`0`； <br>(3) 建议该参数和`top_p`只设置其中一个。 |
 | penalty_score | float | 否 | 通过对已生成的token增加惩罚，减少重复生成的现象，值越高则惩罚越大。 <br>(1) 值越大表示惩罚越大； <br>(2) 默认`1.0`，取值范围：`[1.0, 2.0]`。 |
@@ -45,7 +45,7 @@ erniebot.ChatCompletion.create(**kwargs: Any)
 
 `messages`中的每个元素包含如下键值对：
 
-| 键名 | 类型 | 必填 | 描述 |
+| 键名 | 值类型 | 必填 | 值描述 |
 |:--- | :---- | :--- | :---- |
 | role | string | 是 | `'user'`表示用户，`'assistant'`表示对话助手，`'function'`表示函数。 |
 | content | string or `None` | 是 | 对话内容，当`role`不为`'function'`时，必须设置该参数为非`None`值；当`role`为`'function'`时，可以设置该参数为`None`。 |
@@ -103,7 +103,7 @@ erniebot.ChatCompletion.create(**kwargs: Any)
 
 `functions`中的每个元素包含如下键值对：
 
-| 键名 | 类型 | 必填 | 描述 |
+| 键名 | 值类型 | 必填 | 值描述 |
 |:--- | :---- | :--- | :---- |
 | name | string | 是 | 函数名称。 |
 | description | string | 是 | 对函数功能的描述。 |
@@ -116,7 +116,7 @@ erniebot.ChatCompletion.create(**kwargs: Any)
 
 `function_call`为一个Python dict，其中包含如下键值对：
 
-| 键名 | 类型 | 必填 | 描述 |
+| 键名 | 值类型 | 必填 | 值描述 |
 |:--- | :---- | :--- | :---- |
 | name | string | 是 | 函数名称。 |
 | thoughts | string | 是 | 模型思考过程。 |
@@ -149,10 +149,9 @@ erniebot.ChatCompletion.create(**kwargs: Any)
 
 各字段含义如下表所示：
 
-| 字段 | 类型 | 描述 |
+| 字段名 | 类型 | 描述 |
 | :--- | :---- | :---- |
 | code | int | 请求返回状态。 |
-| body | dict | 请求返回的源数据。 |
 | result | string | 对话返回的生成结果。 |
 | is_truncated | boolean | 生成结果是否被长度限制截断。 |
 | sentence_id | int | 仅流式模式下返回该字段，表示返回结果中的文本顺序，从`0`开始计数。 |

docs/api_reference/embedding.md

@@ -2,7 +2,7 @@
 
 将文本转化为用数值表示的向量形式，用于文本检索、信息推荐、知识挖掘等场景。
 
-## 函数接口
+## Python接口
 
 ``` {.py .copy}
 erniebot.Embedding.create(**kwargs: Any)
@@ -61,10 +61,10 @@ erniebot.Embedding.create(**kwargs: Any)
 
 其中字段含义如下表所示：
 
-| 字段 | 类型 | 描述 |
+| 字段名 | 类型 | 描述 |
 | :--- | :---- | :---- |
 | code | int | 请求返回状态。 |
-| data | list[dict] | 向量计算结果，列表中元素个数与输入的文本个数一致。列表中的元素均为dict，包含如下键值对：<br>object：固定为`'embedding'`； <br>`embedding`：384维的向量结果； <br>`index`：序号。 |
+| data | list[dict] | 向量计算结果，列表中元素个数与输入的文本个数一致。列表中的元素均为dict，包含如下键值对：<br>`object`：固定为`'embedding'`； <br>`embedding`：384维的向量结果； <br>`index`：序号。 |
 | usage | dict | 输入输出token统计信息。token数量采用如下公式估算：`token数 = 汉字数 + 单词数 * 1.3`。<br>`prompt_tokens/total_tokens`：输入token数量。 |
 
 ## 使用示例

docs/api_reference/image.md

@@ -59,26 +59,28 @@ ernie.api_type = "yinian"
 
 返回结果的具体字段含义如下表：
 
-| 字段  | 类型   | 描述  |
+| 字段名  | 类型   | 描述  |
+| :--- | :---- | :---- |
+| code | int | 请求返回状态。 |
+| data | dict | 返回数据。 |
+
+`data`包含如下键值对：
+
+| 键名  | 值类型   | 值描述  |
 | :--- | :---- | :---- |
-| data | object | 返回数据。 |
 | task_id | int | 任务ID。 |
 | task_status | string | 任务总体状态，有`'INIT'`（初始化）、`'WAIT'`（排队中）、`'RUNNING'`（生成中）、`'FAILED'`（失败）、`'SUCCESS'`（成功）五种状态，只有`'SUCCESS'`为成功状态。 |
 | task_progress | int | 任务总体进度，`0`表示未处理完，`1`表示处理完成。 |
 | sub_task_result_list | list[dict] | 子任务的结果列表。 |
-| final_image_list | object[] | 子任务生成图像的列表。 |
-| img_url | string | 图片的下载地址，默认1小时后失效。 |
-| height | int | 图片的高度。 |
-| width | int | 图片的宽度。 |
-| img_approve_conclusion | string | 图片机审结果，`'block'`表示输出图片违规，`'review'`表示输出图片疑似违规，`'pass'`表示输出图片未发现问题。 |
 
-`sub_task_status`为一个Python list，其中每个元素为一个dict，包含如下键值对：
+`sub_task_result_list`为一个Python list，其中每个元素为一个dict，包含如下键值对：
 
-| 字段  | 类型   | 描述  |
+| 键名  | 值类型   | 值描述  |
 | :--- | :---- | :---- |
 | sub_task_status | string | 子任务状态，有`'INIT'`（初始化）、`'WAIT'`（排队中）、`'RUNNING'`（生成中）、`'FAILED'`（失败）、`'SUCCESS'`（成功）五种状态，只有`'SUCCESS'`为成功状态。 |
 | sub_task_progress | int | 子任务进度，`0`表示未处理完，`1`表示处理完成。 |
 | sub_task_error_code | int | 子任务任务错误码，`0`表示正常，`501`表示文本黄反拦截，`201`表示模型生图失败。 |
+| final_image_list | list[dict] | 子任务生成图像的列表。列表中的元素均为dict，包含如下键值对：<br>`img_url`：图片的下载地址，默认1小时后失效； <br>`height`：图片的高度； <br>`width`：图片的宽度； <br>`img_approve_conclusion`：图片机审结果，`'block'`表示输出图片违规，`'review'`表示输出图片疑似违规，`'pass'`表示输出图片未发现问题。 |
 
 ## 使用示例
 

docs/authentication.md

@@ -11,7 +11,7 @@
 | api_type     | EB_API_TYPE | string | 否 | 后端平台的类型。支持`'qianfan'`、`'yinian'`和`'aistudio'`，默认是`'qianfan'`。|
 | ak           | EB_AK       | string | 否 | 认证鉴权使用的access key（AK）。必须和`sk`同时设置。 |
 | sk           | EB_SK       | string | 否 | 认证鉴权使用的secret key（SK）。必须和`ak`同时设置。 |
-| access_token | EB_ACCESS_TOKEN | string | 否 | 认证鉴权使用的access token。推荐优先使用`ak`和`sk`。如果设置了`access_token`，则使用该access token；如果`access_token`没有设置或者失效，并且设置了`ak`和`sk`，部分后端平台类型支持自动通过`ak`和`sk`获取access token。|
+| access_token | EB_ACCESS_TOKEN | string | 否 | 认证鉴权使用的access token。推荐优先使用`ak`和`sk`。如果设置了`access_token`，则使用该access token；如果`access_token`没有设置或者失效，并且设置了`ak`和`sk`，部分后端平台类型支持自动通过AK/SK获取access token。|
 | access_token_path | EB_ACCESS_TOKEN_PATH | string | 否 | 存有access token的文件路径。推荐优先使用`ak`和`sk`。`access_token_path`生效原理和`access_token`相同。|
 
 ERNIE Bot SDK支持的文心大模型来自多个后端平台，不同平台支持的用户凭证类型不尽相同。请阅读下表，参照对应的文档申请用户凭证。
@@ -24,7 +24,7 @@ ERNIE Bot SDK支持的文心大模型来自多个后端平台，不同平台支
 
 与其它参数类似，鉴权参数可通过如下3种方式设置，请根据需要自由选择。关于参数配置的更多技巧，请在[此文档](./configuration.md)了解。
 
-(1）使用环境变量：
+1. 使用环境变量：
 
 ```shell
 export EB_API_TYPE="<EB-API-TYPE>"
@@ -33,7 +33,7 @@ export EB_SK="<EB-SECRET-KEY>"
 export EB_ACCESS_TOKEN="<EB-ACCESS-TOKEN>"
 ```
 
-(2）使用全局变量：
+2. 使用全局变量：
 
 ``` {.py .copy}
 import erniebot
@@ -44,7 +44,7 @@ erniebot.sk = "<EB-SECRET-KEY>"
 erniebot.access_token = "<EB-ACCESS-TOKEN>"
 ```
 
-(3) 使用`_config_`参数：
+3. 使用`_config_`参数：
 
 ``` {.py .copy}
 import erniebot
@@ -90,7 +90,7 @@ response = erniebot.ChatCompletion.create(
 
 * AK/SK是私人信息，大家不要分享给他人，也不要对外暴露。
 * 千帆大模型平台的新用户，默认会有20元代金券，大家可以快速体验ERNIE Bot SDK。
-* 千帆大模型平台的完整介绍，请参考[使用文档](https://cloud.baidu.com/doc/WENXINWORKSHOP/index.html)；费用、充值相关的问题，请参考[价格文档](https://cloud.baidu.com/doc/WENXINWORKSHOP/s/Blfmc9dlf)
+* 千帆大模型平台的完整介绍，请参考[使用文档](https://cloud.baidu.com/doc/WENXINWORKSHOP/index.html)；费用、充值相关的问题，请参考[价格文档](https://cloud.baidu.com/doc/WENXINWORKSHOP/s/Blfmc9dlf)。
 
 ## 申请智能创作平台的用户凭证
 

docs/configuration.md

@@ -4,20 +4,20 @@ ERNIE Bot SDK参数配置，主要涉及认证鉴权、后端平台等信息。
 
 ERNIE Bot SDK支持3种参数配置的方法：1）使用环境变量，2）使用全局变量，3) 使用`_config_`参数。
 
-(1) 使用环境变量：
+1. 使用环境变量：
 
 ``` {.copy}
 export EB_API_TYPE="<EB-API-TYPE>"
 ```
 
-(2) 使用全局变量：
+2. 使用全局变量：
 
 ``` {.py .copy}
 import erniebot
 erniebot.api_type = "<EB-API-TYPE>"
 ```
 
-(3) 使用`_config_`参数：
+3. 使用`_config_`参数：
 
 ``` {.py .copy}
 import erniebot