# LPT AI 服务(lpt-ai) > TypeScript + Fastify 独立 AI 服务,集成 DeepSeek LLM,为后端提供异步 AI 任务。 > **版本耦合警告**:本服务的 `/ai/tasks` 入参与任务结果字段**直接对接着 lpt-be**。 > 改 `aggregate-report` 的结果字段(曾经把 `report` 字符串改成 `{sessionSummary,expectationVerdict,freeSummary}`) > 或 `generate-mind-map` 的 `reports` 入参形状(曾经从 `string[]` 改成对象数组)时, > 必须同时确认 lpt-be 侧已经能读新形状;否则旧版 lpt-be 读不到字段会**静默降级**,界面无报错。 > 具体做法:两边同分支同环境一起发(`dev` 配 `dev`、`master` 配 `master`),不要跨环境出包。 ## 规则与技能位置 - 通用规则(跨仓库):meta 仓库 `.agents/roles/` - 本仓库专属规则:`roles/` - `roles/task-queue.md`:任务队列设计(含「不要改动的契约」) - `roles/security-and-degradation.md`:安全边界与降级策略 - 本仓库专属技能:本仓库暂无专属技能目录 - Git 提交规范属通用规则,见 meta 仓库 `.agents/roles/commit-convention.md`,本文件不再重复。 ## 技术栈 - 运行时: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 接口,返回正文 + token 用量) │ ├── usage.ts → 用量归一化(null 与 0 区分、跨尝试累加) │ ├── thinking.ts → 按 prompt 长度选思考强度(reasoning_effort) │ ├── retry.ts → 退避重试(哪些错误可重试、等多久) │ ├── prompts.ts → Prompt 模板(4 种任务类型) │ └── prompts.test.ts ├── task-queue.ts → 异步任务队列(Worker 池 + 幂等复用 + 用量归集) ├── task-queue.test.ts └── admin/ ├── index.ts → 管理面板路由 ├── routes.ts ├── store.ts → 日志存储(环形缓冲 + 原子落盘) ├── pricing.ts → 计价(DeepSeek 三档单价 + 峰谷时段) ├── reporter.ts → 用量上报(lpt-ai → lpt-be,本地 outbox 重试) └── balance.ts → 上游余额查询(对账用) ``` ## API 端点(6 个) | 方法 | 路径 | 说明 | |------|------|------| | GET | `/health` | 健康检查(返回 LLM 可用状态和模型名) | | POST | `/ai/tasks` | 提交异步任务(返回 taskId) | | GET | `/ai/tasks/:taskId` | 轮询任务结果 | | POST | `/fetch-title` | 抓取网页标题 | | GET | `/admin` | 管理面板(最近 500 条日志、用量与计价快照) | | GET | `/admin/usage/balance` | 上游账户余额(对账用;未配置时 `configured:false`) | ## 用量统计 用量是「任务级」口径,不是「请求级」:一个任务重试 N 次就是 N 次计费。 - `llm/usage.ts`:把上游 `usage` 归一成 6 个维度(输入/输出/总计/缓存命中/缓存未命中/推理)。 **`null` 表示上游未上报,与「明确上报为 0」不同**,面板上必须区分显示。 - `task-queue.ts`:跨所有尝试累加用量(含失败尝试,如上游 200 但内容为空);`attempts` 是实际发起的调用次数。 - `admin/pricing.ts`:DeepSeek 三档单价(缓存命中/未命中/输出,USD per 1M)+ 峰谷时段。 峰时窗口按 UTC 判定(`01:00-04:00`、`06:00-10:00`,周一至周五),谷时 = 峰时 × 0.5。 计价结果在结算时**冻结进日志快照**,改价不会重算历史账。 - `admin/reporter.ts`:把用量推给 lpt-be(长期账本)。上报失败先落本地 outbox 再重试, 幂等靠 `record_id` 唯一索引;4xx 属于确定性拒绝,丢弃这批并计数,不无限重试。 未配置 `LPT_AI_REPORT_URL` 时为空操作。 - **权威口径在 lpt-be 的 MySQL**;本地面板只是最近 500 条的调试视图。 ### 用量归属(callerRef) lpt-ai 不知道调用方是谁,所以归属标记由调用方带过来:`POST /ai/tasks` 接受顶层可选字段 `callerRef`(lpt-be 传的是用户 id),结算时原样写进用量记录,lpt-be 据此做用户维度报表。 三条硬约束,改动时必须守住: 1. **不放进 `params`** —— 会污染 prompt 模板的输入; 2. **不参与幂等键** —— 否则同一份输入会因为调用方不同而重复调 LLM; 3. **不进入 prompt** —— 它只是记账标记。 复用已有任务时**沿用原任务的 `callerRef`**:那次 LLM 调用只发生了一次,账算在原调用方头上; 复用方没有产生新的 token 消耗,也不会有新的用量记录。 > `/admin` 用 `?token=…` 首次打开时会换发 `HttpOnly` cookie,否则面板 HTML 与它内部的 > `fetch` 是两个独立请求,内部请求会全部 401。详见 `roles/security-and-degradation.md`。 ## 支持的任务类型 | 类型 | 说明 | 温度 | Max Tokens | |------|------|------|------------| | `aggregate-report` | 残片聚合为学习报告 | 0.3 | 2048 | | `generate-mind-map` | 从报告/残片生成思维导图大纲 | 0.3 | 4096 | | `compare-recall` | 用户回忆 vs 标准导图语义对比 | 0.2 | 4096 | | `guidance` | 学习引导多轮对话 | 0.7 | 1024 | | `guidance` | 学习引导单轮追问 | 0.7 | 1024 | > 思考强度(`reasoning_effort`)不按任务类型固定,而是按 **prompt 总字符数**(所有 message 正文之和)自适应: > 低于 `LPT_AI_REASONING_LOW_AT` → `none`(直接关掉思考),之后依次 `low` / `high`,超过 `LPT_AI_REASONING_MAX_AT` → `max`。 > 原因是 DeepSeek 缺省 `high`,不显式指定则短输入也会满档思考。映射实现在 `src/llm/thinking.ts`,阈值见 `.env.example`。 ## 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_REASONING_ENABLED=true # 显式 false 才关闭自适应,回到供应商默认 LPT_AI_REASONING_LOW_AT=500 # 达到该长度起用 low,低于则为 none LPT_AI_REASONING_HIGH_AT=2000 # 达到该长度起用 high LPT_AI_REASONING_MAX_AT=8000 # 达到该长度起用 max # 任务队列(完整注释见 .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) # 用量统计(完整注释见 .env.example) LLM_BALANCE_URL= # 留空按 LLM_API_URL 的 origin 推导 LLM_PRICE_CACHE_HIT_PER_M=0.006 LLM_PRICE_CACHE_MISS_PER_M=0.3 LLM_PRICE_OUTPUT_PER_M=1.2 LLM_PRICE_OFFPEAK_FACTOR=0.5 LLM_PRICE_PEAK_WINDOWS=01:00-04:00,06:00-10:00 LLM_PRICE_PEAK_HOLIDAYS= # 中国法定节假日,每年需要更新 # 用量上报(lpt-ai → lpt-be);留空表示不上报,只保留本地面板 LPT_AI_REPORT_URL= LPT_AI_REPORT_TOKEN= ``` > 部署侧的变量在 `lpt-infra` 的 `dev/`、`prod/` configmap 里;本服务只读环境变量,默认值写在 `src/llm/client.ts` 与 `loadQueueConfig()` 里。 ## 启动命令 ```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-fe` 同规则,**一个分支对一个环境**,靠分支而不是靠参数区分: | 分支 | 环境 | namespace | 镜像 tag | |------|------|-----------|----------| | `dev` | 开发 | `lpt-dev` | `lpt-ai:dev` | | `master` | 生产 | `lpt-prod` | `lpt-ai:prod` | - 发版在 Gitea 上手动触发 `lpt-ai Build & Deploy`(`workflow_dispatch`),选择 `environment`。 - 流水线第一步会校验**分支 ↔ 环境**:从 `dev` 发 `prod`、或从 `master` 发 `dev` 都会被直接拒绝。 - 例外:`main` 仅作为历史分支保留在 `7c751bf`(prod 冻结点),不再用于发版。 - 日常开发在 `dev`;需要上生产时,把 `dev` 合并进 `master`,并**同步升级 lpt-be**(见顶部版本耦合警告)。 ## 关联项目 | 项目 | 路径 | 端口 | 说明 | |------|------|------|------| | 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) ```