feat: 任务队列改为并发池并支持幂等复用与退避重试
This commit is contained in:
+36
-1
@@ -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 {
|
||||
|
||||
@@ -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]);
|
||||
});
|
||||
});
|
||||
@@ -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;
|
||||
}
|
||||
Reference in New Issue
Block a user