Assistants API (已弃用)

相关源文件

• src/openai/resources/beta/assistants.py
• src/openai/resources/beta/threads/messages.py
• src/openai/resources/beta/threads/runs/steps.py
• src/openai/types/beta/assistant_update_params.py
• src/openai/types/chat_model.py
• src/openai/types/moderation.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

本文档介绍了 OpenAI Python 客户端库中旧版的助手 API 实现。助手 API 已弃用，取而代之的是响应 API，目前仅为向后兼容而维护。有关当前推荐的 AI 交互方法，请参阅响应 API。

助手 API 提供了一个有状态的对话接口，AI 助手可以通过线程维护跨多个交互的上下文，执行工具并管理文件。尽管仍然可用，但所有 API 端点现在都会发出弃用警告。

弃用状态

所有助手 API 资源均标记为已弃用，并附带消息：“助手 API 已弃用，取而代之的是响应 API”。此弃用通过 Python 的 typing_extensions.deprecated 装饰器实现，并一致地出现在所有相关模块中。

弃用实现

来源： src/openai/resources/beta/threads/messages.py51-52 src/openai/resources/beta/threads/runs/steps.py46-47

API 架构概述

助手 API 遵循以有状态对话和具有持久功能的 AI 助手为中心的层次化资源结构。

来源： src/openai/resources/beta/assistants.py34-481 src/openai/resources/beta/threads/messages.py31-719 src/openai/resources/beta/threads/runs/steps.py26-400

核心组件

助手资源

Assistants 类管理具有持久配置、工具和功能的 AI 助手实体。

关键方法

• create(): 使用模型和配置创建新助手
• retrieve(assistant_id): 获取现有助手
• update(assistant_id): 修改助手配置
• list(): 返回分页助手列表
• delete(assistant_id): 删除助手

来源： src/openai/resources/beta/assistants.py54-481 src/openai/types/beta/assistant_update_params.py16-178

线程和消息

线程提供具有持久消息历史的对话上下文。消息表示线程内的单独通信。

线程操作

• create(): 创建新的对话线程
• create_and_run(assistant_id): 创建线程并立即运行助手
• retrieve(thread_id): 获取线程信息
• update(thread_id): 修改线程元数据
• delete(thread_id): 删除线程及所有消息

消息操作

• create(thread_id, content, role): 向线程添加消息
• retrieve(message_id, thread_id): 获取特定消息
• list(thread_id): 返回线程消息历史
• update(message_id, thread_id): 修改消息元数据
• delete(message_id, thread_id): 从线程中删除消息

来源： tests/api_resources/beta/test_threads.py27-420 src/openai/resources/beta/threads/messages.py52-719

运行和运行步骤

运行表示线程内的助手执行会话。运行步骤提供详细的执行跟踪。

运行操作

• create(thread_id, assistant_id): 启动助手执行
• retrieve(run_id, thread_id): 获取运行状态和结果
• update(run_id, thread_id): 修改运行元数据
• list(thread_id): 返回线程的运行历史
• cancel(run_id, thread_id): 停止运行中的执行
• submit_tool_outputs(run_id, thread_id, tool_outputs): 提供工具结果

运行步骤操作

• retrieve(step_id, thread_id, run_id): 获取详细的步骤信息
• list(run_id, thread_id): 返回执行步骤序列

来源： tests/api_resources/beta/threads/test_runs.py26-568 src/openai/resources/beta/threads/runs/steps.py47-336

响应处理模式

所有助手 API 资源都支持同步和异步操作，并具有一致的响应处理模式。

响应类型	用法模式	描述
标准	client.beta.assistants.create()	解析后的响应对象
原始响应	client.beta.assistants.with_raw_response.create()	带标头的完整 HTTP 响应
流式传输	client.beta.assistants.with_streaming_response.create()	用于响应流的上下文管理器

流式传输支持

• 运行支持带 stream=True 参数的流式传输
• 工具输出提交支持流式响应
• 线程创建和运行执行可以流式传输

来源： tests/api_resources/beta/threads/test_runs.py115-124 tests/api_resources/beta/test_assistants.py72-82

错误处理与验证

该 API 在所有资源上都实现了通用的验证模式

常见验证模式

• 所有 ID 参数的非空字符串验证
• API 调用前进行所需参数检查
• 通过 Pydantic 模型进行类型验证
• 所有方法调用均发出弃用警告

来源： src/openai/resources/beta/threads/messages.py98-99 src/openai/resources/beta/threads/runs/steps.py81-86

迁移指南

即时行动

1. 抑制弃用警告: 在测试中使用 pytest.warns(DeprecationWarning)
2. 规划迁移: 评估响应 API 功能是否适合您的用例
3. 监控更新: 关注移除时间表的公告

长期迁移

• 通过响应 API，用直接的模型交互取代基于助手的流程
• 将线程/消息模式迁移到您应用程序中的对话管理
• 将工具使用转换为聊天补全中的函数调用

当前兼容性

• 所有端点均可正常运行并发出弃用警告
• 仍然需要 Beta 标头 "OpenAI-Beta": "assistants=v2"
• 现有助手配置继续有效

来源： tests/api_resources/beta/threads/test_runs.py27-28 tests/api_resources/beta/test_threads.py28-29