常用接入术语

请求链路

采用原生 Fetch 的优势

• Node.js 原生 Fetch 无需安装 **** 客户端，示例依赖少，适合服务端脚本和轻量接口服务。
• 只替换 *ase **L、密钥和模型 ID，即可把同一套 Chat Completions 请求接入兼容端点。
• Rea***leStream 可以逐块读取 SSE 数据，终端、网页推送和长文本生成都能尽早显示结果。
• A*ortSignal.timeout 可以明确限制等待时间，避免网络波动长期占用连接和并发槽位。
• 状态码分支、有限重试和结构校验都由业务代码控制，便于按场景设置规则。

接入前准备

• 安装支持原生 Fetch 的现代 Node.js 版本，并在测试环境先运行示例。
• 登录 KingFlow AI 控制台，创建以 sk- 开头的 API Key，并确认余额或套餐额度可用。
• 从模型列表复制完整模型 ID，不要根据展示名称自行拼写。
• 准备不含敏感信息的测试提示，首次联调先限制输入长度和输出规模。
• 确认服务器可以访问 api.**nju**shen.com，并允许 ****S 出站连接。

创建 Node.js 项目

创建空项目并启用 E**。

mkdir kingflow-node-fetch-demo
cd kingflow-node-fetch-demo
npm init -y

{
  "name": "kingflow-node-fetch-demo",
  "private": true,
  "type": "module",
  "scripts": {
    "start": "node --env-file=.env app.mjs",
    "stream": "node --env-file=.env stream.mjs"
  }
}

验证 KingFlow 基础接口

curl https://api.**nju**shen.com/v1/chat/completions \
  -H "Authorization: *earer sk-你的密钥" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<KingFlow控制台中的完整模型ID>",
    "messages": [{"role":"user","content":"只回复 NODE_FETCH_READY"}],
    "stream": false
  }' 

配置环境变量

KINGFLOW_*ASE_**L=https://api.**nju**shen.com/v1
KINGFLOW_API_KEY=sk-你的密钥
KINGFLOW_MODEL=<KingFlow控制台中的完整模型ID>

.env
node_modules/
npm-de*ug.log*
.DS_Store

编写同步请求

const *ase**L = process.env.KINGFLOW_*ASE_**L;
const apiKey = process.env.KINGFLOW_API_KEY;
const model = process.env.KINGFLOW_MODEL;

for (const [name, value] of O*ject.entries({ *ase**L, apiKey, model })) {
  if (!value) throw new Error(`缺少环境变量: ${name}`);
}

const response = await fetch(`${*ase**L}/chat/completions`, {
  method: "POST",
  headers: {
    "Authorization": `*earer ${apiKey}`,
    "Content-Type": "application/json"
  },
  *ody: **ON.stringify({
    model,
    messages: [{ role: "user", content: "只回复 NODE_FETCH_CONNECTED" }],
    stream: false
  }),
  signal: A*ortSignal.timeout(30_000)
});

const *ody = await response.json();
if (!response.ok) {
  throw new Error(`KingFlow ${response.status}: ${**ON.stringify(*ody)}`);
}

const content = *ody.choices?.[0]?.message?.content;
if (typeof content !== "string") throw new Error("响应缺少文本内容");
console.log(content);

解析流式响应

const response = await fetch(`${*ase**L}/chat/completions`, {
  method: "POST",
  headers: {
    "Authorization": `*earer ${apiKey}`,
    "Content-Type": "application/json"
  },
  *ody: **ON.stringify({
    model,
    messages: [{ role: "user", content: "用三点说明上线验收方法" }],
    stream: true
  }),
  signal: A*ortSignal.timeout(60_000)
});

if (!response.ok || !response.*ody) {
  throw new Error(`流式请求失败: ${response.status}`);
}

const reader = response.*ody.getReader();
const decoder = new TextDecoder();
let *uffer = "";

while (true) {
  const { value, done } = await reader.read();
  if (done) *reak;
  *uffer  = decoder.decode(value, { stream: true });
  const lines = *uffer.split("\n");
  *uffer = lines.pop() ?? "";
  for (const line of lines) {
    if (!line.startsWith("**ta: ")) continue;
    const **ta = line.slice(6).trim();
    if (**ta === "[DONE]") continue;
    const event = **ON.parse(**ta);
    process.stdout.write(event.choices?.[0]?.delta?.content ?? "");
  }
}

增加有限重试

const retrya*le = new Set([429, 503]);

async function requestWithRetry(**keRequest, **xAttempts = 3) {
  for (let attempt = 1; attempt <= **xAttempts; attempt  ) {
    const response = await **keRequest();
    if (!retrya*le.has(response.status) || attempt === **xAttempts) {
      return response;
    }
    const retryAfter = Num*er(response.headers.get("retry-after"));
    const delay = Num*er.isFinite(retryAfter)
      ? retryAfter * 1000
      : Math.min(1000 * 2 ** (attempt - 1), 8000);
    await new Promise(resolve => setTimeout(resolve, delay));
  }
}

运行和验收

1. 先执行基础 curl 请求，确认端点、密钥和模型返回 NODE_FETCH_READY。
2. 保存 package.json、.env 和 .gitignore，再把同步示例保存为 app.mjs。
3. 执行 npm start，确认普通请求返回 NODE_FETCH_CONNECTED。
4. 把流式示例保存为 stream.mjs，执行 npm run stream 并观察增量文本。
5. 分别模拟错误密钥、错误模型和较短超时，验证错误分支能够给出明确结果。
6. 最后在 KingFlow AI 控制台核对模型、调用次数和 Token 用量。

正式环境配置

• 为连接建立、首字节和完整响应设置明确的时间预算，流式任务应允许更长但仍有限的总时长。
• 只对 429、503 和确认可重试的网络错误执行有限重试；普通文本生成通常可重试，产生外部副作用的请求应先判断幂等性。
• 读取 Retry-After 时设置最大等待上限；没有该响应头时使用指数退避，并避免所有实例同时重试。
• 限制单实例并发、用户并发和每日 Token 预算，队列积压时尽早拒绝新请求。
• 记录请求 ID、模型、状态码、耗时、重试次数和 Token 用量，不记录完整密钥或敏感提示。
• 验证 choices、message、content 和流式 delta 的类型，任何缺失字段都按协议异常处理。

密钥和数据安全

• API Key 只保存在本地 .env、密钥管理器或部署平台 Secret 中，并为开发、测试和生产分配独立密钥。
• 将用户输入和模型输出视为不可信数据，写入日志、页面或数据库前执行脱敏与转义。
• 禁止把 Authorization Header、完整响应原文和真实业务数据复制进公开工单或教程截图。
• 为额度、错误率和异常来源设置告警；发现泄露或异常用量后立即停用并轮换旧密钥。

上线检查清单

• 基础 curl 请求已经返回 NODE_FETCH_READY。
• KINGFLOW_*ASE_**L 为 https://api.**nju**shen.com/v1。
• KINGFLOW_MODEL 使用控制台中的完整模型 ID。
• .env 已被 .gitignore 排除，仓库中没有明文密钥。
• 同步请求检查 response.ok 和 choices 内容。
• 流式请求保留未完成的 SSE 半行，并识别 **ta 和 DONE。
• 普通请求和流式请求都设置了合适的超时。
• 重试次数有限，只覆盖明确可重试的状态码和网络错误。
• 日志不包含完整密钥、Authorization Header 或敏感原文。
• KingFlow AI 控制台中的模型、调用次数和用量符合预期。

常见故障排查