OpenAI CTO

助理 (Beta)

构建可以调用模型并使用工具执行任务的助理。

开始使用助理 API

创建助手

POST <https://api.openai.com/v1/assistants>

使用模型和说明创建助手。

请求正文

名称类型必需描述
modelstring必需要使用的模型的ID。您可以使用列出模型 API查看所有可用模型，或查看我们的模型概述以了解它们的描述。
namestring或null可选助手的名称。最大长度为256个字符。
descriptionstring或null可选助手的描述。最大长度为512个字符。
instructionsstring或null可选助手使用的系统指令。最大长度为256,000个字符。
tools数组可选助手上启用的工具列表。每个助手最多可以有128个工具。工具可以是code_interpreter、file_search或function类型。
tool_resourcesobject或null可选助手的工具使用的一组资源。资源特定于工具的类型。例如，code_interpreter工具需要文件ID的列表，而file_search工具需要矢量存储ID的列表。
metadatamap可选可以附加到对象的16个键值对。这对于以结构化的方式存储有关对象的其他信息非常有用。键最多可以有64个字符长，值最多可以有512个字符长。
temperaturenumber或null可选使用的采样温度，范围为0到2。较高的值，如0.8，会使输出更加随机，而较低的值，如0.2，会使其更加集中和确定性。默认为1。
top_pnumber或null可选称为核采样，其中模型仅考虑具有top_p概率质量的令牌的结果。因此，0.1意味着仅考虑构成前10％概率质量的令牌。我们通常建议更改此值或温度，但不是两者。默认为1。
response_formatstring或object可选指定模型必须输出的格式。与GPT-4o、GPT-4 Turbo and GPT-4以及所有自gpt-3.5-turbo-1106以来的GPT-3.5 Turbo模型兼容。将其设置为{ "type": "json_object" }将启用JSON模式，该模式保证模型生成的消息是有效的JSON。

返回

助手对象。

代码解释器

示例请求

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": "你是一个私人数学辅导员。当被问到问题时，编写并运行 Python 代码来回答问题。",
    "name": "数学辅导员",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4-turbo"
  }'

响应

{
  "id": "asst_abc123",
  "object": "assistant",
  "created_at": 1698984975,
  "name": "数学辅导员",
  "description": null,
  "model": "gpt-4-turbo",
  "instructions": "你是一个私人数学辅导员。当被问到问题时，编写并运行 Python 代码来回答问题。",
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "metadata": {},
  "top_p": 1.0,
  "temperature": 1.0,
  "response_format": "auto"
}

示例请求

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 an HR bot, and you have access to files to answer employee questions about company policies.",
    "tools": [{"type": "file_search"}],
    "tool_resources": {"file_search": {"vector_store_ids": ["vs_123"]}},
    "model": "gpt-4-turbo"
  }'

响应

{
  "id": "asst_abc123",
  "object": "assistant",
  "created_at": 1699009403,
  "name": "HR Helper",
  "description": null,
  "model": "gpt-4-turbo",
  "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.",
  "tools": [
    {
      "type": "file_search"
    }
  ],
  "tool_resources": {
    "file_search": {
      "vector_store_ids": [
        "vs_123"
      ]
    }
  x,
  "metadata": {},
  "top_p": 1.0,
  "temperature": 1.0,
  "response_format": "auto"
}

列表助手

get https://api.openai.com/v1/assistants

返回助手列表。

查询参数

名称类型必填默认值描述
limitinteger否20要返回的对象数量上限。limit 可以在 1 到 100 之间，默认为 20。
orderstring否desc按照对象的 created_at 时间戳进行排序。asc 表示升序，desc 表示降序。
afterstring否用于分页的游标。after 是一个对象 ID，表示你在列表中的位置。例如，如果你进行了一个列表请求并收到了 100 个对象，以 obj_foo 结尾，则你的后续请求可以包含 after=obj_foo 以获取列表的下一页。
beforestring否用于分页的游标。before 是一个对象 ID，表示你在列表中的位置。例如，如果你进行了一个列表请求并收到了 100 个对象，以 obj_foo 结尾，则你的后续请求可以包含 before=obj_foo 以获取列表的上一页。

返回值

一个助手对象的列表。

例子：

示例请求

curl "https://api.openai.com/v1/assistants?order=desc&limit=20" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2"

响应

{
  "object": "list",
  "data": [
    {
      "id": "asst_abc123",
      "object": "assistant",
      "created_at": 1698982736,
      "name": "Coding Tutor",
      "description": null,
      "model": "gpt-4-turbo",
      "instructions": "You are a helpful assistant designed to make me better at coding!",
      "tools": [],
      "tool_resources": {},
      "metadata": {},
      "top_p": 1.0,
      "temperature": 1.0,
      "response_format": "auto"
    },
    {
      "id": "asst_abc456",
      "object": "assistant",
      "created_at": 1698982718,
      "name": "My Assistant",
      "description": null,
      "model": "gpt-4-turbo",
      "instructions": "You are a helpful assistant designed to make me better at coding!",
      "tools": [],
      "tool_resources": {},
      "metadata": {},
      "top_p": 1.0,
      "temperature": 1.0,
      "response_format": "auto"
    },
    {
      "id": "asst_abc789",
      "object": "assistant",
      "created_at": 1698982643,
      "name": null,
      "description": null,
      "model": "gpt-4-turbo",
      "instructions": null,
      "tools": [],
      "tool_resources": {},
      "metadata": {},
      "top_p": 1.0,
      "temperature": 1.0,
      "response_format": "auto"
    }
  ],
  "first_id": "asst_abc123",
  "last_id": "asst_abc789",
  "has_more": false
}

检索助手 (Beta)

检索一个助手。

Endpoint:

GET https://api.openai.com/v1/assistants/{assistant_id}

Path parameters

NameTypeRequiredDescription
assistant_idstringYes要检索的助手的 ID。

返回

匹配指定 ID 的 assistant object。

示例请求

curl https://api.openai.com/v1/assistants/asst_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2"

回应

{
  "id": "asst_abc123",
  "object": "assistant",
  "created_at": 1699009709,
  "name": "HR Helper",
  "description": null,
  "model": "gpt-4-turbo",
  "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.",
  "tools": [
    {
      "type": "file_search"
    }
  ],
  "metadata": {},
  "top_p": 1.0,
  "temperature": 1.0,
  "response_format": "auto"
}

修改助手

修改助手。

路径参数

参数名称类型是否必需
assistant_idstring是

请求正文

参数名称类型是否必需
model可选
namestring or null可选
descriptionstring or null可选
instructionsstring or null可选
toolsarray可选
tool_resourcesobject or null可选
metadatamap可选
temperaturenumber or null可选
top_pnumber or null可选
response_formatstring or object可选

返回值

已修改的助手对象。

示例请求

curl https://api.openai.com/v1/assistants/asst_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
      "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.",
      "tools": [{"type": "file_search"}],
      "model": "gpt-4-turbo"
    }'

响应

{
  "id": "asst_123",
  "object": "assistant",
  "created_at": 1699009709,
  "name": "HR Helper",
  "description": null,
  "model": "gpt-4-turbo",
  "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.",
  "tools": [
    {
      "type": "file_search"
    }
  ],
  "tool_resources": {
    "file_search": {
      "vector_store_ids": []
    }
  },
  "metadata": {},
  "top_p": 1.0,
  "temperature": 1.0,
  "response_format": "auto"
}

删除助手 (Beta)

删除助手。

Endpoint

DELETE https://api.openai.com/v1/assistants/{assistant\_id}

路径参数

参数名称类型必须描述
assistant_idstring是要删除的助手的 ID。

返回

删除状态

示例请求

curl https://api.openai.com/v1/assistants/asst_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2" \
  -X DELETE

响应

{
  "id": "asst_abc123",
  "object": "assistant.deleted",
  "deleted": true
}

助手对象

assistant 对象表示一个可以调用模型并使用工具的助手。

  • id: 助理的标识符，可以在API端点中引用。
  • object: 对象类型，总是assistant。
  • created_at: 创建助理的Unix时间戳（秒）。
  • name: 助理的名称，最大长度为256字符。
  • description: 助理的描述，最大长度为512字符。
  • model: 使用的模型ID。你可以使用List models API查看所有可用模型，或查看我们的模型概述了解模型描述。
  • instructions: 助理使用的系统指令，最大长度为256,000字符。
  • tools: 启用在助理上的工具列表，每个助理最多可以有128个工具。工具类型可以是code_interpreter、file_search或function。
  • metadata: 可以附加到对象的16对键值对，这可以用于以结构化格式存储有关对象的额外信息。键最长可以是64个字符，值最长可以是512个字符。
  • top_p: 采用名为核心采样的采样方式，模型只考虑top_p概率质量的结果。例如0.1意味着只考虑组成前10%概率质量的tokens。
  • temperature: 使用的采样温度，范围从0到2。较高的值如0.8会使输出更随机，而较低的值如0.2会使其更集中和确定。
  • response_format: 指定模型必须输出的格式。与GPT-4o、GPT-4 Turbo和所有GPT-3.5 Turbo模型兼容，从gpt-3.5-turbo-1106开始。设置为{"type": "json_object"}启用JSON模式，这保证了模型生成的消息是有效的JSON。

示例请求

{
  "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"
    }
  ],
  "metadata": {},
  "top_p": 1.0,
  "temperature": 1.0,
  "response_format": "auto"
}

Was this page helpful?