Compare commits
8
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
09670673de | ||
|
|
cbdac21301 | ||
|
|
7c751bfc02 | ||
|
|
098b119655 | ||
|
|
2393e4ba93 | ||
|
|
30b8d859e9 | ||
|
|
83fd1dddd8 | ||
|
|
c4c2ba1ed9 |
@@ -0,0 +1,4 @@
|
|||||||
|
# 行尾规范:文本文件统一 LF,Windows 批处理保留 CRLF
|
||||||
|
* text=auto eol=lf
|
||||||
|
*.bat text eol=crlf
|
||||||
|
*.cmd text eol=crlf
|
||||||
+26
-13
@@ -4,7 +4,7 @@ on:
|
|||||||
workflow_dispatch:
|
workflow_dispatch:
|
||||||
inputs:
|
inputs:
|
||||||
environment:
|
environment:
|
||||||
description: '部署环境(本仓库仅 main 分支;dev/prod 均从 main 部署)'
|
description: '部署环境(dev 仅允许 dev 分支;prod 仅允许 master 分支)'
|
||||||
required: true
|
required: true
|
||||||
type: choice
|
type: choice
|
||||||
options:
|
options:
|
||||||
@@ -14,7 +14,7 @@ on:
|
|||||||
env:
|
env:
|
||||||
REGISTRY: 192.168.123.199:5000
|
REGISTRY: 192.168.123.199:5000
|
||||||
APP: lpt-ai
|
APP: lpt-ai
|
||||||
REPO_URL: http://git.cat-shark.xyz/cat-shark/lpt-ai.git
|
REPO_URL: https://git.cat-shark.xyz/cat-shark/lpt-ai.git
|
||||||
|
|
||||||
jobs:
|
jobs:
|
||||||
build-and-deploy:
|
build-and-deploy:
|
||||||
@@ -33,18 +33,31 @@ jobs:
|
|||||||
fi
|
fi
|
||||||
ENV="${{ inputs.environment }}"
|
ENV="${{ inputs.environment }}"
|
||||||
echo "branch=$BRANCH environment=$ENV sha=${{ gitea.sha }}"
|
echo "branch=$BRANCH environment=$ENV sha=${{ gitea.sha }}"
|
||||||
# lpt-ai 仅维护 main:dev/prod 都从 main 出包,靠 environment 区分 namespace/镜像 tag
|
# lpt-ai 与 lpt-be/lpt-fe 同规则:master 发 prod,dev 发 dev。
|
||||||
case "$BRANCH" in
|
# 不允许跨环境出包:本服务的入参/出参结构与 lpt-be 的版本强耦合,
|
||||||
main|master)
|
# 把 dev 的代码推到 prod 会让旧版 lpt-be 读到不认识的字段(静默降级)。
|
||||||
echo "OK: lpt-ai 从 $BRANCH 部署到 $ENV"
|
|
||||||
;;
|
|
||||||
*)
|
|
||||||
echo "ERROR: lpt-ai 只能从 main/master 部署,当前分支是 '$BRANCH'"
|
|
||||||
exit 1
|
|
||||||
;;
|
|
||||||
esac
|
|
||||||
case "$ENV" in
|
case "$ENV" in
|
||||||
dev|prod) ;;
|
prod)
|
||||||
|
case "$BRANCH" in
|
||||||
|
master) echo "OK: prod 允许从 $BRANCH 部署" ;;
|
||||||
|
*)
|
||||||
|
echo "ERROR: prod 只能从 master 部署,当前分支是 '$BRANCH'"
|
||||||
|
echo "请切换到 master 后再 Run workflow,并选择 environment=prod"
|
||||||
|
exit 1
|
||||||
|
;;
|
||||||
|
esac
|
||||||
|
;;
|
||||||
|
dev)
|
||||||
|
case "$BRANCH" in
|
||||||
|
dev) echo "OK: dev 允许从 $BRANCH 部署" ;;
|
||||||
|
*)
|
||||||
|
echo "ERROR: dev 只能从 dev 分支部署,当前分支是 '$BRANCH'"
|
||||||
|
echo "请切换到 dev 后再 Run workflow,并选择 environment=dev"
|
||||||
|
echo "(禁止用 master 代码部署到 lpt-dev,避免环境错配)"
|
||||||
|
exit 1
|
||||||
|
;;
|
||||||
|
esac
|
||||||
|
;;
|
||||||
*)
|
*)
|
||||||
echo "ERROR: 未知 environment=$ENV"
|
echo "ERROR: 未知 environment=$ENV"
|
||||||
exit 1
|
exit 1
|
||||||
|
|||||||
@@ -11,7 +11,7 @@
|
|||||||
|
|
||||||
- 运行时:Node.js 20+
|
- 运行时:Node.js 20+
|
||||||
- 框架:Fastify 5
|
- 框架:Fastify 5
|
||||||
- LLM:SiliconFlow OpenAI 兼容接口(Qwen/Qwen2.5-32B-Instruct)
|
- LLM:DeepSeek OpenAI 兼容接口(deepseek-flash / DeepSeek-V4.1-Flash)
|
||||||
- 运行时依赖:除 fastify 外无其他外部依赖
|
- 运行时依赖:除 fastify 外无其他外部依赖
|
||||||
|
|
||||||
## 项目结构
|
## 项目结构
|
||||||
@@ -60,9 +60,9 @@ lpt-ai/src/
|
|||||||
## LLM 配置
|
## LLM 配置
|
||||||
|
|
||||||
```env
|
```env
|
||||||
LLM_API_URL=https://api.siliconflow.cn/v1/chat/completions
|
LLM_API_URL=https://api.deepseek.com/v1/chat/completions
|
||||||
LLM_API_KEY= # 必填,未配置时 /health 返回 llmAvailable: false
|
LLM_API_KEY= # 必填,未配置时 /health 返回 llmAvailable: false
|
||||||
LLM_MODEL=Qwen/Qwen2.5-32B-Instruct
|
LLM_MODEL=deepseek-flash
|
||||||
LLM_TIMEOUT_MS=60000 # 单次 LLM 调用超时
|
LLM_TIMEOUT_MS=60000 # 单次 LLM 调用超时
|
||||||
PORT=5199
|
PORT=5199
|
||||||
```
|
```
|
||||||
|
|||||||
+3
-1
@@ -8,7 +8,9 @@ RUN npx tsc
|
|||||||
|
|
||||||
FROM node:20-alpine AS runner
|
FROM node:20-alpine AS runner
|
||||||
WORKDIR /app
|
WORKDIR /app
|
||||||
RUN apk add --no-cache curl
|
# 固定容器时区:alpine 默认无 tzdata,必须先安装,TZ 才会生效
|
||||||
|
ENV TZ=Asia/Shanghai
|
||||||
|
RUN apk add --no-cache curl tzdata
|
||||||
COPY --from=builder /app/dist ./dist
|
COPY --from=builder /app/dist ./dist
|
||||||
COPY package*.json ./
|
COPY package*.json ./
|
||||||
RUN npm ci --omit=dev --ignore-scripts
|
RUN npm ci --omit=dev --ignore-scripts
|
||||||
|
|||||||
@@ -1,136 +0,0 @@
|
|||||||
# 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[]`, `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 流式输出
|
|
||||||
+3
-3
@@ -1,5 +1,5 @@
|
|||||||
/**
|
/**
|
||||||
* LLM 客户端 — SiliconFlow OpenAI 兼容接口
|
* LLM 客户端 — DeepSeek OpenAI 兼容接口
|
||||||
*
|
*
|
||||||
* 设计要点:
|
* 设计要点:
|
||||||
* - Key 从环境变量读取,永不写入代码或日志
|
* - Key 从环境变量读取,永不写入代码或日志
|
||||||
@@ -21,9 +21,9 @@ export interface LlmConfig {
|
|||||||
|
|
||||||
export function loadConfig(): LlmConfig {
|
export function loadConfig(): LlmConfig {
|
||||||
return {
|
return {
|
||||||
apiUrl: process.env.LLM_API_URL ?? "https://api.siliconflow.cn/v1/chat/completions",
|
apiUrl: process.env.LLM_API_URL ?? "https://api.deepseek.com/v1/chat/completions",
|
||||||
apiKey: process.env.LLM_API_KEY ?? "",
|
apiKey: process.env.LLM_API_KEY ?? "",
|
||||||
model: process.env.LLM_MODEL ?? "Qwen/Qwen2.5-32B-Instruct",
|
model: process.env.LLM_MODEL ?? "deepseek-flash",
|
||||||
timeoutMs: Number(process.env.LLM_TIMEOUT_MS ?? 120000),
|
timeoutMs: Number(process.env.LLM_TIMEOUT_MS ?? 120000),
|
||||||
};
|
};
|
||||||
}
|
}
|
||||||
|
|||||||
+10
-6
@@ -13,7 +13,7 @@ export interface FragmentInput {
|
|||||||
/**
|
/**
|
||||||
* 残片聚合为学习报告。
|
* 残片聚合为学习报告。
|
||||||
* 原则:报告是写给"未来复习的自己"的,保留具体知识点,剔除口语碎屑;
|
* 原则:报告是写给"未来复习的自己"的,保留具体知识点,剔除口语碎屑;
|
||||||
* 不虚构残片中不存在的内容。
|
* 不虚构残片中不存在的内容;对抽象概念补充正反例子以明确边界。
|
||||||
*/
|
*/
|
||||||
export function aggregateReportPrompt(
|
export function aggregateReportPrompt(
|
||||||
taskName: string,
|
taskName: string,
|
||||||
@@ -34,12 +34,16 @@ export function aggregateReportPrompt(
|
|||||||
content: [
|
content: [
|
||||||
"你是一名学习记录整理助手。用户在一次学习会话中随手记录了若干学习残片,",
|
"你是一名学习记录整理助手。用户在一次学习会话中随手记录了若干学习残片,",
|
||||||
"请将它们整理为一份简洁的学习报告。要求:",
|
"请将它们整理为一份简洁的学习报告。要求:",
|
||||||
"1. 只基于残片内容,不虚构、不扩写残片中没有的知识;",
|
"1. 只基于残片内容,不虚构残片中不存在的知识;",
|
||||||
"2. 保留具体的知识点、概念、结论,去掉口语化的碎屑;",
|
"2. 保留具体的知识点、概念、结论,去掉口语化的碎屑;",
|
||||||
"3. 按逻辑而非时间组织内容,相关的点合并;",
|
"3. 对残片中的抽象概念或知识,除定义/要点外,再补充一组正反例子,",
|
||||||
"4. 报告以要点形式呈现,控制在 300 字以内;",
|
" 用「是X:…;不是X:…」的形式列出具体具象,帮助明确概念边界;",
|
||||||
"5. 如果提供了学习预期,在报告末尾用一句话说明本次学习与预期的差距(完成/部分完成/未涉及);",
|
" 例如:奇数(也叫单数)是不能被 2 整除的整数;是奇数:1、3、5、7;不是奇数:2、4、6、8;",
|
||||||
"6. 直接输出报告正文,不要输出「报告如下」之类的引导语。",
|
" 例子只用于解释残片已有的抽象内容,不引入新的知识点;",
|
||||||
|
"4. 按逻辑而非时间组织内容,相关的点合并;",
|
||||||
|
"5. 报告以要点形式呈现,因包含示例,目标 600 字左右,不超过 1000 字;",
|
||||||
|
"6. 如果提供了学习预期,在报告末尾用一句话说明本次学习与预期的差距(完成/部分完成/未涉及);",
|
||||||
|
"7. 直接输出报告正文,不要输出「报告如下」之类的引导语。",
|
||||||
].join(""),
|
].join(""),
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
|
|||||||
Reference in New Issue
Block a user