切换语言

Assistants 迁移指南
试用版

从 Assistant API v1 迁移到 v2。

我们更改了工具和文件在 Assistants API 中的工作方式，从v1和v2beta 版本。目前，两个版本的测试版都可以继续通过 API 访问，但我们建议您尽快迁移到最新版本的 API。我们将弃用v1到 2024 年底测试版。source

如果您目前未将工具或文件与 Assistants API 一起使用，则无需进行任何更改即可从v1version 添加到v2beta 版的 beta 版本。只需将v2beta 版本标头和/或迁移到最新版本的 Node 和 Python SDK！source

更改的内容

这v2版本的 Assistants API 包含以下更改：source

  1. 工具重命名：这retrieval工具已重命名为file_search工具
  2. 文件属于 tools：文件现在与工具关联，而不是 Assistants 和 Messages。这意味着：
    • AssistantFile和MessageFile对象不再存在。
    • 而不是AssistantFile和MessageFile，文件使用新的tool_resources对象。
      • 这tool_resources对于 Code Interpreter 工具，有一个file_ids.
      • 这tool_resources对于file_search工具是一个名为vector_stores.
    • 消息现在具有attachments，而不是file_ids参数。消息附件是将文件添加到 Thread 的tool_resources.
V1 助手
1
2
3
4
5
6
7
8
9
10
11
12
{
  "id": "asst_abc123",
  "object": "assistant",
  "created_at": 1698984975,
  "name": "Math Tutor",
  "description": null,
  "model": "gpt-4-turbo",
  "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
  "tools": [{ "type": "code_interpreter" }],
  "file_ids": [],
  "metadata": {}
}
V2 助手
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
{
  "id": "asst_abc123",
  "object": "assistant",
  "created_at": 1698984975,
  "name": "Math Tutor",
  "description": null,
  "model": "gpt-4-turbo",
  "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
  "tools": [
    {
      "type": "code_interpreter"
    },
    {
      "type": "file_search"
    }
  ],
  "tool_resources": {
    "file_search": {
      "vector_store_ids": ["vs_abc"]
    },
    "code_interpreter": {
      "file_ids": ["file-123", "file-456"]
    }
  }
}

助手有tools和tool_resources而不是file_ids.这retrieval工具现在是file_search工具。这tool_resource对于file_searchtool 是一个vector_store.source

V1 线程
1
2
3
4
5
6
{
  "id": "thread_abc123",
  "object": "thread",
  "created_at": 1699012949,
  "metadata": {}
}
V2 线程
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "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"]
    }
  }
}

线程可以自带tool_resources进入对话。source

V1 消息
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
  "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 消息
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
  "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" }
      ]
    }
  ]
}

消息有attachments而不是file_ids.attachments是将文件添加到线程的tool_resources.source

都v1Assistants API 的端点和对象可以在 API 参考的 Legacy 部分下找到。source

在 v2 中访问 v1 数据

为了简化您在v1和v2API，我们会自动映射AssistantFiles和MessageFiles到适当的tool_resources根据在 Assistants 或 Runs 中启用的工具，这些文件是其中的一部分。source

v1版本v2版本
的 AssistantFilescode_interpreterfile_ids在 Google 助理上Assistant 的tool_resources.code_interpreter
的 AssistantFilesretrievalfile_ids在 Google 助理上附加到 Assistant 的 vector_store 中的文件 （tool_resources.file_search)
的 MessageFilescode_interpreterfile_ids在消息上线程的tool_resources.code_interpreter
的 MessageFilesretrievalfile_ids在消息上附加到线程 （vector_storetool_resources.file_search)

需要注意的是，虽然file_ids从v1映射到tool_resources在v2，则反之则不然。您对tool_resources在v2不会反映为file_ids在v1.source

由于 Assistant Files 和 Message Files 已经映射到相应的tool_resources在v2，当您准备好迁移到v2您不必担心数据迁移。相反，您只需：source

  1. 更新您的集成以反映新的 API 和对象。您可能需要执行以下作：
    • 迁移到创建vector_stores并使用file_search，如果您使用的是retrieval工具。重要的是，由于这些作是异步的，因此您需要确保vector_stores在创建 Run 之前。
    • 迁移到将文件添加到tool_resources.code_interpreter而不是 Assistant 或 Message 的文件，如果您使用code_interpreter工具。
    • 迁移到使用 Messageattachments而不是file_ids.
  2. 升级到最新版本的 SDK

更改 beta 版本

不带 SDK

可以通过在 API 请求中传递正确的 API 版本标头来访问这两个 beta 版本：source

  1. v1:OpenAI-Beta: assistants=v1
  2. v2:OpenAI-Beta: assistants=v2
1
2
3
4
5
6
7
8
9
10
curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
    "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.",
    "name": "Math Tutor",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4-turbo"
  }'

使用 SDK

在v2beta 将具有openai.betaNamespace 指向v2版本。您仍然可以访问v1版本的API，使用较旧的 SDK 版本（Python 为 1.20.0 或更早版本，Node 为 4.36.0 或更早版本）或覆盖版本标头。source

要安装旧版本的 SDK，您可以使用以下命令：source

安装旧版本的 SDK
pip install openai==1.20.0

您也可以在较新的 SDK 版本中覆盖此标头，但我们不建议使用此方法，因为这些较新的 SDK 版本中的对象类型将与v1对象。source

在新 SDK 中访问“v1”API 版本
1
2
3
from openai import OpenAI

client = OpenAI(default_headers={"OpenAI-Beta": "assistants=v1"})

计费

在v2API（2024 年 4 月 17 日）将免费使用至 2024 年底。这意味着，由于我们将v1data 到v2，在v2Launch 将是免费的。2024 年底之后，他们将按照届时载体商店的任何费用收费。有关最新的定价信息，请参阅我们的定价页面。source

在发布v2API（2024 年 4 月 17 日），但在该发布日期至 2024 年底之间未在单次运行中使用过的 API 将被删除。这是为了避免我们开始向您收取您在 Beta 版期间创建但从未使用过的内容的费用。source

在v2API 将按定价页面上指定的当前费率计费。source

删除文件

通过 删除 Assistant 文件 / 消息文件v1API 还会将它们从v2应用程序接口。但是，反之则不然 - 删除v2版本的 API 不会传播到v1.如果您在v1并希望从您的帐户中“完全”删除文件v1和v2您应该：source

  • 删除您使用创建的 Assistant 文件 / 消息文件v1使用v1endpoints 或
  • delete the underlying file object （删除底层文件对象） — 这可确保将其从 API 的所有版本中的所有对象中完全删除。

操场

默认 Playground 体验已迁移为使用v2版本（您仍将拥有v1版本，但无法编辑它们）。您通过 Playground 对工具和文件所做的任何更改都只能在v2API 的版本。source

要更改v1版本，则需要直接使用 API。source

这个页面有用吗？