Files
lpt-ai/AGENTS.md
T

7.5 KiB
Raw Blame History

LPT AI 服务(lpt-ai)

TypeScript + Fastify 独立 AI 服务,集成 DeepSeek LLM,为后端提供异步 AI 任务。

Git 提交规范

  • 提交信息必须简短且使用中文,不要使用英文长句。
  • 格式:类型: 简述,例如 feat: 新增思维导图生成任务、fix: 修复任务队列TTL清理、docs: 补充环境变量说明。

技术栈

  • 运行时:Node.js 20+
  • 框架:Fastify 5
  • LLM:DeepSeek OpenAI 兼容接口(deepseek-flash)
  • 运行时依赖:除 fastify 外无其他外部依赖

项目结构

lpt-ai/src/
├── index.ts          → 服务入口(加载 .env,启动 Fastify)
├── routes/ai.ts      → AI 路由(health, tasks, fetch-title)
├── llm/
│   ├── client.ts     → LLM 客户端(DeepSeek 接口)
│   ├── retry.ts      → 退避重试(哪些错误可重试、等多久)
│   ├── prompts.ts    → Prompt 模板(3 种任务类型)
│   └── prompts.test.ts
├── task-queue.ts     → 异步任务队列(Worker 池 + 幂等复用)
├── task-queue.test.ts
└── admin/
    ├── index.ts      → 管理面板路由
    ├── routes.ts
    └── store.ts      → 日志存储

API 端点(5 个)

方法 路径 说明
GET /health 健康检查(返回 LLM 可用状态和模型名)
POST /ai/tasks 提交异步任务(返回 taskId)
GET /ai/tasks/:taskId 轮询任务结果
POST /fetch-title 抓取网页标题
GET /admin 管理面板(查看最近 200 条日志)

支持的任务类型

类型 说明 温度 Max Tokens
aggregate-report 残片聚合为学习报告 0.3 2048
generate-mind-map 从报告/残片生成思维导图大纲 0.3 4096
compare-recall 用户回忆 vs 标准导图语义对比 0.2 4096

任务队列设计

  • 异步任务模式: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 周期移除过期记录,同时清理幂等索引。
  • 异常隔离:单个任务失败不影响后续任务。
  • 管理面板日志:复用 logStore,记录最近 200 条请求/响应。

不要改动的契约

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

LLM 配置

LLM_API_URL=https://api.deepseek.com/v1/chat/completions
LLM_API_KEY=                    # 必填,未配置时 /health 返回 llmAvailable: false
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   # 已完成结果可被相同请求复用的窗口

# 安全(完整注释见 .env.example)
LPT_AI_TOKEN=                   # 入站令牌:设置后 /ai/* 与 /admin 都要求携带(留空=不校验)
LPT_AI_RATE_LIMIT=30            # 每来源每窗口允许提交的 AI 任务数
LPT_AI_RATE_WINDOW_MS=60000     # 限流窗口
LPT_AI_BODY_LIMIT_BYTES=262144  # 请求体上限
LPT_AI_FETCH_ALLOWED_PORTS=     # 抓取允许的额外端口(默认只有 80/443)

部署侧的变量在 lpt-infra 的 dev/、prod/ configmap 里;本服务只读环境变量,默认值写在 src/llm/client.ts 与 loadQueueConfig() 里。

安全边界

本服务是 ClusterIP 且未被 Traefik 路由,公网不可达;但集群内任何工作负载都能访问它,因此仍有防护:

  • 入站令牌(可选):设置 LPT_AI_TOKEN 后,/ai/* 与 /admin 都要求携带(header x-api-token 或 query token)。 部署清单用 secretKeyRef.optional: true 引用 lpt-secrets/lpt-ai-token,没设这个 key 也能正常启动(此时不校验)。 lpt-be 侧由 lpt.ai-service.token 提供,部署经 LPT_AI-SERVICE_TOKEN 注入。 开发阶段可以不设,保持零摩擦;生产只需往 secret 加一个 key。
  • 限流:/ai/tasks 按来源限流(默认 30 次/分钟),因为是单进程内存计数,属于粗粒度保护,不是精确配额。
  • 抓取加固:/fetch-title 的目标由调用方给出,抓取前做四层校验 —— 协议白名单、端口白名单、DNS 解析后逐个校验(防解析到内网与 DNS rebinding)、重定向逐跳校验(防「首跳合法、次跳内网」);响应体截断到 512 KiB,且只在网页类型上取标题。
  • /admin 面板会展示完整 prompt 与学习内容,未设置令牌时会启动告警提示。

/fetch-title 当前全工作区零调用(lpt-fe 走的是 lpt-be 的 /utils/fetch-title,用 Java 侧 TitleFetcher)。 保留它是为了满足安全条目的验收;如需精简可连同本文件的抓取工具一并删除。

降级策略

  • LLM API Key 未配置 → /health 返回 llmAvailable: false。
  • 后端(lpt-be)检测到 AI 不可用 → 自动切换到内置规则引擎(BuiltinMindMapGenerator)。
  • Java 后端是唯一调用方;本服务不直接暴露给前端(Service 是 ClusterIP,且 Traefik 未路由本服务)。

启动命令

npm install
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 运行。
  • 暴露端口:5199。
  • 健康检查:curl http://localhost:5199/health。

关联项目

项目 路径 端口 说明
lpt-be ../lpt-be/ 5157 Spring Boot 后端,通过 lpt.ai-service.url 调用本服务
lpt-fe ../lpt-fe/ 5158 Vue 3 前端,不直接调用本服务

调用关系

lpt-be (5157) ──HTTP POST /ai/tasks──→ lpt-ai (5199)
lpt-be (5157) ──HTTP GET  /ai/tasks/:id──→ lpt-ai (5199)