Nimi

中文

English

中文

English

深色模式

流式 ​

流式不只是文字渐渐到达。Runtime 流式合同定义了四种类型化模式、终止帧、backpressure、fail-close 语义。App 把流看作权威事件时间线，不是任意 chunk 汤。

四种流式模式 ​

模式载什么关闭语义
Mode A文本与语音生成；chunk 直到终止显式 done=true 终止帧
Mode B状态事件流（工作流事件、状态更新）终态状态后关闭
Mode C审计导出eof 标记后关闭
Mode D长存订阅（健康、App 间消息、实时事件）长存；只在 session 拆除时关闭

每种模式有显式关闭语义。消费 Mode A 流的 App 等 done=true；消费 Mode B 流的 App 等终态状态。流的模式是被声明的；App 不必猜。

终止帧 ​

没有准入的终止信号就结束的流是合同违规。Runtime 发类型化失败终止，不是静默截断。

模式终止信号
Mode Adone=true 帧
Mode B终态状态事件
Mode Ceof 标记
Mode Dsession 拆除

如果 Provider 中途让合同失败 — 形状错、缺必填字段、schema 违规 — 流式合同发类型化失败终止帧。工作流搬到 FAILED。没有静默截断。

Backpressure ​

流式有端到端 backpressure。预算从生产方共享到消费方；慢消费方对上游施压，而不是丢帧。

性质值
预算按流
方向生产方 → 消费方
溢出App 通过 SDK 看到 backpressure；Runtime 不静默丢

长生成时这点重要。用户 30 秒不在 chat 窗口里打字；消费方施压；生产方暂停。消费方恢复后，流继续。没有帧丢失。

Fail-close 语义 ​

流式合同失败 fail-close：

失败类型行为
帧形状错类型化失败终止；工作流 FAILED
缺必填字段类型化失败终止
Schema 违规类型化失败终止
MIME 不匹配类型化失败终止
瞬时 transport 错误按 transport 策略重试；可恢复则流继续
需要 auth 刷新按 auth 策略刷新；可恢复则流继续

重试只救 transport 级失败。它不救合同失败。Schema 违规是合同失败、fail-close；它不会被重试救成成功。

阅读场景：Mode A 文本流式 ​

App 发起一个流式文本生成。

  1. 流打开。 Mode A。Runtime 开始发文本 chunk。
  2. Chunk 到达。 每条 chunk 是类型化形状。App 增量渲染。
  3. Provider 抖动。 瞬时 transport 错。Runtime 按 transport 策略重试。流从合适边界恢复。
  4. Provider 返回内容。 流继续。
  5. 生成完成。 Runtime 发 done=true 终止帧。
  6. App 标记响应完成。 用户可以进入下一轮。

没发生：流从未静默截断。要么走到 done=true，要么发了类型化失败。

阅读场景：Mode B 工作流事件流 ​

App 订阅一个工作流的事件流。

  1. 流打开。 Mode B。Runtime 开始发工作流事件。
  2. 事件到达。 STARTED → NODE_STARTED → NODE_PROGRESS → NODE_COMPLETED → ...
  3. 工作流到终态。 Runtime 发终态状态事件（COMPLETED / FAILED / CANCELED / SKIPPED）。
  4. 流关闭。 Mode B 关闭语义满足。

App UI 随事件到达增量更新。无 polling；事件流就是「这个工作流现在怎么样」的真相来源。

阅读场景：慢消费方触发 backpressure ​

App 在消费一段长 Mode A 流。用户打开了一个重 modal，渲染暂停。

  1. 消费方变慢。 App chunk 处理速率下降。
  2. backpressure 应用。 SDK 流消费方向上游发 backpressure 信号。
  3. 生产方暂停。 Runtime 按预算暂停 Provider 流消费。
  4. 用户关 modal。 消费方恢复。
  5. 生产方恢复。 流从合适边界继续。

没帧丢。没有队列无限增长。Backpressure 端到端。

来源 ​

Nimi AI open world platform documentation.

Copyright 2026-present Nimi Platform