[Doc] Refine docs for function calling

Author: juncaipeng

README.md

@@ -76,9 +76,10 @@ erniebot api image.create --model ernie-vilg-v2 --prompt "画一只驴肉火烧"
 ### 对话补全（Chat Completion）
 
 ERNIE Bot SDK提供具备对话补全能力的文心一言旗舰版模型ernie-bot-3.5和文心一言迅捷版模型ernie-bot-turbo。
+
 旗舰版模型的效果更好，迅捷版模型的响应速度更快、推理时延更低，大家可以根据实际场景的需求选择合适的模型。
 
-以下是调用文心一言旗舰版模型进行多轮对话的示例。
+以下是调用文心一言旗舰版模型进行多轮对话的示例：
 
 ```python
 import erniebot
@@ -107,6 +108,7 @@ print(response)
 ### 语义向量（Embedding）
 
 ERNIE Bot SDK提供用于提取语义向量的Embedding模型。
+
 该模型基于文心大模型，使用海量数据训练得到，为[文心百中](https://wenxin.baidu.com/baizhong/index/)系统提供关键能力。该模型可以将字符串转为384维浮点数表达的语义向量，语义向量具备极其精准的语义表达能力，可以用于度量两个字符串之间的语义相似度。
 
 大家可以使用以下代码提取句子的语义向量。
@@ -133,6 +135,7 @@ print(response)
 ### 文生图（Image Generation）
 
 ERNIE Bot SDK提供具备文生图能力的ERNIE-ViLG大模型。
+
 该模型具备丰富的风格与强大的中文理解能力，支持生成多种尺寸的图片。
 
 ```python
@@ -155,7 +158,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)
@@ -164,9 +166,11 @@ print(response)
 
 ### 【beta】函数调用（Function Calling）
 
-ERNIE Bot SDK提供函数调用功能，即通过大模型根据对话上下文确定何时以及如何调用函数。该功能目前处于测试状态。
+ERNIE Bot SDK提供函数调用功能，即由大模型根据对话上下文确定何时以及如何调用函数。
+
+借由函数调用，用户可以从大模型获取结构化数据，进而利用编程手段将大模型与已有的内外部API结合以构建应用。该功能目前处于测试状态。
 
-以下是调用文心一言旗舰版模型进行函数调用的示例。
+以下是调用文心一言旗舰版模型进行函数调用的示例：
 
 ```python
 import erniebot

docs/README.md

@@ -67,6 +67,7 @@ erniebot api image.create --model ernie-vilg-v2 --prompt "画一只驴肉火烧"
 ### 对话补全（Chat Completion）
 
 ERNIE Bot SDK提供具备对话补全能力的文心一言旗舰版模型ernie-bot-3.5和文心一言迅捷版模型ernie-bot-turbo。
+
 旗舰版模型的效果更好，迅捷版模型的响应速度更快、推理时延更低，大家可以根据实际场景的需求选择合适的模型。
 
 以下是调用文心一言旗舰版模型进行多轮对话的示例。
@@ -98,6 +99,7 @@ print(response)
 ### 语义向量（Embedding）
 
 ERNIE Bot SDK提供提取语义向量的Embedding模型。
+
 该模型基于文心大模型，使用海量数据训练得到，为[文心百中](https://wenxin.baidu.com/baizhong/index/)系统提供关键能力。该模型可以将字符串转为384维浮点数表达的语义向量，语义向量具备极其精准的语义表达能力，可以用于度量两个字符串之间的语义相似度。
 
 大家可以使用以下代码提取句子的语义向量。
@@ -124,6 +126,7 @@ print(response)
 ### 文生图（Image Generation）
 
 ERNIE Bot SDK提供具备文生图能力的ERNIE-ViLG大模型。
+
 该模型具备丰富的风格与强大的中文理解能力，支持生成多种尺寸的图片。
 
 ```python
@@ -155,9 +158,11 @@ print(response)
 
 ### 【beta】函数调用（Function Calling）
 
-ERNIE Bot SDK提供函数调用功能，即通过大模型根据对话上下文确定何时以及如何调用函数。该功能目前处于测试状态。
+ERNIE Bot SDK提供函数调用功能，即由大模型根据对话上下文确定何时以及如何调用函数。
+
+借由函数调用，用户可以从大模型获取结构化数据，进而利用编程手段将大模型与已有的内外部API结合以构建应用。该功能目前处于测试状态。
 
-以下是调用文心一言旗舰版模型进行函数调用的示例。
+以下是调用文心一言旗舰版模型进行函数调用的示例：
 
 ```python
 import erniebot

docs/api_reference/chat_completion.md

@@ -22,7 +22,8 @@ erniebot.ChatCompletion.create(**kwargs: Any)
 | stream | boolean | 否 | 是否以流式接口返回数据，默认`False`。 |
 | user_id | string | 否 | 表示最终用户的唯一标识符，可以监视和检测滥用行为，防止接口恶意调用。 |
 
-### `messages`
+<details>
+<summary><code name="messages">messages</code></summary>
 
 `messages`为一个Python list，其中每个元素为一个dict。在如下示例中，为了与模型进行多轮对话，我们将模型的回复结果插入在`messages`中再继续请求：
 
@@ -50,9 +51,12 @@ erniebot.ChatCompletion.create(**kwargs: Any)
 | role | string | 是 | `'user'`表示用户，`'assistant'`表示对话助手，`'function'`表示函数。 |
 | content | string or `None` | 是 | 对话内容，当`role`不为`'function'`时，必须设置该参数为非`None`值；当`role`为`'function'`时，可以设置该参数为`None`。 |
 | name | string | 否 | 信息的作者。当`role='function'`时，此参数必填，且是`function_call`中的`name`。 |
-| function_call | dict | 否 | 由模型生成的函数调用，包含函数名称和请求参数等。详见[`function_call`](#functioncall)。 |
+| function_call | dict | 否 | 由模型生成的函数调用，包含函数名称和请求参数等。详见[`function_call`](#function_call)。 |
 
-### `functions`
+</details>
+
+<details>
+<summary><code name="functions">functions</code></summary>
 
 `functions`为一个Python list，其中每个元素为一个dict。示例如下：
 
@@ -112,7 +116,10 @@ erniebot.ChatCompletion.create(**kwargs: Any)
 | examples | list[dict] | 否 | 函数调用示例。可提供与`messages`类似的对话上下文信息作为函数调用的例子。 |
 | plugin_id | string | 否 | 标记函数关联的插件，便于数据统计。 |
 
-### `function_call`
+</details>
+
+<details>
+<summary><code name="function_call">function_call</code></summary>
 
 `function_call`为一个Python dict，其中包含如下键值对：
 
@@ -122,11 +129,13 @@ erniebot.ChatCompletion.create(**kwargs: Any)
 | thoughts | string | 是 | 模型思考过程。 |
 | arguments | string | 是 | 请求参数。 |
 
+</details>
+
 ## 返回结果
 
-当采用非流式接口、即`stream`为`False`时，接口返回`erniebot.response.EBResponse`对象；当采用流式接口、即`stream`为`True`时，接口返回一个Python生成器，其产生的每个元素均为`erniebot.response.EBResponse`对象。
+当采用非流式接口（即`stream`为`False`）时，接口返回`erniebot.response.EBResponse`对象；当采用流式接口、即`stream`为`True`时，接口返回一个Python生成器，其产生的每个元素均为`erniebot.response.EBResponse`对象。
 
-`erniebot.response.EBResponse`对象中包含一些字段，可通过`x[key]`或`x.key`的方式访问。一个典型示例如下：
+`erniebot.response.EBResponse`对象中包含一些字段。一个典型示例如下：
 
 ```python
 {
@@ -147,7 +156,7 @@ erniebot.ChatCompletion.create(**kwargs: Any)
 }
 ```
 
-各字段含义如下表所示：
+`erniebot.response.EBResponse`对象的各字段含义如下表所示：
 
 | 字段名 | 类型 | 描述 |
 | :--- | :---- | :---- |
@@ -159,7 +168,9 @@ erniebot.ChatCompletion.create(**kwargs: Any)
 | ban_round | int | 当`need_clear_history`为`True`时，会返回此字段表示第几轮对话有敏感信息，如果是当前轮次存在问题，则`ban_round=-1`。 |
 | is_end | boolean | 仅流式模式下返回该字段，表示是否为是返回结果的最后一段文本。 |
 | usage | dict | 输入输出token统计信息。token数量采用如下公式估算：`token数 = 汉字数 + 单词数 * 1.3`。<br>`prompt_tokens`：输入token数量（含上下文拼接）；<br>`completion_tokens`：当前生成结果包含的token数量；<br>`total_tokens`：输入与输出的token总数；<br> `plugins`：插件消耗的token数量。 |
-| function_call | dict | 由模型生成的函数调用，包含函数名称和请求参数等。详见[`function_call`](#functioncall)。 |
+| function_call | dict | 由模型生成的函数调用，包含函数名称和请求参数等。详见[`function_call`](#function_call)。 |
+
+字段的访问方式有2种：假设`resp`为一个`erniebot.response.EBResponse`对象，`resp['result']`或`resp.result`均可获取`result`字段的内容。
 
 ## 使用示例
 

docs/authentication.md

@@ -20,11 +20,11 @@ ERNIE Bot SDK支持的文心大模型来自多个后端平台，不同平台支
 | :---     | :----      | :----  | :----  | :---  |
 | 千帆大模型平台 | qianfan | AK/SK，access token | [申请千帆大模型平台的用户凭证](#申请千帆大模型平台的用户凭证) | ernie-bot-3.5，ernie-bot-turbo，ernie-text-embedding |
 | 智能创作平台 | yinian | AK/SK，access token | [申请智能创作平台的用户凭证](#申请智能创作平台的用户凭证) | ernie-vilg-v2 |
-| AI Studio | aistudio | access token | [申请AI Studio平台的用户凭证](#申请ai-studio平台的用户凭证) | ernie-bot-3.5，ernie-bot-turbo，ernie-text-embedding |
+| AI Studio | aistudio | access token |  | ernie-bot-3.5，ernie-bot-turbo，ernie-text-embedding |
 
 与其它参数类似，鉴权参数可通过如下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
@@ -108,5 +108,3 @@ response = erniebot.ChatCompletion.create(
 
 * AK/SK是私人信息，大家不要分享给他人，也不要对外暴露。
 * 智能创作平台的完整介绍，请参考[使用文档](https://ai.baidu.com/ai-doc/NLP/Uk53wndcb)；费用、充值相关的问题，请参考[计费简介](https://ai.baidu.com/ai-doc/NLP/qla2beec2)。
-
-## 申请AI Studio平台的用户凭证

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

docs/guides/function_calling.md

@@ -4,7 +4,7 @@
 
 文心一言提供函数调用功能，模型根据用户需求以及对函数的描述确定何时以及如何调用函数。具体而言，一个典型的函数调用流程如下：
 
-1. 用户提供对一组函数的名称、功能、请求参数（输入参数）和响应参数（返回值）的描述，并以自然语言阐述需求；
+1. 用户提供对一组函数的名称、功能、请求参数（输入参数）和响应参数（返回值）的描述；
 2. 模型根据用户需求以及函数描述信息，智能确定是否应该调用函数、调用哪一个函数、以及在调用该函数时需要如何设置输入参数；
 3. 用户根据模型的提示调用函数，并将函数的响应传递给模型；
 4. 模型综合对话上下文信息，以自然语言形式给出满足用户需求的回答。
@@ -17,7 +17,7 @@
 
 如下展示了一个函数调用的例子。
 
-首先对函数的基本信息进行描述，使用[JSON Schema](https://json-schema.org/)格式描述函数的请求参数与响应参数。
+(1) 首先，对函数的基本信息进行描述，使用[JSON Schema](https://json-schema.org/)格式描述函数的请求参数与响应参数。
 
 ``` {.py .copy}
 functions = [
@@ -66,7 +66,7 @@ functions = [
 
 代码中定义了一个列表`functions`，作为示例，其中仅包含对一个函数`get_current_temperature`的名称、请求参数等信息的描述。
 
-接着，将以上信息与对需要完成的任务的自然语言描述一同传入`erniebot.ChatCompletion` API。
+(2) 接着，将以上信息与对需要完成的任务的自然语言描述一同传给`erniebot.ChatCompletion` API。
 
 ``` {.py .copy}
 import erniebot
@@ -92,15 +92,15 @@ function_call = response.function_call
 print(function_call)
 ```
 
-上述代码中的断言语句用于确保`response`中包含`function_call`字段。在实际生产中通常还需要考虑`response`中不包含`function_call`的情况，这意味着模型选择不调用任何函数。上述代码输出结果可能如下（由于大模型生成结果具有不确定性，执行上述代码的结果与本示例不一定一致）：
+以上代码中的断言语句用于确保`response`中包含`function_call`字段。在实际生产中通常还需要考虑`response`中不包含`function_call`的情况，这意味着模型选择不调用任何函数。以上代码的输出结果可能如下（由于大模型生成结果具有不确定性，执行上述代码的结果与本示例不一定一致）：
 
 ```text
 {'name': 'get_current_temperature', 'thoughts': '我需要获取指定城市的气温', 'arguments': '{"unit":"摄氏度","location":"深圳市"}'}
 ```
 
-`function_call`是一个Python dict，其中包含的键`name`、`thoughts`分别对应大模型选择调用的函数名称以及模型的思考过程。`function_call["arguments"]`是一个JSON格式的字符串，其中包含了调用函数时需要用到的参数。
+`function_call`是一个字典，其中包含的键`name`、`thoughts`分别对应大模型选择调用的函数名称以及模型的思考过程。`function_call["arguments"]`是一个JSON格式的字符串，其中包含了调用函数时需要用到的参数。
 
-解析`function_call["arguments"]`，并使用解析得到的参数调用对应的函数。本示例使用一个硬编码的dummy函数作为演示，在实际生产中可将其替换为真正具备相应功能的API。
+(3) 然后，根据模型的提示调用相应函数得到结果。
 
 ``` {.py .copy}
 import json
@@ -114,7 +114,9 @@ args = json.loads(function_call["arguments"])
 res = func(location=args["location"], unit=args["unit"])
 ```
 
-将模型上一轮的响应以及函数的响应加入到对话上下文信息中，再次传递给模型。如果函数的响应不是JSON格式的字符串，需要先对其进行编码。
+以上代码从`function_call`中获取模型选择调用的函数名称（`function_call["name"]`），通过该名称找到对应的函数，并从`function_call["arguments"]`中解析需要传入函数的参数，最终完成对函数的调用。作为演示，以上代码所使用的`get_current_temperature`是一个硬编码的dummy函数，在实际生产中可将其替换为真正具备相应功能的API。
+
+(4) 最后，将模型上一轮的响应以及函数的响应加入到对话上下文信息中，再次传递给模型。回传给模型的函数响应内容应当是JSON格式的字符串（如`'{"temperature": 25, "unit": "摄氏度"}'`），在本示例中，函数的响应是一个字典，因此需要先调用`json.dumps`函数对其进行编码。
 
 ``` {.py .copy}
 messages.append(

erniebot/client.py

@@ -406,7 +406,6 @@ def _validate_headers(
     def _parse_line(self, line: bytes) -> Optional[str]:
         if line:
             if line.startswith(b"data: "):
-                # Data-only messages
                 line = line[len(b"data: "):]
                 return line.decode('utf-8')
             else: