114 lines
3.5 KiB
Markdown
114 lines
3.5 KiB
Markdown
# LPT AI 服务（lpt-ai）
|
||
|
||
> TypeScript + Fastify 独立 AI 服务，集成 SiliconFlow LLM，为后端提供异步 AI 任务
|
||
|
||
## Git 提交规范
|
||
- 提交信息使用**中文**，简洁描述变更内容
|
||
- 格式：`类型: 简述`，如 `feat: 新增思维导图生成任务`、`fix: 修复任务队列TTL清理`、`docs: 补充环境变量说明`
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
- **运行时**: Node.js 20+
|
||
- **框架**: Fastify 5
|
||
- **LLM**: SiliconFlow OpenAI 兼容接口（Qwen/Qwen2.5-32B-Instruct）
|
||
- **依赖**: 零外部依赖（除 fastify）
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
```
|
||
lpt-ai/src/
|
||
├── index.ts → 服务入口（加载 .env，启动 Fastify）
|
||
├── routes/ai.ts → AI 路由（health, tasks, fetch-title）
|
||
├── llm/
|
||
│ ├── client.ts → LLM 客户端（SiliconFlow 接口）
|
||
│ ├── prompts.ts → Prompt 模板（3种任务类型）
|
||
│ └── prompts.test.ts
|
||
├── task-queue.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**: `setImmediate` 链，同一时刻只处理一个 LLM 调用，防止 API 限流
|
||
- **TTL 清理**: 5 分钟一次，移除完成超过 1 小时的记录
|
||
- **异常隔离**: 单个任务失败不影响后续任务
|
||
- **管理面板日志**: 复用 `logStore`，记录最近 200 条请求/响应
|
||
|
||
---
|
||
|
||
## LLM 配置
|
||
|
||
### 环境变量（`.env`）
|
||
```env
|
||
LLM_API_URL=https://api.siliconflow.cn/v1/chat/completions
|
||
LLM_API_KEY= # 必填，未配置时 /health 返回 llmAvailable: false
|
||
LLM_MODEL=Qwen/Qwen2.5-32B-Instruct
|
||
LLM_TIMEOUT_MS=60000 # 单次 LLM 调用超时
|
||
PORT=5199
|
||
```
|
||
|
||
### 降级策略
|
||
- LLM API Key 未配置 → `/health` 返回 `llmAvailable: false`
|
||
- 后端（lpt-be）检测到 AI 不可用 → 自动切换到内置规则引擎（`BuiltinMindMapGenerator`）
|
||
|
||
---
|
||
|
||
## 启动命令
|
||
```bash
|
||
npm install # 安装依赖
|
||
npm run dev # 开发模式（tsx watch，热重载）
|
||
npm run build # 编译 TypeScript
|
||
npm run start # 生产模式
|
||
npm run test # 测试
|
||
```
|
||
|
||
---
|
||
|
||
## 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)
|
||
```
|