资讯 文档
技术能力
语音技术
文字识别
人脸与人体
图像技术
语言与知识
视频技术

公共类型定义

本文档描述 Assistants API 的公共请求头和请求对象、公共响应头和响应对象信息。当您调用具体接口时,可进行参考。排查问题时,可附加公共响应头中的

公共请求头

参数 语义 是否必填 取值/类型 备注
Content-Type Content-Type
Authorization 鉴权Token string 格式为:Bearer xxxx
可以从千帆AppBuilder平台获取

请求对象

Thread

参数名称 类型 是否必须 备注
messages array[Message] 本次对话追加的messages
metadata map<string, string> 一组可以附加到对象的16个键值对。这对于以结构化格式存储关于对象的附加信息非常有用。键的长度最多为64个字符,值的长度最多可为512个字符

Message

参数名称 类型 是否必须 备注
role string 当前接口的角色
当作为请求内容时,role仅可以为user
当系统返回Meesage对象时,role可能为user或者assistant
content string 消息内容
file_ids array[string] 可选字段
例如图生文,或者retrieval有都有输入文件的需求,使用该字段
整体最多不超过10个文件
metadata map<string, string> 一组可以附加到对象的16个键值对。这对于以结构化格式存储关于对象的附加信息非常有用。键的长度最多为64个字符,值的长度最多可为512个字符

ModelParameters

参数名称 类型 是否必须 备注
chat_parameters object 回复模型超参
+temperature float 采样温度,较高的数值会使输出更随机。取值范围严格大于0,小于等于1,默认为0.8
+top_p float 核采样方法的概率阈值,影响输出文本的多样性,较低的数值会使输出的文本更加多样性。取值范围大于等于0,小于等于1,默认为0.8
+penalty_score float 惩罚分数,影响输出文本的多样性和质量,较高的数值使输出的文本更加多样性。取值范围大于等于1,小于等于2,默认为1.0
thought_parameters object 思考模型超参
+temperature float 采样温度,较高的数值会使输出更随机。取值范围严格大于0,小于等于1,默认为0.01
+top_p float 核采样方法的概率阈值,影响输出文本的多样性,较低的数值会使输出的文本更加多样性。取值范围大于等于0,小于等于1,默认为0
+penalty_score float 惩罚分数,影响输出文本的多样性和质量,较高的数值使输出的文本更加多样性。取值范围大于等于1,小于等于2,默认为1.0

Tool

参数名称 类型 是否必须 备注
type string 枚举:
file_retrieval: 知识库检索工具能够理解文档内容,支持用户针对文档内容的问答。
code_interpreter: 代码解释器, 代码解释器能够生成并执行代码,从而协助用户解决复杂问题,涵盖科学计算(包括普通数学计算题)、数据可视化、文件编辑处理(图片、PDF文档、视频、音频等)、文件格式转换(如WAV、MP3、text、SRT、PNG、jpg、MP4、GIF、MP3等)、数据分析&清洗&处理(文件以excel、csv格式为主)、机器学习&深度学习建模&自然语言处理等多个领域。
function: 支持fucntion call模式调用工具
function Function Function工具描述
仅当type为function 时需要且必须填写

Function

参数名称 类型 是否必须 备注
name string 函数名
只允许数字、大小写字母和中划线和下划线,最大长度为64个字符。一次运行中唯一。
description string 函数描述
parameters object 函数请求参数,JSON Schema 格式,参考JSON Schema描述
在此基础上,新增约束如下:
1. 当某一字段为object类型时,properties字段必选,properties内可为空。
2. 当某一字段为array类型时,items字段必选,items内可为空。
responses object 函数响应参数,JSON Schema 格式,参考JSON Schema描述
在此基础上,新增约束如下:
1. 当某一字段为object类型时,properties字段必选,properties内可为空。
2. 当某一字段为array类型时,items字段必选,items内可为空。

ToolOutput

参数名称 类型 是否必须 描述
tool_call_id string 工具调用的ID。
来源于上一轮Run请求时required_action.id字段。
run_id string 仅当非流式提交工具结果时使用
来源于上一轮Run请求时id字段
output string function call工具的输出。
如果是json,也需要对json序列化成string。

公共响应头

参数 语义 是否必填 取值/类型 备注
Content-Type Content-Type string
Content-Length 消息长度 string
Date 响应时间 string 使用IMF-fixdate格式
Statement 声明 string 值固定为 Al-generated
X-Appbuilder-Request-Id 请求id string 唯一id,使用uuid4规则生成

响应对象

RunObject

字段 类型 描述
id string Run id
object string thread.run
assistant_id string 对应assistant 的assistant_id
thread_id string 对应thread 的 thread id
instructions string 系统人设指令
概述Agent的整体功能和定位,需要它扮演一个什么样的"角色"。
1. 可以参考“你是xxx,你具有xx的特点,你可以做xxx,你需要满足用户xxx的需求”这样的结构。
2. 可以指定一些与能力边界相关要求(对于哪些类型的问题,无法回答)
示例:
你是一个音乐智能语音助手,可以通过调用技能的方式满足用户听音乐,看电影,追剧,刷短视频,听有声读物,信息问答等需求。你无法提供与政治和政策相关的内容;当用户提出与音乐、视频等娱乐信息不相关的问题时,你需要委婉地拒绝用户。
thought_instructions string 思考规范
与业务逻辑和规则相关的指令。希望模型遵守的行为规范和准则、要求都尽可能清晰、详尽地在这里给出描述。包括但不限于:
在什么情况下需要调用什么工具;在调用xxx工具之前需要先调用xxx工具获取什么信息;
xxx工具填参的要求和偏好;(优先设定在工具描述中,如果较复杂,可以在这里强调)
在模型判断结果无法满足用户时采取什么行动(换一个工具,或者改变参数调同一个工具,或是告知用户无法满足但努力基于当前信息提供结果,等);
示例:
你需要遵循以下要求:
1.当用户给出特定的歌曲名,或者给出特定歌手,或者给出特定风格的音乐时,优先调用music_player工具
2.如果发现用户给出的是歌词,或者判断不出歌曲的名字、歌手时,请优先调用调用web_search工具获取歌名以及歌手,然后再去调用music_player工具
3.当web_search返回结果存在内容错误、质量差、不相关、资源陈旧以及信息量不足等情况时,你可以尝试优化查询词并重新调用web_search。
chat_instructions string 回复规范
与模型最终给出的回复内容相关的指令。包括但不限于:
1. 语气偏好
2. 回复格式要求
3. 回复内容的丰富程度
4. 开头和结尾的形式要求,例如在结尾时需要向用户提问引导话题深入进行
示例:
1.你需要对用户的需求和问题给予耐心细致的回应;根据用户的输入,灵活调整对话内容,确保对话流畅自然。
2.当需要推荐电影给用户时,你需要按照以下格式输出:[电影名称](url):推荐理由
3.可以在回复中适当插入emoji表情,提升亲切感
tools array[Tool] Assistant当前使用的所有的工具列表
file_ids array[string] Assistant当前使用的所有的文件列表
status string 状态枚举:
queued:当Run对象首次创建就会变成queued等待运行,正常情况下,很快就会变成in_progress状态。
in_progress:run正在执行中,这时候可以调用run_step接口来查看具体的执行状态。
requires_action:如果Assistant需要执行函数调用(function call),就会转到这个状态,然后你必须按给定的参数调用指定的方法,并提交输出之后,run才可以继续运行,进入in_progress状态。
expired:当没有在expires_at之前提交函数调用输出,run将会过期。另外,如果在expires_at之前没获取输出,run也会变成expired状态。
cancelling:当调用cancel接口后,run就会变成cancelling,取消成功后就会变成cancelled状态
cancelled:Run已成功取消。
failed:运行失败,可以通过查看Run对象中的last_error对象来查看失败的原因。参考 LastError对象。
completed:执行完成,可以获取Assistant返回的消息了,也可以继续向Assistant提问了。
required_action RequiredAction 有关function_call运行所需操作的详细信息。
如果不需要function_call调用,则将为null或不返回此字段。
last_error LastError 错误信息。运行没有正常结束时包含的错误信息。
如果没有错误,则将为null或不返回此字段。
final_answer FinalAnswer 仅在stream=false时存在
运行正常结束时包含message结果。
如果没有正常结束,则将为null或不返回此字段。
created_at integer 创建时间戳
started_at integer 开始运行时间戳。
expired_at integer 实际过期的时间戳。以status=expired状态结束时记录相关的时间戳。
cancelled_at integer 取消时间戳。以status=cancelled状态结束时记录相关的时间戳。
failed_at integer 失败时间戳。以status=failed状态结束时记录相关的时间戳。
completed_at integer 成功时间戳。以status=completed状态结束时记录相关的时间戳。

RunStepObject

字段 类型 描述
id string Run Step id
object string thread.run.step
assistant_id string 对应assistant 的assistant_id
thread_id string 对应thread 的 thread_id
run_id string 对应run的id
status string 状态枚举:同上
created_at integer 创建时间戳
started_at integer 开始运行时间戳。
expired_at integer 实际过期的时间戳。以status=expired状态结束时记录相关的时间戳。
cancelled_at integer 取消时间戳。以status=cancelled状态结束时记录相关的时间戳。
failed_at integer 失败时间戳。以status=failed状态结束时记录相关的时间戳。
completed_at integer 成功时间戳。以status=completed状态结束时记录相关的时间戳。
last_error LastError 错误信息。运行没有正常结束时包含的错误信息。
如果没有错误,则将为null或不返回此字段。
type string 固定为null
step_detail StepDetail 本次step的详情

StepDetail

字段 类型 描述
type string 枚举:
message_creation:run运行过程中,产生了大模型的最终消息时,将message内容通知调用方
tool_calls:run运行中,触发了function_call的requires_action动作时,将tool_calls的信息(含tool_calls_id,arguments等)通知调用方
message_creation object 当type为message_creation时有值
+message_id string 消息ID
tool_calls array[object] 当type为tool_calls时有值
function_call的事件,注意这里是个array
+id string 工具调用的ID
+type string 固定为function
+function object function_call参数
++name string function名
++arguments string function调用参数
++output string function输出

ErrorResponse

字段 类型 描述
error object 公共报错信息
+code integer 错误码
+message string 错误描述
+type string 错误类型
+param string 错误参数

RequiredAction

字段 类型 描述
type string 固定submit_tool_outputs
submit_tool_outputs object 有关此运行继续所需的工具输出的详细信息。
+tool_calls array [object] 相关工具调用的列表。
++id string 工具调用的ID。当您在中使用提交工具输出来运行端点提交工具输出时,必须引用此ID。
++type string 需要输出的工具调用的类型。就目前而言,这始终是函数。
++function object 函数定义。
+++name string 函数的名称
+++arguments string 模型希望您传递给函数的参数,需要是一个json dump string

FinalAnswer

字段 类型 描述
type string 固定为message
message object
+message_id string message对应id
+content Content message内容

Content

字段 类型 描述
type string 当前固定为text
text object 若type为text,则此处有值
+value string 正文

LastError

字段 类型 描述
code string 错误码
message string 错误描述