一、概述

AI智能摘要是知识库系统的重要AI能力之一,用户在文档详情页点击按钮,即可由AI自动分析文档内容并生成简洁摘要,摘要支持流式逐句展示并自动保存到数据库。

本文将详细介绍从后端到前端实现AI智能摘要功能的完整过程。

1.1 功能定位

功能模块说明使用场景
一键生成摘要点击按钮,AI自动分析文档生成摘要快速了解文档核心内容
流式展示逐句打字效果展示生成过程提升交互体验
Redis缓存基于内容MD5的摘要缓存,7天有效期避免重复调用LLM
摘要持久化生成后自动保存到文档记录下次打开直接显示
重新生成已有摘要时支持重新生成更新或优化摘要
一键复制复制摘要到剪贴板快速分享摘要

1.2 整体流程

图片.png

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;
}

设计要点:

  1. 异步线程:LLM调用在独立线程中执行,Controller线程立即返回SseEmitter,不阻塞
  2. 缓存优先:先查Redis,命中则直接流式返回,延迟极低
  3. 逐句推送:按标点切分,每句30-40ms间隔,模拟打字效果
  4. 事件规范: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

图片.png

点击AI生成摘要按钮:

图片.png

可以看到可以基于该文章正常生成摘要。

下次,再访问该文档详情,可以直接显示该摘要信息。

总结

本文详细介绍了从零实现AI智能摘要功能的完整过程,涵盖了以下核心内容:

已完成功能

功能实现方式说明
非流式摘要POST + JSON适合批量场景
流式摘要SSE + 逐句推送主交互路径,体验最佳
Redis缓存MD5去重 + 7天TTL避免重复LLM成本
内容截断头75% + 尾25%控制token用量
摘要保存PATCH端点部分更新,跳过全量校验
复制功能Clipboard API快速分享摘要
重新生成复用同一流程更新摘要
错误处理分级提示 + 重试健壮的用户体验
防重复调用useRef互斥锁避免竞态条件
组件清理AbortController避免内存泄漏

技术要点

  1. SSE流式模式:单向推送,实现简单,浏览器原生支持
  2. 缓存优先策略:先查Redis,命中率越高,用户体验越好
  3. 部分更新设计:PATCH端点,避免全量DTO校验的坑
  4. 前端状态管理:流式文字 + 持久化状态分离,Zustand直接更新
  5. 防御性编程:互斥锁、AbortController、空值守卫、try-catch全覆盖

通过本文的学习,你应该能够掌握:

  • SSE(Server-Sent Events)的完整实现模式
  • Redis缓存在AI场景中的最佳实践
  • 前端流式数据消费的通用方案
  • 微服务架构下的跨服务协作方式
  • PATCH端点用于部分更新的设计理念

祝你开发顺利!

最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏