feat: 任务队列改为并发池并支持幂等复用与退避重试
This commit is contained in:
+20
-4
@@ -1,11 +1,27 @@
|
||||
# LLM 提供商配置(SiliconFlow OpenAI 兼容接口)
|
||||
LLM_API_URL=https://api.siliconflow.cn/v1/chat/completions
|
||||
# LLM 提供商配置(DeepSeek OpenAI 兼容接口)
|
||||
LLM_API_URL=https://api.deepseek.com/v1/chat/completions
|
||||
# API Key(必填,未配置时服务返回 503)
|
||||
LLM_API_KEY=
|
||||
# 模型名(32B 级别即可满足残片聚合需求)
|
||||
LLM_MODEL=Qwen/Qwen2.5-32B-Instruct
|
||||
# 模型名(轻量快速即可满足残片聚合需求)
|
||||
LLM_MODEL=deepseek-flash
|
||||
# 请求超时(毫秒)
|
||||
LLM_TIMEOUT_MS=60000
|
||||
|
||||
# 服务端口
|
||||
PORT=5199
|
||||
|
||||
# ---- 任务队列 ----
|
||||
# 并发处理的任务数。设得越高吞吐越高,但要注意 LLM 服务商的限流配额
|
||||
LPT_AI_CONCURRENCY=2
|
||||
# 单个任务的总尝试次数(含首次);1 表示不重试
|
||||
LPT_AI_MAX_ATTEMPTS=3
|
||||
# 退避重试的首次等待(毫秒),之后按 2 倍增长
|
||||
LPT_AI_RETRY_BASE_MS=1000
|
||||
# 单次退避上限(毫秒)
|
||||
LPT_AI_RETRY_MAX_MS=20000
|
||||
# 完成记录的保留时长(毫秒)
|
||||
LPT_AI_TTL_MS=3600000
|
||||
# 已完成结果可被相同请求复用的时间窗口(毫秒)
|
||||
LPT_AI_RESULT_CACHE_MS=600000
|
||||
# 过期记录清理间隔(毫秒)
|
||||
LPT_AI_CLEANUP_MS=300000
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# LPT AI 服务(lpt-ai)
|
||||
|
||||
> TypeScript + Fastify 独立 AI 服务,集成 SiliconFlow LLM,为后端提供异步 AI 任务。
|
||||
> TypeScript + Fastify 独立 AI 服务,集成 DeepSeek LLM,为后端提供异步 AI 任务。
|
||||
|
||||
## Git 提交规范
|
||||
|
||||
@@ -11,7 +11,7 @@
|
||||
|
||||
- 运行时:Node.js 20+
|
||||
- 框架:Fastify 5
|
||||
- LLM:DeepSeek OpenAI 兼容接口(deepseek-flash / DeepSeek-V4.1-Flash)
|
||||
- LLM:DeepSeek OpenAI 兼容接口(`deepseek-flash`)
|
||||
- 运行时依赖:除 fastify 外无其他外部依赖
|
||||
|
||||
## 项目结构
|
||||
@@ -21,10 +21,12 @@ lpt-ai/src/
|
||||
├── index.ts → 服务入口(加载 .env,启动 Fastify)
|
||||
├── routes/ai.ts → AI 路由(health, tasks, fetch-title)
|
||||
├── llm/
|
||||
│ ├── client.ts → LLM 客户端(SiliconFlow 接口)
|
||||
│ ├── client.ts → LLM 客户端(DeepSeek 接口)
|
||||
│ ├── retry.ts → 退避重试(哪些错误可重试、等多久)
|
||||
│ ├── prompts.ts → Prompt 模板(3 种任务类型)
|
||||
│ └── prompts.test.ts
|
||||
├── task-queue.ts → 异步任务队列
|
||||
├── task-queue.ts → 异步任务队列(Worker 池 + 幂等复用)
|
||||
├── task-queue.test.ts
|
||||
└── admin/
|
||||
├── index.ts → 管理面板路由
|
||||
├── routes.ts
|
||||
@@ -52,11 +54,26 @@ lpt-ai/src/
|
||||
## 任务队列设计
|
||||
|
||||
- 异步任务模式:submit + poll,避免 LLM 长耗时(10-60s)超时。
|
||||
- 单线程 Worker:`setImmediate` 链,同一时刻只处理一个 LLM 调用,防止 API 限流。
|
||||
- TTL 清理:5 分钟一次,移除完成超过 1 小时的记录。
|
||||
- **Worker 池**:并发度由 `LPT_AI_CONCURRENCY` 控制(默认 2)。
|
||||
不要改回单 worker 串行:N 个请求会等 N × LLM 耗时,客户端会先超时。
|
||||
- **退避重试**:429 / 5xx / 超时等瞬时抖动会重试(`LPT_AI_MAX_ATTEMPTS`,默认 3),
|
||||
4xx 客户端错误与「API Key 未配置」不重试。服务端返回的 `Retry-After` 优先于自算退避。
|
||||
- **相同输入复用**:以 `type + params` 的稳定哈希为幂等键。
|
||||
- 同键任务 pending/running → 合并为同一个任务,不重复调用 LLM(不重复计费)
|
||||
- 同键任务已完成且在 `LPT_AI_RESULT_CACHE_MS` 窗口内 → 复用结果
|
||||
- 同键任务已失败 → 新建(失败必须可重试)
|
||||
- 请求体传 `force: true` 可跳过复用(用户主动「重新生成」)
|
||||
- 也可传 `idempotencyKey` 显式指定幂等键
|
||||
- TTL 清理:按 `LPT_AI_CLEANUP_MS` 周期移除过期记录,同时清理幂等索引。
|
||||
- 异常隔离:单个任务失败不影响后续任务。
|
||||
- 管理面板日志:复用 `logStore`,记录最近 200 条请求/响应。
|
||||
|
||||
### 不要改动的契约
|
||||
|
||||
- `/ai/tasks` **必须固定返回 201**。Java 端 `AiServiceClient.submitTask()` 把非 201 视为提交失败,
|
||||
所以不能用 200 表达「复用了已有任务」;复用信息放在响应体的 `reused` / `status` 字段里。
|
||||
- `TaskRecord` 的 `status` / `result` / `error` 字段名被 Java 端轮询逻辑依赖,新增字段可以,改名不行。
|
||||
|
||||
## LLM 配置
|
||||
|
||||
```env
|
||||
@@ -65,8 +82,17 @@ LLM_API_KEY= # 必填,未配置时 /health 返回 llmAvaila
|
||||
LLM_MODEL=deepseek-flash
|
||||
LLM_TIMEOUT_MS=60000 # 单次 LLM 调用超时
|
||||
PORT=5199
|
||||
|
||||
# 任务队列(完整注释见 .env.example)
|
||||
LPT_AI_CONCURRENCY=2 # Worker 池并发度
|
||||
LPT_AI_MAX_ATTEMPTS=3 # 单任务总尝试次数(含首次)
|
||||
LPT_AI_RETRY_BASE_MS=1000 # 退避首次等待,之后 ×2
|
||||
LPT_AI_RETRY_MAX_MS=20000 # 单次退避上限
|
||||
LPT_AI_RESULT_CACHE_MS=600000 # 已完成结果可被相同请求复用的窗口
|
||||
```
|
||||
|
||||
> 部署侧的变量在 `lpt-infra` 的 `dev/`、`prod/` configmap 里;本服务只读环境变量,默认值写在 `src/llm/client.ts` 与 `loadQueueConfig()` 里。
|
||||
|
||||
## 降级策略
|
||||
|
||||
- LLM API Key 未配置 → `/health` 返回 `llmAvailable: false`。
|
||||
@@ -81,8 +107,12 @@ npm run dev # 开发模式(tsx watch,热重载)
|
||||
npm run build # 编译 TypeScript
|
||||
npm run start # 生产模式
|
||||
npm run test # 测试
|
||||
npm run typecheck # 同时校验 src 与测试文件
|
||||
```
|
||||
|
||||
> `tsconfig.json` 排除 `*.test.ts`(不入打包产物),因此测试的类型检查走单独的 `tsconfig.test.json`;
|
||||
> 新增测试后靠 `npm run typecheck` 把关,不要只跑 `tsc --noEmit`。
|
||||
|
||||
## Docker
|
||||
|
||||
- 多阶段构建:`node:20-alpine` 编译 → `node:20-alpine` 运行。
|
||||
|
||||
+2
-2
@@ -9,7 +9,7 @@
|
||||
"build": "tsc",
|
||||
"start": "node --env-file=.env dist/index.js",
|
||||
"test": "vitest run",
|
||||
"typecheck": "tsc --noEmit"
|
||||
"typecheck": "tsc --noEmit && tsc -p tsconfig.test.json"
|
||||
},
|
||||
"dependencies": {
|
||||
"fastify": "^5.2.0"
|
||||
@@ -23,4 +23,4 @@
|
||||
"engines": {
|
||||
"node": ">=20"
|
||||
}
|
||||
}
|
||||
}
|
||||
+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;
|
||||
}
|
||||
+21
-4
@@ -17,8 +17,17 @@ export async function aiRoutes(app: FastifyInstance): Promise<void> {
|
||||
}));
|
||||
|
||||
/** 提交 AI 任务,立即返回 taskId */
|
||||
app.post<{ Body: { type: string; params: Record<string, unknown> } }>("/ai/tasks", async (request, reply) => {
|
||||
const { type, params } = request.body ?? {};
|
||||
app.post<{
|
||||
Body: {
|
||||
type: string;
|
||||
params: Record<string, unknown>;
|
||||
/** 可选:显式幂等键,用于跨请求去重 */
|
||||
idempotencyKey?: string;
|
||||
/** 可选:跳过结果复用,强制重新生成 */
|
||||
force?: boolean;
|
||||
};
|
||||
}>("/ai/tasks", async (request, reply) => {
|
||||
const { type, params, idempotencyKey, force } = request.body ?? {};
|
||||
|
||||
if (!type || !["aggregate-report", "generate-mind-map", "compare-recall"].includes(type)) {
|
||||
return reply.status(400).send({ error: "无效的 type,允许: aggregate-report, generate-mind-map, compare-recall" });
|
||||
@@ -27,8 +36,16 @@ export async function aiRoutes(app: FastifyInstance): Promise<void> {
|
||||
return reply.status(400).send({ error: "params 必须为非空对象" });
|
||||
}
|
||||
|
||||
const taskId = createTask(type as TaskType, params as Record<string, unknown>);
|
||||
return reply.status(201).send({ taskId });
|
||||
const created = createTask(type as TaskType, params as Record<string, unknown>, {
|
||||
...(typeof idempotencyKey === "string" && idempotencyKey.trim().length > 0
|
||||
? { idempotencyKey }
|
||||
: {}),
|
||||
...(force === true ? { force: true } : {}),
|
||||
});
|
||||
|
||||
// 固定返回 201:Java 端 AiServiceClient 把非 201 当作提交失败,
|
||||
// 所以不能改用 200 表达「复用」。复用信息放在响应体里。
|
||||
return reply.status(201).send(created);
|
||||
});
|
||||
|
||||
/** 查询任务状态与结果 */
|
||||
|
||||
@@ -0,0 +1,496 @@
|
||||
import { describe, expect, it } from "vitest";
|
||||
import { LlmError } from "./llm/client.js";
|
||||
import { TaskQueue, computeTaskKey, loadQueueConfig, type QueueConfig, type TaskRecord } from "./task-queue.js";
|
||||
|
||||
/** 测试用队列:不碰真实 LLM、不写管理面板日志、不启定时器 */
|
||||
function makeQueue(
|
||||
overrides: Partial<QueueConfig> = {},
|
||||
runOnce?: (task: TaskRecord) => Promise<unknown>,
|
||||
): TaskQueue {
|
||||
return new TaskQueue({
|
||||
config: {
|
||||
concurrency: 2,
|
||||
maxAttempts: 3,
|
||||
retryBaseMs: 1,
|
||||
retryMaxMs: 10,
|
||||
ttlMs: 60_000,
|
||||
cleanupIntervalMs: 60_000,
|
||||
resultCacheMs: 10_000,
|
||||
...overrides,
|
||||
},
|
||||
enableCleanup: false,
|
||||
isLlmAvailable: () => true,
|
||||
sleep: async () => {},
|
||||
onSettled: () => {},
|
||||
...(runOnce ? { runOnce: async (task) => runOnce(task) } : {}),
|
||||
});
|
||||
}
|
||||
|
||||
function ok(params: Record<string, unknown> = { taskName: "t", fragments: [] }) {
|
||||
return params;
|
||||
}
|
||||
|
||||
describe("loadQueueConfig", () => {
|
||||
it("缺省值可用", () => {
|
||||
const config = loadQueueConfig({});
|
||||
expect(config.concurrency).toBe(2);
|
||||
expect(config.maxAttempts).toBe(3);
|
||||
expect(config.resultCacheMs).toBe(600_000);
|
||||
});
|
||||
|
||||
it("环境变量可覆盖", () => {
|
||||
const config = loadQueueConfig({
|
||||
LPT_AI_CONCURRENCY: "5",
|
||||
LPT_AI_MAX_ATTEMPTS: "7",
|
||||
LPT_AI_RETRY_BASE_MS: "250",
|
||||
});
|
||||
expect(config.concurrency).toBe(5);
|
||||
expect(config.maxAttempts).toBe(7);
|
||||
expect(config.retryBaseMs).toBe(250);
|
||||
});
|
||||
|
||||
it("非法值回退到缺省", () => {
|
||||
const config = loadQueueConfig({ LPT_AI_CONCURRENCY: "-1", LPT_AI_MAX_ATTEMPTS: "abc" });
|
||||
expect(config.concurrency).toBe(2);
|
||||
expect(config.maxAttempts).toBe(3);
|
||||
});
|
||||
});
|
||||
|
||||
describe("computeTaskKey", () => {
|
||||
it("同输入得到同键", () => {
|
||||
const a = computeTaskKey("aggregate-report", { taskName: "t", fragments: [{ content: "x" }] });
|
||||
const b = computeTaskKey("aggregate-report", { taskName: "t", fragments: [{ content: "x" }] });
|
||||
expect(a).toBe(b);
|
||||
});
|
||||
|
||||
it("对象键顺序不影响结果", () => {
|
||||
const a = computeTaskKey("compare-recall", { taskName: "t", standardOutline: "s" });
|
||||
const b = computeTaskKey("compare-recall", { standardOutline: "s", taskName: "t" });
|
||||
expect(a).toBe(b);
|
||||
});
|
||||
|
||||
it("参数不同则键不同", () => {
|
||||
const a = computeTaskKey("aggregate-report", { taskName: "t", fragments: [{ content: "x" }] });
|
||||
const b = computeTaskKey("aggregate-report", { taskName: "t", fragments: [{ content: "y" }] });
|
||||
expect(a).not.toBe(b);
|
||||
});
|
||||
|
||||
it("类型不同则键不同", () => {
|
||||
const a = computeTaskKey("aggregate-report", { taskName: "t" });
|
||||
const b = computeTaskKey("generate-mind-map", { taskName: "t" });
|
||||
expect(a).not.toBe(b);
|
||||
});
|
||||
});
|
||||
|
||||
describe("TaskQueue 并发", () => {
|
||||
it("并发度内的任务同时执行,不再串行", async () => {
|
||||
let inFlight = 0;
|
||||
let maxInFlight = 0;
|
||||
const started: string[] = [];
|
||||
|
||||
const queue = makeQueue({ concurrency: 3 }, async (task) => {
|
||||
inFlight += 1;
|
||||
maxInFlight = Math.max(maxInFlight, inFlight);
|
||||
started.push(task.id);
|
||||
await new Promise((resolve) => setTimeout(resolve, 20));
|
||||
inFlight -= 1;
|
||||
return { ok: true };
|
||||
});
|
||||
|
||||
for (let i = 0; i < 3; i += 1) {
|
||||
queue.create("aggregate-report", { taskName: `t${i}`, fragments: [{ content: `c${i}` }] });
|
||||
}
|
||||
await queue.drain();
|
||||
|
||||
// 三个任务应同时在跑,而不是一个个来
|
||||
expect(maxInFlight).toBe(3);
|
||||
expect(started).toHaveLength(3);
|
||||
queue.stop();
|
||||
});
|
||||
|
||||
it("超出并发度的任务排队等待", async () => {
|
||||
let inFlight = 0;
|
||||
let maxInFlight = 0;
|
||||
|
||||
const queue = makeQueue({ concurrency: 2 }, async () => {
|
||||
inFlight += 1;
|
||||
maxInFlight = Math.max(maxInFlight, inFlight);
|
||||
await new Promise((resolve) => setTimeout(resolve, 15));
|
||||
inFlight -= 1;
|
||||
return { ok: true };
|
||||
});
|
||||
|
||||
for (let i = 0; i < 6; i += 1) {
|
||||
queue.create("aggregate-report", { taskName: `t${i}`, fragments: [{ content: `c${i}` }] });
|
||||
}
|
||||
await queue.drain();
|
||||
|
||||
expect(maxInFlight).toBe(2);
|
||||
queue.stop();
|
||||
});
|
||||
|
||||
it("并发 N 个任务的总耗时明显小于串行累加", async () => {
|
||||
const perTaskMs = 30;
|
||||
const n = 6;
|
||||
|
||||
const queue = makeQueue({ concurrency: n }, async () => {
|
||||
await new Promise((resolve) => setTimeout(resolve, perTaskMs));
|
||||
return { ok: true };
|
||||
});
|
||||
|
||||
const t0 = Date.now();
|
||||
for (let i = 0; i < n; i += 1) {
|
||||
queue.create("aggregate-report", { taskName: `t${i}`, fragments: [{ content: `c${i}` }] });
|
||||
}
|
||||
await queue.drain();
|
||||
const elapsed = Date.now() - t0;
|
||||
|
||||
// 串行需要 n * perTaskMs;并发后应接近单次耗时
|
||||
expect(elapsed).toBeLessThan(perTaskMs * n * 0.6);
|
||||
queue.stop();
|
||||
});
|
||||
|
||||
it("drain 在队列空闲时立即返回", async () => {
|
||||
const queue = makeQueue();
|
||||
await queue.drain();
|
||||
expect(queue.pendingCount).toBe(0);
|
||||
queue.stop();
|
||||
});
|
||||
});
|
||||
|
||||
describe("TaskQueue 相同输入复用", () => {
|
||||
it("进行中的相同请求被合并,不重复执行", async () => {
|
||||
let calls = 0;
|
||||
const queue = makeQueue({ concurrency: 1 }, async () => {
|
||||
calls += 1;
|
||||
await new Promise((resolve) => setTimeout(resolve, 20));
|
||||
return { ok: true };
|
||||
});
|
||||
|
||||
const params = { taskName: "t", fragments: [{ content: "same" }] };
|
||||
const first = queue.create("aggregate-report", params);
|
||||
const second = queue.create("aggregate-report", params);
|
||||
|
||||
expect(second.taskId).toBe(first.taskId);
|
||||
expect(second.reused).toBe(true);
|
||||
expect(second.status).toBe("pending");
|
||||
|
||||
await queue.drain();
|
||||
expect(calls).toBe(1);
|
||||
queue.stop();
|
||||
});
|
||||
|
||||
it("参数不同则各自新建", async () => {
|
||||
const queue = makeQueue({}, async () => ({ ok: true }));
|
||||
const a = queue.create("aggregate-report", { taskName: "t", fragments: [{ content: "a" }] });
|
||||
const b = queue.create("aggregate-report", { taskName: "t", fragments: [{ content: "b" }] });
|
||||
expect(a.taskId).not.toBe(b.taskId);
|
||||
expect(b.reused).toBe(false);
|
||||
await queue.drain();
|
||||
queue.stop();
|
||||
});
|
||||
|
||||
it("已完成且在窗口内的结果被复用", async () => {
|
||||
let calls = 0;
|
||||
const queue = makeQueue({}, async () => {
|
||||
calls += 1;
|
||||
return { value: calls };
|
||||
});
|
||||
const params = { taskName: "t", fragments: [{ content: "same" }] };
|
||||
|
||||
const first = queue.create("aggregate-report", params);
|
||||
await queue.drain();
|
||||
|
||||
const second = queue.create("aggregate-report", params);
|
||||
expect(second.taskId).toBe(first.taskId);
|
||||
expect(second.reused).toBe(true);
|
||||
expect(second.status).toBe("done");
|
||||
expect(calls).toBe(1);
|
||||
queue.stop();
|
||||
});
|
||||
|
||||
it("超出结果复用窗口后重新执行", async () => {
|
||||
let nowMs = 1_000_000;
|
||||
let calls = 0;
|
||||
const queue = new TaskQueue({
|
||||
config: {
|
||||
concurrency: 1,
|
||||
maxAttempts: 1,
|
||||
retryBaseMs: 1,
|
||||
retryMaxMs: 10,
|
||||
ttlMs: 10_000_000,
|
||||
cleanupIntervalMs: 60_000,
|
||||
resultCacheMs: 5_000,
|
||||
},
|
||||
enableCleanup: false,
|
||||
isLlmAvailable: () => true,
|
||||
sleep: async () => {},
|
||||
onSettled: () => {},
|
||||
now: () => nowMs,
|
||||
runOnce: async () => {
|
||||
calls += 1;
|
||||
return { value: calls };
|
||||
},
|
||||
});
|
||||
|
||||
const params = { taskName: "t", fragments: [{ content: "same" }] };
|
||||
queue.create("aggregate-report", params);
|
||||
await queue.drain();
|
||||
|
||||
nowMs += 10_000; // 超过窗口
|
||||
const again = queue.create("aggregate-report", params);
|
||||
await queue.drain();
|
||||
|
||||
expect(again.reused).toBe(false);
|
||||
expect(calls).toBe(2);
|
||||
queue.stop();
|
||||
});
|
||||
|
||||
it("失败的任务不进入复用,用户能重试", async () => {
|
||||
let calls = 0;
|
||||
const queue = makeQueue({ maxAttempts: 1 }, async () => {
|
||||
calls += 1;
|
||||
throw new LlmError("上游 400", 400);
|
||||
});
|
||||
const params = { taskName: "t", fragments: [{ content: "same" }] };
|
||||
|
||||
const first = queue.create("aggregate-report", params);
|
||||
await queue.drain();
|
||||
expect(queue.get(first.taskId)?.status).toBe("failed");
|
||||
|
||||
const second = queue.create("aggregate-report", params);
|
||||
await queue.drain();
|
||||
expect(second.reused).toBe(false);
|
||||
expect(calls).toBe(2);
|
||||
queue.stop();
|
||||
});
|
||||
|
||||
it("force 强制新建,跳过复用", async () => {
|
||||
let calls = 0;
|
||||
const queue = makeQueue({}, async () => {
|
||||
calls += 1;
|
||||
return { value: calls };
|
||||
});
|
||||
const params = { taskName: "t", fragments: [{ content: "same" }] };
|
||||
|
||||
queue.create("aggregate-report", params);
|
||||
await queue.drain();
|
||||
const forced = queue.create("aggregate-report", params, { force: true });
|
||||
await queue.drain();
|
||||
|
||||
expect(forced.reused).toBe(false);
|
||||
expect(calls).toBe(2);
|
||||
queue.stop();
|
||||
});
|
||||
|
||||
it("显式幂等键可跨不同参数去重", async () => {
|
||||
let calls = 0;
|
||||
const queue = makeQueue({}, async () => {
|
||||
calls += 1;
|
||||
return { ok: true };
|
||||
});
|
||||
|
||||
const first = queue.create("aggregate-report", { taskName: "a", fragments: [] }, { idempotencyKey: "k1" });
|
||||
const second = queue.create("aggregate-report", { taskName: "b", fragments: [] }, { idempotencyKey: "k1" });
|
||||
await queue.drain();
|
||||
|
||||
expect(second.taskId).toBe(first.taskId);
|
||||
expect(calls).toBe(1);
|
||||
queue.stop();
|
||||
});
|
||||
});
|
||||
|
||||
describe("TaskQueue 重试", () => {
|
||||
it("429 抖动后成功,任务最终为 done 而不是 failed", async () => {
|
||||
let calls = 0;
|
||||
const queue = makeQueue({ maxAttempts: 3 }, async () => {
|
||||
calls += 1;
|
||||
if (calls < 3) throw new LlmError("限流", 429);
|
||||
return { ok: true };
|
||||
});
|
||||
|
||||
const created = queue.create("aggregate-report", { taskName: "t", fragments: [] });
|
||||
await queue.drain();
|
||||
|
||||
const task = queue.get(created.taskId);
|
||||
expect(task?.status).toBe("done");
|
||||
expect(calls).toBe(3);
|
||||
expect(task?.attempts).toBe(3);
|
||||
queue.stop();
|
||||
});
|
||||
|
||||
it("不可重试错误只尝试一次", async () => {
|
||||
let calls = 0;
|
||||
const queue = makeQueue({ maxAttempts: 5 }, async () => {
|
||||
calls += 1;
|
||||
throw new LlmError("请求体非法", 400);
|
||||
});
|
||||
|
||||
const created = queue.create("aggregate-report", { taskName: "t", fragments: [] });
|
||||
await queue.drain();
|
||||
|
||||
expect(queue.get(created.taskId)?.status).toBe("failed");
|
||||
expect(calls).toBe(1);
|
||||
queue.stop();
|
||||
});
|
||||
|
||||
it("重试用尽后为 failed", async () => {
|
||||
let calls = 0;
|
||||
const queue = makeQueue({ maxAttempts: 2 }, async () => {
|
||||
calls += 1;
|
||||
throw new LlmError("上游挂了", 503);
|
||||
});
|
||||
|
||||
const created = queue.create("aggregate-report", { taskName: "t", fragments: [] });
|
||||
await queue.drain();
|
||||
|
||||
const task = queue.get(created.taskId);
|
||||
expect(task?.status).toBe("failed");
|
||||
expect(task?.error).toContain("上游挂了");
|
||||
expect(calls).toBe(2);
|
||||
queue.stop();
|
||||
});
|
||||
|
||||
it("LLM 不可用时直接失败,不空跑重试", async () => {
|
||||
let calls = 0;
|
||||
const queue = new TaskQueue({
|
||||
config: {
|
||||
concurrency: 1,
|
||||
maxAttempts: 3,
|
||||
retryBaseMs: 1,
|
||||
retryMaxMs: 10,
|
||||
ttlMs: 60_000,
|
||||
cleanupIntervalMs: 60_000,
|
||||
resultCacheMs: 10_000,
|
||||
},
|
||||
enableCleanup: false,
|
||||
isLlmAvailable: () => false,
|
||||
sleep: async () => {},
|
||||
onSettled: () => {},
|
||||
runOnce: async () => {
|
||||
calls += 1;
|
||||
return { ok: true };
|
||||
},
|
||||
});
|
||||
|
||||
const created = queue.create("aggregate-report", { taskName: "t", fragments: [] });
|
||||
await queue.drain();
|
||||
|
||||
const task = queue.get(created.taskId);
|
||||
expect(task?.status).toBe("failed");
|
||||
expect(task?.error).toContain("API Key");
|
||||
expect(calls).toBe(0);
|
||||
queue.stop();
|
||||
});
|
||||
});
|
||||
|
||||
describe("TaskQueue 清理", () => {
|
||||
it("只清理过期的完成记录,进行中的不动", async () => {
|
||||
let nowMs = 1_000_000;
|
||||
const queue = new TaskQueue({
|
||||
config: {
|
||||
concurrency: 1,
|
||||
maxAttempts: 1,
|
||||
retryBaseMs: 1,
|
||||
retryMaxMs: 10,
|
||||
ttlMs: 1_000,
|
||||
cleanupIntervalMs: 60_000,
|
||||
resultCacheMs: 10,
|
||||
},
|
||||
enableCleanup: false,
|
||||
isLlmAvailable: () => true,
|
||||
sleep: async () => {},
|
||||
onSettled: () => {},
|
||||
now: () => nowMs,
|
||||
runOnce: async () => ({ ok: true }),
|
||||
});
|
||||
|
||||
const created = queue.create("aggregate-report", { taskName: "t", fragments: [] });
|
||||
await queue.drain();
|
||||
expect(queue.size()).toBe(1);
|
||||
|
||||
nowMs += 5_000;
|
||||
const removed = queue.cleanup();
|
||||
|
||||
expect(removed).toBe(1);
|
||||
expect(queue.size()).toBe(0);
|
||||
expect(queue.get(created.taskId)).toBeUndefined();
|
||||
queue.stop();
|
||||
});
|
||||
|
||||
it("清理后同输入可以重新提交,不会命中已删记录的索引", async () => {
|
||||
let nowMs = 1_000_000;
|
||||
let calls = 0;
|
||||
const queue = new TaskQueue({
|
||||
config: {
|
||||
concurrency: 1,
|
||||
maxAttempts: 1,
|
||||
retryBaseMs: 1,
|
||||
retryMaxMs: 10,
|
||||
ttlMs: 1_000,
|
||||
cleanupIntervalMs: 60_000,
|
||||
resultCacheMs: 10,
|
||||
},
|
||||
enableCleanup: false,
|
||||
isLlmAvailable: () => true,
|
||||
sleep: async () => {},
|
||||
onSettled: () => {},
|
||||
now: () => nowMs,
|
||||
runOnce: async () => {
|
||||
calls += 1;
|
||||
return { value: calls };
|
||||
},
|
||||
});
|
||||
|
||||
const params = { taskName: "t", fragments: [{ content: "x" }] };
|
||||
queue.create("aggregate-report", params);
|
||||
await queue.drain();
|
||||
|
||||
nowMs += 5_000;
|
||||
queue.cleanup();
|
||||
|
||||
const again = queue.create("aggregate-report", params);
|
||||
await queue.drain();
|
||||
|
||||
expect(again.reused).toBe(false);
|
||||
expect(calls).toBe(2);
|
||||
queue.stop();
|
||||
});
|
||||
});
|
||||
|
||||
describe("TaskQueue 基本行为", () => {
|
||||
it("get 返回拷贝,外部修改不影响内部状态", async () => {
|
||||
const queue = makeQueue({}, async () => ({ ok: true }));
|
||||
const created = queue.create("aggregate-report", ok());
|
||||
await queue.drain();
|
||||
|
||||
const task = queue.get(created.taskId);
|
||||
expect(task).toBeDefined();
|
||||
if (task) {
|
||||
task.status = "failed";
|
||||
}
|
||||
expect(queue.get(created.taskId)?.status).toBe("done");
|
||||
queue.stop();
|
||||
});
|
||||
|
||||
it("不存在的任务返回 undefined", () => {
|
||||
const queue = makeQueue();
|
||||
expect(queue.get("nope")).toBeUndefined();
|
||||
queue.stop();
|
||||
});
|
||||
|
||||
it("任务记录带类型、参数、尝试次数与时间戳", async () => {
|
||||
const queue = makeQueue({}, async () => ({ ok: true }));
|
||||
const params = { taskName: "Java 并发", fragments: [{ content: "x" }] };
|
||||
const created = queue.create("aggregate-report", params);
|
||||
await queue.drain();
|
||||
|
||||
const task = queue.get(created.taskId);
|
||||
expect(task?.type).toBe("aggregate-report");
|
||||
expect(task?.params).toEqual(params);
|
||||
expect(task?.attempts).toBe(1);
|
||||
expect(Number.isNaN(Date.parse(task?.createdAt ?? ""))).toBe(false);
|
||||
expect(Number.isNaN(Date.parse(task?.completedAt ?? ""))).toBe(false);
|
||||
queue.stop();
|
||||
});
|
||||
});
|
||||
+357
-106
@@ -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 };
|
||||
|
||||
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"extends": "./tsconfig.json",
|
||||
"compilerOptions": {
|
||||
"noEmit": true
|
||||
},
|
||||
"include": ["src/**/*"],
|
||||
"exclude": ["node_modules", "dist"]
|
||||
}
|
||||
Reference in New Issue
Block a user