1 Star 0 Fork 2

ybot / ERNIE-Bot-SDK

forked from PaddlePaddle / ERNIE-Bot-SDK 
加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
克隆/下载
chat_completion.md 10.87 KB
AI 代码解读
一键复制 编辑 原始数据 按行查看 历史
Bobholamovic 提交于 2023-11-30 14:17 . Fix doc style (#110)

ChatCompletion

提供对话上下文与输入文本,由对话模型给出新的回复,回复中包括生成的文本内容、函数调用信息以及token数量统计信息等。

Python接口

erniebot.ChatCompletion.create(
    model: str,
    messages: List[dict],
    *,
    functions: Optional[List[dict]] = ...,
    temperature: Optional[float] = ...,
    top_p: Optional[float] = ...,
    penalty_score: Optional[float] = ...,
    system: Optional[str] = ...,
    user_id: Optional[str] = ...,
    stream: Optional[bool] = ...,
    validate_functions: bool = ...,
    headers: Optional[HeadersType] = ...,
    request_timeout: Optional[float] = ...,
    _config_: Optional[ConfigDictType] = ...,
) -> Union[ChatCompletionResponse, Iterator[ChatCompletionResponse]]

输入参数

参数名 类型 必填 描述
model str 模型名称。当前支持"ernie-bot""ernie-bot-turbo""ernie-bot-4""ernie-bot-8k"
messages list[dict] 对话上下文信息。列表中的元素个数须为奇数。详见messages
functions list[dict] 可触发函数的描述列表。详见functions。ernie-bot-turbo模型暂不支持此参数。
temperature float 用于调节模型输出概率分布,从而控制生成结果的随机性。
  • 较高的数值会使生成结果更加随机,而较低的数值会使结果更加集中和确定;
  • 默认0.95,范围为(0, 1.0],不能为0
  • 建议只设置此参数和top_p中的一个。
top_p float 生成的token从概率和恰好达到或超过top_p的token集合中采样得到。
  • 影响生成文本的多样性,值越大,生成文本的多样性越强;
  • 默认0.8,取值范围为[0, 1.0]
  • 建议只设置此参数和temperature中的一个。
penalty_score float 通过对已生成的token增加惩罚,减少重复生成的现象。
  • 值越大表示惩罚越大;
  • 默认1.0,取值范围:[1.0, 2.0]
system str 提示模型行为的文本。如果设置了functions,则不支持设置此参数。
user_id str 终端用户的唯一标识符,可以监视和检测滥用行为,防止接口被恶意调用。
stream bool 如果设置此参数为True,则流式返回数据。
validate_functions bool 是否对functions进行格式校验。
headers dict 附加的HTTP请求头。
request_timeout float 单个HTTP请求的超时时间,单位为秒。
_config_ dict 用于覆盖全局配置。

messages

详情

messages为一个Python list,其中每个元素为一个dict。在如下示例中,为了与模型进行多轮对话,我们将模型的回复结果插入到messages中再继续请求:

[
    {
        "role": "user",
        "content": "你好啊"
    },
    {
        "role": "assistant",
        "content": "你好,我是文心一言"
    },
    {
        "role": "user",
        "content": "深圳周末去哪里玩好?"
    }
]

messages中的每个元素包含如下键值对:

键名 值类型 必填 值描述
role str "user"表示用户,"assistant"表示对话助手,"function"表示函数。
content str or None role不为"function"时,表示消息内容,必须设置此参数为非None值;当role"function"时,表示函数响应参数,可以设置此参数为None
name str 消息的作者。当role"function"时,此参数必填,且是function_call中的name
function_call dict 由模型生成的函数调用,包含函数名称和请求参数等。

function_call为一个Python dict,其中包含如下键值对:

键名 值类型 必填 值描述
name str 函数名称。
thoughts str 模型思考过程。
arguments str 请求参数。

functions

详情

functions为一个Python list,其中每个元素为一个dict。示例如下:

[
    {
        "name": "get_current_temperature",
        "description": "获取指定城市的气温",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {
                    "type": "string",
                    "description": "城市名称"
                },
                "unit": {
                    "type": "string",
                    "enum": [
                        "摄氏度",
                        "华氏度"
                    ]
                }
            },
            "required": [
                "location",
                "unit"
            ]
        },
        "responses": {
            "type": "object",
            "properties": {
                "temperature": {
                    "type": "integer",
                    "description": "城市气温"
                },
                "unit": {
                    "type": "string",
                    "enum": [
                        "摄氏度",
                        "华氏度"
                    ]
                }
            }
        }
    }
]

functions中的每个元素包含如下键值对:

键名 值类型 必填 值描述
name str 函数名称。
description str 对函数功能的描述。
parameters dict 函数请求参数。采用JSON Schema格式。如果函数不接受任何参数,使用{"type": "object", "properties": {}}
responses dict 函数响应参数。采用JSON Schema格式。
examples list[dict] 函数调用示例。可提供与messages类似的对话上下文信息作为函数调用的例子。一个例子如下:[{"role": "user", "content": "深圳市今天气温如何?"}, {"role": "assistant", "content": None, "function_call": {"name": "get_current_temperature", "arguments": "{"location":"深圳市","unit":"摄氏度"}"}}, {"role": "function", "name": "get_current_temperature", "content": "{"temperature":25,"unit":"摄氏度"}"}]
plugin_id str 标记函数关联的插件,便于数据统计。

返回结果

当采用非流式模式(即streamFalse)时,接口返回erniebot.ChatCompletionResponse对象;当采用流式模式(即streamTrue)时,接口返回一个Python生成器,其产生的每个元素均为erniebot.ChatCompletionResponse对象,包含完整生成文本的一个片段。

erniebot.ChatCompletionResponse对象中包含一些字段。一个典型示例如下:

{
    "rcode": 200,
    "id": "as-0rphgw7hw2",
    "object": "chat.completion",
    "created": 1692875360,
    "result": "深圳有很多不同的地方可以周末去玩,以下是一些推荐:\n\n1. 深圳东部:深圳东部有着美丽的海滩和壮观的山脉,是进行户外活动和探险的好地方。你可以去大梅沙海滨公园、小梅沙海洋世界、南澳岛等地方。\n2. 深圳中心城区:这里有许多购物中心、美食街、夜市等,可以品尝各种美食,逛街购物。你也可以去世界之窗、深圳华侨城等主题公园。\n3. 深圳西部:深圳西部有许多历史文化名胜和自然风光,比如深圳大学城、蛇口海上世界、南山海岸城等。\n4. 深圳郊区:深圳郊区有许多农业观光园、水果采摘园等,可以体验农家乐和亲近大自然。你可以去光明农场、欢乐田园等地方。\n5. 深圳室内:如果你想在周末找一个室内活动,可以去深圳的博物馆、艺术馆、电影院等,欣赏文化展览或者观看电影。\n\n以上是一些深圳周末游的推荐,你可以根据自己的兴趣和时间来选择合适的地方。",
    "is_truncated": false,
    "need_clear_history": false,
    "sentence_id": 0,
    "is_end": false,
    "usage": {
        "prompt_tokens": 8,
        "completion_tokens": 311,
        "total_tokens": 319
    }
}

erniebot.ChatCompletionResponse对象的各关键字段含义如下表所示:

字段名 类型 描述
rcode int HTTP响应状态码。
result str 模型生成的回复文本。
is_truncated bool 生成文本是否被长度限制截断。
sentence_id int 当前片段的序号,从0开始计数。仅流式模式下包含该字段。
need_clear_history bool 用户输入是否存在安全风险,是否应该关闭当前会话、清理历史会话信息。
  • True:是,表示用户输入存在安全风险,建议关闭当前会话,清理历史会话信息;
  • False:否,表示用户输入无安全风险。
ban_round int need_clear_historyTrue时,此字段表示第几轮对话有敏感信息。如果是当前轮次存在问题,则ban_round=-1
is_end bool 当前片段是否为生成结果的最后一段文本。仅流式模式下包含该字段。
usage dict 输入、输出token统计信息。
  • prompt_tokens:输入token数量(包括输入中的历史消息);
  • completion_tokens:当前生成结果包含的token数量;
  • total_tokens:输入与输出的token总数;
  • plugins:插件消耗的token数量。
function_call dict 由模型生成的函数调用信息,包含函数名称和请求参数等。详见messages中的function_call

假设resp为一个erniebot.ChatCompletionResponse对象,字段的访问方式有2种:resp["result"]resp.result均可获取result字段的内容。此外,可以使用resp.get_result()获取响应中的“主要结果”:当模型给出函数调用信息时(此时,resp具有function_call字段),resp.get_result()的返回结果与resp.function_call一致;否则,resp.get_result()的返回结果与resp.result一致,即模型给出的回复文本。

使用示例

import erniebot

erniebot.api_type = "aistudio"
erniebot.access_token = "<access-token-for-aistudio>"

stream = False
response = erniebot.ChatCompletion.create(
    model="ernie-bot",
    messages=[{
        "role": "user",
        "content": "周末深圳去哪里玩?"
    }],
    top_p=0.95,
    stream=stream)

result = ""
if stream:
    for resp in response:
        result += resp.get_result()
else:
    result = response.get_result()

print("ERNIEBOT: ", result)
Python
1
https://gitee.com/ybot/ERNIE-Bot-SDK.git
git@gitee.com:ybot/ERNIE-Bot-SDK.git
ybot
ERNIE-Bot-SDK
ERNIE-Bot-SDK
develop

搜索帮助