OpenAI Assistant API（二）：Thread、Messges及Run应用方法

一、Assistant API基础概念

1. Assistant与Thread关系
   每个Assistant对象可应用多个Thread（线程）执行不同聊天或任务。在Assistant API机制中，Assistant与Thread在创建阶段并非直接绑定，而是在运行过程中才进行有效绑定。

Thread创建方式简单，通过client.threads.create()即可创建。返回响应体包含关键信息，如下表所示：

字段名	说明
id	对话线程唯一标识符，类似聊天对话框特殊标识
created_at	Unix时间戳表示的创建时间
object	标识为thread类型，用于区分对象类型

创建Thread示例代码：

thread = client.threads.create()
print(thread.to_dict())

2. Message概念及作用
   Message是Assistant和用户之间的对话会话，所有会话信息存放在Thread中。其最大优势是能自主管理聊天会话记录，无需手动构建。 Message支持多种类型，不仅有文本，还包括图像、音频等。每个线程的消息数限制为10万条，达到限制会触发截断策略（后续介绍），原因是模型有最长上下文输入限制。

构建Message时，其endpoint：https://api.openai.com/v1/threads/{thread_id}/messages ，该接口核心参数如下：

字段名	类型	是否必需	描述
thread_id	string	必需	用于创建消息的线程ID
role	string	必需	创建消息的实体角色，user表示用户发送，assistant表示助手生成
content	string/array	必需	消息的内容

构建并添加Message示例代码：

message = client.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="写一篇关于一个小女孩在森林里遇到一只怪兽的故事。详细介绍她的所见所闻,并描述她的心理活动"
)
print(message.to_dict())

3. Run的功能与意义
   Run（运行）状态用于指示Assistant读取Thread中的消息并采取适当操作，即让Assistant响应Thread中最新追加的消息。

Run需传递thread_id（用于运行的线程ID）和assistant_id（助手的ID）两个必需参数，在运行阶段实现Thread与Assistant的绑定，这种灵活性可使创建多个代理执行不同任务，执行具体线程对话时能灵活选择代理。

创建Run示例代码：

run = client.threads.runs.create(
    thread_id=thread.id,
    assistant_id=assistant.id
)
print(run.to_dict())

run_info = {
    'id': 'run_Ko3eH0xJW4FzV2onGHDbVo5',
    'assistant_id': 'asst_2cCuAivmPc66vpmMGYINDePS',
    'cancelled_at': None,
    'completed_at': None,
    'created_at': 1727266914,
    'expires_at': 1727267514,
    'failed_at': None,
    'incomplete_details': None,
    'instructions': 'You are an expert at writing excellent literature',
    'last_error': None,
   'max_completion_tokens': None,
   'max_prompt_tokens': None,
   'metadata': {},
   'model': 'gpt-4o-mini-2024-07-18',
    'object': 'thread.run',
    'parallel_tool_calls': True,
   'required_action': None,
   'response_format': 'auto',
   'started_at': None,
   'status': 'queued',
    'thread_id': 'thread_8t2o4a7qQ1lnJZE3JtxA2khh',
    'tool_choice': 'auto',
    'tools': [],
    'truncation_strategy': {'type': 'auto', 'last_messages': None},
    'usage': None,
    'temperature': 1.0,
    'top_p': 1.0,
    'tool_resources': {}
}

• 1. 基本标识类
  • id：Run 的唯一标识符，用于在系统中标识特定的 Run 实例。
  • assistant_id：关联的 Assistant 的唯一标识符，表明该 Run 是由哪个 Assistant 执行的。
  • thread_id：关联的对话线程 ID，说明该 Run 是在哪个线程中执行的。
  • object：固定值thread.run，用于标识当前对象类型是线程中的 Run。
• 2. 时间相关类
  • created_at：Run 创建的 Unix 时间戳。
  • completed_at：Run 完成的 Unix 时间戳，当前为None表示尚未完成。
  • cancelled_at：Run 被取消的 Unix 时间戳，None表示未被取消。
  • failed_at：Run 失败的 Unix 时间戳，None表示未失败。
  • expires_at：Run 的过期时间 Unix 时间戳 。
  • started_at：Run 开始执行的 Unix 时间戳，当前为None表示尚未开始。
• 3. 状态相关类
  • status：当前 Run 的状态，queued表示处于排队等待执行状态。
  • required_action：执行 Run 所需的额外操作，None表示当前无需额外操作。
• 4. 配置相关类
  • instructions：对 Assistant 的指令，这里设定为“你是撰写优秀文学作品的专家” 。
  • model：使用的模型名称，gpt-4o-mini-2024-07-18 。
  • response_format：期望的响应格式，auto表示自动格式。
  • tool_choice：工具选择策略，auto表示自动选择工具。
  • parallel_tool_calls：是否允许并行工具调用，True表示允许。
• 5. 参数相关类
  • max_completion_tokens：最大完成标记数，当前为None表示未设定限制。
  • max_prompt_tokens：最大提示标记数，当前为None表示未设定限制。
  • temperature：生成文本时的温度参数，值为1.0 ，控制生成文本的随机性。
  • top_p：核采样参数，值为1.0 ，用于控制生成文本的多样性。
• 6. 其他类
  • last_error：最近一次错误信息，None表示无错误。
  • incomplete_details：未完成原因详情，None表示无相关信息。
  • metadata：自定义元数据，当前为空字典。
  • tools：使用的工具列表，当前为空列表。
  • truncation_strategy：截断策略，type为auto表示自动截断，last_messages为None 。
  • tool_resources：工具资源相关信息，当前为空字典。
  • usage：使用情况统计信息，当前为None。

二、Assistant API操作流程示意图

此流程图展示了Assistant API的基本操作流程，从创建Thread开始，接着构建并添加Message到Thread，最后创建Run来执行大模型响应。