# 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 外无其他外部依赖 ## 项目结构 ```text 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 配置 ```env 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 # 已完成结果可被相同请求复用的窗口 ``` > 部署侧的变量在 `lpt-infra` 的 `dev/`、`prod/` configmap 里;本服务只读环境变量,默认值写在 `src/llm/client.ts` 与 `loadQueueConfig()` 里。 ## 降级策略 - LLM API Key 未配置 → `/health` 返回 `llmAvailable: false`。 - 后端(lpt-be)检测到 AI 不可用 → 自动切换到内置规则引擎(`BuiltinMindMapGenerator`)。 - Java 后端是唯一调用方;本服务不直接暴露给前端,不做鉴权(部署在内网)。 ## 启动命令 ```bash 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 前端,不直接调用本服务 | ## 调用关系 ```text lpt-be (5157) ──HTTP POST /ai/tasks──→ lpt-ai (5199) lpt-be (5157) ──HTTP GET /ai/tasks/:id──→ lpt-ai (5199) ```