流式输出

使用 OpenAI SDK 逐段接收模型回答,判断生成是否完成,并主动取消流式请求。

🎯 引言

前三篇已经实现了文本生成和多轮对话,但调用方式有一个共同点:程序需要等模型生成完整回答,才能拿到结果。如果回答比较长,用户就只能等待。

聊天应用通常会让文字随着生成过程逐步显示,这就是 流式输出。本篇继续使用 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,或请求中途断开,都不能仅凭文本非空就判断生成正常完成。


🧪 小练习

  1. 把 04.streaming.mjs 的问题改为“列出五个 TypeScript 的优势,每条单独一行”,观察终端内容如何逐步出现,并确认最后有无 stop。
  2. 在 04.cancel.mjs 生成较长回答时按 Ctrl + C,观察主动停止提示;再不按快捷键运行一次,对比两种结束状态。

验证标准: 能够通过 delta.content 拼接出完整文本,知道为什么需要读取 finish_reason,并能区分正常结束、主动取消和异常中断。


🎉 你已经能够在 Node.js 中接收和控制模型的流式回复。下一篇开始学习让模型输出更适合程序处理的结构化数据。