线程与运行

相关源文件

• src/openai/resources/beta/threads/messages.py
• src/openai/resources/beta/threads/runs/runs.py
• src/openai/resources/beta/threads/runs/steps.py
• src/openai/resources/beta/threads/threads.py
• src/openai/types/beta/assistant_create_params.py
• src/openai/types/beta/thread_create_and_run_params.py
• src/openai/types/beta/threads/run.py
• src/openai/types/beta/threads/run_create_params.py
• tests/api_resources/audio/test_transcriptions.py
• tests/api_resources/beta/test_assistants.py
• tests/api_resources/beta/test_threads.py
• tests/api_resources/beta/threads/runs/test_steps.py
• tests/api_resources/beta/threads/test_messages.py
• tests/api_resources/beta/threads/test_runs.py
• tests/api_resources/fine_tuning/test_jobs.py

本文档涵盖了已弃用的助手 API 的对话管理和助手执行模式，特别是线程与运行系统。该系统为助手交互提供了结构化的对话容器（线程）和执行实例（运行）。

注意：整个助手 API 已弃用，取而代之的是响应 API。有关当前助手功能，请参阅响应 API。

系统概览

线程与运行系统实现了一种有状态的对话模式，其中线程充当持久的对话容器，运行则表示这些线程内的独立助手执行实例。

核心架构

来源: src/openai/resources/beta/threads/threads.py62-89 src/openai/resources/beta/threads/runs/runs.py61-84 src/openai/types/beta/threads/run.py83-246

线程管理

线程提供持久的对话容器，可在多次助手交互中维护消息历史和工具资源。

线程生命周期操作

操作	方法	目的
创建	client.beta.threads.create()	初始化新对话线程
检索	client.beta.threads.retrieve(thread_id)	获取线程详情
更新	client.beta.threads.update(thread_id)	修改线程元数据/资源
删除	client.beta.threads.delete(thread_id)	永久删除线程

线程组件

来源: src/openai/resources/beta/threads/threads.py90-147 src/openai/types/beta/thread_create_and_run_params.py304-333

运行执行模式

运行代表独立的助手执行实例，它们通过预定义的生命周期处理线程内容并生成响应。

运行创建模式

标准运行创建

创建并运行模式

来源: src/openai/resources/beta/threads/runs/runs.py85-607 src/openai/resources/beta/threads/threads.py274-677

运行配置参数

参数	类型	目的
assistant_id	字符串	要执行的助手
instructions	字符串	覆盖助手指令
model	字符串	覆盖助手模型
tools	数组	覆盖助手工具
max_completion_tokens	整数	Token 使用限制
temperature	浮点数	响应随机性控制
流	布尔值	启用流式响应

来源: src/openai/types/beta/threads/run_create_params.py30-181

运行生命周期与状态管理

运行通过一个定义好的状态机进行，具有特定的状态转换和所需的操作。

运行状态流

状态定义

状态	描述	后续操作
queued	等待执行	自动进展
in_progress	正在处理	监控完成情况
requires_action	需要工具输出	提交工具输出
completed	成功完成	检索结果
failed	发生错误	检查 last_error
incomplete	Token 限制超出	检查 incomplete_details
cancelled	用户取消	无需进一步操作
expired	达到超时限制	如果需要，重新开始

来源: src/openai/types/beta/threads/run.py83-246 src/openai/resources/beta/threads/runs/runs.py1199-1298

所需操作处理

当运行进入 requires_action 状态时，它们需要提交工具输出。

来源: src/openai/resources/beta/threads/runs/runs.py1199-1298 src/openai/types/beta/threads/run.py42-53

流式传输与事件处理

运行支持通过服务器发送事件进行实时流式传输，以实现即时响应处理。

流式传输配置

流事件类型

事件类型	描述	负载
thread.run.created	运行初始化	运行对象
thread.run.in_progress	执行已开始	运行对象
thread.run.requires_action	需要工具输出	具有 required_action 的运行
thread.run.completed	成功完成	最终运行对象
thread.run.failed	执行失败	带有错误详情的运行

来源: src/openai/resources/beta/threads/runs/runs.py236-385 src/openai/lib/streaming.py

集成模式

消息与运行协调

错误处理模式

错误场景	检测	恢复策略
运行失败	status == "failed"	检查 last_error，尝试修改后重试
Token 限制	status == "incomplete"	增加限制或截断上下文
工具错误	requires_action 超时	处理带有错误响应的工具调用
速率限制	HTTP 429 响应	实现指数退避

来源: src/openai/resources/beta/threads/runs/runs.py608-691 src/openai/types/beta/threads/run.py109-123

资源清理

来源: src/openai/resources/beta/threads/threads.py239-272 src/openai/resources/beta/threads/runs/runs.py726-782