Caspian流式回复完整指南:用 thread.stream() 实现打字机效果实时更新

原创2026-10-22 23:42:321,971 阅读

Caspian流式回复完整指南:用 thread.stream() 实现打字机效果实时更新

Caspian 是面向 AI 智能体的开源通信 SDK,支持 Telegram、Slack、Discord、邮件、WhatsApp、SMS 等渠道。本教程讲一个很实用的功能:流式回复(streaming reply)——用一行 thread.stream(),让机器人的长回答像打字机一样边生成边显示,而不是干等几十秒才收到一整段消息。

Caspian 开源智能体通信 SDK,让 AI 智能体在每个渠道拥有统一身份

为什么需要流式回复

传统机器人的模式是"收消息 → 思考很久 → 发完整回复"。当回答是一段长文(比如让 AI 总结文档、写邮件、讲故事)时,用户体验会很差:

  • 用户盯着屏幕干等,不知道机器人卡没卡;
  • 消息越长等待越久,中途无法看到任何进展。

流式回复把体验反了过来:先发出第一条消息,之后每生成一段文字就编辑(edit)这条消息,用户看到文字"自己长出来",就像 ChatGPT 网页版的效果。

Caspian 智能体在邮件渠道进行线程回复的示例截图

thread.stream() 工作原理

Python SDK 中,stream() 定义在 handler 拿到的 Thread 对象上:

def stream(self, *, min_chars: int = 24, throttle: float = 0.5) -> Stream:

它的内部逻辑非常清晰(见 Stream 类实现):

  1. 首次 flush 时发一条 Post,并记下返回的 message_id;
  2. 后续每次 flush 都发 Edit,用同一 message_id 更新那条消息的全文;
  3. close() 时兜底:无论之前发过几次,最后一定会把完整文本发出去。

两个参数控制"发送节奏":

参数 默认值 作用
min_chars 24 新增文字累计到这么多字符才值得发一次,避免频繁调用
throttle 0.5 两次编辑之间的最小间隔(秒),防止触发平台限流

还有一个关键属性 live:当运行时具备实时发送能力(有 transport 且渠道支持编辑消息)时为 True,表示真正边写边发;否则 Stream 会自动降级为缓冲模式——攒够全文,在 close() 时一次性 post()。这一点在 StreamSink 端口定义 中有说明:你的 handler 代码不需要为"能不能流式"写任何分支,SDK 自动处理。

三步开启打字机效果(Python)

第 1 步:注册 handler,声明 overlap: "stream"

@cx.on_message({"channel": "telegram", "overlap": "stream"})
def stream_story(thread, msg, ctx):
    with thread.stream(min_chars=1, throttle=0.25) as out:
        for chunk in llm_stream:        # 任意 chunk 来源
            out.append(chunk)

overlap 是同一会话里新消息到达时的并发策略,stream 表示"边流边并行",与打字机效果是绝配。策略状态机实现在 overlap.py。

第 2 步:用 with 上下文管理器

这是官方推荐写法。with 退出时自动调用 close(),保证最终全文一定发出——即使中途抛异常也不会留下半截消息。

第 3 步:逐块 append

每个 chunk 进来后 SDK 自行判断:够 min_chars 且距上次 flush 超过 throttle 秒,才真正发一次 Edit。快模型每 token 一个 chunk 也不会被限流。

调参速查:让打字节奏更自然

  • min_chars=1、throttle=0.25:最快的视觉节奏,适合演示(官方 Telegram 示例 就用的这组参数);
  • 默认 min_chars=24, throttle=0.5:适合生产,省配额;
  • throttle=0:关闭节流(不建议,容易撞平台编辑频率限制)。

测试文件 test_streaming.py 验证了完整行为:一次 sendMessage 首发 + 多次 editMessageText,且最终文本完整。

TypeScript 版:同一套契约

TypeScript SDK 提供 camelCase 版本的同一 API(thread.ts 中 stream 定义):

const out = thread.stream({ minChars: 1, throttle: 0.25 })
for (const chunk of story) {
  await out.append(chunk)
}
await out.close()

TS 没有上下文管理器,所以要显式 await out.close() 兜底。对照示例见 examples/telegram-ts/app.ts。

常见问题

问:我的渠道不支持编辑消息,流式还有用吗? 有。live 为 False 时自动降级为缓冲 + 一次 Post,回复照常送达,代码零改动(见 降级测试)。

问:流式消息和 thread.typing() 什么关系? typing() 发的是"对方正在输入…"指示器,适合短思考;流式回复是真实文本的持续更新,适合长回答。二者可配合使用。

问:支持哪些渠道? 任何支持"编辑已发消息"的渠道都能真正流式,例如 Telegram(webhook 或 poll)、Discord(socket)、Slack(socket 或 webhook);托管模式覆盖网关支持的所有渠道。渠道能力一览见 中文 README。

小结

  • thread.stream() = 先发一条、边写边 Edit,实现打字机效果;
  • with 保证收尾,live 决定实时还是缓冲降级,代码无需分支;
  • 用 min_chars 和 throttle 两个参数调节节奏与平台限流;
  • Python 与 TypeScript 同一契约,改个命名即可切换语言。

更多可运行示例都在 examples/ 目录,每个渠道一个文件夹,可直接照抄。

登录后查看全文
caspian-sdk