feat: 任务队列改为并发池并支持幂等复用与退避重试
This commit is contained in:
@@ -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` 运行。
|
||||
|
||||
Reference in New Issue
Block a user