AI 服务接口开发
🎯 引言
前面我们已经能在 Node.js 终端中接收模型的流式回答。现在,如果想把回答显示在 Vue 聊天页面中,就需要让浏览器也能获取这些内容。
但 API Key 不能放在浏览器代码里,否则其他人可能拿到密钥并使用你的模型额度。更合适的做法是在中间增加一个 Express 接口:浏览器负责发送问题和显示回答, 后端负责调用模型 并返回结果。
本篇将完成 POST /api/chat,学习如何接收用户消息、转发模型的流式回答,以及处理连接中断和调用失败。
🧱 浏览器如何收到模型的回答
一次请求会经过以下过程。浏览器负责提问和展示回答,Express 负责调用模型并转发结果:
- 1浏览器 向 Express 发送问题
- 2Express 调用模型 API
- 3模型 API 逐段返回文字给 Express
- 4Express 将 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:如果已经开始发送文字,后续却发生异常,用这一类消息告诉浏览器生成中断。
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();
处理过程只有两个重点:
- 模型返回文字片段时,立即写出一行
delta。 - 模型的流结束后,写出
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 或 NDJSONerror。如果请求已取消,或者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 流式接口。下一篇将处理聊天记录的保存与恢复。
