调用本接口,向智能体发起一次对话请求。
POST /api/v3/bots/chat/completions HTTP/1.1 Host: ark.cn-beijing.volces.com Content-Type: application/json Authorization: <authorization string> body
本接口支持的地域及 API 访问域名参见地域和访问域名。
本接口支持 API Key 鉴权方式,详见鉴权认证方式。
参数名称 | 类型 | 是否必填 | 默认值 | 描述 | 示例值 |
---|---|---|---|---|---|
model | String | 是 | - | 您创建的智能体 ID | bot-202406040*****-***** |
messages | Array of MessageParam | 是 | - | 由目前为止的对话组成的消息列表
| - |
stream | Boolean | 否 | false | 响应内容是否流式返回
| false |
stream_options | 否 | - | 流式响应的选项。仅当 | - | |
max_tokens | Integer | 否 | 4096 | 模型可以生成的最大 token 数量。取值范围为 [0, 4096]。输入 token 和输出 token 的总长度还受模型的上下文长度限制。 | 4096 |
stop | Array or String | 否 | - | 模型遇到 stop 字段所指定的字符串时将停止继续生成,这个词语本身不会输出。最多支持 4 个字符串。 | ["你好", "天气"] |
frequency_penalty | Float | 否 | 0 | 频率惩罚系数。如果值为正,会根据新 token 在文本中的出现频率对其进行惩罚,从而降低模型逐字重复的可能性。取值范围为 [-2.0, 2.0]。 | 1 |
temperature | Float | 否 | 1 | 采样温度。控制了生成文本时对每个候选词的概率分布进行平滑的程度。取值范围为 [0, 1]。0 特殊处理 | 0.8 |
top_p | Float | 否 | 0.7 | 核采样概率阈值。模型会考虑概率质量在 | 0.8 |
logprobs | Boolean | 否 | false | 是否返回输出 tokens 的对数概率。
| false |
top_logprobs | Integer | 否 | 0 | 指定每个输出 token 位置最有可能返回的 token 数量,每个 token 都有关联的对数概率。仅当 | 2 |
logit_bias | Map<String, Integer> | 否 | - | 调整指定 token 在模型输出内容中出现的概率,使模型生成的内容更加符合特定的偏好。 |
|
tools | Array of ToolParam | 否 | - | 模型可以调用的工具列表。目前,仅函数作为工具被支持。用这个来提供模型可能为其生成 JSON 输入的函数列表。 | - |
metadata | Metadata | 否 | - | 额外参数 | - |
参数名称 | 类型 | 是否必填 | 默认值 | 描述 | 示例值 |
---|---|---|---|---|---|
role | String | 是 | - | 发出该消息的对话参与者角色,可选值包括:
| user |
content | String | 否 | - | 消息内容
| 世界第一高山是什么? |
tool_calls | Array of MessageToolCallParam | 否 | - | 模型生成的工具调用。当 | - |
tool_call_id | String | 否 | - | 此消息所回应的工具调用 ID,当 role 为 tool 时必填 | call_5y********************** |
参数名称 | 类型 | 是否必填 | 默认值 | 描述 | 示例值 |
---|---|---|---|---|---|
id | String | 是 | - | 当前工具调用 ID | call_5y********************** |
type | String | 是 | - | 工具类型,当前仅支持function | function |
function | FunctionParam | 是 | - | 模型需要调用的函数 | - |
参数名称 | 类型 | 是否必填 | 默认值 | 描述 | 示例值 |
---|---|---|---|---|---|
name | String | 是 | - | 模型需要调用的函数名称 | get_current_weather |
arguments | String | 是 | - | 模型生成的用于调用函数的参数,JSON 格式。请注意,模型并不总是生成有效的 JSON,并且可能会虚构出一些您的函数参数规范中未定义的参数。在调用函数之前,请在您的代码中验证这些参数是否有效。 | {\"location\": \"Boston, MA\"} |
参数名称 | 类型 | 是否必填 | 默认值 | 描述 | 示例值 |
---|---|---|---|---|---|
type | String | 是 | - | 工具类型,当前仅支持 function | function |
function | 是 | - | 模型可以调用的工具列表。 | - |
参数名称 | 类型 | 是否必填 | 默认值 | 描述 | 示例值 |
---|---|---|---|---|---|
name | String | 是 | - | 函数的名称 | get_current_weather |
description | String | 否 | - | 对函数用途的描述,供模型判断何时以及如何调用该工具函数 | 获取指定城市的天气信息 |
parameters | Object | 否 | 函数请求参数,以 JSON Schema 格式描述。具体格式请参考 JSON Schema 文档 |
|
参数名称 | 类型 | 是否必填 | 默认值 | 描述 | 示例值 |
---|---|---|---|---|---|
include_usage | Boolean | 否 | false | 是否包含本次请求的 token 用量统计信息
| false |
参数名称 | 类型 | 是否必填 | 默认值 | 描述 | 示例值 |
---|---|---|---|---|---|
user_info | String | 否 | - | 可以被反序列化成 json 的字符串,需要包含 |
|
emit_intention_signal_extra | String | 否 | "false" | 值是 "true" 时,会中途返回intention状态 "正在搜索" | - |
target_character_name | String | 否 | - | 群聊Bot对话时填写,指定本次要发言的角色名 | - |
参数名称 | 类型 | 描述 | 示例值 |
---|---|---|---|
id | String | 本次请求的唯一标识 | 021718049470528d92fcbe0865fdffdde******************** |
model | String | 本次请求实际使用的模型名称和版本 | doubao-pro-4k-240515 |
created | Integer | 本次请求创建时间的 Unix 时间戳(秒) | 1718049470 |
object | String | 固定为 chat.completion | chat.completion |
choices | Array of Choice | 本次请求的模型输出内容 | - |
bot_usage | 本次请求的 tokens 和插件消耗 | - | |
references | Array of Reference |
| - |
metadata | Metadata | 请求时附带的额外参数信息 | - |
参数名称 | 类型 | 描述 | 示例值 |
---|---|---|---|
id | String | 本次请求的唯一标识 | 021718049470528d92fcbe0865fdffdde******************** |
model | String | 本次请求实际使用的模型名称和版本 | doubao-pro-4k-240515 |
created | Integer | 本次请求创建时间的 Unix 时间戳(秒) | 1718049470 |
object | String | 固定为 chat.completion.chunk | chat.completion.chunk |
choices | Array of StreamChoice | 本次请求的模型输出内容 | - |
bot_usage | BotUsage | 本次请求的 tokens 和插件消耗 | - |
references | Array of Reference |
| - |
metadata | Metadata | 额外参数 | - |
参数名称 | 类型 | 描述 | 示例值 |
---|---|---|---|
index | Integer | 当前元素在 choices 列表的索引 | 0 |
finish_reason | String | 模型停止生成 token 的原因。可能的值包括:
| stop |
message | 模型输出的内容 | - | |
logprobs | ChoiceLogprobs | 当前内容的对数概率信息 | - |
参数名称 | 类型 | 描述 | 示例值 |
---|---|---|---|
role | String | 固定为 assistant | assistant |
content | String | 模型生成的消息内容,content 与 tool_calls 字段二者至少有一个为非空 | "你好" |
tool_calls | Array of MessageToolCall | 模型生成的工具调用,content 与 tool_calls 字段二者至少有一个为非空 | - |
参数名称 | 类型 | 描述 | 示例值 |
---|---|---|---|
id | String | 当前工具调用 ID | call_5y********************** |
type | String | 工具类型,当前仅支持function | function |
function | Function | 模型需要调用的函数 | - |
参数名称 | 类型 | 描述 | 示例值 |
---|---|---|---|
name | String | 模型需要调用的函数名称 | get_current_weather |
arguments | String | 模型生成的用于调用函数的参数,JSON 格式。请注意,模型并不总是生成有效的 JSON,并且可能会虚构出一些您的函数参数规范中未定义的参数。在调用函数之前,请在您的代码中验证这些参数是否有效。 | {\"location\": \"Boston, MA\"} |
参数名称 | 类型 | 描述 | 示例值 |
---|---|---|---|
content | Array of TokenLogprob | message 列表中每个 content 元素中的 token 对数概率信息 | - |
参数名称 | 类型 | 描述 | 示例值 |
---|---|---|---|
token | String | 当前 token | The |
bytes | Array of Integer | 当前 token 的 UTF-8 值,格式为整数列表。当一个字符由多个 token 组成(表情符号或特殊字符等)时可以用于字符的编码和解码。如果 token 没有 UTF-8 值则为空。 | [84, 104, 101] |
logprob | Float | 当前 token 的对数概率 | -0.0155029296875 |
top_logprobs | Array of TopLogprob | 在当前 token 位置最有可能的标记及其对数概率的列表。在一些情况下,返回的数量可能比请求参数 top_logprobs 指定的数量要少。 | - |
参数名称 | 类型 | 描述 | 示例值 |
---|---|---|---|
token | String | 当前 token | The |
bytes | Array of Integer | 当前 token 的 UTF-8 值,格式为整数列表。当一个字符由多个 token 组成(表情符号或特殊字符等)时可以用于字符的编码和解码。如果 token 没有 UTF-8 值则为空。 | [84, 104, 101] |
logprob | Float | 当前 token 的对数概率 | -0.0155029296875 |
参数名称 | 类型 | 描述 | 示例值 |
---|---|---|---|
model_usage | Array of ModelUsage | 本次请求不同 endpoint 的 token 消耗 | - |
参数名称 | 类型 | 描述 | 示例值 |
---|---|---|---|
name | String | endpoint id | |
prompt_tokens | Integer | 输入的 prompt token 数量 | 130 |
completion_tokens | Integer | 模型生成的 token 数量 | 100 |
total_tokens | Integer | 本次请求消耗的总 token 数量(输入 + 输出) |
参数名称 | 类型 | 描述 | 示例值 |
---|---|---|---|
index | Integer | 当前元素在 choices 列表的索引 | 0 |
finish_reason | String | 模型停止生成 token 的原因。可能的值包括:
| stop |
delta | 模型输出的内容 | - | |
logprobs | ChoiceLogprobs | 当前内容的对数概率信息 | - |
参数名称 | 类型 | 描述 | 示例值 |
---|---|---|---|
role | String | 固定为 assistant | assistant |
content | String | 模型生成的消息内容,content 与 tool_calls 字段二者必有一个为非空 | "你好" |
tool_calls | Array of ChoiceDeltaToolCall | 模型生成的工具调用列表,content 与 tool_calls 字段二者必有一个为非空 | - |
参数名称 | 类型 | 描述 | 示例值 |
---|---|---|---|
index | Interger | 当前元素在 tool_calls 列表的索引 | 0 |
id | String | 当前工具调用 ID | call_5y********************** |
type | String | 工具类型,当前仅支持function | function |
function | Function | 模型需要调用的函数 | - |
不同的结构体详见插件文档:
本接口调用失败的返回结构和参数释义请参见返回结构文档。
本接口与业务逻辑相关的错误码如下表所示。公共错误码请参见公共错误码文档。
HTTP 状态码 | 错误类型 type | 错误代码 code | 错误信息 message | 含义 |
---|---|---|---|---|
400 | BadRequest | SensitiveContentDetected | The request failed because the input text may contain sensitive information. | 输入文本可能包含敏感信息,请您使用其他 prompt。 |