117 lines
4.4 KiB
Markdown
117 lines
4.4 KiB
Markdown
# LPT AI 服务(lpt-ai)
|
||
|
||
> TypeScript + Fastify 独立 AI 服务,集成 DeepSeek LLM,为后端提供异步 AI 任务。
|
||
|
||
## 规则与技能位置
|
||
|
||
- 通用规则(跨仓库):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 接口)
|
||
│ ├── 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 |
|
||
|
||
## 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 # 已完成结果可被相同请求复用的窗口
|
||
|
||
# 安全(完整注释见 .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()` 里。
|
||
|
||
## 启动命令
|
||
|
||
```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)
|
||
```
|