Node.js / TypeScript 接入:流式与类型定义
Node 侧接网关的体验通常不错——官方 SDK 的类型定义很完整,流式的 for-await 写法也很顺手。真正需要注意的是 TypeScript 的类型和实际能力不一定对得上。
先固定类型,再谈用法
SDK 的类型定义覆盖了它自己支持的能力,但网关侧的额外能力(比如自定义路由头、模型别名)往往不在类型里,需要自己扩展声明。
任何客户端接入,先把这三样固定下来:Base URL、模型 ID、Key。
因为网关支持模型映射别名,文档里的名字和你实际能调的名字可能不是同一个。
for await 消费流式最直观
官方 SDK 把 SSE 解析成异步迭代器,for await (const chunk of stream) 就是最自然的消费方式。错误会以抛异常的形式出现,需要 try/catch 包住。
很多自建转发在流式上做得糙:要么等上游整个响应回来再切片伪流式,要么把 SSE 帧原样透传但不做任何错误处理。
真正的流式代理要处理三件事:帧的边界、上游的中途报错、以及客户端中途断开时的取消传播。
AbortController 是取消的正确姿势
客户端主动取消时,把 signal 传给请求,网关会收到取消信号并把取消传播到上游——这直接影响你的账单。
客户端断开连接后,如果网关不把取消信号传给上游,上游会继续把整个响应算完——这部分 token 费用是你照付的。
所以取消传播不是锦上添花,是直接影响账单的功能。
超时设多少要分级
流式请求的整体超时和首字节超时应该分开设置。用一个统一的 30 秒超时去卡一个跑两分钟的长回答,只会得到一个莫名其妙的失败。
常见原因有三类:上游连接断开、客户端超时、以及网关自身触发了某种保护策略。
实操:Node.js / TypeScript 接入。
顺便看一下 AbortController 的用法,取消语义是这里最容易漏的。
import OpenAI from "openai";
const client = new OpenAI({
apiKey: process.env.GATEWAY_API_KEY,
baseURL: "https://aiminis.info/v1",
});
const stream = await client.chat.completions.create({
model: "gpt-6-sol",
messages: [{ role: "user", content: "用三句话解释熔断器模式" }],
stream: true,
});
for await (const chunk of stream) {
process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}
几个容易踩的坑
- 把 API Key 硬编码在代码里然后提交到仓库。
- 每次失败都重试,包括参数错误、额度不足这类永远不会成功的错误。
- 没有对已经产生上游用量的请求做重放保护,账单翻倍。
- 模型 ID 从旧文档里抄,实际 Key 没有该模型权限。
小结
把配置项和凭据都外置,是成本最低、收益最持久的一个工程习惯。
文中的示例接口都可以在 https://aiminis.info/ 上直接验证,用量与额度在用户中心 https://aiminis.info/console 随时可查。
- 点赞
- 收藏
- 关注作者
评论(0)