AI 服务接口开发

使用 Express 接收浏览器消息,调用模型并将流式回答逐段返回给前端。

🎯 引言

前面我们已经能在 Node.js 终端中接收模型的流式回答。现在,如果想把回答显示在 Vue 聊天页面中,就需要让浏览器也能获取这些内容。

但 API Key 不能放在浏览器代码里,否则其他人可能拿到密钥并使用你的模型额度。更合适的做法是在中间增加一个 Express 接口:浏览器负责发送问题和显示回答, 后端负责调用模型 并返回结果。

本篇将完成 POST /api/chat,学习如何接收用户消息、转发模型的流式回答,以及处理连接中断和调用失败。


🧱 浏览器如何收到模型的回答

一次请求会经过以下过程。浏览器负责提问和展示回答,Express 负责调用模型并转发结果:

  1. 1
    浏览器 向 Express 发送问题
  2. 2
    Express 调用模型 API
  3. 3
    模型 API 逐段返回文字给 Express
  4. 4
    Express 将 NDJSON 逐段返回浏览器

浏览器只访问自己的 /api/chat 接口,不需要知道 AIHubMix 的地址和 API Key。密钥留在后端的 .env 中。

为什么要约定返回格式?

聊天页面希望收到一段文字就显示一段,而不是等待完整回答。因此,我们让 Express 使用 NDJSON 格式返回内容。它将每个 JSON 对象放在单独的一行,并以 \n 分隔。

例如,浏览器可能依次收到:

{"type":"delta","text":"你好"}
{"type":"delta","text":",我是 AI 助手。"}
{"type":"done","finishReason":"stop"}

这里约定:

  • delta:模型新增的一段文字,浏览器把 text 追加到当前回答中。
  • done:本次流式传输结束;finishReason 记录模型的结束原因。
  • error:如果已经开始发送文字,后续却发生异常,用这一类消息告诉浏览器生成中断。
SSE 和 NDJSON 都能用于流式返回。这里选择 NDJSON,是因为浏览器可以按每行一个 JSON 对象来识别 delta、done 和 error。上游 SSE 已由 OpenAI SDK 处理,我们不需要自行解析。

🛠 创建 Express 接口

继续使用前面的 ai-sdk-course 项目,环境为 Node.js 24.x ,已安装的 OpenAI SDK 版本是 openai@7.62.0。现在只需额外安装 Express 5.1.0:

npm install --save-exact express@5.1.0

原有 .env 不需要修改:

AI_API_KEY=你的AIHubMix密钥
AI_BASE_URL=https://aihubmix.com/v1
AI_MODEL=gpt-4o-mini

第一步:先理解 Express 怎样分段返回内容

在 Express 中,app.post("/api/chat", ...) 用来处理这个地址的 POST 请求。处理函数中的 req 是请求,res 是响应。

先看一段 暂时不调用模型的路由代码 :

app.post("/api/chat", (req, res) => {
    res.setHeader("Content-Type", "application/x-ndjson; charset=utf-8");

    res.write(JSON.stringify({ type: "delta", text: "你好" }) + "\n");
    res.write(JSON.stringify({ type: "delta", text: "!" }) + "\n");
    res.write(JSON.stringify({ type: "done" }) + "\n");
    res.end();
});

这里只展示路由代码,app 的创建和服务器启动会在后面的完整示例中给出。固定文字用于说明响应方式:

  • res.write() 向浏览器写入一段数据,之后还可以继续写入下一段。
  • res.end() 结束这次 HTTP 响应,后续不再发送数据。

因为这几次 res.write() 是连续执行的,客户端可能几乎同时收到三行内容。这里先学习 如何分段写入 ,接入模型后才会随着模型生成陆续转发文字。

第二步:读取并检查用户消息

浏览器会向 /api/chat 发送这样的 JSON 请求体:

{"message":"请介绍 Node.js"}

Express 使用 express.json() 解析请求体,再通过 req.body 读取内容。接口只接受非空字符串,并限制消息长度:

app.use(express.json({ limit: "16kb" }));

app.post("/api/chat", async (req, res) => {
    const message = req.body?.message;

    if (typeof message !== "string" || !message.trim() || message.length > 2000) {
        return res.status(400).json({ error: "请输入 1~2000 个字符的消息" });
    }

    // 校验通过后,再调用模型
});

16kb 限制的是整个请求体的字节大小,2000 限制的是 message 的长度。校验失败时,直接返回 HTTP 400,不会调用模型。

第三步:把模型片段转发给浏览器

在《流式输出》中,我们已经通过 choice.delta.content 获取模型新增的文字。现在只需要把原本打印到终端的文字,改成通过 res.write() 返回。

下面只展示接口中负责调用模型和转发文字的部分。client 是前面创建的 SDK 客户端,message 是通过请求体读取并校验后的用户消息。完整的变量定义和路由会在后面给出。

const stream = await client.chat.completions.create({
    model: process.env.AI_MODEL,
    messages: [{ role: "user", content: message }],
    stream: true
});

res.setHeader("Content-Type", "application/x-ndjson; charset=utf-8");

let finishReason = null;

for await (const chunk of stream) {
    const choice = chunk.choices[0];
    if (!choice) continue;

    const text = choice.delta?.content;
    if (text) {
        res.write(JSON.stringify({ type: "delta", text }) + "\n");
    }

    if (choice.finish_reason != null) {
        finishReason = choice.finish_reason;
    }
}

res.write(JSON.stringify({ type: "done", finishReason }) + "\n");
res.end();

处理过程只有两个重点:

  1. 模型返回文字片段时,立即写出一行 delta。
  2. 模型的流结束后,写出 done,再调用 res.end()。

模型有时会返回不含文字的片段,因此要先判断 text 是否存在。finish_reason 则表示停止生成的原因,例如 stop 表示正常停止,length 表示回答可能因长度限制而截断。

第四步:处理连接中断和调用失败

假设用户在回答生成到一半时关闭页面。如果浏览器已经断开,后端就没必要继续调用模型了。

为此,可以创建一个 AbortController,并把 controller.signal 传给 SDK。当响应连接提前关闭时,调用 controller.abort(),尝试取消上游请求。

异常处理还有一个关键区别:

情况如何处理
还没向浏览器发送数据就失败返回 HTTP 502 和 JSON 错误
已经发送了部分文字才失败继续写出一行 NDJSON error,然后结束响应
浏览器已经断开取消模型请求,不再向浏览器写入

因为 HTTP 响应头一旦发送,就不能再修改状态码。代码中的 res.headersSent 正是用来判断是否已经开始发送响应。

取消请求和异常处理稍微涉及一些边界情况。现在只需记住它们各自解决的问题,下面的完整代码已经把这些逻辑组合好了。


🧩 完整代码

在项目根目录创建 08.server.mjs,将前面学过的几个步骤组合起来:

import express from "express";
import OpenAI from "openai";

const app = express();
const client = new OpenAI({
    apiKey: process.env.AI_API_KEY,
    baseURL: process.env.AI_BASE_URL
});

app.use(express.json({ limit: "16kb" }));

app.post("/api/chat", async (req, res) => {
    const message = req.body?.message;

    if (typeof message !== "string" || !message.trim() || message.length > 2000) {
        return res.status(400).json({ error: "请输入 1~2000 个字符的消息" });
    }

    const controller = new AbortController();
    let finished = false;

    res.on("close", () => {
        if (!finished) controller.abort();
    });

    try {
        const stream = await client.chat.completions.create({
            model: process.env.AI_MODEL,
            messages: [{ role: "user", content: message }],
            stream: true
        }, { signal: controller.signal });

        res.setHeader("Content-Type", "application/x-ndjson; charset=utf-8");
        res.setHeader("Cache-Control", "no-cache, no-transform");
        res.setHeader("X-Accel-Buffering", "no");

        let finishReason = null;

        for await (const chunk of stream) {
            const choice = chunk.choices[0];
            if (!choice) continue;

            const text = choice.delta?.content;
            if (text) {
                res.write(JSON.stringify({ type: "delta", text }) + "\n");
            }

            if (choice.finish_reason != null) {
                finishReason = choice.finish_reason;
            }
        }

        finished = true;
        res.write(JSON.stringify({ type: "done", finishReason }) + "\n");
        res.end();
    } catch (error) {
        finished = true;
        if (controller.signal.aborted || res.destroyed) return;

        if (!res.headersSent) {
            res.status(502).json({ error: "模型服务暂时不可用" });
        } else {
            res.write(JSON.stringify({ type: "error", message: "生成中断" }) + "\n");
            res.end();
        }

        console.error(error);
    }
});

app.listen(3000, "127.0.0.1", () => {
    console.log("http://127.0.0.1:3000");
});

与前面的核心片段相比,这里多了三处必要的处理:

  • res.on("close"):在响应提前断开时取消模型请求;finished 用来避免正常结束后再取消。
  • { signal: controller.signal }:把取消信号传给模型请求。
  • try...catch:根据响应是否已经开始发送,选择 HTTP 502 或 NDJSON error。如果请求已取消,或者 res.destroyed 表示响应连接已关闭,就不再尝试向浏览器写入内容。

另外,Cache-Control 和 X-Accel-Buffering 用于减少部分缓存、代理造成的流式缓冲;它们并不能保证所有网络环境都逐字显示内容。


🧪 测试接口

先在项目根目录启动服务:

node --env-file=.env 08.server.mjs

如果之前调用 AIHubMix 需要本地代理,则使用:

HTTPS_PROXY=http://127.0.0.1:7890 NODE_USE_ENV_PROXY=1 node --env-file=.env 08.server.mjs

打开另一个终端,发送一条问题:

curl -N -X POST http://127.0.0.1:3000/api/chat \
    -H 'Content-Type: application/json' \
    -d '{"message":"请用一句话介绍 Node.js"}'

终端可能会看到:

{"type":"delta","text":"Node.js"}
{"type":"delta","text":" 让 JavaScript 可以在服务端运行。"}
{"type":"done","finishReason":"stop"}

这只是 返回格式示意 ,不是实际模型调用记录。每次回答的内容和分段方式都可能不同。curl -N 可以减少 curl 自身的输出缓冲,便于观察流式返回。

再发送一条空消息:

curl -i -X POST http://127.0.0.1:3000/api/chat \
    -H 'Content-Type: application/json' \
    -d '{"message":""}'

此时应该收到 HTTP 400 和 JSON 错误,不会进入模型调用阶段。

浏览器可以用 fetch() 读取 NDJSON。需要注意,fetch() 读到的数据块不一定刚好对应完整的一行,因此前端必须先拼接出完整行,再调用 JSON.parse()。
本例只监听 127.0.0.1,用于本地学习。真正开放给其他用户使用前,还需要身份验证、限流和额度控制,否则其他人仍可能通过你的后端接口消耗模型费用。

❓ 知识问答

Q1:为什么 curl 可以测试接口,但 Vue 页面直接请求时可能出现跨域错误?

curl 不受浏览器同源策略的限制。Vue 开发服务器和 Express 使用不同端口时,浏览器会按跨域请求处理。后续接入 Vue 时,可以通过 Vite 开发代理转发 /api/chat,本篇先专注于验证后端接口。

Q2:为什么已经调用了 res.write(),文字也不一定一个字一个字地显示?

模型每次返回的文本长度本来就不固定,而且网络、代理和客户端也可能缓冲数据。流式返回的重点是 不必等完整回答生成后才发送 ,而不是保证每次只发送一个字。


🧪 小练习

先用 /api/chat 验证正常消息和空消息:正常请求应依次收到 delta 和 done,空消息应返回 HTTP 400。

接着自己修改一处功能:将接口允许的消息长度从 2000 个字符改为 1000 个字符 ,并同步修改对应的错误提示,然后重启服务。

用下面的命令生成一条恰好 1000 个字符的消息:

node -e 'process.stdout.write(JSON.stringify({ message: "a".repeat(Number(process.argv[1])) }))' 1000 \
    | curl -i -X POST http://127.0.0.1:3000/api/chat \
        -H 'Content-Type: application/json' --data-binary @-

将命令中的 1000 改为 1001,再执行一次。

验证标准: 1000 个字符可以进入模型调用;1001 个字符应直接收到 HTTP 400,且不会调用模型。

思考一下:如果把所有文字片段收集起来,等模型生成结束后才调用一次 res.write(),浏览器还能边生成边显示回答吗?


🎉 现在,你已经为模型创建了一个可以供浏览器调用的 Express 流式接口。下一篇将处理聊天记录的保存与恢复。