streamText 流式输出全解析:chatbot-template 如何实现丝滑打字机效果

原创2026-10-14 23:39:301,621 阅读

streamText 流式输出全解析:chatbot-template 如何实现丝滑打字机效果

chatbot-template 是一个基于 Next.js、Vercel AI SDK、shadcn/ui 构建的极简 AI 聊天机器人模板。它的核心体验在于:回答逐字"打字"出现、工具调用实时显示进度。这套丝滑体验的秘密,就是 AI SDK 提供的 streamText 流式输出方案。本文将带你完整解析它的前后端实现链路,新手也能看懂。

为什么流式输出决定聊天体验

想象两种等待体验:

  • ❌ 阻塞式:点击发送后盯着转圈,30 秒后才"哗啦"一下出现整段回答
  • ✅ 流式:第一个字 1 秒内就出现,回答像打字机一样逐字"生长"

streamText 的作用就是把模型的响应从"一次性返回的大包"变成"细水长流的 token 片段"。整条链路可以概括为:

后端 streamText 产生流 → 打包成 UI Message 流 → 前端 useChat 消费 → 按 part 增量渲染出打字机效果

下面逐段拆解。

后端:用 streamText 把响应变成"数据流"

流式输出的起点是 app/api/chat/route.ts,这个 Next.js Route Handler 做了三件事:校验请求 → 调 streamText → 打包成 UI 流响应。

核心代码集中在 app/api/chat/route.ts:

const result = streamText({
  model: modelId,
  messages: await convertToModelMessages(messages),
  tools,
  stopWhen: isStepCount(5),
  maxOutputTokens: MAX_OUTPUT_TOKENS,
  abortSignal: req.signal,
})

return createUIMessageStreamResponse({
  stream: toUIMessageStream({
    stream: result.stream,
    sendSources: true,
    onError: () => "Something went wrong. Please try again.",
  }),
})

每个参数都在为"又快又稳"服务:

参数 作用 对体验的影响
model 走 Vercel AI Gateway 调用的模型,白名单见 lib/models.ts 非法模型名直接 400,避免无效等待
messages 经 validateUIMessages 校验后的对话历史 挡住恶意/畸形消息体
tools 由 tools/index.ts 按模型动态组装的工具集 让"搜索网页"等过程也能流式展示
stopWhen: isStepCount(5) 工具调用最多跑 5 步 防止死循环把流拖长
maxOutputTokens: 8192 单次输出上限(见 route.ts 的常量定义) 给单次回答"封顶"
abortSignal: req.signal 客户端断开即中止生成 用户关页面不再浪费额度

两个容易忽略的细节:

  • export const maxDuration = 30(route.ts):声明该路由最长执行 30 秒,适配流式长连接;
  • sendSources: true:把网页搜索的引用来源一并塞进流里,前端稍后用它渲染 "Searched N websites" 抽屉(见 components/parts/sources-part.tsx)。

前端:useChat 接管数据流,驱动打字机渲染

前端入口在 components/chat.tsx,它只用了 AI SDK React 的 useChat 一个 Hook(见 chat.tsx):

const { messages, sendMessage, status, stop, error, addToolOutput } =
  useChat<ChatUIMessage>({
    sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls,
  })

useChat 负责订阅后端那条流,并把每个到达的片段实时"拼"进 messages 数组——打字机效果的数据源就来自这里。围绕它还有几个体验细节:

1. 状态机驱动界面切换。 status 会在 submitted(已发出、等首字)和 streaming(流进行中)之间流转,组件据此计算 isBusy(chat.tsx)。

2. "Thinking…" 占位提示。 流还没吐出第一个字时,界面底部会出现一个微光渐变的 "Thinking…"(chat.tsx),消灭了"点了没反应"的焦虑感。

3. 一键停止。 流式期间,发送按钮会自动变成停止按钮(components/prompt-form.tsx),点击触发 stop() 中止请求,配合后端的 abortSignal 立刻停止生成。

最后一公里:按 part 增量渲染

流到达前端后并不是"一整段文字",而是一串分类型的 part(文本、工具调用、来源 URL 等)。components/chat-message.tsx 按 part.type 分发渲染:

Part 类型 渲染组件 效果
text text-part.tsx 用 react-markdown 实时渲染 Markdown,边流边排版
tool-github_repo github-repo-part.tsx 查询中显示转圈,完成后显示仓库星标/语言等
tool-web_search web-search-part.tsx 搜索时显示 "Searching the web…"
tool-ask_user ask-user-part.tsx 模型向用户提问的交互式问卷

工具类 part 会随流推进经历 input-streaming → input-available → output-available 的状态变化,各组件按 part.state 切换"进行中/完成/失败"三种界面——这就是工具调用"看得见进度"的原因。

还有一个巧妙的收尾逻辑:网页搜索的回答会每个引用一段地流入,于是 chat-message.tsx 的 mergeTextParts 把相邻的 text part 合并回一篇完整 Markdown,避免答案被切成碎片;而来源列表(SourcesPart)只在 !isStreaming 时才渲染,保证引用区在流结束后一次性出现,不闪烁。

流式 + 工具调用:让对话可以"自我续播"

模板通过 tools/index.ts 按模型组装工具:服务端执行的 github_repo 查询、provider 原生 web_search,以及没有 execute 的交互式 ask_user。

当模型调用了 ask_user 停下等待用户回答时,useChat 的 sendAutomaticallyWhen: lastAssistantMessageIsCompleteWithToolCalls 配置(chat.tsx)会在用户提交问卷后自动发起下一轮流式请求,对话像播客一样"续播",全程无需用户手动再点发送。

另外,tools/index.ts 用 InferUITools 从工具定义推断消息类型,part.input / part.output 在前端组件里全类型安全——改字段名直接编译报错,而不是运行时悄悄变 undefined。

本地快速跑起来

想亲眼看看打字机效果?三步搞定:

git clone https://gitcode.com/gh_mirrors/chatbo/chatbot-template
cd chatbot-template
pnpm install

给应用一个 AI Gateway 凭证后启动开发服务器(详见 README.md 的 Local development 一节):

cp .env.example .env.local   # 填入 AI_GATEWAY_API_KEY
pnpm dev

打开本地页面发一句"介绍下 Next.js",就能观察到文字逐字流出、搜索过程实时显示的效果。

小结

chatbot-template 的丝滑体验,本质是三层分工的协作:

  1. streamText(app/api/chat/route.ts):把模型响应变成受控的数据流,maxOutputTokens、isStepCount、abortSignal 负责安全边界;
  2. useChat(components/chat.tsx):消费流、维护消息状态机,提供 stop() 与自动续播;
  3. part 增量渲染(components/chat-message.tsx):按类型分发、按状态切换,让文本、工具进度、引用来源各得其所。

这套"流式优先"的写法,是构建 AI 聊天应用时非常值得抄的模板。

登录后查看全文
chatbot-template