ChatCompletion¶
提供对话上下文与输入文本，由对话模型给出新的回复，回复中包括生成的文本内容、函数调用信息以及token数量统计信息等。
Python接口¶
erniebot.ChatCompletion.create(
model: str,
messages: List[dict],
*,
functions: Union[List[dict], NotGiven] = ...,
temperature: Union[float, NotGiven] = ...,
top_p: Union[float, NotGiven] = ...,
penalty_score: Union[float, NotGiven] = ...,
system: Union[str, NotGiven] = ...,
stop: Union[List[str], NotGiven] = ...,
disable_search: Union[bool, NotGiven] = ...,
enable_citation: Union[bool, NotGiven] = ...,
user_id: Union[str, NotGiven] = ...,
stream: Union[bool, NotGiven] = ...,
validate_functions: bool = ...,
headers: Optional[HeadersType] = ...,
request_timeout: Optional[float] = ...,
_config_: Optional[ConfigDictType] = ...,
) -> Union[ChatCompletionResponse, Iterator[ChatCompletionResponse]]
输入参数¶
| 参数名 | 类型 | 必填 | 描述 |
|---|---|---|---|
| model | str | 是 | 模型名称。当前支持"ernie-3.5"、"ernie-turbo"、"ernie-4.0"和"ernie-longtext"。 |
| messages | list[dict] | 是 | 对话上下文信息。列表中的元素个数须为奇数。详见messages。 |
| functions | list[dict] | 否 | 可触发函数的描述列表。详见functions。ernie-turbo模型暂不支持此参数。 |
| temperature | float | 否 | 用于调节模型输出概率分布，从而控制生成结果的随机性。
|
| top_p | float | 否 | 生成的token从概率和恰好达到或超过top_p的token集合中采样得到。
|
| penalty_score | float | 否 | 通过对已生成的token增加惩罚，减少重复生成的现象。
|
| system | str | 否 | 提示模型行为的文本。如果设置了functions，则不支持设置此参数。 |
| stop | list[str] | 否 | 停止标识。在生成文本中第一次出现此参数包含的任一个字符串时，生成过程停止。ernie-turbo模型暂不支持此参数。 |
| disable_search | bool | 否 | 如果设置此参数为True，则禁用搜索引擎。默认为False。ernie-turbo模型暂不支持此参数。 |
| enable_citation | bool | 否 | 如果设置此参数为True，则开启上角标返回。默认为False。ernie-turbo模型暂不支持此参数。 |
| system | bool | 否 | 提示模型行为的文本。如果设置了functions，则不支持设置此参数。 |
| user_id | str | 否 | 终端用户的唯一标识符，可以监视和检测滥用行为，防止接口被恶意调用。 |
| stream | bool | 否 | 如果设置此参数为True，则流式返回数据。默认为False。 |
| validate_functions | bool | 否 | 是否对functions进行格式校验。 |
| headers | dict | 否 | 附加的HTTP请求头。 |
| request_timeout | float | 否 | 单个HTTP请求的超时时间，单位为秒。 |
| _config_ | dict | 否 | 用于覆盖全局配置。 |
messages¶
详情
`messages`为一个Python list，其中每个元素为一个dict。在如下示例中，为了与模型进行多轮对话，我们将模型的回复结果插入到`messages`中再继续请求： `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": [
"摄氏度",
"华氏度"
]
}
}
}
}
]
返回结果¶
当采用非流式模式（即stream为False）时，接口返回erniebot.ChatCompletionResponse对象；当采用流式模式（即stream为True）时，接口返回一个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响应状态码。 |
| sentence_id | int | 当前片段的序号，从0开始计数。仅流式模式下包含该字段。 |
| is_end | bool | 当前片段是否为生成结果的最后一段文本。仅流式模式下包含该字段。 |
| is_truncated | bool | 生成文本是否被长度限制截断。 |
| finish_reason | str | 生成过程结束的原因。 |
| search_info | str | 搜索引擎返回的结果。 |
| result | str | 模型生成的回复文本。 |
| need_clear_history | bool | 用户输入是否存在安全风险，是否应该关闭当前会话、清理历史会话信息。
|
| ban_round | int | 当need_clear_history为True时，此字段表示第几轮对话有敏感信息。如果是当前轮次存在问题，则ban_round=-1。 |
| usage | dict | 输入、输出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-3.5",
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)