流式输出
🎯 引言
前三篇已经实现了文本生成和多轮对话,但调用方式有一个共同点:程序需要等模型生成完整回答,才能拿到结果。如果回答比较长,用户就只能等待。
聊天应用通常会让文字随着生成过程逐步显示,这就是 流式输出。本篇继续使用 AIHubMix 和 OpenAI SDK,学习如何在 Node.js 中接收文本片段、拼接完整回答、判断生成是否结束,以及主动取消请求。这里先处理 模型 API → Node.js 程序 的数据流;《AI 服务接口开发》再介绍如何通过 Express 把流式内容传给浏览器。
⚖️ 普通响应与流式响应有什么区别
假设我们让模型介绍 Vue 3,两种方式最终都可能得到相同的文字,但程序拿到内容的时间不同。
| 普通响应 | 流式响应 |
|---|---|
| 等待模型生成完毕,再一次拿到完整文本 | 模型生成过程中,逐段收到内容并立即显示 |
| 适合只关心最终结果的任务 | 适合聊天、长文本生成等希望尽早显示内容的任务 |
以“Vue 3 支持组合式 API,可以更灵活地组织代码”为例,流式模式在界面上可能呈现为:
第一次显示:Vue 3
继续显示:Vue 3 支持组合式 API
最终显示:Vue 3 支持组合式 API,可以更灵活地组织代码。
这只是 展示效果的示意,并不表示 SDK 一定按这些位置切分文本。一次收到的片段可能是几个字,也可能是一段文字;一个片段不等于一个字,也不等于一个 Token。
Chat Completions 的流式响应通常通过 SSE(Server-Sent Events)从服务端持续传输。OpenAI SDK 会把流中的数据解析成可遍历的对象,所以这里不需要手动解析 SSE。流式输出的主要优势是 更早看到第一段内容,不代表完整生成一定更快。
🛠 使用 SDK 接收流式文本
继续使用前面创建的 ai-sdk-course 项目,沿用 Node.js 24.x、openai@7.62.0 以及 .env 中的 AIHubMix 配置,不需要重新安装依赖。
在项目根目录创建 04.streaming.mjs:
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.AI_API_KEY,
baseURL: process.env.AI_BASE_URL
});
const stream = await client.chat.completions.create({
model: process.env.AI_MODEL,
messages: [
{
role: "user",
content: "请用三句话介绍 Vue 3 的核心特点。"
}
],
stream: true
});
let text = "";
let finishReason = null;
for await (const chunk of stream) {
const choice = chunk.choices[0];
if (!choice) continue;
const content = choice.delta?.content;
if (content) {
text += content;
process.stdout.write(content);
}
if (choice.finish_reason != null) {
finishReason = choice.finish_reason;
}
}
console.log("\n结束原因:", finishReason ?? "未收到");
console.log("累计收到字符数:", text.length);
if (finishReason !== "stop") {
console.warn("回答可能未完整生成,请检查结束原因");
}
在项目根目录运行:
node --env-file=.env 04.streaming.mjs
如果需要通过本地 HTTP 代理访问 AIHubMix,使用《AI SDK 简介与环境搭建》验证过的命令:
HTTPS_PROXY=http://127.0.0.1:7890 NODE_USE_ENV_PROXY=1 node --env-file=.env 04.streaming.mjs
运行时,你会看到文本逐渐出现在终端中,而不是等请求结束才一次性打印。下面是最终终端内容的一种 示意结果:
Vue 3 的组合式 API 便于按功能组织代码。
响应式系统可以在数据变化时更新界面。
单文件组件让模板、逻辑和样式可以放在同一个文件中。
结束原因: stop
累计收到字符数: 70
实际文字、片段数量与字符数都可能不同。上面的示意文本按 JavaScript 字符串长度计算为 70;代码会根据本次真实收到的内容输出对应数值。
代码与前面有什么不同?
和前两篇的 chat.completions.create() 相比,请求只需增加 stream: true,结果的读取方式就会发生变化:
- 普通请求返回完整响应,通过
response.choices[0].message.content取得文字。 - 流式请求返回可以异步遍历的数据流,通过每个
chunk的choices[0].delta.content取得 本次新增的文字。
程序把每段 content 追加到 text,同时使用 process.stdout.write() 显示到终端。它不会像 console.log() 那样每次自动换行,因此能看到文字在同一段内容后面不断增长。
🧱 一次流式响应不只有文本
流式响应的数据块不仅用于传递正文,也可能携带角色信息或结束原因。因此,不能假设每次遍历都能拿到 delta.content。
下面是 省略其他字段后的结构示意,并不是完整的 API 响应:
// 收到一段文本
{
choices: [
{ delta: { content: "Vue 3" }, finish_reason: null }
]
}
// 另一段文本
{
choices: [
{ delta: { content: " 支持组合式 API" }, finish_reason: null }
]
}
// 生成结束,可能不再有正文
{
choices: [
{ delta: {}, finish_reason: "stop" }
]
}
正因为最后一个数据块可能没有正文,完整代码才分别处理 delta.content 和 finish_reason。
如何判断生成是否完整?
《文本生成与模型参数》已经介绍过 finish_reason。区别在于:普通响应可以直接读取结束原因,流式响应则需要在遍历过程中记录它。
| 结束原因 | 代表什么 | 程序应该怎样处理 |
|---|---|---|
stop | 正常结束 | 可以将本次文本视为已完整生成 |
length | 达到输出长度限制 | 文本可能被截断,不应直接当作完整回答 |
content_filter | 生成受到内容过滤限制 | 按受限结果处理 |
| 没有收到结束原因 | 无法确认完整结束 | 不应仅凭已有文本认定成功 |
例如,流式传输可能已经返回“Vue 3 的组合式 API 可以”,但随后连接中断。收到部分文本不等于生成成功。如果请求在传输中发生异常,SDK 可能直接抛出错误;如果流结束但没有正常的 finish_reason,也不能显示“生成完成”。
本篇只判断文本是否正常结束。至于生成内容是否准确、是否符合业务要求,仍然需要应用自行检查。
🪤 主动停止正在生成的回答
流式聊天还有一个实际需求:用户发现模型回答方向不对,希望在它继续生成时点击“停止”。在 Node.js 终端中,可以先用 Ctrl + C 模拟这个操作。
创建 04.cancel.mjs:
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.AI_API_KEY,
baseURL: process.env.AI_BASE_URL
});
const controller = new AbortController();
process.once("SIGINT", () => {
controller.abort();
});
let finishReason = null;
try {
const stream = await client.chat.completions.create({
model: process.env.AI_MODEL,
messages: [
{
role: "user",
content: "请详细介绍 JavaScript 的发展历史。"
}
],
stream: true
}, { signal: controller.signal });
for await (const chunk of stream) {
const choice = chunk.choices[0];
if (choice?.delta?.content) {
process.stdout.write(choice.delta.content);
}
if (choice?.finish_reason != null) {
finishReason = choice.finish_reason;
}
}
} catch (error) {
if (!controller.signal.aborted) throw error;
}
if (controller.signal.aborted) {
console.log("\n已主动停止,现有文字可能不完整");
} else if (finishReason === "stop") {
console.log("\n生成完成");
} else {
console.log("\n生成未正常完成:", finishReason ?? "未收到结束原因");
}
运行:
HTTPS_PROXY=http://127.0.0.1:7890 NODE_USE_ENV_PROXY=1 node --env-file=.env 04.cancel.mjs
在文字仍在生成时按 Ctrl + C,AbortController 会发出取消信号,SDK 随后停止继续接收该请求的数据。如果模型已经先一步生成完毕,程序会正常结束,这时再按快捷键就无法观察取消效果,可以换一个需要更长回答的问题重试。
这里区分三种结果:
| 情况 | 应当呈现的状态 |
|---|---|
收到 stop,没有主动取消 | 生成完成 |
| 用户主动取消 | 已停止,保留已有的部分文字 |
| 请求报错或未收到正常结束原因 | 失败或未完整生成 |
取消请求不意味着模型服务端一定在同一瞬间停止计算;实际费用和取消行为以 AIHubMix 及所选模型的规则为准。
❓ 知识问答
Q1:流式输出一定要使用 WebSocket 吗?
不需要。Chat Completions 可以通过 HTTP 上的 SSE 持续传输内容,SDK 负责解析流。WebSocket 是另一种双向通信方案,并非展示模型流式回复的必要条件。
Q2:为什么已经收到文字,还要检查 finish_reason?
因为收到的文字可能只是部分结果。例如,输出上限触发 length,或请求中途断开,都不能仅凭文本非空就判断生成正常完成。
🧪 小练习
- 把
04.streaming.mjs的问题改为“列出五个 TypeScript 的优势,每条单独一行”,观察终端内容如何逐步出现,并确认最后有无stop。 - 在
04.cancel.mjs生成较长回答时按 Ctrl + C,观察主动停止提示;再不按快捷键运行一次,对比两种结束状态。
验证标准: 能够通过 delta.content 拼接出完整文本,知道为什么需要读取 finish_reason,并能区分正常结束、主动取消和异常中断。
🎉 你已经能够在 Node.js 中接收和控制模型的流式回复。下一篇开始学习让模型输出更适合程序处理的结构化数据。
