nojava
200 lines
6.1 KiB
Markdown
200 lines
6.1 KiB
Markdown
# 文章标签自动推荐功能技术实施文档
|
||
|
||
**与其它 AI 功能**：标签推荐使用 `properties.getModel()`，**不接入** 助手模型表；实施助手模型管理时 **无需改动** `TagRecommendServiceImpl`。参见《文章标签自动推荐功能需求》§6 及《AI助手模型管理功能需求》D-10。
|
||
|
||
## 前提条件
|
||
|
||
**数据安全规则**：
|
||
- 联调和测试过程中如需创建测试数据，测试完成后必须删除
|
||
- **数据库中存在一篇名为 "hello" 的文章，此文章不允许任何修改或删除操作**
|
||
|
||
---
|
||
|
||
## 1. 功能概述
|
||
|
||
基于 AI 模型根据文章内容自动推荐 3-5 个合适标签，博主可一键确认添加。
|
||
|
||
## 2. 核心实现思路
|
||
|
||
### 2.1 复用现有 AI 能力
|
||
|
||
项目已有 `AiSummaryService` 调用阿里云 DashScope 模型的能力，标签推荐功能将**完全复用**该服务：
|
||
|
||
- 复用 `DashScopeProperties` 配置（API Key、超时、限流等）
|
||
- 复用模型调用逻辑（HTTP 请求、响应解析、错误处理）
|
||
- 复用 Rate Limit 限流机制
|
||
|
||
### 2.2 差异化实现
|
||
|
||
与摘要生成的主要差异：
|
||
|
||
| 特性 | 摘要生成 | 标签推荐 |
|
||
|------|----------|----------|
|
||
| System Prompt | 生成摘要的专业提示词 | 提取标签的专业提示词 |
|
||
| User Prompt | 标题 + 正文 | 标题 + 正文（需要提取标签） |
|
||
| 响应解析 | 截取摘要文本 | 解析逗号分隔的标签列表 |
|
||
| 返回格式 | SummaryResultVO | 推荐标签列表 |
|
||
|
||
### 2.3 实现方案
|
||
|
||
**后端**：新建 `TagRecommendService` 服务类，复用 `AiSummaryServiceImpl` 的模型调用能力
|
||
|
||
**前端**：在文章编辑页标签区域添加推荐按钮，展示推荐标签并支持一键添加
|
||
|
||
---
|
||
|
||
## 3. 改动项清单
|
||
|
||
### 3.1 后端改动
|
||
|
||
#### 3.1.1 新增 DTO
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `dto/RecommendTagsDTO.java` | 请求 DTO，包含 title、content 字段 |
|
||
|
||
#### 3.1.2 新增 VO
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `dto/TagRecommendResultVO.java` | 返回 VO，包含 tags 列表、model、costMillis 等 |
|
||
|
||
#### 3.1.3 新增服务接口
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `service/TagRecommendService.java` | 标签推荐服务接口 |
|
||
|
||
#### 3.1.4 新增服务实现
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `service/impl/TagRecommendServiceImpl.java` | 复用 AiSummaryServiceImpl 的 callModel 方法，实现标签推荐逻辑 |
|
||
|
||
#### 3.1.5 新增 Controller 接口
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `controller/ArticleController.java` | 新增 `/recommend-tags` POST 接口 |
|
||
|
||
#### 3.1.6 错误码（如需要）
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `common/exception/ErrorCode.java` | 可能需要新增错误码（如 AI_CONTENT_TOO_SHORT 已存在可复用） |
|
||
|
||
---
|
||
|
||
### 3.2 前端改动
|
||
|
||
#### 3.2.1 新增 API 方法
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `src/api/article.js` | 新增 `recommendTags(data)` 方法 |
|
||
|
||
#### 3.2.2 修改文章编辑器
|
||
|
||
| 文件 | 说明 |
|
||
|------|------|
|
||
| `src/views/app/ArticleEditor.vue` | 在标签区域添加"智能推荐"按钮及交互逻辑 |
|
||
|
||
---
|
||
|
||
## 4. 核心逻辑说明
|
||
|
||
### 4.1 后端核心逻辑
|
||
|
||
```java
|
||
// TagRecommendServiceImpl.java
|
||
|
||
// 专用提示词
|
||
private static final String SYSTEM_PROMPT =
|
||
"你是一名专业的博客编辑，请根据用户提供的标题与正文，" +
|
||
"提取 3-5 个最合适的标签。只返回标签词，用逗号分隔，不要有其他内容。";
|
||
|
||
private static final int TAG_RECOMMEND_MIN_LENGTH = 10;
|
||
|
||
// 1. 构建请求（复用 AiSummaryServiceImpl.callModel）
|
||
Map<String, Object> requestBody = Map.of(
|
||
"model", properties.getModel(),
|
||
"messages", List.of(
|
||
Map.of("role", "system", "content", SYSTEM_PROMPT),
|
||
Map.of("role", "user", "content", buildUserPrompt(dto.getTitle(), plainContent))
|
||
),
|
||
"temperature", 0.5 // 标签推荐可以稍高一些，增加多样性
|
||
);
|
||
|
||
// 2. 调用模型（复用 AiSummaryServiceImpl.callModel）
|
||
Map<String, Object> response = callModel(requestBody);
|
||
|
||
// 3. 解析响应（解析逗号分隔的标签）
|
||
List<String> tags = parseTagsFromResponse(response);
|
||
```
|
||
|
||
### 4.2 前端核心逻辑
|
||
|
||
```vue
|
||
<!-- ArticleEditor.vue 标签区域 -->
|
||
<el-form-item label="标签">
|
||
<el-select v-model="form.tagIds" multiple ...>
|
||
<el-option v-for="tag in tags" ... />
|
||
</el-select>
|
||
<!-- 新增推荐按钮 -->
|
||
<el-button
|
||
type="primary"
|
||
size="small"
|
||
:loading="recommending"
|
||
@click="handleRecommendTags"
|
||
>
|
||
智能推荐
|
||
</el-button>
|
||
</el-form-item>
|
||
|
||
<!-- 推荐结果展示 -->
|
||
<div v-if="recommendedTags.length" class="tag-recommend-result">
|
||
<el-checkbox-group v-model="selectedRecommendedTags">
|
||
<el-checkbox
|
||
v-for="tag in recommendedTags"
|
||
:key="tag"
|
||
:label="tag"
|
||
/>
|
||
</el-checkbox-group>
|
||
<el-button @click="confirmAddTags">确认添加</el-button>
|
||
</div>
|
||
```
|
||
|
||
---
|
||
|
||
## 5. 待办事项
|
||
|
||
| 序号 | 待办项 | 状态 |
|
||
|------|--------|------|
|
||
| 1 | 后端：创建 RecommendTagsDTO.java | ✅ 已完成 |
|
||
| 2 | 后端：创建 TagRecommendResultVO.java | ✅ 已完成 |
|
||
| 3 | 后端：创建 TagRecommendService 接口 | ✅ 已完成 |
|
||
| 4 | 后端：创建 TagRecommendServiceImpl 实现类 | ✅ 已完成 |
|
||
| 5 | 后端：在 ArticleController 添加 /recommend-tags 接口 | ✅ 已完成 |
|
||
| 6 | 前端：在 article.js 添加 recommendTags API 方法 | ✅ 已完成 |
|
||
| 7 | 前端：在 ArticleEditor.vue 添加智能推荐按钮和交互 | ✅ 已完成 |
|
||
| 8 | 后端：单元测试（18 个用例，P0+P1） | ✅ 已完成 |
|
||
| 9 | 前后端联调测试（LiveIT 真实 AI 调用验证） | ✅ 已完成 |
|
||
| 10 | 功能验收测试（API + 前端静态资源验证） | ✅ 已完成 |
|
||
|
||
---
|
||
|
||
## 6. 实施顺序建议
|
||
|
||
1. **先做后端**：DTO → VO → Service → Controller
|
||
2. **再做前端**：API 方法 → 页面交互
|
||
3. **最后联调**：前后端对接、bug 修复、验收
|
||
|
||
---
|
||
|
||
## 7. 风险与注意事项
|
||
|
||
1. **模型响应格式**：需处理模型返回格式不稳定的情况（如多余空格、换行）
|
||
2. **标签去重**：推荐标签可能与已有标签重复，需前端过滤
|
||
3. **内容过短**：正文少于 10 字符时不调用 AI，直接提示用户
|
||
4. **限流复用**：复用现有 Rate Limit 机制，避免额外开发
|