OpenAI CTO

运行 (Beta)

表示线程上的执行运行。

相关指南：Assistants

注意：这是一个 Beta 版本的 API，可能会在未经通知的情况下发生变化。

创建运行

请求路径

POST https://api.openai.com/v1/threads/{thread_id}/runs

简介

创建一个运行。

路径参数

  • thread_id (string)：必需。要运行的线程的ID。

请求体

  • assistant_id (string)：必需。用于执行此运行的助手的ID。
  • model (string)：可选。用于执行此运行的模型的ID。如果在此处提供了值，则会覆盖与助手关联的模型。如果没有，则使用与助手关联的模型。
  • instructions (string或null)：可选。覆盖助手的指令。这对于在每次运行的基础上修改行为很有用。
  • additional_instructions (string或null)：可选。在运行的指令末尾追加额外的指令。这对于在不覆盖其他指令的情况下修改行为很有用。
  • additional_messages (array或null)：可选。在创建运行之前向线程添加额外的消息。
  • tools (array或null)：可选。覆盖此运行中助手可以使用的工具。这对于在每次运行的基础上修改行为很有用。
  • metadata (map)：可选。可以附加到对象的16对键值对。这对于以结构化格式存储有关对象的额外信息很有用。键最长可以是64个字符，值最长可以是512个字符。
  • temperature (number或null)：可选，默认为1。使用的采样温度，范围在0到2之间。较高的值（如0.8）将使输出更随机，而较低的值（如0.2）将使其更集中和确定。
  • top_p (number或null)：可选，默认为1。一种替代温度采样的方法，称为核心采样，模型考虑了top_p概率质量的结果。因此0.1意味着只考虑组成前10%概率质量的标记。
  • stream (boolean或null)：可选。如果为true，返回在运行期间发生的事件的流，作为服务器发送的事件，当运行进入终端状态时以data: [DONE]消息终止。
  • max_prompt_tokens (integer或null)：可选。在运行过程中可能使用的最大提示标记数。运行将尽最大努力只使用指定的提示标记数，在运行的多个转换中。如果运行超过了指定的提示标记数，运行将以incomplete状态结束。
  • max_completion_tokens (integer或null)：可选。在运行过程中可能使用的最大完成标记数。运行将尽最大努力只使用指定的完成标记数，在运行的多个转换中。如果运行超过了指定的完成标记数，运行将以incomplete状态结束。
  • truncation_strategy (object)：可选。控制在运行之前如何截断线程。使用此选项来控制运行的初始上下文窗口。
  • tool_choice (string或object)：可选。控制模型调用哪个（如果有的话）工具。none表示模型不会调用任何工具，而是生成一条消息。auto是默认值，表示模型可以选择生成消息或调用一个或多个工具。required表示模型必须在响应用户之前调用一个或多个工具。指定特定工具如{"type": "file_search"}或{"type": "function", "function": {"name": "my_function"}}会强制模型

调用该工具。

  • response_format (string或object)：可选。指定模型必须输出的格式。与GPT-4o、GPT-4 Turbo和所有GPT-3.5 Turbo模型兼容，自gpt-3.5-turbo-1106起。设置为{"type": "json_object"}启用JSON模式，这保证模型生成的消息是有效的JSON。

返回

返回一个run对象。

示例请求

curl https://api.openai.com/v1/threads/thread_abc123/runs \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
    "assistant_id": "asst_abc123"
  }'

响应

{
  "id": "run_abc123",
  "object": "thread.run",
  "created_at": 1699063290,
  "assistant_id": "asst_abc123",
  "thread_id": "thread_abc123",
  "status": "queued",
  "started_at": 1699063290,
  "expires_at": null,
  "cancelled_at": null,
  "failed_at": null,
  "completed_at": 1699063291,
  "last_error": null,
  "model": "gpt-4-turbo",
  "instructions": null,
  "incomplete_details": null,
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "metadata": {},
  "usage": null,
  "temperature": 1.0,
  "top_p": 1.0,
  "max_prompt_tokens": 1000,
  "max_completion_tokens": 1000,
  "truncation_strategy": {
    "type": "auto",
    "last_messages": null
  },
  "response_format": "auto",
  "tool_choice": "auto"
}

创建线程并运行

请求

POST https://api.openai.com/v1/threads/runs

在一个请求中创建线程并运行它。

请求体参数

assistant_id (必需)

  • 类型: 字符串

你要使用的 助手 的 ID 来执行此运行。

thread (可选)

  • 类型: 对象

thread.messages

  • 类型: 消息对象数组
  • 描述: 线程消息历史。每个消息对象应该有一个 role 属性("user" 或 "assistant")和一个 content 属性。

model (可选)

  • 类型: 字符串
  • 描述: 要用于执行此运行的 模型 的 ID。如果在这里提供了一个值，它将覆盖与助手关联的模型。如果没有，将使用与助手关联的模型。

instructions (可选)

  • 类型: 字符串或 null
  • 描述: 覆盖助手的默认系统消息。这对于在每次运行的基础上修改行为很有用。

tools (可选)

  • 类型: 数组或 null
  • 描述: 覆盖助手在此运行中可以使用的工具。这对于在每次运行的基础上修改行为很有用。

tool_resources (可选)

  • 类型: 对象或 null
  • 描述: 助手工具所使用的一组资源。资源是特定于工具类型的。例如，code_interpreter 工具需要一个文件 ID 列表，而 file_search 工具需要一个向量存储 ID 列表。

metadata (可选)

  • 类型: map
  • 描述: 可以附加到对象上的 16 个键值对集合。这可以用于以结构化的格式存储有关该对象的其他信息。键最多可以是 64 个字符长,值最多可以是 512 个字符长。

temperature (可选,默认为 1)

  • 类型: 数字或 null
  • 描述: 采样的温度,介于 0 到 2 之间。较高的值(如 0.8)会使输出更加随机,而较低的值(如 0.2)会使其更加集中和确定性。

top_p (可选,默认为 1)

  • 类型: 数字或 null
  • 描述: 一种替代温度采样的方法,称为 nucleus sampling,模型考虑概率质量前 top_p 的标记结果。所以 0.1 表示只考虑包含前 10% 概率质量的标记。我们通常建议修改这个或温度,但不要同时修改两者。

stream (可选)

  • 类型: 布尔值或 null
  • 描述: 如果为 true,则以服务器发送事件的形式返回在运行期间发生的事件流,当运行进入终止状态时以 data: [DONE] 消息终止。

max_prompt_tokens (可选)

  • 类型: 整数或 null
  • 描述: 在运行过程中可能使用的最大提示标记数。运行将尽最大努力在多次交互过程中仅使用指定的提示标记数。如果运行超过了指定的提示标记数,运行将以状态 incomplete 结束。有关更多信息,请参阅 incomplete_details。

max_completion_tokens (可选)

  • 类型: 整数或 null
  • 描述: 在运行过程中可能使用的最大完成标记数。运行将尽最大努力在多次交互过程中仅使用指定的完成标记数。如果运行超过了指定的完成标记数,运行将以状态 incomplete 结束。有关更多信息,请参阅 incomplete_details。

truncation_strategy (可选)

  • 类型: 对象
  • 描述: 控制在运行之前线程将如何被截断。用于控制运行的初始上下文窗口。

tool_choice (可选)

  • 类型: 字符串或对象
  • 描述: 控制模型是否调用工具以及调用哪个工具。
    • none 表示模型不会调用任何工具,而是生成一条消息。
    • auto(默认值)表示模型可以在生成消息或调用一个或多个工具之间进行选择。
    • required 表示模型必须在响应用户之前调用一个或多个工具。
    • 指定特定工具(如 {"type": "file_search"} 或 {"type": "function","function": {"name": "my_function"}})会强制模型调用该工具。

response_format (可选)

  • 类型: 字符串或对象
  • 描述: 指定模型必须输出的格式。兼容 GPT-4o, GPT-4 Turbo 和自 gpt-3.5-turbo-1106 以来的所有 GPT-3.5 Turbo 模型。

将其设置为 { "type": "json_object" } 会启用 JSON 模式,此模式保证模型生成的消息是有效的 JSON。

重要提示: 当使用 JSON 模式时,您必须通过系统消息或用户消息自行指示模型产生 JSON。如果不这样做,模型可能会生成一个无止境的空格流,直到生成达到标记限制,从而导致一个长时间运行且看似"卡住"的请求。另请注意,如果 finish_reason="length"(表示生成超过了 max_tokens 或对话超过了最大上下文长度),则消息内容可能会被部分截断。

返回值

返回一个 run 对象。

示例请求

curl https://api.openai.com/v1/threads/runs \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
      "assistant_id": "asst_abc123",
      "thread": {
        "messages": [
          {"role": "user", "content": "Explain deep learning to a 5 year old."}
        ]
      }
    }'

响应

{
  "id": "run_abc123",
  "object": "thread.run",
  "created_at": 1699076792,
  "assistant_id": "asst_abc123",
  "thread_id": "thread_abc123",
  "status": "queued",
  "started_at": null,
  "expires_at": 1699077392,
  "cancelled_at": null,
  "failed_at": null,
  "completed_at": null,
  "required_action": null,
  "last_error": null,
  "model": "gpt-4-turbo",
  "instructions": "You are a helpful assistant.",
  "tools": [],
  "tool_resources": {},
  "metadata": {},
  "temperature": 1.0,
  "top_p": 1.0,
  "max_completion_tokens": null,
  "max_prompt_tokens": null,
  "truncation_strategy": {
    "type": "auto",
    "last_messages": null
  },
  "incomplete_details": null,
  "usage": null,
  "response_format": "auto",
  "tool_choice": "auto"
}

以下是将提供的代码示例转换为标记语言（markdown）的格式，并将其翻译成中文。

示例请求

curl https://api.openai.com/v1/threads/runs \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
      "assistant_id": "asst_123",
      "thread": {
        "messages": [
          {"role": "user", "content": "Hello"}
        ]
      },
      "stream": true
    }'

响应

请注意，该响应是实时流式传输的，并且包含多个事件。以下是可能的事件序列：

event: thread.created
data: {"id":"thread_123","object":"thread","created_at":1710348075,"metadata":{}}

event: thread.run.created
data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4-turbo","instructions":null,"tools":[],"tool_resources":{},"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto"}

event: thread.run.queued
data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4-turbo","instructions":null,"tools":[],"tool_resources":{},"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto"}

event: thread.run.in_progress
data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4-turbo","instructions":null,"tools":[],"tool_resources":{},"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto"}

event: thread.run.step.created
data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}}},"usage":null}

event: thread.run.step.in_progress
data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}}},"usage":null}

event: thread.message.created
data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}}

event: thread.message.in_progress
data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}}

event: thread.message.delta
data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}}]}}

...

event: thread.message.delta
data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today","annotations":[]}}]}}

event: thread.message.delta
data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?","annotations":[]}}]}}

event: thread.message.completed
data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710348077,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! How can I assist you today?","annotations":[]}}],"metadata":{}}

event: thread.run.step.completed
data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710348077,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}}

event: thread.run.completed
{"id":"run_123","object":"thread.run","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1713226836,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1713226837,"required_action":null,"last_error":null,"model":"gpt-4-turbo","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":345,"completion_tokens":11,"total_tokens":356},"response_format":"auto","tool_choice":"auto"}

event: done
data: [DONE]

# 使用函数进行实时流式处理的示例请求

## 示例请求

```bash
curl https://api.openai.com/v1/threads/runs \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
    "assistant_id": "asst_abc123",
    "thread": {
      "messages": [
        {"role": "user", "content": "What is the weather like in San Francisco?"}
      ]
    },
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "get_current_weather",
          "description": "Get the current weather in a given location",
          "parameters": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string",
                "description": "The city and state, e.g. San Francisco, CA"
              },
              "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"]
              }
            },
            "required": ["location"]
          }
        }
      }
    ],
    "stream": true
  }'

响应

event: thread.created
data: {"id":"thread_123","object":"thread","created_at":1710351818,"metadata":{}}

event: thread.run.created
data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4-turbo","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto"}}

event: thread.run.queued
data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4-turbo","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto"}}

event: thread.run.in_progress
data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710351818,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4-turbo","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto"}}

event: thread.run.step.created
data: {"id":"step_001","object":"thread.run.step","created_at":1710351819,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710352418,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[]},"usage":null}

event: thread.run.step.in_progress
data: {"id":"step_001","object":"thread.run.step","created_at":1710351819,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710352418,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[]},"usage":null}

event: thread.run.step.delta
data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"id":"call_XXNp8YGaFrjrSjgqxtC8JJ1B","type":"function","function":{"name":"get_current_weather","arguments":"","output":null}}]}}}

event: thread.run.step.delta
data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"{\""}}]}}}

event: thread.run.step.delta
data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"location"}}]}}}

...

event: thread.run.step.delta
data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"ahrenheit"}}]}}}

event: thread.run.step.delta
data: {"id":"step_001","object":"thread.run.step.delta","delta":{"step_details":{"type":"tool_calls","tool_calls":[{"index":0,"type":"function","function":{"arguments":"\"}"}}]}}}

event: thread.run.requires_action
data: {"id":"run_123","object":"thread.run","created_at":1710351818,"assistant_id":"asst_123","thread_id":"thread_123","status":"requires_action","started_at":1710351818,"expires_at":1710352418,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":{"type":"submit_tool_outputs","submit_tool_outputs":{"tool_calls":[{"id":"call_XXNp8YGaFrjrSjgqxtC8JJ1B","type":"function","function":{"name":"get_current_weather","arguments":"{\"location\":\"San Francisco, CA\",\"unit\":\"fahrenheit\"}"}}]}},"last_error":null,"model":"gpt-4-turbo","instructions":null,"tools":[{"type":"function","function":{"name":"get_current_weather","description":"Get the current weather in a given location","parameters":{"type":"object","properties":{"location":{"type":"string","description":"The city and state, e.g. San Francisco, CA"},"unit":{"type":"string","enum":["celsius","fahrenheit"]}},"required":["location"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":345,"completion_tokens":11,"total_tokens":356},"response_format":"auto","tool_choice":"auto"}}

event: done
data: [DONE]

列出运行记录

发送请求 /threads/{thread_id}/runs

返回属于某个线程的运行记录列表。

路径参数

  • thread_id (字符串, 必填) - 运行记录所属线程的ID。

查询参数

  • limit (整数, 可选, 默认为20) - 要返回的对象数量限制。限制范围为1到100。
  • order (字符串, 可选, 默认为desc) - 按created_at时间戳对对象进行排序。asc为升序, desc为降序。
  • after (字符串, 可选) - 用于分页的游标。after是一个对象ID,定义了您在列表中的位置。
  • before (字符串, 可选) - 用于分页的游标。before是一个对象ID,定义了您在列表中的位置。

返回

返回一个run对象列表。

示例请求

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

示例响应

{
  "object": "list",
  "data": [
    {
      "id": "run_abc123",
      "object": "thread.run",
      "created_at": 1699075072,
      "assistant_id": "asst_abc123",
      "thread_id": "thread_abc123",
      "status": "completed",
      "started_at": 1699075072,
      "expires_at": null,
      "cancelled_at": null,
      "failed_at": null,
      "completed_at": 1699075073,
      "last_error": null,
      "model": "gpt-4-turbo",
      "instructions": null,
      "incomplete_details": null,
      "tools": [
        {
          "type": "code_interpreter"
        }
      ],
      "tool_resources": {
        "code_interpreter": {
          "file_ids": [
            "file-abc123",
            "file-abc456"
          ]
        }
      },
      "metadata": {},
      "usage": {
        "prompt_tokens": 123,
        "completion_tokens": 456,
        "total_tokens": 579
      },
      "temperature": 1.0,
      "top_p": 1.0,
      "max_prompt_tokens": 1000,
      "max_completion_tokens": 1000,
      "truncation_strategy": {
        "type": "auto",
        "last_messages": null
      },
      "response_format": "auto",
      "tool_choice": "auto"
    },
    {
      "id": "run_abc456",
      "object": "thread.run",
      "created_at": 1699063290,
      "assistant_id": "asst_abc123",
      "thread_id": "thread_abc123",
      "status": "completed",
      "started_at": 1699063290,
      "expires_at": null,
      "cancelled_at": null,
      "failed_at": null,
      "completed_at": 1699063291,
      "last_error": null,
      "model": "gpt-4-turbo",
      "instructions": null,
      "incomplete_details": null,
      "tools": [
        {
          "type": "code_interpreter"
        }
      ],
      "tool_resources": {
        "code_interpreter": {
          "file_ids": [
            "file-abc123",
            "file-abc456"
          ]
        }
      },
      "metadata": {},
      "usage": {
        "prompt_tokens": 123,
        "completion_tokens": 456,
        "total_tokens": 579
      },
      "temperature": 1.0,
      "top_p": 1.0,
      "max_prompt_tokens": 1000,
      "max_completion_tokens": 1000,
      "truncation_strategy": {
        "type": "auto",
        "last_messages": null
      },
      "response_format": "auto",
      "tool_choice": "auto"
    }
  ],
  "first_id": "run_abc123",
  "last_id": "run_abc456",
  "has_more": false
}

检索运行

GET https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}

检索指定线程和运行 ID 的运行。

路径参数

  • thread_id (string, 必需) - 运行所属的线程的 ID。
  • run_id (string, 必需) - 要检索的运行的 ID。

返回值

匹配指定 ID 的运行对象。

示例请求

curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2"

响应

{
  "id": "run_abc123",
  "object": "thread.run",
  "created_at": 1699075072,
  "assistant_id": "asst_abc123",
  "thread_id": "thread_abc123", 
  "status": "completed",
  "started_at": 1699075072,
  "expires_at": null,
  "cancelled_at": null,
  "failed_at": null,
  "completed_at": 1699075073,
  "last_error": null,
  "model": "gpt-4-turbo",
  "instructions": null,
  "incomplete_details": null,
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "metadata": {},
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 456,
    "total_tokens": 579
  },
  "temperature": 1.0,
  "top_p": 1.0,
  "max_prompt_tokens": 1000,
  "max_completion_tokens": 1000,
  "truncation_strategy": {
    "type": "auto",
    "last_messages": null
  },
  "response_format": "auto",
  "tool_choice": "auto"
}

修改运行

POST https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}

修改指定线程和运行ID的运行。

路径参数

  • thread_id (string, 必需) - 运行所属的线程的ID。
  • run_id (string, 必需) - 要修改的运行的ID。

请求体

  • metadata (map, 可选) - 可以附加到对象的最多16个键值对集合。这可用于以结构化格式存储有关对象的其他信息。键最长可为64个字符,值最长可为512个字符。

返回值

匹配指定ID的修改后的运行对象。

示例请求

curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
    "metadata": {
      "user_id": "user_abc123" 
    }
  }'

响应

{
  "id": "run_abc123",
  "object": "thread.run",
  "created_at": 1699075072,
  "assistant_id": "asst_abc123",
  "thread_id": "thread_abc123",
  "status": "completed",
  "started_at": 1699075072,
  "expires_at": null,
  "cancelled_at": null,
  "failed_at": null,
  "completed_at": 1699075073,
  "last_error": null,
  "model": "gpt-4-turbo",
  "instructions": null,
  "incomplete_details": null,
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "tool_resources": {
    "code_interpreter": {
      "file_ids": [
        "file-abc123",
        "file-abc456"
      ]
    }
  },
  "metadata": {
    "user_id": "user_abc123"
  },
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 456,
    "total_tokens": 579
  },
  "temperature": 1.0,
  "top_p": 1.0,
  "max_prompt_tokens": 1000,
  "max_completion_tokens": 1000,
  "truncation_strategy": {
    "type": "auto",
    "last_messages": null
  },
  "response_format": "auto",
  "tool_choice": "auto"
}

提交工具输出到运行

POST https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}/submit_tool_outputs

当运行的status为"requires_action"且required_action.type为submit_tool_outputs时,可使用此端点在所有工具调用完成后提交它们的输出。所有输出必须在一个请求中提交。

路径参数

  • thread_id (string, 必需) - 该运行所属的线程的ID。
  • run_id (string, 必需) - 需要提交工具输出的运行的ID。

请求体

  • tool_outputs (array, 必需) - 提交输出的工具列表。
    • tool_call_id (string) - 工具调用的ID。
    • output (string) - 工具调用的输出。
  • stream (boolean or null, 可选) - 如果为true,则以服务器发送事件的形式返回运行期间发生的事件流,在运行进入终止状态时以data: [DONE]消息终止。

返回值

匹配指定ID的修改后的运行对象。

示例请求

curl https://api.openai.com/v1/threads/thread_123/runs/run_123/submit_tool_outputs \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
    "tool_outputs": [
      {
        "tool_call_id": "call_001",
        "output": "70 degrees and sunny."
      }
    ]
  }'

响应

{
  "id": "run_123",
  "object": "thread.run",
  "created_at": 1699075592,
  "assistant_id": "asst_123",
  "thread_id": "thread_123",
  "status": "queued",
  "started_at": 1699075592,
  "expires_at": 1699076192,
  "cancelled_at": null,
  "failed_at": null,
  "completed_at": null,
  "last_error": null,
  "model": "gpt-4-turbo",
  "instructions": null,
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_current_weather",
        "description": "Get the current weather in a given location",
        "parameters": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            },
            "unit": {
              "type": "string",
              "enum": ["celsius", "fahrenheit"]
            }
          },
          "required": ["location"]
        }
      }
    }
  ],
  "metadata": {},
  "usage": null,
  "temperature": 1.0,
  "top_p": 1.0,
  "max_prompt_tokens": 1000,
  "max_completion_tokens": 1000,
  "truncation_strategy": {
    "type": "auto",
    "last_messages": null
  },
  "response_format": "auto",
  "tool_choice": "auto"
}

取消运行

Beta

POST https://api.openai.com/v1/threads/{thread_id}/runs/{run_id}/cancel

取消一个状态为 in_progress 的运行。

路径参数

  • thread_id (string, 必需): 该运行所属的线程 ID。
  • run_id (string, 必需): 要取消的运行 ID。

返回值

返回修改后的与指定 ID 匹配的 run 对象。

请求示例

curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/cancel \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2" \
  -X POST

响应示例

{
  "id": "run_abc123",
  "object": "thread.run",
  "created_at": 1699076126,
  "assistant_id": "asst_abc123",
  "thread_id": "thread_abc123",
  "status": "cancelling",
  "started_at": 1699076126,
  "expires_at": 1699076726,
  "cancelled_at": null,
  "failed_at": null,
  "completed_at": null,
  "last_error": null,
  "model": "gpt-4-turbo",
  "instructions": "You summarize books.",
  "tools": [
    {
      "type": "file_search"
    }
  ],
  "tool_resources": {
    "file_search": {
      "vector_store_ids": ["vs_123"]
    }
  },
  "metadata": {},
  "usage": null,
  "temperature": 1.0,
  "top_p": 1.0,
  "response_format": "auto"
}

运行对象

表示在一个线程上执行的运行。

属性

  • id (string): 标识符，可在 API 端点中引用。
  • object (string): 对象类型，总是 thread.run。
  • created_at (integer): 运行创建时的 Unix 时间戳（以秒为单位）。
  • assistant_id (string): 执行此运行所用的助手 ID。
  • thread_id (string): 此运行所属的线程 ID。
  • status (string): 运行的状态，可以是 queued、in_progress、requires_action、cancelling、cancelled、failed、completed、incomplete 或 expired。
  • required_action (object or null): 继续运行所需的操作详情。如果不需要操作，则为 null。
  • last_error (object or null): 与此运行关联的最后一个错误。如果没有错误，则为 null。
  • expires_at (integer or null): 运行过期时的 Unix 时间戳（以秒为单位）。
  • started_at (integer or null): 运行开始时的 Unix 时间戳（以秒为单位）。
  • cancelled_at (integer or null): 运行取消时的 Unix 时间戳（以秒为单位）。
  • failed_at (integer or null): 运行失败时的 Unix 时间戳（以秒为单位）。
  • completed_at (integer or null): 运行完成时的 Unix 时间戳（以秒为单位）。
  • incomplete_details (object or null): 运行不完整的原因详情。如果运行不不完整，则为 null。
  • model (string): 此运行中助手使用的模型。
  • instructions (string): 此运行中助手使用的指令。
  • tools (array): 此运行中助手使用的工具列表。
  • metadata (map): 可附加到对象的一组 16 个键值对。对于以结构化格式存储对象的附加信息很有用。键的最大长度为 64 个字符，值的最大长度为 512 个字符。
  • usage (object or null): 与运行相关的使用统计数据。如果运行不在终止状态（例如 in_progress、queued 等），则此值为 null。
  • temperature (number or null): 此运行使用的采样温度。如果未设置，则默认为 1。
  • top_p (number or null): 此运行使用的 nucleus 采样值。如果未设置，则默认为 1。
  • max_prompt_tokens (integer or null): 在运行过程中指定使用的最大提示令牌数量。
  • max_completion_tokens (integer or null): 在运行过程中指定使用的最大完成令牌数量。
  • truncation_strategy (object): 控制线程在运行前的截断方式。用于控制运行的初始上下文窗口。
  • tool_choice (string or object): 控制模型调用的工具类型。可以是 none（模型不会调用任何工具而是生成消息）、auto（默认值，模型可以在生成消息或调用一个或多个工具之间选择）、required（模型必须在响应用户之前调用一个或多个工具）或特定工具（例如 {"type": "file_search"} 或 {"type": "function", "function": {"name": "my_function"}}）。
  • response_format (string or object): 指定模型必须输出的格式。与 GPT-4o、GPT-4 Turbo 以及所有 GPT-3.5 Turbo 模型（从 gpt-3.5-turbo-1106 开始）兼容。设置为 {"type": "json_object"} 启用 JSON 模式，确保模型生成的消息是有效的 JSON。

示例

{
  "id": "run_abc123",
  "object": "thread.run",
  "created_at": 1698107661,
  "assistant_id": "asst_abc123",
  "thread_id": "thread_abc123",
  "status": "completed",
  "started_at": 1699073476,
  "expires_at": null,
  "cancelled_at": null,
  "failed_at": null,
  "completed_at": 1699073498,
  "last_error": null,
  "model": "gpt-4-turbo",
  "instructions": null,
  "tools": [{"type": "file_search"}, {"type": "code_interpreter"}],
  "metadata": {},
  "incomplete_details": null,
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 456,
    "total_tokens": 579
  },
  "temperature": 1.0,
  "top_p": 1.0,
  "max_prompt_tokens": 1000,
  "max_completion_tokens": 1000,
  "truncation_strategy": {
    "type": "auto",
    "last_messages": null
  },
  "response_format": "auto",
  "tool_choice": "auto"
}

Was this page helpful?