developer
137 lines
3.5 KiB
Markdown
137 lines
3.5 KiB
Markdown
# lpt-ai
|
|
|
|
LPT 学习进度跟踪系统的独立 AI 服务。将 LLM 相关能力从 Java 主服务中剥离，便于独立迭代、增加安全层与沙箱。
|
|
|
|
## 能力
|
|
|
|
| 端点 | 方法 | 说明 |
|
|
|------|------|------|
|
|
| `/health` | GET | 健康检查，返回 LLM 可用状态 |
|
|
| `/ai/tasks` | POST | 提交异步 AI 任务（聚合报告/生成导图/回忆对比） |
|
|
| `/ai/tasks/:taskId` | GET | 轮询任务状态和结果 |
|
|
| `/fetch-title` | GET | 抓取 URL 页面标题 |
|
|
| `/admin` | GET | 管理面板（任务日志、Prompt 调试） |
|
|
|
|
## 快速开始
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# 编辑 .env，填入 LLM_API_KEY
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
未配置 `LLM_API_KEY` 时服务可启动，但 AI 端点返回 503，由调用方（Java 后端）降级到内置规则。
|
|
|
|
## 异步任务架构
|
|
|
|
由于 LLM 调用耗时长（可达数十秒），所有 AI 任务采用异步模式：
|
|
|
|
### 1. 提交任务
|
|
|
|
```bash
|
|
curl -X POST http://localhost:5199/ai/tasks \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"type": "aggregate-report",
|
|
"params": {
|
|
"taskName": "Java 并发编程",
|
|
"expectation": "理解线程池核心参数",
|
|
"fragments": [
|
|
{"content": "corePoolSize 是核心线程数，即使空闲也不回收"},
|
|
{"content": "workQueue 满了之后才会创建超过 core 的线程"}
|
|
]
|
|
}
|
|
}'
|
|
```
|
|
|
|
响应：
|
|
```json
|
|
{
|
|
"taskId": "550e8400-e29b-41d4-a716-446655440000",
|
|
"status": "pending"
|
|
}
|
|
```
|
|
|
|
### 2. 轮询结果
|
|
|
|
```bash
|
|
curl http://localhost:5199/ai/tasks/550e8400-e29b-41d4-a716-446655440000
|
|
```
|
|
|
|
响应（进行中）：
|
|
```json
|
|
{
|
|
"taskId": "550e8400-e29b-41d4-a716-446655440000",
|
|
"status": "running",
|
|
"progress": 50
|
|
}
|
|
```
|
|
|
|
响应（完成）：
|
|
```json
|
|
{
|
|
"taskId": "550e8400-e29b-41d4-a716-446655440000",
|
|
"status": "completed",
|
|
"result": {
|
|
"summary": "本次学习主要掌握了线程池的核心参数配置...",
|
|
"keyPoints": ["corePoolSize 核心线程数", "workQueue 工作队列"]
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. 支持的任务类型
|
|
|
|
| type | 说明 | params 字段 |
|
|
|------|------|------------|
|
|
| `aggregate-report` | 聚合学习残片为报告 | `taskName`, `expectation`, `fragments[]` |
|
|
| `generate-mind-map` | 生成思维导图大纲 | `taskName`, `reports[]`, `fragments[]`, `applications[]` |
|
|
| `compare-recall` | 对比用户回忆与标准导图 | `taskName`, `standardOutline`, `recallOutline` |
|
|
|
|
## 架构位置
|
|
|
|
```
|
|
LPT 前端 (Vue) ──► LPT 后端 (Java/Spring Boot) ──► lpt-ai (TS/Fastify) ──► SiliconFlow API
|
|
```
|
|
|
|
Java 后端是唯一调用方；本服务不直接暴露给前端，不做鉴权（部署在内网）。
|
|
|
|
## 任务队列机制
|
|
|
|
- 任务提交后进入内存队列，返回 taskId
|
|
- 后台异步执行，Java 端通过轮询获取结果
|
|
- 任务超时时间：5 分钟
|
|
- 任务结果保留时间：30 分钟（自动清理）
|
|
- 失败重试：无（由 Java 端决定是否重试或降级）
|
|
|
|
## 降级策略
|
|
|
|
```
|
|
AI 服务不可用
|
|
↓
|
|
Java 后端捕获 503/超时
|
|
↓
|
|
自动切换到内置生成器
|
|
↓
|
|
- 聚合报告：简单拼接残片
|
|
- 生成导图：按 session 分组 + 规则去重
|
|
- 回忆对比：字符串相似度匹配
|
|
```
|
|
|
|
确保系统在 AI 服务异常时仍可正常工作。
|
|
|
|
## 管理面板
|
|
|
|
访问 `http://localhost:5199/admin` 查看：
|
|
- 任务执行日志（状态、耗时、token 消耗）
|
|
- Prompt 模板预览与调试
|
|
- 队列状态监控
|
|
|
|
## 后续规划
|
|
|
|
- 输入内容安全过滤（Prompt 注入防护）
|
|
- 输出审核
|
|
- 多模型路由（按任务复杂度选择模型）
|
|
- 用量与成本监控
|
|
- SSE 流式输出
|