一、概述
AI智能摘要是知识库系统的重要AI能力之一,用户在文档详情页点击按钮,即可由AI自动分析文档内容并生成简洁摘要,摘要支持流式逐句展示并自动保存到数据库。
本文将详细介绍从后端到前端实现AI智能摘要功能的完整过程。
1.1 功能定位
| 功能模块 | 说明 | 使用场景 |
|---|---|---|
| 一键生成摘要 | 点击按钮,AI自动分析文档生成摘要 | 快速了解文档核心内容 |
| 流式展示 | 逐句打字效果展示生成过程 | 提升交互体验 |
| Redis缓存 | 基于内容MD5的摘要缓存,7天有效期 | 避免重复调用LLM |
| 摘要持久化 | 生成后自动保存到文档记录 | 下次打开直接显示 |
| 重新生成 | 已有摘要时支持重新生成 | 更新或优化摘要 |
| 一键复制 | 复制摘要到剪贴板 | 快速分享摘要 |
1.2 整体流程

1.4 技术要点
- SSE(Server-Sent Events):实现流式逐句推送,用户体验优于一次性加载
- Redis缓存:基于文档内容MD5去重,相同内容不重复调用LLM
- 内容截断:超长文档取头尾拼接(前75% + 后25%),避免token超限
- PATCH端点:专用的摘要更新接口,跳过全量DTO校验
- AbortController:组件卸载时自动取消进行中的请求,避免内存泄漏
二、后端实现 — kb-ai 服务
kb-ai 是AI处理微服务,负责调用大语言模型(LLM)生成摘要。
2.1 新增接口方法签名
在 AiDocumentService.java 接口中新增2个方法:
// kb-ai/src/main/java/com/knowledge/base/ai/service/AiDocumentService.java
/**
* 基于内容生成摘要(非流式)
*
* @param dto 处理请求
* @param userId 用户ID
* @return 处理结果
*/
DocumentProcessVO generateSummaryByContent(DocumentProcessDTO dto, Long userId);
/**
* 基于内容流式生成摘要
*
* @param dto 处理请求
* @param userId 用户ID
* @return SSE事件流
*/
SseEmitter generateSummaryByContentStream(DocumentProcessDTO dto, Long userId);说明:已有的 generateSummary(MultipartFile file, ...) 方法要求上传文件,但文档详情页已有文档内容文本,新增的方法直接接受 JSON 请求体中的文档内容,避免重复上传。2.2 实现核心方法
在 AiDocumentServiceImpl.java 中实现新方法。先了解一下请求DTO:
// kb-ai/src/main/java/com/knowledge/base/ai/dto/DocumentProcessDTO.java
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Schema(description = "文档处理参数")
public class DocumentProcessDTO {
@NotBlank(message = "文档内容不能为空")
private String content; // 文档内容
private String title; // 文档标题
@NotBlank(message = "处理类型不能为空")
private String processType; // 处理类型:summary/outline/expansion/...
private ProcessParams processParams; // 处理参数(如摘要长度)
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public static class ProcessParams {
private Integer summaryLength; // 摘要长度(默认200字)
private Integer outlineLevel; // 大纲层级
private String expansionType; // 扩展类型
private String optimizationTarget; // 优化目标
private String exampleType; // 示例类型
}
}2.2.1 Redis缓存基架
首先在实现类中添加Redis缓存相关字段和方法:
// kb-ai/src/main/java/com/knowledge/base/ai/service/impl/AiDocumentServiceImpl.java
@Slf4j
@Service
@RequiredArgsConstructor
public class AiDocumentServiceImpl implements AiDocumentService {
private final ModelProvider modelProvider;
private final StringRedisTemplate redisTemplate;
private static final String SUMMARY_CACHE_PREFIX = "ai:summary:";
private static final Duration SUMMARY_CACHE_TTL = Duration.ofDays(7);
/**
* 计算内容摘要的缓存Key,基于内容MD5去重
*/
private String buildSummaryCacheKey(String content) {
return SUMMARY_CACHE_PREFIX + DigestUtils.md5DigestAsHex(
content.getBytes(StandardCharsets.UTF_8));
}
/**
* 从Redis缓存中获取摘要
*/
private String getCachedSummary(String content) {
try {
if (redisTemplate == null) return null;
return redisTemplate.opsForValue().get(buildSummaryCacheKey(content));
} catch (Exception e) {
log.warn("读取摘要缓存失败:{}", e.getMessage());
return null;
}
}
/**
* 将摘要写入Redis缓存
*/
private void cacheSummary(String content, String summary) {
try {
if (redisTemplate == null) return;
redisTemplate.opsForValue().set(
buildSummaryCacheKey(content), summary, SUMMARY_CACHE_TTL);
log.info("摘要已缓存:key={}", buildSummaryCacheKey(content));
} catch (Exception e) {
log.warn("写入摘要缓存失败:{}", e.getMessage());
}
}
}2.2.2 内容截断工具方法
/**
* 内容截断:超长文档取头尾拼接,减少LLM token消耗
*
* <p>超过 maxChars 字符时,取前75%和后25%,中间用"..."分隔。
* 保证LLM同时看到文档开头(通常含摘要信息)和结尾(通常含结论)。</p>
*/
private String truncateContent(String content, int maxChars) {
if (content == null || content.length() <= maxChars) {
return content;
}
int headLen = (int) (maxChars * 0.75);
int tailLen = maxChars - headLen;
String head = content.substring(0, headLen);
String tail = content.substring(content.length() - tailLen);
return head + "\n\n...\n\n" + tail;
}2.2.3 句子切分工具方法
/**
* 按句号/换行切分文本为句子块,用于流式逐句推送
*
* <p>切分标志:。!?\n。每个切分块作为一次SSE message事件发送。</p>
*/
static List<String> chunkBySentence(String text) {
if (text == null || text.isEmpty()) {
return List.of();
}
List<String> chunks = new ArrayList<>();
StringBuilder current = new StringBuilder();
for (int i = 0; i < text.length(); i++) {
char c = text.charAt(i);
current.append(c);
if (c == '。' || c == '\n' || c == '!' || c == '?') {
String chunk = current.toString().trim();
if (!chunk.isEmpty()) {
chunks.add(chunk);
}
current.setLength(0);
}
}
String remaining = current.toString().trim();
if (!remaining.isEmpty()) {
chunks.add(remaining);
}
return chunks;
}2.2.4 Prompt构建
/**
* 构建摘要Prompt
*/
private String buildSummaryPrompt(String content, String title, int length) {
StringBuilder sb = new StringBuilder();
sb.append("请为以下文档生成一个简洁的摘要,要求:\n");
sb.append("1. 摘要长度约").append(length).append("字\n");
sb.append("2. 涵盖文档的核心内容和主要观点\n");
sb.append("3. 语言简洁明了\n");
sb.append("4. 不要添加任何额外的解释\n");
if (title != null && !title.isEmpty()) {
sb.append("\n文档标题:").append(title).append("\n");
}
sb.append("\n文档内容:\n").append(content);
return sb.toString();
}2.2.5 非流式版本
/**
* 基于内容生成摘要(非流式)
*
* <p>先查Redis缓存,未命中再调用LLM,生成后写入缓存。</p>
*/
@Override
public DocumentProcessVO generateSummaryByContent(DocumentProcessDTO dto, Long userId) {
log.info("基于内容生成摘要(非流式):userId={}, title={}", userId, dto.getTitle());
DocumentProcessVO result = new DocumentProcessVO();
result.setProcessType("summary");
try {
// 1. 截断长内容
String content = truncateContent(dto.getContent(), 8000);
// 2. 先查Redis缓存
String cached = getCachedSummary(content);
if (cached != null) {
log.info("摘要缓存命中");
result.setProcessedContent(cached);
result.setOriginalContent(dto.getContent());
result.setSuccess(true);
result.setMessage("缓存命中");
return result;
}
// 3. 获取摘要长度参数
Integer length = dto.getProcessParams() != null
? dto.getProcessParams().getSummaryLength()
: 200;
if (length == null || length <= 0) {
length = 200;
}
// 4. 调用LLM生成摘要
String prompt = buildSummaryPrompt(content, dto.getTitle(), length);
UserMessage userMessage = UserMessage.from(prompt);
Response<AiMessage> response = modelProvider.getDefaultModel().generate(userMessage);
String summary = response.content().text().trim();
// 5. 写入Redis缓存
cacheSummary(content, summary);
result.setProcessedContent(summary);
result.setOriginalContent(dto.getContent());
result.setSuccess(true);
result.setMessage("生成成功");
} catch (Exception e) {
log.error("基于内容生成摘要失败:{}", e.getMessage(), e);
result.setSuccess(false);
result.setMessage("生成失败: " + e.getMessage());
}
return result;
}2.2.6 流式版本(核心)
/**
* 基于内容流式生成摘要
*
* <p>使用SSE逐句推送摘要内容。缓存命中时直接流式返回缓存数据;
* 未命中时异步调用LLM,生成后逐句推送并写入缓存。</p>
*/
@Override
public SseEmitter generateSummaryByContentStream(DocumentProcessDTO dto, Long userId) {
log.info("基于内容流式生成摘要:userId={}, title={}", userId, dto.getTitle());
SseEmitter emitter = new SseEmitter(5 * 60 * 1000L); // 5分钟超时
try {
String content = truncateContent(dto.getContent(), 8000);
// 先查Redis缓存,命中直接流式返回缓存的摘要
String cached = getCachedSummary(content);
if (cached != null) {
log.info("摘要缓存命中(流式)");
new Thread(() -> {
try {
List<String> chunks = chunkBySentence(cached);
for (int i = 0; i < chunks.size(); i++) {
emitter.send(SseEmitter.event()
.name("message")
.data(chunks.get(i)));
if (i < chunks.size() - 1) {
Thread.sleep(30); // 句子间短暂间隔,模拟打字效果
}
}
DocumentProcessVO result = new DocumentProcessVO();
result.setProcessType("summary");
result.setProcessedContent(cached);
result.setSuccess(true);
result.setMessage("缓存命中");
emitter.send(SseEmitter.event().name("done").data(result));
emitter.complete();
} catch (Exception e) {
try {
emitter.send(SseEmitter.event().name("error").data(e.getMessage()));
} catch (IOException ignored) {}
emitter.completeWithError(e);
}
}, "summary-stream-cached-" + userId).start();
return emitter;
}
// 缓存未命中,异步调用LLM生成
Integer lengthParam = dto.getProcessParams() != null
? dto.getProcessParams().getSummaryLength()
: 200;
final Integer length = (lengthParam == null || lengthParam <= 0) ? 200 : lengthParam;
final String finalContent = content;
new Thread(() -> {
try {
String prompt = buildSummaryPrompt(finalContent, dto.getTitle(), length);
UserMessage userMessage = UserMessage.from(prompt);
Response<AiMessage> response = modelProvider.getDefaultModel().generate(userMessage);
String summary = response.content().text().trim();
// 写入Redis缓存
cacheSummary(finalContent, summary);
// 按句子切分并逐句流式推送
List<String> chunks = chunkBySentence(summary);
for (int i = 0; i < chunks.size(); i++) {
emitter.send(SseEmitter.event()
.name("message")
.data(chunks.get(i)));
if (i < chunks.size() - 1) {
Thread.sleep(40); // 句子间间隔,模拟打字效果
}
}
// 发送完成事件
DocumentProcessVO result = new DocumentProcessVO();
result.setProcessType("summary");
result.setProcessedContent(summary);
result.setSuccess(true);
result.setMessage("生成成功");
emitter.send(SseEmitter.event().name("done").data(result));
emitter.complete();
} catch (Exception e) {
log.error("流式生成摘要失败:{}", e.getMessage(), e);
try {
emitter.send(SseEmitter.event()
.name("error")
.data("生成失败: " + e.getMessage()));
emitter.completeWithError(e);
} catch (IOException ex) {
emitter.completeWithError(ex);
}
}
}, "summary-stream-" + userId).start();
} catch (Exception e) {
log.error("流式生成摘要启动失败:{}", e.getMessage(), e);
emitter.completeWithError(e);
}
return emitter;
}设计要点:
- 异步线程:LLM调用在独立线程中执行,Controller线程立即返回
SseEmitter,不阻塞- 缓存优先:先查Redis,命中则直接流式返回,延迟极低
- 逐句推送:按标点切分,每句30-40ms间隔,模拟打字效果
- 事件规范:
message(内容块)、done(完成,含完整JSON)、error(异常)
2.3 新增Controller端点
在 AiDocumentController.java 中新增2个端点:
// kb-ai/src/main/java/com/knowledge/base/ai/controller/AiDocumentController.java
/**
* 基于内容生成摘要(非流式)
*/
@PostMapping("/summary/content")
@Operation(summary = "基于内容生成摘要", description = "传入文档内容,使用AI生成摘要")
public Result<DocumentProcessVO> generateSummaryByContent(
@Valid @RequestBody DocumentProcessDTO dto,
HttpServletRequest request) {
Long userId = UserContextUtil.getUserIdFromHeader(request);
DocumentProcessVO result = aiDocumentService.generateSummaryByContent(dto, userId);
return Result.success(result);
}
/**
* 基于内容流式生成摘要
*/
@PostMapping("/summary/content/stream")
@Operation(summary = "基于内容流式生成摘要", description = "传入文档内容,使用AI流式生成摘要")
public SseEmitter generateSummaryByContentStream(
@Valid @RequestBody DocumentProcessDTO dto,
HttpServletRequest request) {
Long userId = UserContextUtil.getUserIdFromHeader(request);
return aiDocumentService.generateSummaryByContentStream(dto, userId);
}注意事项:
- Controller的
@RequestMapping为/document(不包含/api/ai前缀)- 网关配置了
StripPrefix=2对/api/ai/**路径剥离前两级,所以实际访问路径为/api/ai/document/summary/content/stream
三、后端实现 — kb-document 服务
kb-document 是文档管理微服务,需要新增一个专用的摘要更新端点。
3.1 Service接口
在 DocumentService.java 中新增方法签名:
// kb-document/src/main/java/com/knowledge/base/document/service/DocumentService.java
/**
* 更新文档摘要(部分更新,不受全量校验约束)
*
* @param documentId 文档ID
* @param summary 摘要内容
* @return 是否成功
*/
Boolean updateSummary(Long documentId, String summary);3.2 Service实现
在 DocumentServiceImpl.java 中实现:
// kb-document/src/main/java/com/knowledge/base/document/service/impl/DocumentServiceImpl.java
@Override
public Boolean updateSummary(Long documentId, String summary) {
log.info("更新文档摘要:documentId={}", documentId);
if (documentId == null) {
throw new BusinessException("文档ID不能为空");
}
Document existDocument = documentMapper.selectById(documentId);
if (existDocument == null) {
throw new BusinessException(ResultCode.DOCUMENT_NOT_EXIST);
}
Document document = new Document();
document.setId(documentId);
document.setSummary(summary);
int count = documentMapper.updateById(document);
return count > 0;
}设计要点:
- 使用
updateById进行部分字段更新,只设置id和summary字段- 不走
DocumentDTO的全量校验(@NotBlank title等),避免因缺少其他必填字段导致更新失败
3.3 Controller端点
在 DocumentController.java 中新增 PATCH 端点:
// kb-document/src/main/java/com/knowledge/base/document/controller/DocumentController.java
/**
* 更新文档摘要(部分更新,不受全量校验约束)
*/
@PatchMapping("/{documentId}/summary")
@Operation(summary = "更新文档摘要", description = "仅更新文档的summary字段")
public Result<Boolean> updateSummary(
@Parameter(description = "文档ID", required = true)
@PathVariable Long documentId,
@RequestBody Map<String, String> body) {
String summary = body.get("summary");
if (summary == null || summary.isBlank()) {
return Result.error("摘要内容不能为空");
}
if (summary.length() > 500) {
summary = summary.substring(0, 500);
}
log.info("更新文档摘要请求:documentId={}", documentId);
Boolean success = documentService.updateSummary(documentId, summary);
return Result.success("摘要更新成功", success);
}**使用 **@PatchMapping** 而非 **@PutMapping:语义上PATCH代表部分更新,PUT代表全量替换,此处语义更匹配。
四、前端实现 — Service 层
4.1 AI摘要Service
在 services/ai.service.ts 中新增2个方法:
// knowledge-base-frontend/src/services/ai.service.ts
// ==================== Document Summary APIs ====================
/**
* 基于文档内容生成AI摘要(非流式)
*/
generateDocSummary: (params: { content: string; title?: string; length?: number }) => {
return http.post<{
processType: string;
processedContent: string;
success: boolean;
message: string;
tokens?: number;
}>('/ai/document/summary/content', {
content: params.content,
title: params.title || '',
processType: 'summary',
processParams: {
summaryLength: params.length || 200,
},
});
},
/**
* 基于文档内容生成AI摘要(流式SSE)
*
* @param onChunk - 每收到一个句子块时调用
* @param onDone - 流完成时调用,携带完整摘要
* @param onError - 出错时调用
*/
generateDocSummaryStream: (
params: { content: string; title?: string; length?: number },
onChunk: (chunk: string) => void,
onDone?: (result: { processedContent: string; success: boolean; message: string }) => void,
onError?: (error: string) => void,
) => {
const apiBase = import.meta.env.VITE_API_BASE_URL;
return fetch(`${apiBase}/ai/document/summary/content/stream`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': tokenStorage.getAuthorizationHeader(),
},
body: JSON.stringify({
content: params.content,
title: params.title || '',
processType: 'summary',
processParams: {
summaryLength: params.length || 200,
},
}),
}).then(async (response) => {
if (!response.ok) {
throw new Error(`HTTP ${response.status}: ${response.statusText}`);
}
const reader = response.body?.getReader();
const decoder = new TextDecoder();
if (!reader) throw new Error('无法读取响应流');
let buffer = '';
let currentEvent = '';
let messageLines: string[] = [];
while (true) {
const { done, value } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
const lines = buffer.split('\n');
buffer = lines.pop() || '';
for (const line of lines) {
// 解析 event: 行
if (line.startsWith('event:')) {
if (messageLines.length > 0) {
onChunk(messageLines.join('\n'));
messageLines = [];
}
currentEvent = line.slice(6).trim();
continue;
}
// 解析 data: 行
if (line.startsWith('data:')) {
const data = line.startsWith('data: ') ? line.slice(6) : line.slice(5);
if (currentEvent === 'error') {
onError?.(data);
continue;
}
if (currentEvent === 'done') {
try {
const parsed = JSON.parse(data);
onDone?.(parsed);
} catch { /* ignore */ }
continue;
}
messageLines.push(data);
continue;
}
// 空行 = SSE事件边界
if (line === '') {
if (messageLines.length > 0) {
onChunk(messageLines.join('\n'));
messageLines = [];
}
currentEvent = '';
}
}
}
if (messageLines.length > 0) {
onChunk(messageLines.join('\n'));
}
});
},4.2 文档摘要更新Service
在 services/document.service.ts 中新增:
// knowledge-base-frontend/src/services/document.service.ts
// 仅更新文档摘要(走专用PATCH端点,不做全量校验)
updateSummary: (id: string, summary: string) => {
return http.patch<boolean>(`/document/documents/${id}/summary`, { summary });
},五、前端实现 — 文档详情页UI
在 DocumentDetailPage.tsx 中改造AI摘要卡片,实现完整的交互体验。
5.1 引入依赖
import { RobotOutlined, CopyOutlined, CheckOutlined } from '@ant-design/icons';
import { aiService } from '@/services/ai.service';5.2 新增状态
// AI摘要生成相关状态
const [isSummarizing, setIsSummarizing] = useState(false);
const [streamedSummary, setStreamedSummary] = useState('');
const [summaryError, setSummaryError] = useState<string | null>(null);
const [summaryCopied, setSummaryCopied] = useState(false);
const isSummarizingRef = useRef(false); // 防重复调用互斥锁
const summaryAbortRef = useRef<AbortController | null>(null); // 取消控制5.3 组件卸载清理
在已有的 useEffect(监听 id 变化)的 cleanup 中添加:
useEffect(() => {
if (id) {
fetchDocument(id);
}
// 文档切换/组件卸载时取消进行中的摘要生成
return () => {
if (summaryAbortRef.current) {
summaryAbortRef.current.abort();
summaryAbortRef.current = null;
}
isSummarizingRef.current = false;
setIsSummarizing(false);
setStreamedSummary('');
setSummaryError(null);
};
}, [id]);5.4 生成摘要处理函数
const handleGenerateSummary = async () => {
const currentDoc = useDocumentStore.getState().currentDocument;
if (!currentDoc || !id) return;
// 互斥锁防止重复调用
if (isSummarizingRef.current) return;
isSummarizingRef.current = true;
// 内容为空检查
if (!currentDoc.content || currentDoc.content.trim().length === 0) {
message.warning('文档内容为空,无法生成摘要');
isSummarizingRef.current = false;
return;
}
setIsSummarizing(true);
setStreamedSummary('');
setSummaryError(null);
const controller = new AbortController();
summaryAbortRef.current = controller;
try {
await aiService.generateDocSummaryStream(
{
content: currentDoc.content,
title: currentDoc.title,
length: 200,
},
// onChunk:逐句累积显示
(chunk) => {
setStreamedSummary((prev) => prev + chunk);
},
// onDone:持久化到后端 + 更新本地状态
async (result) => {
const finalSummary = result.processedContent;
try {
await documentService.updateSummary(id, finalSummary);
// 立即更新 Zustand store
const store = useDocumentStore.getState();
if (store.currentDocument) {
store.setCurrentDocument({
...store.currentDocument,
summary: finalSummary,
});
}
message.success('AI摘要已生成');
} catch {
// 持久化失败不阻塞UI,streamedSummary 仍会展示
message.warning('摘要已生成,但保存失败,刷新后可能丢失');
}
setIsSummarizing(false);
setSummaryError(null);
isSummarizingRef.current = false;
summaryAbortRef.current = null;
},
// onError:区分主动取消和真实错误
(error) => {
if (error === 'AbortError' || error.includes('abort')) {
setStreamedSummary('');
} else {
setSummaryError(error || '生成失败,请重试');
}
setIsSummarizing(false);
isSummarizingRef.current = false;
summaryAbortRef.current = null;
},
);
} catch {
setSummaryError('网络异常,请检查连接后重试');
setIsSummarizing(false);
isSummarizingRef.current = false;
summaryAbortRef.current = null;
}
};5.5 AI摘要卡片UI
{/* AI摘要 */}
<div style={{
background: 'linear-gradient(135deg, rgba(37, 99, 235, 0.05), rgba(139, 92, 246, 0.05))',
border: `1px solid ${summaryError ? 'rgba(239, 68, 68, 0.3)' : 'rgba(37, 99, 235, 0.2)'}`,
borderRadius: '12px',
padding: '12px 16px',
}}>
{/* 头部:标题 + 操作按钮 */}
<div style={{
display: 'flex',
alignItems: 'center',
justifyContent: 'space-between',
marginBottom: '8px',
}}>
<div style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
<div style={{
width: '36px', height: '36px', borderRadius: '8px',
background: 'linear-gradient(135deg, rgba(37, 99, 235, 0.1), rgba(139, 92, 246, 0.1))',
display: 'flex', alignItems: 'center', justifyContent: 'center',
}}>
<RobotOutlined style={{ color: '#2563eb', fontSize: '20px' }} />
</div>
<span style={{ fontWeight: 600, fontSize: '15px' }}>AI智能摘要</span>
{isSummarizing && <Tag color="processing">生成中...</Tag>}
</div>
<div style={{ display: 'flex', gap: '6px', alignItems: 'center' }}>
{/* 复制按钮:仅在已有摘要且不在生成中时显示 */}
{currentDoc.summary && !isSummarizing && !streamedSummary && (
<Tooltip title="复制摘要">
<Button
type="text" size="small"
icon={summaryCopied ? <CheckOutlined /> : <CopyOutlined />}
onClick={() => {
navigator.clipboard.writeText(currentDoc.summary || '');
setSummaryCopied(true);
message.success('摘要已复制');
setTimeout(() => setSummaryCopied(false), 2000);
}}
/>
</Tooltip>
)}
{/* 生成/重新生成按钮 */}
<Button
type={currentDoc.summary ? 'default' : 'primary'}
size="small"
icon={isSummarizing ? undefined : <RobotOutlined />}
loading={isSummarizing}
disabled={isSummarizing}
onClick={handleGenerateSummary}
style={currentDoc.summary ? undefined : {
background: 'linear-gradient(135deg, #2563eb, #7c3aed)',
border: 'none',
}}
>
{currentDoc.summary ? '重新生成' : 'AI生成摘要'}
</Button>
</div>
</div>
{/* 摘要内容区域 */}
<div style={{ fontSize: '15px', lineHeight: 1.8, color: '#4b5563', minHeight: '24px' }}>
{(() => {
const effectiveSummary = streamedSummary || currentDoc.summary;
// 状态1:生成中
if (isSummarizing) {
return (
<div>
{streamedSummary ? (
<span>
{streamedSummary}
<span style={{
display: 'inline-block', width: '2px', height: '16px',
background: '#2563eb', marginLeft: '2px',
animation: 'blink 0.8s infinite',
verticalAlign: 'text-bottom',
}} />
</span>
) : (
<span style={{ color: '#9ca3af', fontStyle: 'italic' }}>
AI正在分析文档内容...
</span>
)}
</div>
);
}
// 状态2:错误
if (summaryError) {
return (
<div style={{ color: '#ef4444', display: 'flex', alignItems: 'center', gap: '8px' }}>
<span>生成失败:{summaryError}</span>
<Button type="link" size="small" danger onClick={handleGenerateSummary}>
重试
</Button>
</div>
);
}
// 状态3:有摘要
if (effectiveSummary) {
return <span>{effectiveSummary}</span>;
}
// 状态4:无摘要
return (
<span style={{ color: '#9ca3af', fontStyle: 'italic' }}>
点击"AI生成摘要"按钮,让AI帮你快速了解文档核心内容
</span>
);
})()}
</div>
</div>UI状态说明:
stateDiagram-v2
[*] --> 无摘要: 初始状态
无摘要 --> 生成中: 点击"AI生成摘要"
生成中 --> 生成完成: done事件收到
生成中 --> 生成失败: error事件/网络异常
生成中 --> 无摘要: 组件卸载/文档切换
生成完成 --> 生成中: 点击"重新生成"
生成失败 --> 生成中: 点击"重试"
生成失败 --> 无摘要: 组件卸载/文档切换
state 生成中 {
[*] --> 等待LLM
等待LLM --> 流式展示: 收到第一个message
流式展示 --> 流式展示: 逐句累积<br/>闪烁光标
}
note right of 生成完成: 显示完整摘要<br/>可复制
note right of 生成失败: 红色错误提示<br/>可重试| 状态 | 卡片内容 | 按钮状态 |
|---|---|---|
| 无摘要 | 引导文案 | "AI生成摘要"(蓝色) |
| 生成中 | 流式文字 + 闪烁光标 / "AI正在分析..." | loading + disabled |
| 生成完成 | 完整摘要 | "重新生成" + "复制" |
| 生成失败 | 错误信息 + "重试" | "AI生成摘要"(可点击) |
六、API接口汇总
6.1 新增接口一览
| 方法 | 路径 | 说明 | 请求方式 |
|---|---|---|---|
| POST | /api/ai/document/summary/content | 基于内容生成摘要(非流式) | JSON Body |
| POST | /api/ai/document/summary/content/stream | 基于内容流式生成摘要 | JSON Body → SSE |
| PATCH | /api/document/documents/{id}/summary | 更新文档摘要 | JSON Body |
6.2 请求参数
生成摘要请求:
{
"content": "Spring Boot是由Pivotal团队提供的全新框架...",
"title": "Spring Boot入门指南",
"processType": "summary",
"processParams": {
"summaryLength": 200
}
}更新摘要请求:
{
"summary": "本文介绍了Spring Boot框架的核心特性,包括自动配置、起步依赖、Actuator监控..."
}6.3 SSE事件格式
event:message
data:本文介绍了Spring Boot框架的核心特性,
event:message
data:包括自动配置、起步依赖、Actuator监控等功能。
event:done
data:{"processType":"summary","processedContent":"完整摘要文本...","success":true,"message":"生成成功"}测试
按顺序启动下面这些微服务:
kb-auth-user
kb-ai
kb-document
kb-gateway
启动前端
cd knowledge-base-frontend
npm run dev
浏览器访问文章详情页面:
http://localhost:3003/documents/318294787478392832

点击AI生成摘要按钮:

可以看到可以基于该文章正常生成摘要。
下次,再访问该文档详情,可以直接显示该摘要信息。
总结
本文详细介绍了从零实现AI智能摘要功能的完整过程,涵盖了以下核心内容:
已完成功能
| 功能 | 实现方式 | 说明 |
|---|---|---|
| 非流式摘要 | POST + JSON | 适合批量场景 |
| 流式摘要 | SSE + 逐句推送 | 主交互路径,体验最佳 |
| Redis缓存 | MD5去重 + 7天TTL | 避免重复LLM成本 |
| 内容截断 | 头75% + 尾25% | 控制token用量 |
| 摘要保存 | PATCH端点 | 部分更新,跳过全量校验 |
| 复制功能 | Clipboard API | 快速分享摘要 |
| 重新生成 | 复用同一流程 | 更新摘要 |
| 错误处理 | 分级提示 + 重试 | 健壮的用户体验 |
| 防重复调用 | useRef互斥锁 | 避免竞态条件 |
| 组件清理 | AbortController | 避免内存泄漏 |
技术要点
- SSE流式模式:单向推送,实现简单,浏览器原生支持
- 缓存优先策略:先查Redis,命中率越高,用户体验越好
- 部分更新设计:PATCH端点,避免全量DTO校验的坑
- 前端状态管理:流式文字 + 持久化状态分离,Zustand直接更新
- 防御性编程:互斥锁、AbortController、空值守卫、try-catch全覆盖
通过本文的学习,你应该能够掌握:
- SSE(Server-Sent Events)的完整实现模式
- Redis缓存在AI场景中的最佳实践
- 前端流式数据消费的通用方案
- 微服务架构下的跨服务协作方式
- PATCH端点用于部分更新的设计理念
祝你开发顺利!