streamText 流式输出全解析:chatbot-template 如何实现丝滑打字机效果
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 的丝滑体验,本质是三层分工的协作:
streamText(app/api/chat/route.ts):把模型响应变成受控的数据流,maxOutputTokens、isStepCount、abortSignal负责安全边界;useChat(components/chat.tsx):消费流、维护消息状态机,提供stop()与自动续播;- part 增量渲染(components/chat-message.tsx):按类型分发、按状态切换,让文本、工具进度、引用来源各得其所。
这套"流式优先"的写法,是构建 AI 聊天应用时非常值得抄的模板。