切换语言

Assistants 迁移指南
试用版

从 Assistant API v1 迁移到 v2。

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

如果您目前未将工具或文件与 Assistants API 一起使用，则无需进行任何更改即可从 Beta 版迁移到 Beta 版。只需传递 v2 测试版标头和/或迁移到最新版本的 Node 和 Python SDK！v1v2

更改的内容

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

  1. 工具重命名：该工具已重命名为工具retrievalfile_search
  2. 文件属于 tools：文件现在与工具关联，而不是 Assistants 和 Messages。这意味着：
    • AssistantFile和对象不再存在。MessageFile
    • 文件不是 和 ，而是使用新对象附加到 Assistants 和 Threads。AssistantFileMessageFiletool_resources
      • 代码解释器工具是 .tool_resourcesfile_ids
      • 该工具是一个名为 .tool_resourcesfile_searchvector_stores
    • 消息现在具有 ， 而不是参数。消息附件是将文件添加到线程的 .attachmentsfile_idstool_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"]
    }
  }
}

助手有 和 而不是 .该工具现在是工具。该工具的 是 .toolstool_resourcesfile_idsretrievalfile_searchtool_resourcefile_searchvector_store

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

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" }
      ]
    }
  ]
}

消息 has 而不是 . 是将文件添加到线程的 .attachmentsfile_idsattachmentstool_resources

Assistants API 的所有端点和对象都可以在 API 参考的 Legacy 部分找到。v1

在 v2 中访问 v1 数据

为了简化您在我们的 API 和 API 之间的迁移，我们会根据 Assistants 或 Runs 中启用的工具自动映射并到适当的 files 这些文件。v1v2AssistantFilesMessageFilestool_resources

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)

请务必注意，虽然 from 映射到 in ，但反之则不然。您对 in 所做的更改不会反映在 中。file_idsv1tool_resourcesv2tool_resourcesv2file_idsv1

由于 Assistant Files 和 Message Files 已映射到相应的 ，因此当您准备好迁移到 时，您不必担心数据迁移。相反，您只需：tool_resourcesv2v2

  1. 更新您的集成以反映新的 API 和对象。您可能需要执行以下操作：
    • 迁移到 creating and using （如果您正在使用该工具）。重要的是，由于这些操作是异步的，因此您需要确保 before creating 运行成功摄取文件。vector_storesfile_searchretrievalvector_stores
    • 如果您使用的是该工具，请迁移到添加文件而不是 Assistant 或 Message 的文件。tool_resources.code_interpretercode_interpreter
    • 迁移到使用 Message 而不是 。attachmentsfile_ids
  2. 升级到最新版本的 SDK

更改 beta 版本

不带 SDK

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

  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

在 v2 测试版发布后发布的 SDK 版本将具有 openai.beta 命名空间 指向 API 的 v2 版本。您仍然可以使用较旧的 SDK 版本（Python 为 1.20.0 或更早版本，Node 为 4.36.0 或更早版本）或覆盖版本标头。

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

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

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

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

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

计费

在 API 发布（2024 年 4 月 17 日）之前创建的所有矢量存储都可以在 2024 年底之前免费使用。这意味着，在启动之前，由于我们将您的数据映射到 而创建的任何矢量存储都是免费的。2024 年底之后，他们将按照届时载体商店的任何费用收费。有关最新的定价信息，请参阅我们的定价页面。v2v1v2v2

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

在 API 发布后创建的矢量存储将按定价页面上指定的当前费率计费。v2

删除文件

通过 API 删除 Assistant 文件/消息文件也会将其从 API 中删除。但是，反之则不然 — API 版本中的删除不会传播到 。如果您在这两个 上都创建了文件，并希望从您的帐户中“完全”删除文件，您应该：v1v2v2v1v1v1v2

  • 删除使用终端节点的 API 创建的 Assistant Files / Message Files，或者v1v1
  • delete the underlying file object （删除底层文件对象） — 这可确保将其从 API 的所有版本中的所有对象中完全删除。

操场

默认 Playground 体验已迁移为使用 API 版本（您仍将拥有对象版本的只读视图，但无法编辑它们）。您通过 Playground 对工具和文件所做的任何更改只能在 API 版本中访问。v2v1v2

为了更改 API 版本中的文件，您需要直接使用 API。v1

这个页面有用吗？