OpenAI CTO

助手 (v1) Legacy

助手是可以调用模型并使用工具执行任务的系统。

开始使用 Assistants API

创建助手 (v1) Legacy

Endpoint

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

描述

创建一个带有模型和指令的助手。

请求体

参数名类型必需描述
modelstring必需使用的模型 ID。您可以使用 List models API 查看所有可用模型，或查看我们的 Model overview 获取描述。
namestring 或 null可选助手的名称。最大长度为 256 个字符。
descriptionstring 或 null可选助手的描述。最大长度为 512 个字符。
instructionsstring 或 null可选助手使用的系统指令。最大长度为 256,000 个字符。
toolsarray可选助手启用的工具列表。每个助手最多可以有 128 个工具。工具可以是 code_interpreter、retrieval 或 function 类型。默认值为 []。
file_idsarray可选附加到此助手的文件 ID 列表。每个助手最多可以附加 20 个文件。文件按创建日期升序排列。默认值为 []。
metadatamap可选附加到对象的一组 16 个键值对。这对于以结构化格式存储有关对象的附加信息非常有用。键的最大长度为 64 个字符，值的最大长度为 512 个字符。
temperaturenumber 或 null可选采样温度，范围在 0 到 2 之间。较高的值（如 0.8）将使输出更加随机，而较低的值（如 0.2）将使其更加集中和确定性。默认值为 1。
top_pnumber 或 null可选温度采样的替代方案，称为核采样，模型考虑 top_p 概率质量的标记结果。例如 0.1 表示只考虑占前 10% 概率质量的标记。我们通常建议更改此参数或 temperature，但不建议同时更改这两个参数。默认值为 1。
response_formatstring 或 object可选指定模型必须输出的格式。与 GPT-4o、GPT-4 Turbo 以及所有 GPT-3.5 Turbo 模型兼容。从 gpt-3.5-turbo-1106 开始。将其设置为 { "type": "json_object" } 可启用 JSON 模式，这保证模型生成的消息是有效的 JSON。

返回值

一个 assistant 对象。

示例请求

curl

curl "https://api.openai.com/v1/assistants" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -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"
  }'

示例响应

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

创建助手文件 (v1)

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

功能说明

通过附加一个 文件 来为一个 助手 创建一个助手文件。

路径参数

参数名称类型是否必需描述
assistant_idstring必需要为其创建文件的助手的 ID。

请求体

参数名称类型是否必需描述
file_idstring必需一个 文件 ID (带有 purpose="assistants") 供助手使用。对于像 retrieval 和 code_interpreter 这样可以访问文件的工具很有用。

返回值

一个 助手文件 对象。

示例请求

curl https://api.openai.com/v1/assistants/asst_abc123/files \
    -H 'Authorization: Bearer $OPENAI_API_KEY"' \
    -H 'Content-Type: application/json' \
    -H 'OpenAI-Beta: assistants=v1' \
    -d '{
      "file_id": "file-abc123"
    }'

示例响应

{
  "id": "file-abc123",
  "object": "assistant.file",
  "created_at": 1699055364,
  "assistant_id": "asst_abc123"
}

列出助手 (v1)

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

功能说明

返回一个助手列表。

查询参数

参数名称类型是否必需默认值描述
limitinteger可选20要返回的对象数量限制。限制范围是 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=v1"

示例响应

{
  "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": [],
      "file_ids": [],
      "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": [],
      "file_ids": [],
      "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": [],
      "file_ids": [],
      "metadata": {},
      "top_p": 1.0,
      "temperature": 1.0,
      "response_format": "auto"
    }
  ],
  "first_id": "asst_abc123",
  "last_id": "asst_abc789",
  "has_more": false
}

列出助手文件 (v1)

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

功能说明

返回一个助手文件列表。

路径参数

参数名称类型是否必需描述
assistant_idstring必需文件所属的助手的 ID。

查询参数

参数名称类型是否必需默认值描述
limitinteger可选20要返回的对象数量限制。限制范围是 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/asst_abc123/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v1"

示例响应

{
  "object": "list",
  "data": [
    {
      "id": "file-abc123",
      "object": "assistant.file",
      "created_at": 1699060412,
      "assistant_id": "asst_abc123"
    },
    {
      "id": "file-abc456",
      "object": "assistant.file",
      "created_at": 1699060412,
      "assistant_id": "asst_abc123"
    }
  ],
  "first_id": "file-abc123",
  "last_id": "file-abc456",
  "has_more": false
}

获取助手 (v1)

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

功能说明

获取一个指定 ID 的助手。

路径参数

参数名称类型是否必需描述
assistant_idstring必需要获取的助手的 ID。

返回值

与指定 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=v1"

示例响应

{
  "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": "retrieval"
    }
  ],
  "file_ids": [
    "file-abc123"
  ],
  "metadata": {}
}

获取助手文件 (v1)

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

功能说明

获取一个指定 ID 的助手文件。

路径参数

参数名称类型是否必需描述
assistant_idstring必需文件所属的助手的 ID。
file_idstring必需要获取的文件的 ID。

返回值

与指定 ID 匹配的 助手文件 对象。

示例请求

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

示例响应

{
  "id": "file-abc123",
  "object": "assistant.file",
  "created_at": 1699055364,
  "assistant_id": "asst_abc123"
}

修改助手 (v1)

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

功能说明

修改一个助手。

路径参数

参数名称类型是否必需描述
assistant_idstring必需要修改的助手的 ID。

请求体

参数名称类型是否必需默认值描述
modelstring可选-要使用的模型 ID。你可以使用 列出模型 API 查看所有可用的模型，或查看我们的 模型概览 了解它们的描述。
namestring or null可选-助手的名称。最大长度为 256 个字符。
descriptionstring or null可选-助手的描述。最大长度为 512 个字符。
instructionsstring or null可选-助手使用的系统说明。最大长度为 256,000 个字符。
toolsarray可选[]助手启用的工具列表。每个助手最多可以有 128 个工具。工具类型可以是 code_interpreter、retrieval 或 function。
file_idsarray可选[]附加到此助手的 文件 ID 列表。每个助手最多可以有 20 个附加文件。文件按创建日期以升序排列。如果某个文件之前附加到列表但不在列表中显示，它将从助手中删除。
metadatamap可选-一组最多 16 个键值对,可以附加到对象上。这对于以结构化格式存储有关对象的附加信息很有用。键最大长度为 64 个字符,值最大长度为 512 个字符。
temperaturenumber or null可选1要使用的采样温度,介于 0 到 2 之间。较高的值(如 0.8)会使输出更加随机,而较低的值(如 0.2)会使其更加集中和确定性。
top_pnumber or null可选1一种替代温度采样的方法,称为核心采样,即模型仅考虑 top_p 概率质量的结果标记。所以 0.1 意味着只考虑前 10% 概率质量的标记。我们一般建议改变这个或温度,但不要同时改变。
response_formatstring or object可选-指定模型必须输出的格式。与 GPT-4o、GPT-4 Turbo 和所有 GPT-3.5 Turbo 模型(自 gpt-3.5-turbo-1106 起)兼容。设置为 { "type": "json_object" } 可启用 JSON 模式,这样可以保证生成的消息是有效的 JSON。重要的是,在使用 JSON 模式时,你 必须 自己通过系统或用户消息指示模型输出 JSON。否则,模型可能会生成一个无休止的空白流,直到生成达到令牌限制,导致请求长时间运行和"卡住"。另请注意,如果 finish_reason="length",则消息内容可能会被部分截断,这表示生成超过了 max_tokens 或对话超过了最大上下文长度。

返回值

修改后的 助手 对象。

示例请求

curl https://api.openai.com/v1/assistants/asst_abc123 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v1" \
  -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": "retrieval"}],
      "model": "gpt-4-turbo",
      "file_ids": ["file-abc123", "file-abc456"]
    }'

示例响应

{
  "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. Always response with info from either of the files.",
  "tools": [
    {
      "type": "retrieval"
    }
  ],
  "file_ids": [
    "file-abc123",
    "file-abc456"
  ],
  "metadata": {},
  "top_p": 1.0,
  "temperature": 1.0,
  "response_format": "auto"
}

删除助手 (v1)

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=v1" \
  -X DELETE

示例响应

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

删除助手文件 (v1)

DELETE https://api.openai.com/v1/assistants/{assistant_id}/files/{file_id}

功能说明

删除一个助手文件。

路径参数

参数名称类型是否必需描述
assistant_idstring必需文件所属的助手的 ID。
file_idstring必需要删除的文件的 ID。

返回值

删除状态

示例请求

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

示例响应

{
  id: "file-abc123",
  object: "assistant.file.deleted",
  deleted: true
}

助手对象 (v1)

表示一个可以调用模型和使用工具的 assistant。

参数名称类型描述
idstring可在 API 端点中引用的标识符。
objectstring对象类型,始终为 assistant。
created_atinteger创建助手的 Unix 时间戳(秒)。
namestring or null助手的名称。最大长度为 256 个字符。
descriptionstring or null助手的描述。最大长度为 512 个字符。
modelstring要使用的模型 ID。你可以使用 列出模型 API 查看所有可用的模型,或查看我们的 模型概览 了解它们的描述。
instructionsstring or null助手使用的系统说明。最大长度为 256,000 个字符。
toolsarray启用的工具列表。每个助手最多可以有 128 个工具。工具类型可以是 code_interpreter、retrieval 或 function。
file_idsarray附加到此助手的 文件 ID 列表。每个助手最多可以有 20 个附加文件。文件按创建日期以升序排列。
metadatamap一组最多 16 个键值对,可以附加到对象上。这对于以结构化格式存储有关对象的附加信息很有用。键最大长度为 64 个字符,值最大长度为 512 个字符。
temperaturenumber or null要使用的采样温度,介于 0 到 2 之间。较高的值(如 0.8)会使输出更加随机,而较低的值(如 0.2)会使其更加集中和确定性。
top_pnumber or null一种替代温度采样的方法,称为核心采样,即模型仅考虑 top_p 概率质量的结果标记。所以 0.1 意味着只考虑前 10% 概率质量的标记。我们一般建议改变这个或温度,但不要同时改变。
response_formatstring or object指定模型必须输出的格式。与 GPT-4o、GPT-4 Turbo 和所有 GPT-3.5 Turbo 模型(自 gpt-3.5-turbo-1106 起)兼容。设置为 { "type": "json_object" } 可启用 JSON 模式,这样可以保证生成的消息是有效的 JSON。重要的是,在使用 JSON 模式时,你 必须 自己通过系统或用户消息指示模型输出 JSON。否则,模型可能会生成一个无休止的空白流,直到生成达到令牌限制,导致请求长时间运行和"卡住"。另请注意,如果 finish_reason="length",则消息内容可能会被部分截断,这表示生成超过了 max_tokens 或对话超过了最大上下文长度。

示例:

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

助手文件对象 (v1)

附加到 assistant 的 文件 列表。

参数名称类型描述
idstring可在 API 端点中引用的标识符。
objectstring对象类型,始终为 assistant.file。
created_atinteger创建助手文件的 Unix 时间戳(秒)。
assistant_idstring文件附加到的助手 ID。

示例:

{
  "id": "file-abc123",
  "object": "assistant.file",
  "created_at": 1699055364,
  "assistant_id": "asst_abc123"
}

Was this page helpful?