feat: 任务队列改为并发池并支持幂等复用与退避重试

This commit is contained in:
cat
2026-10-08 17:32:34 +08:00
parent 7c751bfc02
commit bf56c2bd46
10 changed files with 1296 additions and 123 deletions
+36 -1
View File
@@ -36,11 +36,40 @@ export class LlmError extends Error {
constructor(
message: string,
public readonly statusCode: number,
/**
* 服务端给出的建议重试等待(毫秒)。
*
* 来自 429/503 的 `Retry-After` 头;有值时退避重试应优先采用它,
* 而不是用自己的指数退避——服务商限流时自己的退避往往偏短。
*/
public readonly retryAfterMs?: number,
) {
super(message);
this.name = "LlmError";
}
}
/**
* 解析 `Retry-After` 头。
*
* 规范允许秒数或 HTTP 日期两种形式,两种都支持;解析不出来时返回 undefined。
*/
export function parseRetryAfter(value: string | null, now: number = Date.now()): number | undefined {
if (!value) return undefined;
const trimmed = value.trim();
if (trimmed.length === 0) return undefined;
// 纯数字:秒
if (/^\d+$/.test(trimmed)) {
return Number(trimmed) * 1000;
}
// HTTP 日期
const at = Date.parse(trimmed);
if (Number.isNaN(at)) return undefined;
return Math.max(0, at - now);
}
/**
* 非流式调用,返回完整文本
*/
@@ -75,7 +104,13 @@ export async function chat(
if (!response.ok) {
const body = await response.text().catch(() => "");
throw new LlmError(`LLM 请求失败 (${response.status}): ${body.slice(0, 200)}`, 502);
const retryAfterMs = parseRetryAfter(response.headers.get("retry-after"));
// 保留上游真实状态码:重试策略靠它区分 429/5xx(可重试)与 4xx(不可重试)
throw new LlmError(
`LLM 请求失败 (${response.status}): ${body.slice(0, 200)}`,
response.status,
retryAfterMs,
);
}
const data = (await response.json()) as {
+196
View File
@@ -0,0 +1,196 @@
import { describe, expect, it } from "vitest";
import { LlmError, parseRetryAfter } from "./client.js";
import { computeBackoffMs, isRetryableLlmError, withRetry } from "./retry.js";
describe("parseRetryAfter", () => {
it("解析秒数形式", () => {
expect(parseRetryAfter("5")).toBe(5000);
expect(parseRetryAfter("0")).toBe(0);
});
it("解析 HTTP 日期形式", () => {
const now = Date.parse("2026-10-08T10:00:00Z");
expect(parseRetryAfter("Thu, 08 Oct 2026 10:00:03 GMT", now)).toBe(3000);
});
it("空值与非法值返回 undefined", () => {
expect(parseRetryAfter(null)).toBeUndefined();
expect(parseRetryAfter("")).toBeUndefined();
expect(parseRetryAfter(" ")).toBeUndefined();
expect(parseRetryAfter("soon")).toBeUndefined();
});
it("已过期的日期不会返回负数", () => {
const now = Date.parse("2026-10-08T10:00:10Z");
expect(parseRetryAfter("Thu, 08 Oct 2026 10:00:00 GMT", now)).toBe(0);
});
});
describe("isRetryableLlmError", () => {
it("限流与服务端错误可重试", () => {
for (const status of [408, 429, 500, 502, 503, 504]) {
expect(isRetryableLlmError(new LlmError("x", status))).toBe(true);
}
});
it("客户端错误不重试", () => {
for (const status of [400, 401, 403, 404, 422]) {
expect(isRetryableLlmError(new LlmError("x", status))).toBe(false);
}
});
it("未配置 API Key 不重试(重试也不会成功)", () => {
expect(isRetryableLlmError(new LlmError("LLM API Key 未配置", 503))).toBe(false);
});
it("非 LlmError 不重试", () => {
expect(isRetryableLlmError(new Error("boom"))).toBe(false);
expect(isRetryableLlmError("boom")).toBe(false);
expect(isRetryableLlmError(undefined)).toBe(false);
});
});
describe("computeBackoffMs", () => {
const base = { baseDelayMs: 1000, maxDelayMs: 20000, factor: 2, jitterRatio: 0 };
it("按指数增长", () => {
expect(computeBackoffMs(1, base)).toBe(1000);
expect(computeBackoffMs(2, base)).toBe(2000);
expect(computeBackoffMs(3, base)).toBe(4000);
});
it("受上限约束", () => {
expect(computeBackoffMs(10, base)).toBe(20000);
});
it("服务端给的建议等待优先于指数退避", () => {
expect(computeBackoffMs(1, base, 7000)).toBe(7000);
});
it("服务端建议同样受上限约束", () => {
expect(computeBackoffMs(1, base, 999999)).toBe(20000);
});
it("抖动落在 ±比例范围内且不为负", () => {
const jittered = { ...base, jitterRatio: 0.2 };
// random()=0 → 减满抖动;random()=1 → 加满抖动
expect(computeBackoffMs(1, jittered, undefined, () => 0)).toBe(800);
expect(computeBackoffMs(1, jittered, undefined, () => 1)).toBe(1200);
expect(computeBackoffMs(1, jittered, undefined, () => 0.5)).toBe(1000);
});
});
describe("withRetry", () => {
const noSleep = async (): Promise<void> => {};
it("首次成功不重试", async () => {
let calls = 0;
const result = await withRetry(
async () => {
calls += 1;
return "ok";
},
{ maxAttempts: 3, baseDelayMs: 1, maxDelayMs: 10, sleep: noSleep },
);
expect(result).toBe("ok");
expect(calls).toBe(1);
});
it("可重试错误会重试直到成功", async () => {
let calls = 0;
const result = await withRetry(
async () => {
calls += 1;
if (calls < 3) throw new LlmError("限流了", 429);
return "ok";
},
{ maxAttempts: 5, baseDelayMs: 1, maxDelayMs: 10, sleep: noSleep },
);
expect(result).toBe("ok");
expect(calls).toBe(3);
});
it("不可重试错误立即抛出,不浪费重试", async () => {
let calls = 0;
await expect(
withRetry(
async () => {
calls += 1;
throw new LlmError("参数错误", 400);
},
{ maxAttempts: 5, baseDelayMs: 1, maxDelayMs: 10, sleep: noSleep },
),
).rejects.toThrow("参数错误");
expect(calls).toBe(1);
});
it("重试次数用尽后抛出最后一次的错误", async () => {
let calls = 0;
await expect(
withRetry(
async () => {
calls += 1;
throw new LlmError(`第 ${calls} 次`, 503);
},
{ maxAttempts: 3, baseDelayMs: 1, maxDelayMs: 10, sleep: noSleep },
),
).rejects.toThrow("第 3 次");
expect(calls).toBe(3);
});
it("maxAttempts 为 1 时等价于不重试", async () => {
let calls = 0;
await expect(
withRetry(
async () => {
calls += 1;
throw new LlmError("x", 503);
},
{ maxAttempts: 1, baseDelayMs: 1, maxDelayMs: 10, sleep: noSleep },
),
).rejects.toThrow();
expect(calls).toBe(1);
});
it("每次重试前回调,带上尝试序号与等待时长", async () => {
const seen: Array<{ attempt: number; delayMs: number }> = [];
await expect(
withRetry(
async () => {
throw new LlmError("x", 503);
},
{
maxAttempts: 3,
baseDelayMs: 100,
maxDelayMs: 10_000,
jitterRatio: 0,
sleep: noSleep,
onRetry: (info) => seen.push({ attempt: info.attempt, delayMs: info.delayMs }),
},
),
).rejects.toThrow();
expect(seen).toEqual([
{ attempt: 1, delayMs: 100 },
{ attempt: 2, delayMs: 200 },
]);
});
it("服务端 Retry-After 会覆盖指数退避的等待时长", async () => {
const delays: number[] = [];
await expect(
withRetry(
async () => {
throw new LlmError("限流", 429, 5000);
},
{
maxAttempts: 2,
baseDelayMs: 10,
maxDelayMs: 10_000,
sleep: noSleep,
onRetry: (info) => delays.push(info.delayMs),
},
),
).rejects.toThrow();
expect(delays).toEqual([5000]);
});
});
+124
View File
@@ -0,0 +1,124 @@
/**
* LLM 调用的退避重试。
*
* 背景:LLM 服务商的 429(限流)与 5xx(瞬时故障)是常态抖动,
* 把它们当成永久失败会让用户看到「AI 失败」而实际上只是被限流了一下。
* 本模块只负责「哪些错误值得重试」与「等多久再试」,不关心任务队列。
*/
import { LlmError } from "./client.js";
/** 默认值得重试的上游状态码 */
const RETRYABLE_STATUS = new Set([
408, // 请求超时
425, // Too Early
429, // 限流
500, // 上游内部错误
502, // 网关错误
503, // 服务不可用
504, // 网关超时
]);
/**
* 判断一个错误是否值得重试。
*
* 原则:只有「重试可能成功」的错误才重试。
* - 429 / 5xx / 网络异常 / 超时 → 可重试
* - 400 / 401 / 403 / 404 等客户端错误 → 不可重试(重试多少次都一样)
* - 未配置 API Key(503 但属配置问题)→ 不可重试
*/
export function isRetryableLlmError(error: unknown): boolean {
if (!(error instanceof LlmError)) {
// 非 LlmError 的异常(例如 JSON 解析失败)不重试,避免无限循环
return false;
}
if (error.message.includes("API Key 未配置")) {
return false;
}
// 超时统一为 504,属于可重试
return RETRYABLE_STATUS.has(error.statusCode);
}
export interface RetryOptions {
/** 总尝试次数(含首次)。<=1 表示不重试 */
maxAttempts: number;
/** 首次退避基准(毫秒),之后按倍数增长 */
baseDelayMs: number;
/** 单次退避上限(毫秒) */
maxDelayMs: number;
/** 指数倍数,默认 2 */
factor?: number;
/** 抖动比例 0~1,默认 0.2,避免多个任务同时重试造成共振 */
jitterRatio?: number;
/** 判断是否重试,默认 isRetryableLlmError */
isRetryable?: (error: unknown) => boolean;
/** 注入以便测试 */
sleep?: (ms: number) => Promise<void>;
/** 注入以便测试 */
random?: () => number;
/** 每次重试前的回调,用于日志 */
onRetry?: (info: { attempt: number; delayMs: number; error: unknown }) => void;
}
const defaultSleep = (ms: number): Promise<void> =>
new Promise((resolve) => {
setTimeout(resolve, ms);
});
/**
* 计算第 attempt 次重试(attempt 从 1 开始)应等待的毫秒数。
*
* 优先采用服务端给的 `Retry-After`,否则用指数退避 + 抖动,并受 maxDelayMs 限制。
*/
export function computeBackoffMs(
attempt: number,
options: Pick<RetryOptions, "baseDelayMs" | "maxDelayMs" | "factor" | "jitterRatio">,
serverHintMs?: number,
random: () => number = Math.random,
): number {
const factor = options.factor ?? 2;
const jitterRatio = options.jitterRatio ?? 0.2;
const base = Math.min(options.baseDelayMs * factor ** (attempt - 1), options.maxDelayMs);
// 服务端明确要求等待时以它为准(同样受上限约束),此时不再叠加抖动
if (serverHintMs !== undefined && serverHintMs >= 0) {
return Math.min(serverHintMs, options.maxDelayMs);
}
const jitter = base * jitterRatio * (random() * 2 - 1);
return Math.max(0, Math.round(Math.min(base + jitter, options.maxDelayMs)));
}
/**
* 执行 fn,失败且可重试时按退避策略重试。
*
* 最后一次失败会原样抛出,调用方据此判断任务最终状态。
*/
export async function withRetry<T>(
fn: () => Promise<T>,
options: RetryOptions,
): Promise<T> {
const isRetryable = options.isRetryable ?? isRetryableLlmError;
const sleep = options.sleep ?? defaultSleep;
const random = options.random ?? Math.random;
const attempts = Math.max(1, Math.floor(options.maxAttempts));
let lastError: unknown;
for (let attempt = 1; attempt <= attempts; attempt += 1) {
try {
return await fn();
} catch (error) {
lastError = error;
const isLast = attempt >= attempts;
if (isLast || !isRetryable(error)) {
throw error;
}
const serverHint = error instanceof LlmError ? error.retryAfterMs : undefined;
const delayMs = computeBackoffMs(attempt, options, serverHint, random);
options.onRetry?.({ attempt, delayMs, error });
await sleep(delayMs);
}
}
// 理论不可达:循环内要么返回要么抛出
throw lastError;
}