流式事件允许您通过服务器发送事件 (SSE) 增量呈现聊天响应。当您以 stream: true 调用 POST /api/v1/chat 时，服务器会发出一系列您可以消费的命名事件。这些事件按顺序到达，可能包含多个增量（用于推理和消息内容）、工具调用边界和有效负载，以及遇到的任何错误。流始终以 chat.start 开头，并以 chat.end 结束，后者包含与非流式响应等效的聚合结果。

/api/v1/chat 响应流中可发送的事件类型列表

chat.start
model_load.start
model_load.progress
model_load.end
prompt_processing.start
prompt_processing.progress
prompt_processing.end
reasoning.start
reasoning.delta
reasoning.end
tool_call.start
tool_call.arguments
tool_call.success
tool_call.failure
message.start
message.delta
message.end
error
chat.end

事件将以下列原始格式流式输出

event: <event type>
data: <JSON event data>

`chat.start`

在聊天响应流开始时发出的事件。

model_instance_id : string

将生成响应的已加载模型实例的唯一标识符。

type : "chat.start"

事件类型。始终为 chat.start。

示例事件数据

{
  "type": "chat.start",
  "model_instance_id": "openai/gpt-oss-20b"
}

`model_load.start`

表示开始加载模型以满足聊天请求。如果请求的模型已加载，则不会发出此事件。

model_instance_id : string

正在加载的模型实例的唯一标识符。

type : "model_load.start"

事件类型。始终为 model_load.start。

示例事件数据

{
  "type": "model_load.start",
  "model_instance_id": "openai/gpt-oss-20b"
}

`model_load.progress`

模型加载进度。

model_instance_id : string

正在加载的模型实例的唯一标识符。

progress : number

模型加载进度，为 0 到 1 之间的浮点数。

type : "model_load.progress"

事件类型。始终为 model_load.progress。

示例事件数据

{
  "type": "model_load.progress",
  "model_instance_id": "openai/gpt-oss-20b",
  "progress": 0.65
}

`model_load.end`

表示模型加载成功完成。

model_instance_id : string

已加载模型实例的唯一标识符。

load_time_seconds : number

加载模型所用的时间（秒）。

type : "model_load.end"

事件类型。始终为 model_load.end。

示例事件数据

{
  "type": "model_load.end",
  "model_instance_id": "openai/gpt-oss-20b",
  "load_time_seconds": 12.34
}

`prompt_processing.start`

表示模型开始处理提示词 (Prompt)。

type : "prompt_processing.start"

事件类型。始终为 prompt_processing.start。

示例事件数据

{
  "type": "prompt_processing.start"
}

`prompt_processing.progress`

模型处理提示词的进度。

progress : number

提示词处理进度，为 0 到 1 之间的浮点数。

type : "prompt_processing.progress"

事件类型。始终为 prompt_processing.progress。

示例事件数据

{
  "type": "prompt_processing.progress",
  "progress": 0.5
}

`prompt_processing.end`

表示模型处理提示词结束。

type : "prompt_processing.end"

事件类型。始终为 prompt_processing.end。

示例事件数据

{
  "type": "prompt_processing.end"
}

`reasoning.start`

表示模型开始流式输出推理内容。

type : "reasoning.start"

事件类型。始终为 reasoning.start。

示例事件数据

{
  "type": "reasoning.start"
}

`reasoning.delta`

一段推理内容。可能会有多个增量到达。

content : string

推理文本片段。

type : "reasoning.delta"

事件类型。始终为 reasoning.delta。

示例事件数据

{
  "type": "reasoning.delta",
  "content": "Need to"
}

`reasoning.end`

表示推理流结束。

type : "reasoning.end"

事件类型。始终为 reasoning.end。

示例事件数据

{
  "type": "reasoning.end"
}

`tool_call.start`

当模型开始调用工具时发出。

tool : string

正在调用的工具名称。

provider_info : object

有关工具提供者的信息。基于可能的提供者类型的区分联合。

Plugin provider info : object

当工具由插件提供时出现。

type : "plugin"

提供者类型。

plugin_id : string

插件标识符。

Ephemeral MCP provider info : object

当工具由临时 MCP 服务器提供时出现。

type : "ephemeral_mcp"

提供者类型。

server_label : string

MCP 服务器标签。

type : "tool_call.start"

事件类型。始终为 tool_call.start。

示例事件数据

{
  "type": "tool_call.start",
  "tool": "model_search",
  "provider_info": {
    "type": "ephemeral_mcp",
    "server_label": "huggingface"
  }
}

`tool_call.arguments`

为当前工具调用流式传输的参数。

tool : string

正在调用的工具名称。

arguments : object

传递给工具的参数。根据工具定义，可以包含任何键/值。

provider_info : object

有关工具提供者的信息。基于可能的提供者类型的区分联合。

Plugin provider info : object

当工具由插件提供时出现。

type : "plugin"

提供者类型。

plugin_id : string

插件标识符。

Ephemeral MCP provider info : object

当工具由临时 MCP 服务器提供时出现。

type : "ephemeral_mcp"

提供者类型。

server_label : string

MCP 服务器标签。

type : "tool_call.arguments"

事件类型。始终为 tool_call.arguments。

示例事件数据

{
  "type": "tool_call.arguments",
  "tool": "model_search",
  "arguments": {
    "sort": "trendingScore",
    "limit": 1
  },
  "provider_info": {
    "type": "ephemeral_mcp",
    "server_label": "huggingface"
  }
}

`tool_call.success`

工具调用的结果，以及所使用的参数。

tool : string

所调用工具的名称。

arguments : object

传递给工具的参数。

output : string

原始工具输出字符串。

provider_info : object

有关工具提供者的信息。基于可能的提供者类型的区分联合。

Plugin provider info : object

当工具由插件提供时出现。

type : "plugin"

提供者类型。

plugin_id : string

插件标识符。

Ephemeral MCP provider info : object

当工具由临时 MCP 服务器提供时出现。

type : "ephemeral_mcp"

提供者类型。

server_label : string

MCP 服务器标签。

type : "tool_call.success"

事件类型。始终为 tool_call.success。

示例事件数据

{
  "type": "tool_call.success",
  "tool": "model_search",
  "arguments": {
    "sort": "trendingScore",
    "limit": 1
  },
  "output": "[{\"type\":\"text\",\"text\":\"Showing first 1 models...\"}]",
  "provider_info": {
    "type": "ephemeral_mcp",
    "server_label": "huggingface"
  }
}

`tool_call.failure`

表示工具调用失败。

reason : string

工具调用失败的原因。

metadata : object

关于无效工具调用的元数据。

type : "invalid_name" | "invalid_arguments"

发生的错误类型。

tool_name : string

尝试调用的工具名称。

arguments (可选) : object

传递给工具的参数（仅在 invalid_arguments 错误中存在）。

provider_info (可选) : object

关于工具提供者的信息（仅在 invalid_arguments 错误中存在）。

type : "plugin" | "ephemeral_mcp"

提供者类型。

plugin_id (可选) : string

插件标识符（当 type 为 "plugin" 时）。

server_label (可选) : string

MCP 服务器标签（当 type 为 "ephemeral_mcp" 时）。

type : "tool_call.failure"

事件类型。始终为 tool_call.failure。

示例事件数据

{
  "type": "tool_call.failure",
  "reason": "Cannot find tool with name open_browser.",
  "metadata": {
    "type": "invalid_name",
    "tool_name": "open_browser"
  }
}

`message.start`

表示模型即将流式输出消息。

type : "message.start"

事件类型。始终为 message.start。

示例事件数据

{
  "type": "message.start"
}

`message.delta`

消息内容片段。可能会有多个增量到达。

content : string

消息文本片段。

type : "message.delta"

事件类型。始终为 message.delta。

示例事件数据

{
  "type": "message.delta",
  "content": "The current"
}

`message.end`

表示消息流结束。

type : "message.end"

事件类型。始终为 message.end。

示例事件数据

{
  "type": "message.end"
}

`error`

流式传输期间发生错误。最终有效负载仍将在 chat.end 中发送，包含已生成的内容。

error : object

错误信息。

高级错误类型。

message : string

人类可读的错误消息。

code (可选) : string

更详细的错误代码（例如，验证问题代码）。

param (可选) : string

与错误关联的参数（如果适用）。

type : "error"

事件类型。始终为 error。

示例事件数据

{
  "type": "error",
  "error": {
    "type": "invalid_request",
    "message": "\"model\" is required",
    "code": "missing_required_parameter",
    "param": "model"
  }
}

`chat.end`

包含完整聚合响应的最终事件，等效于非流式 POST /api/v1/chat 响应主体。

result : object

最终响应，包含 model_instance_id、output、stats 以及可选的 response_id。更多详细信息，请参阅非流式聊天文档。

type : "chat.end"

事件类型。始终为 chat.end。

示例事件数据

{
  "type": "chat.end",
  "result": {
    "model_instance_id": "openai/gpt-oss-20b",
    "output": [
      { "type": "reasoning", "content": "Need to call function." },
      {
        "type": "tool_call",
        "tool": "model_search",
        "arguments": { "sort": "trendingScore", "limit": 1 },
        "output": "[{\"type\":\"text\",\"text\":\"Showing first 1 models...\"}]",
        "provider_info": { "type": "ephemeral_mcp", "server_label": "huggingface" }
      },
      { "type": "message", "content": "The current top‑trending model is..." }
    ],
    "stats": {
      "input_tokens": 329,
      "total_output_tokens": 268,
      "reasoning_output_tokens": 5,
      "tokens_per_second": 43.73,
      "time_to_first_token_seconds": 0.781
    },
    "response_id": "resp_02b2017dbc06c12bfc353a2ed6c2b802f8cc682884bb5716"
  }
}