Files
lpt-ai/roles/task-queue.md
T

2.3 KiB

任务队列

  • 功能:定义 lpt-ai 异步任务队列(Worker 池、退避重试、相同输入幂等复用、TTL 清理)的行为与不可改契约。
  • 何时用:改动 /ai/tasks 的提交/轮询、并发度、重试、幂等复用、TTL 清理、管理面板日志,或调整任务响应契约与单次调用参数(温度 / 思考强度)时。

任务队列设计

  • 异步任务模式:submit + poll,避免 LLM 长耗时(10-60s)超时。
  • 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 周期移除过期记录,同时清理幂等索引。
  • 单次调用参数:温度与输出上限按任务类型固定;思考强度(reasoning_effort)按 prompt 总字符数自适应, 短输入直接 none 关掉思考(DeepSeek 缺省 high,不显式指定就会满档思考)。 调用参数不参与幂等键,改阈值不会让已有缓存失效。映射实现在 src/llm/thinking.ts。
  • 异常隔离:单个任务失败不影响后续任务。
  • 管理面板日志:复用 logStore,记录最近 200 条请求/响应。

不要改动的契约

  • /ai/tasks 必须固定返回 201。Java 端 AiServiceClient.submitTask() 把非 201 视为提交失败, 所以不能用 200 表达「复用了已有任务」;复用信息放在响应体的 reused / status 字段里。
  • TaskRecord 的 status / result / error 字段名被 Java 端轮询逻辑依赖,新增字段可以,改名不行。