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
+357 -106
View File
@@ -1,15 +1,19 @@
/**
* 异步任务队列 —— 接收任务,后台 Worker 顺序处理,提供查询。
* 异步任务队列 —— 接收任务,后台 Worker 池并发处理,提供查询与幂等复用。
*
* 设计要点:
* - 单线程 Worker(setImmediate 链),同一时刻只处理一个 LLM 调用
* - TTL 清理:5 分钟一次,移除完成超过 1 小时的记录
* - 异常隔离:单个任务失败不影响后续任务
* - 日志复用 logStore,与管理面板日志统一
* - **Worker 池**:并发度可配置。原实现用单个 processing 标志串行,
* N 个请求要等 N × LLM 耗时,客户端很容易先超时。
* - **退避重试**:429 / 5xx / 超时等瞬时抖动不再直接判失败,见 llm/retry.ts。
* - **相同输入复用**:同一 type + 同参数的请求会复用同一个任务,
* 避免重复计费;进行中的请求直接合并,已完成的结果在窗口内复用。
* - **TTL 清理**:定期移除过期的完成记录,同时清理幂等索引。
* - 依赖以构造参数注入,便于单测;生产使用文件末尾的单例。
*/
import { randomUUID } from "node:crypto";
import { chat, isAvailable, loadConfig, LlmError } from "./llm/client.js";
import { randomUUID, createHash } from "node:crypto";
import { chat, isAvailable, loadConfig, LlmError, type ChatMessage } from "./llm/client.js";
import { withRetry, isRetryableLlmError, type RetryOptions } from "./llm/retry.js";
import { aggregateReportPrompt, compareRecallPrompt, generateMindMapPrompt } from "./llm/prompts.js";
import { logStore } from "./admin/store.js";
@@ -21,133 +25,379 @@ export type TaskStatus = "pending" | "running" | "done" | "failed";
export interface TaskRecord {
id: string;
/** 幂等键:同一 type + 同参数的记录共享同一个键 */
key: string;
type: TaskType;
params: Record<string, unknown>;
status: TaskStatus;
result?: unknown;
error?: string;
/** 已尝试次数(含首次),便于排查重试情况 */
attempts: number;
createdAt: string; // ISO 8601
startedAt?: string;
completedAt?: string;
}
// ---- 存储 ----
export interface CreateTaskOptions {
/** 显式幂等键;不传则由 type + params 计算 */
idempotencyKey?: string;
/** 跳过复用,强制新建任务(用户主动「重新生成」时用) */
force?: boolean;
}
const records = new Map<string, TaskRecord>();
const queue: TaskRecord[] = [];
let processing = false;
export interface CreateTaskResult {
taskId: string;
/** true 表示复用了已有任务,调用方不应按「新任务」处理 */
reused: boolean;
/** 复用的任务当前状态,便于调用方决定返回 200 还是 201 */
status: TaskStatus;
}
// ---- 公开 API ----
export interface QueueConfig {
/** 并发处理的任务数 */
concurrency: number;
/** 单任务总尝试次数(含首次) */
maxAttempts: number;
retryBaseMs: number;
retryMaxMs: number;
/** 完成记录的保留时长 */
ttlMs: number;
cleanupIntervalMs: number;
/** 已完成结果可被复用的时间窗口 */
resultCacheMs: number;
}
export function createTask(type: TaskType, params: Record<string, unknown>): string {
const id = randomUUID();
const task: TaskRecord = {
id,
type,
params,
status: "pending",
createdAt: new Date().toISOString(),
function intFrom(value: string | undefined, fallback: number): number {
if (value === undefined || value.trim() === "") return fallback;
const parsed = Number(value);
return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
}
export function loadQueueConfig(env: NodeJS.ProcessEnv = process.env): QueueConfig {
return {
concurrency: intFrom(env.LPT_AI_CONCURRENCY, 2),
maxAttempts: intFrom(env.LPT_AI_MAX_ATTEMPTS, 3),
retryBaseMs: intFrom(env.LPT_AI_RETRY_BASE_MS, 1_000),
retryMaxMs: intFrom(env.LPT_AI_RETRY_MAX_MS, 20_000),
ttlMs: intFrom(env.LPT_AI_TTL_MS, 60 * 60 * 1000),
cleanupIntervalMs: intFrom(env.LPT_AI_CLEANUP_MS, 5 * 60 * 1000),
resultCacheMs: intFrom(env.LPT_AI_RESULT_CACHE_MS, 10 * 60 * 1000),
};
records.set(id, task);
queue.push(task);
setImmediate(() => tryProcessNext());
return id;
}
export function getTask(id: string): TaskRecord | undefined {
const t = records.get(id);
if (!t) return undefined;
// 返回浅拷贝,防止外部修改
return { ...t };
/** 任务执行器:给定任务与参数返回结果,失败时抛出 */
export type TaskRunner = (
task: TaskRecord,
context: { attempt: number; messages: ChatMessage[]; config: ReturnType<typeof loadConfig> },
) => Promise<unknown>;
export interface TaskQueueDeps {
config?: QueueConfig;
/** 执行单次 LLM 调用;默认走 chat() */
runOnce?: TaskRunner;
/** 任务最终结束(成功或失败)时的回调,默认写管理面板日志 */
onSettled?: (task: TaskRecord) => void;
/** 是否可用 LLM;默认看 API Key 是否配置。注入以便测试 */
isLlmAvailable?: (config: ReturnType<typeof loadConfig>) => boolean;
sleep?: (ms: number) => Promise<void>;
random?: () => number;
now?: () => number;
/** 是否启用定时清理,测试里通常关掉 */
enableCleanup?: boolean;
}
// ---- 后台 Worker ----
// ---- 幂等键 ----
async function tryProcessNext(): Promise<void> {
if (processing || queue.length === 0) return;
processing = true;
/**
* 稳定序列化:键名排序后再序列化,避免对象键顺序不同导致同一输入算出不同键。
*/
function stableStringify(value: unknown): string {
if (value === null || typeof value !== "object") {
return JSON.stringify(value) ?? "null";
}
if (Array.isArray(value)) {
return `[${value.map(stableStringify).join(",")}]`;
}
const entries = Object.entries(value as Record<string, unknown>)
.filter(([, v]) => v !== undefined)
.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`).join(",")}}`;
}
const task = queue.shift()!;
export function computeTaskKey(type: TaskType, params: Record<string, unknown>): string {
const payload = stableStringify({ type, params });
return createHash("sha256").update(payload).digest("hex").slice(0, 32);
}
try {
// ---- 队列 ----
export class TaskQueue {
private readonly config: QueueConfig;
private readonly deps: TaskQueueDeps;
private readonly records = new Map<string, TaskRecord>();
/** 幂等键 → 任务 id */
private readonly keyIndex = new Map<string, string>();
private readonly queue: string[] = [];
private running = 0;
private cleanupTimer: NodeJS.Timeout | null = null;
private readonly idleWaiters: Array<() => void> = [];
constructor(deps: TaskQueueDeps = {}) {
this.deps = deps;
this.config = deps.config ?? loadQueueConfig();
if (deps.enableCleanup ?? true) {
this.cleanupTimer = setInterval(() => this.cleanup(), this.config.cleanupIntervalMs);
// 不要因为清理定时器让进程无法退出
this.cleanupTimer.unref?.();
}
}
private now(): number {
return this.deps.now ? this.deps.now() : Date.now();
}
private sleep(ms: number): Promise<void> {
if (this.deps.sleep) return this.deps.sleep(ms);
return new Promise((resolve) => {
setTimeout(resolve, ms);
});
}
/**
* 提交任务。
*
* 复用规则:
* - 同键任务处于 pending/running → 直接复用(合并重复请求,不重复计费)
* - 同键任务已完成且在 resultCacheMs 窗口内 → 复用结果
* - 同键任务已失败 → 新建(失败不该被缓存)
* - force=true → 一律新建
*/
create(
type: TaskType,
params: Record<string, unknown>,
options: CreateTaskOptions = {},
): CreateTaskResult {
const key = options.idempotencyKey?.trim() || computeTaskKey(type, params);
if (!options.force) {
const existingId = this.keyIndex.get(key);
const existing = existingId ? this.records.get(existingId) : undefined;
if (existing && this.isReusable(existing)) {
return { taskId: existing.id, reused: true, status: existing.status };
}
}
const id = randomUUID();
const task: TaskRecord = {
id,
key,
type,
params,
status: "pending",
attempts: 0,
createdAt: new Date(this.now()).toISOString(),
};
this.records.set(id, task);
this.keyIndex.set(key, id);
this.queue.push(id);
setImmediate(() => this.pump());
return { taskId: id, reused: false, status: "pending" };
}
private isReusable(task: TaskRecord): boolean {
if (task.status === "pending" || task.status === "running") {
return true;
}
if (task.status !== "done") {
// 失败的任务不进入复用,否则用户拿不到重试机会
return false;
}
if (!task.completedAt) return false;
return this.now() - Date.parse(task.completedAt) <= this.config.resultCacheMs;
}
get(id: string): TaskRecord | undefined {
const task = this.records.get(id);
return task ? { ...task } : undefined;
}
/** 待处理 + 处理中的任务数,便于观测与测试 */
get pendingCount(): number {
return this.queue.length + this.running;
}
/** 当前并发度 */
get concurrency(): number {
return this.config.concurrency;
}
/**
* 等待队列跑空。仅用于测试与静态工具场景,生产不应阻塞请求。
*/
drain(): Promise<void> {
if (this.pendingCount === 0) {
return Promise.resolve();
}
return new Promise((resolve) => {
this.idleWaiters.push(resolve);
});
}
stop(): void {
if (this.cleanupTimer) {
clearInterval(this.cleanupTimer);
this.cleanupTimer = null;
}
}
// ---- Worker 池 ----
/** 在并发额度允许的范围内尽量多启动 Worker */
private pump(): void {
while (this.running < this.config.concurrency && this.queue.length > 0) {
const id = this.queue.shift();
if (!id) break;
const task = this.records.get(id);
if (!task) continue;
this.running += 1;
void this.runTask(task).finally(() => {
this.running -= 1;
this.pump();
this.notifyIfIdle();
});
}
this.notifyIfIdle();
}
private notifyIfIdle(): void {
if (this.pendingCount > 0) return;
const waiters = this.idleWaiters.splice(0, this.idleWaiters.length);
for (const resolve of waiters) resolve();
}
private async runTask(task: TaskRecord): Promise<void> {
task.status = "running";
task.startedAt = new Date().toISOString();
task.startedAt = new Date(this.now()).toISOString();
const config = loadConfig();
if (!isAvailable(config)) {
throw new LlmError("LLM API Key 未配置", 503);
const available = this.deps.isLlmAvailable
? this.deps.isLlmAvailable(config)
: isAvailable(config);
if (!available) {
task.status = "failed";
task.error = "LLM API Key 未配置";
task.completedAt = new Date(this.now()).toISOString();
this.settle(task);
return;
}
const messages = buildMessages(task);
let callOptions: { temperature?: number; maxTokens?: number } | undefined;
if (task.type === "compare-recall") {
callOptions = { temperature: 0.2, maxTokens: 4096 };
} else if (task.type === "generate-mind-map") {
callOptions = { temperature: 0.3, maxTokens: 4096 };
} else {
callOptions = { temperature: 0.3, maxTokens: 2048 };
const callOptions = callOptionsFor(task.type);
const retryOptions: RetryOptions = {
maxAttempts: this.config.maxAttempts,
baseDelayMs: this.config.retryBaseMs,
maxDelayMs: this.config.retryMaxMs,
isRetryable: isRetryableLlmError,
sleep: (ms) => this.sleep(ms),
...(this.deps.random ? { random: this.deps.random } : {}),
onRetry: () => {
task.attempts += 1;
},
};
try {
const runOnce =
this.deps.runOnce ?? (async (t, ctx) => parseResult(t.type, await chat(ctx.config, ctx.messages, callOptions)));
const result = await withRetry(
() => runOnce(task, { attempt: task.attempts + 1, messages, config }),
retryOptions,
);
task.attempts += 1;
task.status = "done";
task.result = result;
task.completedAt = new Date(this.now()).toISOString();
} catch (err: unknown) {
task.attempts += 1;
task.status = "failed";
task.error = err instanceof Error ? err.message : String(err);
task.completedAt = new Date(this.now()).toISOString();
} finally {
this.settle(task, config);
}
}
const raw = await chat(config, messages, callOptions);
let result: unknown;
if (task.type === "aggregate-report") {
result = { report: raw.trim(), model: config.model };
} else if (task.type === "generate-mind-map") {
result = { outline: raw.trim(), model: config.model };
} else {
// compare-recall: 清理可能的 ```json 包裹
const clean = raw.trim().replace(/^```(?:json)?\s*/, "").replace(/\s*```$/, "");
result = JSON.parse(clean);
private settle(task: TaskRecord, config = loadConfig()): void {
if (this.deps.onSettled) {
this.deps.onSettled(task);
return;
}
task.status = "done";
task.result = result;
task.completedAt = new Date().toISOString();
// 记录到管理面板日志
const durationMs =
task.startedAt && task.completedAt
? Date.parse(task.completedAt) - Date.parse(task.startedAt)
: 0;
logStore.add({
timestamp: new Date().toISOString(),
timestamp: new Date(this.now()).toISOString(),
endpoint: `/ai/tasks#${task.type}`,
model: config.model,
durationMs: task.startedAt ? Date.parse(task.completedAt) - Date.parse(task.startedAt) : 0,
status: 200,
durationMs,
status: task.status === "done" ? 200 : 500,
requestBody: task.params,
responseBody: result,
messages,
params: callOptions,
responseBody: task.status === "done" ? (task.result ?? {}) : {},
...(task.error ? { error: task.error } : {}),
});
}
} catch (err: unknown) {
const errMsg = err instanceof Error ? err.message : String(err);
task.status = "failed";
task.error = errMsg;
task.completedAt = new Date().toISOString();
// ---- 清理 ----
const config = loadConfig();
logStore.add({
timestamp: new Date().toISOString(),
endpoint: `/ai/tasks#${task.type}`,
model: config.model,
durationMs: task.startedAt ? Date.parse(task.completedAt) - Date.parse(task.startedAt) : 0,
status: err instanceof LlmError ? err.statusCode : 500,
requestBody: task.params,
responseBody: {},
error: errMsg,
});
} finally {
processing = false;
// 处理下一个任务
if (queue.length > 0) {
setImmediate(() => tryProcessNext());
/** 移除过期的完成记录与对应幂等索引;返回移除条数便于测试 */
cleanup(): number {
const cutoff = this.now() - this.config.ttlMs;
let removed = 0;
for (const [id, task] of this.records) {
if (task.status !== "done" && task.status !== "failed") continue;
const completed = task.completedAt ? Date.parse(task.completedAt) : 0;
if (completed > 0 && completed < cutoff) {
this.records.delete(id);
// 索引只在该键仍指向这条记录时才删,避免误删后续新任务的索引
if (this.keyIndex.get(task.key) === id) {
this.keyIndex.delete(task.key);
}
removed += 1;
}
}
return removed;
}
/** 供测试断言内部状态 */
size(): number {
return this.records.size;
}
}
// ---- Prompt 构建 ----
// ---- 结果解析与 Prompt ----
function buildMessages(task: TaskRecord) {
function callOptionsFor(type: TaskType): { temperature: number; maxTokens: number } {
if (type === "compare-recall") return { temperature: 0.2, maxTokens: 4096 };
if (type === "generate-mind-map") return { temperature: 0.3, maxTokens: 4096 };
return { temperature: 0.3, maxTokens: 2048 };
}
/** 把模型原文转成结构化结果 */
export function parseResult(type: TaskType, raw: string, model = ""): unknown {
const text = raw.trim();
if (type === "aggregate-report") {
return { report: text, model };
}
if (type === "generate-mind-map") {
return { outline: text, model };
}
const clean = text.replace(/^```(?:json)?\s*/, "").replace(/\s*```$/, "");
return JSON.parse(clean);
}
export function buildMessages(task: TaskRecord): ChatMessage[] {
const p = task.params;
switch (task.type) {
case "aggregate-report": {
@@ -176,19 +426,20 @@ function buildMessages(task: TaskRecord) {
}
}
// ---- TTL 清理 ----
// ---- 生产单例 ----
const TTL_MS = 60 * 60 * 1000; // 1 小时
const CLEANUP_INTERVAL_MS = 5 * 60 * 1000; // 5 分钟
export const taskQueue = new TaskQueue();
setInterval(() => {
const cutoff = Date.now() - TTL_MS;
for (const [id, task] of records) {
if (task.status === "done" || task.status === "failed") {
const completed = task.completedAt ? Date.parse(task.completedAt) : 0;
if (completed > 0 && completed < cutoff) {
records.delete(id);
}
}
}
}, CLEANUP_INTERVAL_MS);
export function createTask(
type: TaskType,
params: Record<string, unknown>,
options: CreateTaskOptions = {},
): CreateTaskResult {
return taskQueue.create(type, params, options);
}
export function getTask(id: string): TaskRecord | undefined {
return taskQueue.get(id);
}
export { LlmError };