迁移指南
我们已经更改了工具和文件在 助手API 的 v1
和 v2
版本之间的工作方式。 v1
和 v2
版本的 beta 都可以通过 API 访问,但我们建议您尽快将迁移到我们的 API 的最新版本。我们将在 2024 年底前停用 v1
的 beta 版本。
如果您当前不使用 助手API 中的工具或文件,则不需要进行更改即可将从 v1
版本迁移到 v2
版本的 beta。只需传递 v2
beta 版本标头和/或将到最新版本的我们的 Node 和 Python SDK!
更改了什么
助手API 的 v2
版本包含以下更改:
- 工具重命名:
retrieval
工具已重命名为file_search
工具。 - 文件属于工具: 文件现在与工具相关联,而不是 Assistants 和 Messages。这意味着:
AssistantFile
和MessageFile
对象不再存在。- 相反,文件附加到 Assistants 和 Threads 使用新的
tool_resources
对象。file_ids
是代码解释器工具的tool_resource
。vector_stores
是file_search
工具的tool_resource
。
- 消息现在有一个
attachments
参数,而不是file_ids
参数。消息附件是将文件添加到 Thread 的tool_resources
的助手。
以下是一些对象在 v1
和 v2
版本之间的比较:
助手
在 v1
版本中,助手 对象如下所示:
{
"id": "asst_abc123",
"object": "assistant",
"created_at": 1698984975,
"name": "Math Tutor",
"description": null,
"model": "gpt-4-turbo",
"instructions": "你是一位私人数学导师。当被问到问题时,编写并运行 Python 代码来回答问题。",
"tools": [{ "type": "code_interpreter" }],
"file_ids": [],
"metadata": {}
}
在 v2
版本中,Assistant 对象如下所示:
{
"id": "asst_abc123",
"object": "assistant",
"created_at": 1698984975,
"name": "Math Tutor",
"description": null,
"model": "gpt-4-turbo",
"instructions": "你是一位私人数学导师。当被问到问题时,编写并运行 Python 代码来回答问题。",
"tools": [
{
"type": "code_interpreter"
},
{
"type": "file_search"
}
],
"tool_resources": {
"file_search": {
"vector_store_ids": ["vs_abc"]
},
"code_interpreter": {
"file_ids": ["file-123", "file-456"]
}
}
}
Assistants 现在有 tools
和 tool_resources
而不是 file_ids
。 retrieval
工具现在是 file_search
工具。 tool_resource
用于代码解释器工具是 file_ids
。 tool_resource
用于 file_search
工具是 vector_stores
。
Thread
在 v1
版本中,Thread 对象如下所示:
{
"id": "thread_abc123",
"object": "thread",
"created_at": 1699012949,
"metadata": {}
}
在 v2
版本中,Thread 对象如下所示:
{
"id": "thread_abc123",
"object": "thread",
"created_at": 1699012949,
"metadata": {},
"tools": [
{
"type": "file_search"
},
{
"type": "code_interpreter"
}
],
"tool_resources": {
"file_search": {
"vector_store_ids": ["vs_abc"]
},
"code_interpreter": {
"file_ids": ["file-123", "file-456"]
}
}
}
Threads 可以带入自己的 tool_resources
到对话中。
Message
在 v1
版本中,Message 对象如下所示:
{
"id": "msg_abc123",
"object": "thread.message",
"created_at": 1698983503,
"thread_id": "thread_abc123",
"role": "assistant",
"content": [
{
"type": "text",
"text": {
"value": "Hi! How can I help you today?",
"annotations": []
}
}
],
"assistant_id": "asst_abc123",
"run_id": "run_abc123",
"metadata": {},
"file_ids": []
}
在 v2
版本中,Message 对象如下所示:
{
"id": "msg_abc123",
"object": "thread.message",
"created_at": 1698983503,
"thread_id": "thread_abc123",
"role": "assistant",
"content": [
{
"type": "text",
"text": {
"value": "Hi! How can I help you today?",
"annotations": []
}
}
],
"assistant_id": "asst_abc123",
"run_id": "run_abc123",
"metadata": {},
"attachments": [
{
"file_id": "file-123",
"tools": [
{ "type": "file_search" },
{ "type": "code_interpreter" }
]
}
]
}
Messages 有 attachments
而不是 file_ids
。 attachments
是将文件添加到 Thread 的 tool_resources
的助手。
所有 v1
版本的端点和对象都可以在 API 参考的“遗留”部分找到。
在 v2
中访问 v1
数据
为了使您的迁移在我们的 v1
和 v2
APIs 之间简单,我们会自动将 AssistantFiles
和 MessageFiles
映射到适当的 tool_resources
,这取决于 Assistants 或 Runs 这些文件所属的工具。
以下是 v1
和 v2
版本之间的映射:
v1 版本 | v2 版本 | |
---|---|---|
AssistantFiles for code_interpreter | file_ids on Assistant | Files in an Assistant’s tool_resources.code_interpreter |
AssistantFiles for retrieval | file_ids on Assistant | Files in a vector_store attached to an Assistant (tool_resources.file_search ) |
MessageFiles for code_interpreter | file_ids on Message | Files in an Thread’s tool_resources.code_interpreter |
MessageFiles for retrieval | file_ids on Message | Files in a vector_store attached to a Thread (tool_resources.file_search ) |
重要的是要注意,虽然 file_ids
从 v1
被映射到 v2
的 tool_resources
,但反之则不行。对 v2
中的 tool_resources
所做的更改不会反映在 v1
中的 file_ids
。
由于 Assistant Files 和 Message Files 已经映射到适当的 v2
的 tool_resources
,因此当您准备好迁移到 v2
时,您不必担心数据迁移。相反,您只需要:
- 更新您的集成以反映新的 API 和对象。您可能需要执行以下操作:
- 迁移到创建
vector_stores
和使用file_search
,如果您使用的是retrieval
工具。重要的是,由于这些操作是异步的,您应该确保文件已成功由vector_stores
引入,然后再创建运行。 - 迁移到将文件添加到
tool_resources.code_interpreter
而不是 Assistant 或 Message 的文件,如果您使用的是code_interpreter
工具。 - 迁移到使用 Message
attachments
而不是file_ids
。
- 迁移到创建
- 升级到我们的 SDK 的最新版本。
更改 beta 版本
在没有 SDK 的情况下
可以通过在 API 请求中传递正确的 API 版本标头来访问两个 beta 版本:
v1
:OpenAI-Beta: assistants=v1
v2
:OpenAI-Beta: assistants=v2
使用 SDK
我们的 SDK 的版本在 beta 版本的发布后将默认指向 v2
版本的 API。您可以通过使用较旧的 SDK 版本或通过覆盖版本标头来继续访问 v1
版本的 API。
以下是安装较旧 SDK 版本的命令:
- Python:
pip install openai==1.20.0
- Node.js:
npm install @openai/openai-node@4.36.0
不建议使用较新的 SDK 版本并覆盖版本标头,因为这些 SDK 版本中的对象类型与 v1
对象不同。
账单
所有在 beta 期间创建的 vector stores 都将在 beta 期间免费使用。在 beta 期间,我们将继续根据使用情况对模型和 API 请求进行收费。
游乐场
默认的游乐场体验已经迁移到使用 v2
版本的 API,但是您可以在使用 v1
版本的 API 时切换到“旧版”Playground。请注意,在“旧版”Playground 中,一些功能可能无法正常工作,并且我们不再对其进行活动维护或支持。
我们鼓励您在使用 Assistants API 时迁移到 v2
版本的 API,以获得最佳体验和访问最新功能。