Files

9.8 KiB
Raw Permalink Blame History

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 外无其他外部依赖

项目结构

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 配置

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() 里。

启动命令

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 前端,不直接调用本服务

调用关系

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