OpenAI CTO

迁移指南

我们已经更改了工具和文件在 助手API 的 v1 和 v2 版本之间的工作方式。 v1 和 v2 版本的 beta 都可以通过 API 访问，但我们建议您尽快将迁移到我们的 API 的最新版本。我们将在 2024 年底前停用 v1 的 beta 版本。

如果您当前不使用 助手API 中的工具或文件，则不需要进行更改即可将从 v1 版本迁移到 v2 版本的 beta。只需传递 v2 beta 版本标头和/或将到最新版本的我们的 Node 和 Python SDK！

更改了什么

助手API 的 v2 版本包含以下更改：

  1. 工具重命名： retrieval 工具已重命名为 file_search 工具。
  2. 文件属于工具： 文件现在与工具相关联，而不是 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_interpreterfile_ids on AssistantFiles in an Assistant’s tool_resources.code_interpreter
AssistantFiles for retrievalfile_ids on AssistantFiles in a vector_store attached to an Assistant (tool_resources.file_search)
MessageFiles for code_interpreterfile_ids on MessageFiles in an Thread’s tool_resources.code_interpreter
MessageFiles for retrievalfile_ids on MessageFiles 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 时，您不必担心数据迁移。相反，您只需要：

  1. 更新您的集成以反映新的 API 和对象。您可能需要执行以下操作：
    • 迁移到创建 vector_stores 和使用 file_search，如果您使用的是 retrieval 工具。重要的是，由于这些操作是异步的，您应该确保文件已成功由 vector_stores 引入，然后再创建运行。
    • 迁移到将文件添加到 tool_resources.code_interpreter 而不是 Assistant 或 Message 的文件，如果您使用的是 code_interpreter 工具。
    • 迁移到使用 Message attachments 而不是 file_ids。
  2. 升级到我们的 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，以获得最佳体验和访问最新功能。

Was this page helpful?