一、概述

智能搜索是知识库系统的核心功能之一,不仅要支持传统的关键词匹配,还需要结合语义理解,让用户能够快速准确地找到所需知识。

本文将详细介绍如何从零构建一套完整的智能搜索系统,支持关键词搜索和混合智能搜索两种模式。

1.1 功能定位

智能搜索作为知识检索的入口,提供以下核心功能:

功能模块说明使用场景
关键词搜索基于ES multi\_match的BM25全文检索精确关键词匹配,快速返回
混合智能搜索BM25 + kNN向量 + RRF融合 + LLM重排序语义搜索,理解意图
搜索建议输入时自动补全文档标题提升搜索体验
搜索历史记录和展示用户搜索历史快速重复搜索
热门搜索统计并展示热门搜索关键词发现热门内容
高亮显示搜索结果中关键字高亮快速定位匹配内容
索引管理文档自动同步到ES索引保证搜索数据实时性

1.2 搜索模式对比

关键词搜索(BM25全文检索)

图片.png

混合智能搜索(BM25 + kNN + RRF + LLM Rerank)

图片.png

1.3 技术架构

整个智能搜索功能横跨多个微服务:

服务模块端口核心职责数据存储
kb-search8083搜索入口、关键词搜索、搜索历史ES(kb\_document索引)、MySQL
kb-ai8086RAG混合搜索、向量检索、LLM重排序ES(kb\_chunk索引)
kb-document8082文档管理、提供文档元数据MySQL

调用链路:

图片.png

二、数据库设计

2.1 搜索历史表

搜索历史记录存储在MySQL的kb_search_history表中:

CREATE TABLE `kb_search_history` (
  `id` BIGINT NOT NULL COMMENT '历史ID',
  `user_id` BIGINT NOT NULL COMMENT '用户ID',
  `keyword` VARCHAR(200) NOT NULL COMMENT '搜索关键词',
  `search_count` INT NOT NULL DEFAULT 1 COMMENT '搜索次数',
  `create_time` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '搜索时间',
  PRIMARY KEY (`id`),
  KEY `idx_user_id` (`user_id`),
  KEY `idx_keyword` (`keyword`),
  KEY `idx_create_time` (`create_time`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='搜索历史表';

2.2 字段说明

字段类型说明必填默认值
idBIGINT历史记录ID(雪花算法生成)是-
user\_idBIGINT用户ID是-
keywordVARCHAR(200)搜索关键词是-
search\_countINT搜索次数(同一用户同一关键词累加)是1
create\_timeDATETIME最近搜索时间是CURRENT\_TIMESTAMP

2.3 搜索历史UPSERT逻辑

同一用户搜索同一关键词时,不新增记录,而是更新search_count和create_time:

// 先查是否存在
SearchHistory existHistory = searchHistoryMapper.selectOne(
    new LambdaQueryWrapper<SearchHistory>()
        .eq(SearchHistory::getUserId, userId)
        .eq(SearchHistory::getKeyword, keyword)
);

if (existHistory != null) {
    // 存在:搜索次数+1,更新时间
    existHistory.setSearchCount(existHistory.getSearchCount() + 1);
    existHistory.setCreateTime(LocalDateTime.now());
    searchHistoryMapper.updateById(existHistory);
} else {
    // 不存在:新增记录
    SearchHistory history = new SearchHistory();
    history.setUserId(userId);
    history.setKeyword(keyword);
    history.setSearchCount(1);
    history.preInsert(); // 生成雪花ID
    searchHistoryMapper.insert(history);
}

三、Elasticsearch索引设计

3.1 kb\_document索引

关键词搜索使用的文档索引,存储文档的全文信息和元数据:

{
  "settings": {
    "number_of_shards": 1,
    "number_of_replicas": 0,
    "refresh_interval": "5s"
  },
  "mappings": {
    "properties": {
      "title":        { "type": "text", "analyzer": "ik_max_word", "fields": { "keyword": { "type": "keyword" } } },
      "summary":      { "type": "text", "analyzer": "ik_max_word" },
      "content":      { "type": "text", "analyzer": "ik_max_word" },
      "categoryId":   { "type": "long" },
      "categoryName": { "type": "keyword" },
      "tagIds":       { "type": "long" },
      "tagNames":     { "type": "keyword" },
      "creatorId":    { "type": "long" },
      "creatorName":  { "type": "keyword" },
      "teamId":       { "type": "long" },
      "teamName":     { "type": "keyword" },
      "docStatus":    { "type": "integer" },
      "viewCount":    { "type": "integer" },
      "likeCount":    { "type": "integer" },
      "commentCount": { "type": "integer" },
      "isPublic":     { "type": "boolean" },
      "publishAt":    { "type": "keyword" },
      "createdAt":    { "type": "keyword" },
      "updatedAt":    { "type": "keyword" }
    }
  }
}

设计要点:

  1. title/summary/content 使用ik_max_word分词器,支持中文分词搜索
  2. title.keyword 子字段用于前缀匹配(搜索建议)
  3. keyword类型用于精确匹配字段(如分类名、作者名、时间)
  4. 时间字段使用keyword类型而非date类型,避免LocalDateTime反序列化问题

3.2 kb\_chunk索引(kb-ai模块)

混合智能搜索使用的块级索引,存储文档分块和向量嵌入:

{
  "settings": {
    "number_of_shards": 3,
    "number_of_replicas": 1
  },
  "mappings": {
    "properties": {
      "chunkId":          { "type": "keyword" },
      "documentId":       { "type": "long" },
      "documentTitle":    { "type": "text", "analyzer": "ik_max_word" },
      "content":          { "type": "text", "analyzer": "ik_max_word" },
      "heading":          { "type": "keyword" },
      "embedding":        { "type": "dense_vector", "dims": 1024, "index": true, "similarity": "cosine" },
      "publishTime":      { "type": "keyword" },
      "documentStatus":   { "type": "integer" },
      "categoryId":       { "type": "long" }
    }
  }
}

设计要点:

  1. embedding 字段使用dense_vector类型,维度1024,支持cosineSimilarity向量检索
  2. content/documentTitle 使用ik_max_word分词器,支持BM25关键词检索
  3. 文档被分割为多个chunk(512字符/块,64字符重叠),每个chunk独立索引

四、实体类设计

4.1 创建DocumentIndex实体类(ES文档)

创建 kb-search/src/main/java/com/knowledge/base/search/entity/DocumentIndex.java:

package com.knowledge.base.search.entity;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;
import org.springframework.data.annotation.Id;
import org.springframework.data.elasticsearch.annotations.Document;
import org.springframework.data.elasticsearch.annotations.Field;
import org.springframework.data.elasticsearch.annotations.FieldType;

import java.util.List;

/**
 * ES文档索引实体
 *
 * <p>映射 kb_document 索引,存储文档的全文信息和元数据,
 * 供关键词搜索和高亮查询使用</p>
 *
 * @author 苏三
 * @since 1.0.0
 */
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Document(indexName = "kb_document", createIndex = false)
public class DocumentIndex {

    /** 文档ID(ES文档_id) */
    @Id
    private String id;

    /** 文档标题(IK分词,支持中文搜索) */
    @Field(type = FieldType.Text, analyzer = "ik_max_word")
    private String title;

    /** 文档摘要 */
    @Field(type = FieldType.Text, analyzer = "ik_max_word")
    private String summary;

    /** 文档正文内容 */
    @Field(type = FieldType.Text, analyzer = "ik_max_word")
    private String content;

    /** 分类ID */
    @Field(type = FieldType.Long)
    private Long categoryId;

    /** 分类名称 */
    @Field(type = FieldType.Keyword)
    private String categoryName;

    /** 标签ID列表 */
    @Field(type = FieldType.Long)
    private List<Long> tagIds;

    /** 标签名称列表 */
    @Field(type = FieldType.Keyword)
    private List<String> tagNames;

    /** 创建者ID */
    @Field(type = FieldType.Long)
    private Long creatorId;

    /** 创建者名称 */
    @Field(type = FieldType.Keyword)
    private String creatorName;

    /** 团队ID */
    @Field(type = FieldType.Long)
    private Long teamId;

    /** 团队名称 */
    @Field(type = FieldType.Keyword)
    private String teamName;

    /** 文档状态(1=已发布) */
    @Field(type = FieldType.Integer)
    private Integer docStatus;

    /** 浏览次数 */
    @Field(type = FieldType.Integer)
    private Integer viewCount;

    /** 点赞次数 */
    @Field(type = FieldType.Integer)
    private Integer likeCount;

    /** 评论次数 */
    @Field(type = FieldType.Integer)
    private Integer commentCount;

    /** 是否公开 */
    @Field(type = FieldType.Boolean)
    private Boolean isPublic;

    /** 发布时间(keyword类型,避免日期解析问题) */
    @Field(type = FieldType.Keyword)
    private String publishAt;

    /** 创建时间 */
    @Field(type = FieldType.Keyword)
    private String createdAt;

    /** 更新时间 */
    @Field(type = FieldType.Keyword)
    private String updatedAt;
}

设计要点:

  1. createIndex = false:不让Spring Data ES自动建索引,索引结构由代码手动控制
  2. IK分词器:对中文文本字段使用ik_max_word分词,标题额外保留keyword子字段
  3. 时间字段用Keyword:避免ES自动推断为date类型导致LocalDateTime反序列化失败

4.2 创建SearchHistory实体类(MySQL)

创建 kb-search/src/main/java/com/knowledge/base/search/entity/SearchHistory.java:

package com.knowledge.base.search.entity;

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import com.knowledge.base.common.utils.SnowflakeIdGenerator;
import lombok.Data;

import java.time.LocalDateTime;

/**
 * 搜索历史实体类
 *
 * @author 苏三
 * @since 1.0.0
 */
@Data
@TableName("kb_search_history")
public class SearchHistory {

    /** 历史记录ID(雪花算法生成) */
    @TableId(type = IdType.INPUT)
    private Long id;

    /** 用户ID */
    private Long userId;

    /** 搜索关键词 */
    private String keyword;

    /** 搜索次数 */
    private Integer searchCount;

    /** 搜索时间 */
    private LocalDateTime createTime;

    /**
     * 插入前自动生成雪花ID
     */
    public void preInsert() {
        if (this.id == null) {
            this.id = SnowflakeIdGenerator.getInstance().nextId();
        }
    }
}

五、DTO和VO设计

5.1 创建SearchRequestDTO

创建 kb-search/src/main/java/com/knowledge/base/search/dto/SearchRequestDTO.java:

package com.knowledge.base.search.dto;

import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.NotBlank;
import lombok.Data;

import java.io.Serializable;
import java.util.List;

/**
 * 搜索请求DTO
 *
 * @author 苏三
 * @since 1.0.0
 */
@Data
@Schema(description = "搜索请求")
public class SearchRequestDTO implements Serializable {

    private static final long serialVersionUID = 1L;

    /** 搜索关键词 */
    @Schema(description = "搜索关键词")
    @NotBlank(message = "搜索关键词不能为空")
    private String keyword;

    /** 分类ID列表(高级搜索) */
    @Schema(description = "分类ID列表")
    private List<Long> categoryIds;

    /** 标签ID列表(高级搜索) */
    @Schema(description = "标签ID列表")
    private List<Long> tagIds;

    /** 团队ID列表(高级搜索) */
    @Schema(description = "团队ID列表")
    private List<Long> teamIds;

    /** 创建者ID */
    @Schema(description = "创建者ID")
    private Long creatorId;

    /** 文档状态 */
    @Schema(description = "文档状态")
    private Integer docStatus;

    /** 开始时间 */
    @Schema(description = "开始时间")
    private String startTime;

    /** 结束时间 */
    @Schema(description = "结束时间")
    private String endTime;

    /** 排序字段 */
    @Schema(description = "排序字段")
    private String sortField;

    /** 排序方式 */
    @Schema(description = "排序方式")
    private String sortOrder;

    /** 页码 */
    @Schema(description = "页码")
    private Integer current = 1;

    /** 每页大小 */
    @Schema(description = "每页大小")
    private Integer size = 10;

    /**
     * 搜索模式:keyword(关键词搜索) / hybrid(混合智能搜索)
     */
    @Schema(description = "搜索模式:keyword / hybrid", example = "hybrid")
    private String searchMode = "keyword";

    /**
     * 混合搜索返回Top-K结果数(searchMode=hybrid时生效)
     */
    @Schema(description = "混合搜索Top-K")
    private int topK = 10;

    /**
     * 是否启用LLM重排序(searchMode=hybrid时生效)
     */
    @Schema(description = "是否启用LLM重排序")
    private boolean enableRerank = true;
}

5.2 创建SearchResultVO(含ChunkResult内部类)

创建 kb-search/src/main/java/com/knowledge/base/search/vo/SearchResultVO.java:

package com.knowledge.base.search.vo;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.io.Serializable;
import java.util.List;

/**
 * 搜索结果VO
 *
 * @author 苏三
 * @since 1.0.0
 */
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Schema(description = "搜索结果")
public class SearchResultVO implements Serializable {

    private static final long serialVersionUID = 1L;

    @Schema(description = "文档ID")
    private Long id;

    /** 文档标题(含高亮标签) */
    @Schema(description = "文档标题")
    private String title;

    /** 文档摘要(含高亮标签) */
    @Schema(description = "文档摘要")
    private String summary;

    /** 高亮片段列表(关键词搜索模式) */
    @Schema(description = "高亮片段")
    private List<String> highlights;

    @Schema(description = "分类名称")
    private String categoryName;

    @Schema(description = "标签名称列表")
    private List<String> tagNames;

    @Schema(description = "创建者名称")
    private String creatorName;

    @Schema(description = "团队名称")
    private String teamName;

    @Schema(description = "浏览次数")
    private Integer viewCount;

    @Schema(description = "点赞次数")
    private Integer likeCount;

    @Schema(description = "评论次数")
    private Integer commentCount;

    @Schema(description = "发布时间")
    private String publishAt;

    /** 相关度得分(0~1) */
    @Schema(description = "相关度得分")
    private Float score;

    /** BM25得分(混合搜索模式) */
    @Schema(description = "BM25得分")
    private Double bm25Score;

    /** 向量相似度得分(混合搜索模式) */
    @Schema(description = "向量相似度得分")
    private Double vectorScore;

    /** LLM重排序得分(混合搜索模式) */
    @Schema(description = "LLM重排序得分")
    private Double rerankScore;

    /** 文档块结果列表(混合搜索模式,含高亮) */
    @Schema(description = "文档块结果列表")
    private List<ChunkResult> chunks;

    // ==================== 内部类:文档块检索结果 ====================

    /**
     * 文档块检索结果
     *
     * <p>混合搜索返回的是块级结果,一个文档可能有多个块命中。
     * 每个块包含匹配的内容片段、所属章节标题和各项得分。</p>
     */
    @Data
    @Builder
    @NoArgsConstructor
    @AllArgsConstructor
    @Schema(description = "文档块检索结果")
    public static class ChunkResult implements Serializable {

        private static final long serialVersionUID = 1L;

        @Schema(description = "块ID")
        private String chunkId;

        @Schema(description = "块文本内容")
        private String content;

        @Schema(description = "所属章节标题")
        private String heading;

        @Schema(description = "融合/重排序得分")
        private double score;

        @Schema(description = "BM25得分")
        private double bm25Score;

        @Schema(description = "向量相似度得分")
        private double vectorScore;
    }
}

5.3 创建SearchSuggestVO

创建 kb-search/src/main/java/com/knowledge/base/search/vo/SearchSuggestVO.java:

package com.knowledge.base.search.vo;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.io.Serializable;

/**
 * 搜索建议VO
 *
 * @author 苏三
 * @since 1.0.0
 */
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class SearchSuggestVO implements Serializable {

    private static final long serialVersionUID = 1L;

    /** 建议文本 */
    private String text;

    /** 建议类型(title/author/category) */
    private String type;

    /** 关联文档ID */
    private Long documentId;

    /** 匹配得分 */
    private Float score;
}

5.4 创建SearchHistoryVO

创建 kb-search/src/main/java/com/knowledge/base/search/vo/SearchHistoryVO.java:

package com.knowledge.base.search.vo;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.time.LocalDateTime;

/**
 * 搜索历史VO
 *
 * @author 苏三
 * @since 1.0.0
 */
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class SearchHistoryVO {

    /** 历史ID */
    private Long id;

    /** 搜索关键词 */
    private String keyword;

    /** 搜索次数 */
    private Integer searchCount;

    /** 最近搜索时间 */
    private LocalDateTime createTime;
}

5.5 DTO/VO设计说明

类型用途特点
SearchRequestDTO接收搜索请求包含关键词、搜索模式、分页、筛选条件
SearchResultVO返回搜索结果包含高亮文本、得分详情、chunk列表
SearchSuggestVO返回搜索建议建议文本、类型、关联文档ID
SearchHistoryVO返回搜索历史关键词、搜索次数、时间

六、数据访问层

6.1 创建SearchHistoryMapper

创建 kb-search/src/main/java/com/knowledge/base/search/mapper/SearchHistoryMapper.java:

package com.knowledge.base.search.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.knowledge.base.search.entity.SearchHistory;
import org.apache.ibatis.annotations.Mapper;

/**
 * 搜索历史Mapper接口
 *
 * @author 苏三
 * @since 1.0.0
 */
@Mapper
public interface SearchHistoryMapper extends BaseMapper<SearchHistory> {

}

使用MyBatis Plus后,基础CRUD操作无需编写SQL:

// 自动生成以下SQL操作
searchHistoryMapper.selectById(id);
searchHistoryMapper.selectList(wrapper);
searchHistoryMapper.insert(history);
searchHistoryMapper.updateById(history);
searchHistoryMapper.deleteById(id);

6.2 Elasticsearch操作

搜索功能的数据操作主要面向ES,通过以下两个Bean进行操作:

// Spring Data ES高级操作(保存、删除、分页查询)
private final ElasticsearchOperations elasticsearchOperations;

// ES低级客户端(原生查询、高亮、索引管理)
private final ElasticsearchClient esClient;

两种客户端的适用场景:

场景使用客户端原因
保存/删除文档elasticsearchOperationssave()/delete() API简洁
关键词搜索 + 高亮esClient(原生)需要对query和高亮做精细控制
前缀建议查询elasticsearchOperationsStringQuery足够简单
创建/删除索引esClient(原生)Spring Data ES不支持索引管理

七、业务逻辑层

7.1 创建SearchService接口

创建 kb-search/src/main/java/com/knowledge/base/search/service/SearchService.java:

package com.knowledge.base.search.service;

import com.knowledge.base.common.result.PageResult;
import com.knowledge.base.search.dto.SearchRequestDTO;
import com.knowledge.base.search.vo.SearchResultVO;
import com.knowledge.base.search.vo.SearchSuggestVO;

import java.util.List;
import java.util.Map;

/**
 * 搜索Service接口
 *
 * @author 苏三
 * @since 1.0.0
 */
public interface SearchService {

    /**
     * 统一搜索入口(根据searchMode路由到关键词或混合搜索)
     */
    PageResult<SearchResultVO> search(SearchRequestDTO dto);

    /**
     * 高级搜索
     */
    PageResult<SearchResultVO> advancedSearch(SearchRequestDTO dto);

    /**
     * 搜索建议(输入自动补全)
     */
    List<SearchSuggestVO> suggest(String keyword, Integer size);

    /**
     * 索引单个文档(通过kb-document API拉取数据)
     */
    void indexDocument(Long documentId);

    /**
     * 直接从Map数据索引文档(kb-document内部调用)
     */
    void indexDocumentData(Map<String, Object> docData);

    /**
     * 批量索引文档
     */
    void batchIndexDocuments(List<Long> documentIds);

    /**
     * 删除文档索引
     */
    void deleteDocument(Long documentId);

    /**
     * 批量删除文档索引
     */
    void batchDeleteDocuments(List<Long> documentIds);

    /**
     * 重建索引(清空+全量同步kb-document已发布文档)
     */
    void rebuildIndex();
}

7.2 创建SearchServiceImpl实现类

创建 kb-search/src/main/java/com/knowledge/base/search/service/impl/SearchServiceImpl.java:

package com.knowledge.base.search.service.impl;

import co.elastic.clients.elasticsearch.ElasticsearchClient;
import co.elastic.clients.elasticsearch.core.SearchResponse;
import co.elastic.clients.elasticsearch.core.search.Hit;
import co.elastic.clients.elasticsearch.indices.CreateIndexRequest;
import co.elastic.clients.elasticsearch.indices.DeleteIndexRequest;
import co.elastic.clients.elasticsearch.indices.ExistsRequest;
import com.fasterxml.jackson.core.type.TypeReference;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.knowledge.base.common.exception.BusinessException;
import com.knowledge.base.common.result.PageResult;
import com.knowledge.base.common.result.Result;
import com.knowledge.base.search.dto.SearchRequestDTO;
import com.knowledge.base.search.entity.DocumentIndex;
import com.knowledge.base.search.feign.RagSearchFeignClient;
import com.knowledge.base.search.feign.RagSearchItemVO;
import com.knowledge.base.search.feign.RagSearchRequest;
import com.knowledge.base.search.service.SearchService;
import com.knowledge.base.search.vo.SearchResultVO;
import com.knowledge.base.search.vo.SearchSuggestVO;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.data.domain.PageRequest;
import org.springframework.data.elasticsearch.core.ElasticsearchOperations;
import org.springframework.data.elasticsearch.core.SearchHit;
import org.springframework.data.elasticsearch.core.SearchHits;
import org.springframework.data.elasticsearch.core.query.Query;
import org.springframework.data.elasticsearch.core.query.StringQuery;
import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpMethod;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Service;
import org.springframework.util.StringUtils;
import org.springframework.web.client.RestTemplate;

import java.util.ArrayList;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;

/**
 * 搜索服务实现
 *
 * <p>提供两种搜索模式:</p>
 * <ol>
 *   <li><b>关键词搜索</b>:基于 ES multi_match 的 BM25 全文检索,支持高亮</li>
 *   <li><b>混合智能搜索</b>:通过 Feign 调用 kb-ai 的 BM25 + kNN + RRF 融合检索</li>
 * </ol>
 *
 * @author 苏三
 * @since 1.0.0
 */
@Slf4j
@Service
@RequiredArgsConstructor
public class SearchServiceImpl implements SearchService {

    /** ES 索引名称 */
    private static final String INDEX_NAME = "kb_document";

    // ==================== 依赖注入 ====================

    private final ElasticsearchOperations elasticsearchOperations;
    private final ElasticsearchClient esClient;
    private final RagSearchFeignClient ragSearchFeignClient;
    private final ObjectMapper objectMapper = new ObjectMapper();

    @Value("${kb-document.base-url:http://localhost:8082}")
    private String kbDocumentBaseUrl;

    // ==================== 搜索入口 ====================

    @Override
    public PageResult<SearchResultVO> search(SearchRequestDTO dto) {
        if ("hybrid".equals(dto.getSearchMode())) {
            return searchHybrid(dto);
        }
        return searchKeyword(dto);
    }

    @Override
    public PageResult<SearchResultVO> advancedSearch(SearchRequestDTO dto) {
        log.info("高级搜索:keyword={}", dto.getKeyword());
        return search(dto);
    }
}

7.3 核心方法:关键词搜索

// ==================== 关键词搜索 ====================

/**
 * 关键词搜索(BM25 全文检索 + ES 高亮)
 *
 * <p>通过 ES 原生客户端构建 multi_match 查询,对 title、summary、content
 * 三个字段做加权匹配,title 权重最高。同时配置 ES highlight 返回高亮片段。</p>
 */
private PageResult<SearchResultVO> searchKeyword(SearchRequestDTO dto) {
    log.info("关键词搜索:keyword={}", dto.getKeyword());

    try {
        String keyword = dto.getKeyword();

        // 构建 ES 查询:multi_match 加权 + docStatus 过滤 + highlight
        SearchResponse<Map> response = esClient.search(s -> {
            s.index(INDEX_NAME)
             .from((dto.getCurrent() - 1) * dto.getSize())
             .size(dto.getSize());

            // 有关键词时:多字段加权匹配 + 已发布过滤
            if (StringUtils.hasText(keyword)) {
                s.query(q -> q.bool(b -> b
                        .must(m -> m.multiMatch(mm -> mm
                                .query(keyword)
                                .fields("title^2", "summary^1.5", "content")))
                        .filter(f -> f.term(t -> t.field("docStatus").value(1)))));
            } else {
                // 无关键词时:只过滤已发布
                s.query(q -> q.bool(b -> b
                        .filter(f -> f.term(t -> t.field("docStatus").value(1)))));
            }

            // 高亮配置:标题和摘要返回完整字段,内容返回 3 个片段
            s.highlight(h -> h
                    .preTags("<em>").postTags("</em>")
                    .fields("title", hf -> hf.numberOfFragments(0))
                    .fields("summary", hf -> hf.numberOfFragments(0))
                    .fields("content", hf -> hf.fragmentSize(150).numberOfFragments(3)));

            return s;
        }, Map.class);

        // 解析搜索结果,提取高亮字段
        List<SearchResultVO> results = new ArrayList<>();
        for (Hit<Map> hit : response.hits().hits()) {
            Map<String, Object> source = hit.source();

            // 从 ES hit 中提取高亮字段
            List<String> titleHighlights = hit.highlight() != null
                    ? hit.highlight().get("title") : null;
            List<String> summaryHighlights = hit.highlight() != null
                    ? hit.highlight().get("summary") : null;
            List<String> contentHighlights = hit.highlight() != null
                    ? hit.highlight().get("content") : null;

            // 标题:优先取高亮版本,合并相邻 em 标签
            String title = (titleHighlights != null && !titleHighlights.isEmpty())
                    ? mergeAdjacentEmTags(titleHighlights.get(0))
                    : getString(source, "title");
            String summary = (summaryHighlights != null && !summaryHighlights.isEmpty())
                    ? mergeAdjacentEmTags(summaryHighlights.get(0))
                    : getString(source, "summary");

            // ES 未返回高亮时,用简单正则高亮兜底
            if (titleHighlights == null && summaryHighlights == null
                    && StringUtils.hasText(keyword)) {
                title = highlightSimple(title, keyword);
                summary = highlightSimple(summary, keyword);
            }

            // 内容高亮片段
            List<String> highlights;
            if (contentHighlights != null && !contentHighlights.isEmpty()) {
                highlights = contentHighlights.stream()
                        .map(this::mergeAdjacentEmTags)
                        .collect(Collectors.toList());
            } else {
                highlights = new ArrayList<>();
            }

            results.add(SearchResultVO.builder()
                    .id(hit.id() != null ? Long.parseLong(hit.id()) : null)
                    .title(title)
                    .summary(summary)
                    .highlights(highlights)
                    .categoryName(getString(source, "categoryName"))
                    .tagNames(getStringList(source, "tagNames"))
                    .creatorName(getString(source, "creatorName"))
                    .teamName(getString(source, "teamName"))
                    .viewCount(toInt(source.get("viewCount")))
                    .likeCount(toInt(source.get("likeCount")))
                    .commentCount(toInt(source.get("commentCount")))
                    .publishAt(getString(source, "publishAt"))
                    .score(hit.score() != null ? hit.score().floatValue() : 0f)
                    .build());
        }

        return PageResult.<SearchResultVO>builder()
                .records(results)
                .total(response.hits().total() != null
                        ? response.hits().total().value() : 0L)
                .current((long) dto.getCurrent())
                .size((long) dto.getSize())
                .build();

    } catch (Exception e) {
        log.error("关键词搜索失败:{}", e.getMessage(), e);
        throw new BusinessException("搜索失败: " + e.getMessage());
    }
}

关键词搜索流程:

图片.png

7.4 核心方法:混合智能搜索

// ==================== 混合智能搜索 ====================

/**
 * 混合智能搜索(BM25 + kNN 向量 + RRF 融合 + LLM 重排序)
 *
 * <p>通过 Feign 调用 kb-ai 的 /rag/search 接口,获取 chunk 级检索结果后
 * 按 documentId 聚合为文档级结果,并从 kb_document 索引补充元数据。</p>
 *
 * <p>失败时自动回退到关键词搜索。</p>
 */
private PageResult<SearchResultVO> searchHybrid(SearchRequestDTO dto) {
    log.info("混合智能搜索:keyword={}, topK={}, enableRerank={}",
            dto.getKeyword(), dto.getTopK(), dto.isEnableRerank());

    try {
        // 1. 构建请求 → Feign 调用 kb-ai
        RagSearchRequest request = RagSearchRequest.builder()
                .query(dto.getKeyword())
                .topK(dto.getTopK() > 0 ? dto.getTopK() : 10)
                .enableRerank(dto.isEnableRerank())
                .build();

        Result<List<RagSearchItemVO>> result = ragSearchFeignClient.search(request);

        List<RagSearchItemVO> dataList = result.getData();
        if (dataList == null || dataList.isEmpty()) {
            return PageResult.<SearchResultVO>builder()
                    .records(new ArrayList<>())
                    .total(0L)
                    .current((long) dto.getCurrent())
                    .size((long) dto.getSize())
                    .build();
        }

        // 2. 按 documentId 聚合 chunk 为文档级结果
        Map<String, SearchResultVO> docMap = new LinkedHashMap<>();
        List<SearchResultVO> standaloneResults = new ArrayList<>();

        for (RagSearchItemVO item : dataList) {
            Long docId = item.getDocumentId();

            // 构建 chunk 结果对象
            SearchResultVO.ChunkResult chunk = SearchResultVO.ChunkResult.builder()
                    .chunkId(item.getChunkId())
                    .content(item.getContent())
                    .heading(item.getHeading())
                    .score(item.getScore())
                    .bm25Score(item.getBm25Score())
                    .vectorScore(item.getVectorScore())
                    .build();

            if (docId == null) {
                // 无 documentId:每个 chunk 独立展示
                String title = item.getDocumentTitle();
                if (title == null || title.isEmpty()) {
                    title = item.getHeading();
                }
                SearchResultVO vo = SearchResultVO.builder()
                        .title(title != null ? title : "未命名文档")
                        .summary(chunk.getContent().length() > 200
                                ? chunk.getContent().substring(0, 200) + "..."
                                : chunk.getContent())
                        .score((float) chunk.getScore())
                        .bm25Score(chunk.getBm25Score())
                        .vectorScore(chunk.getVectorScore())
                        .chunks(new ArrayList<>(List.of(chunk)))
                        .build();
                standaloneResults.add(vo);
                continue;
            }

            // 有 documentId:按 docId 聚合 chunk
            String docIdStr = String.valueOf(docId);
            if (docMap.containsKey(docIdStr)) {
                docMap.get(docIdStr).getChunks().add(chunk);
            } else {
                String publishTime = formatPublishTime(item.getPublishTime());
                SearchResultVO vo = SearchResultVO.builder()
                        .id(docId.longValue())
                        .title(item.getDocumentTitle())
                        .summary(chunk.getContent().length() > 200
                                ? chunk.getContent().substring(0, 200) + "..."
                                : chunk.getContent())
                        .publishAt(publishTime)
                        .score((float) chunk.getScore())
                        .bm25Score(chunk.getBm25Score())
                        .vectorScore(chunk.getVectorScore())
                        .chunks(new ArrayList<>(List.of(chunk)))
                        .build();
                docMap.put(docIdStr, vo);
            }
        }

        List<SearchResultVO> records = new ArrayList<>(docMap.values());
        records.addAll(standaloneResults);

        // 3. 对混合搜索结果做关键字高亮
        if (StringUtils.hasText(dto.getKeyword())) {
            for (SearchResultVO vo : records) {
                vo.setTitle(highlightSimple(vo.getTitle(), dto.getKeyword()));
                vo.setSummary(highlightSimple(vo.getSummary(), dto.getKeyword()));
                if (vo.getChunks() != null) {
                    for (SearchResultVO.ChunkResult chunk : vo.getChunks()) {
                        chunk.setContent(
                                highlightSimple(chunk.getContent(), dto.getKeyword()));
                    }
                }
            }
        }

        // 4. 从 kb_document ES 索引补充文档元数据(分类、作者、浏览数等)
        enrichDocumentMetadata(records);

        return PageResult.<SearchResultVO>builder()
                .records(records)
                .total((long) records.size())
                .current((long) dto.getCurrent())
                .size((long) dto.getSize())
                .build();

    } catch (Exception e) {
        log.error("混合智能搜索失败,回退到关键词搜索:{}", e.getMessage(), e);
        return searchKeyword(dto);
    }
}

混合搜索流程:

7.5 文档元数据补充

混合搜索的结果来自kb_chunk索引,只有块级信息(标题、内容、得分),缺少分类、作者等元数据。需要通过kb_document索引补充:

/**
 * 从 kb_document ES 索引批量补充文档元数据
 */
private void enrichDocumentMetadata(List<SearchResultVO> records) {
    if (records == null || records.isEmpty()) {
        return;
    }

    // 收集所有有 ID 的文档
    List<String> ids = records.stream()
            .filter(r -> r.getId() != null)
            .map(r -> String.valueOf(r.getId()))
            .distinct()
            .collect(Collectors.toList());

    if (ids.isEmpty()) {
        return;
    }

    try {
        // 用 terms 查询批量获取文档元数据
        String idsJson = ids.stream()
                .map(id -> "\"" + id + "\"")
                .collect(Collectors.joining(","));
        String queryJson = "{\"query\":{\"terms\":{\"_id\":["
                + idsJson + "]}},\"size\":" + ids.size() + "}";

        Query searchQuery = new StringQuery(queryJson);
        SearchHits<DocumentIndex> searchHits =
                elasticsearchOperations.search(searchQuery, DocumentIndex.class);

        Map<String, DocumentIndex> docIndexMap = searchHits.getSearchHits().stream()
                .collect(Collectors.toMap(
                        SearchHit::getId,
                        SearchHit::getContent,
                        (a, b) -> a));

        // 逐个填充缺失字段
        for (SearchResultVO vo : records) {
            if (vo.getId() == null) continue;
            DocumentIndex doc = docIndexMap.get(String.valueOf(vo.getId()));
            if (doc == null) continue;

            if (vo.getSummary() == null || vo.getSummary().isEmpty()) {
                vo.setSummary(doc.getSummary());
            }
            if (vo.getPublishAt() == null && doc.getPublishAt() != null) {
                vo.setPublishAt(doc.getPublishAt());
            }
            if (vo.getCategoryName() == null) {
                vo.setCategoryName(doc.getCategoryName());
            }
            if (vo.getCreatorName() == null) {
                vo.setCreatorName(doc.getCreatorName());
            }
            if (vo.getViewCount() == null) {
                vo.setViewCount(doc.getViewCount());
            }
            if (vo.getTagNames() == null) {
                vo.setTagNames(doc.getTagNames());
            }
            // 其他字段同理...
        }
    } catch (Exception e) {
        log.warn("补充文档元数据失败:{}", e.getMessage());
    }
}

7.6 搜索建议实现

通过ES的prefix查询匹配标题前缀:

@Override
public List<SearchSuggestVO> suggest(String keyword, Integer size) {
    if (!StringUtils.hasText(keyword)) {
        return new ArrayList<>();
    }

    if (size == null || size <= 0) {
        size = 10;
    }

    try {
        // 用 prefix 查询匹配标题前缀
        String queryJson = objectMapper.writeValueAsString(
                Map.of("prefix", Map.of("title.keyword", keyword)));
        Query searchQuery = new StringQuery(queryJson);
        searchQuery.setPageable(PageRequest.of(0, size));

        SearchHits<DocumentIndex> searchHits =
                elasticsearchOperations.search(searchQuery, DocumentIndex.class);

        return searchHits.getSearchHits().stream()
                .map(hit -> SearchSuggestVO.builder()
                        .text(hit.getContent().getTitle())
                        .type("title")
                        .documentId(Long.parseLong(hit.getId()))
                        .build())
                .collect(Collectors.toList());

    } catch (Exception e) {
        log.error("搜索建议失败:{}", e.getMessage(), e);
        return new ArrayList<>();
    }
}

7.7 高亮处理工具方法

// ==================== 高亮处理 ====================

/**
 * 简单关键字高亮:用 <em> 标签包裹匹配文本(大小写不敏感)
 */
private String highlightSimple(String text, String keyword) {
    if (text == null || keyword == null || keyword.isEmpty()) {
        return text;
    }
    String escaped = java.util.regex.Pattern.quote(keyword);
    return text.replaceAll("(?i)" + escaped, "<em>$0</em>");
}

/**
 * 合并相邻的 em 标签,解决 IK 分词器 token 碎片问题
 *
 * <p>例如:<em>索</em><em>引</em> → <em>索引</em></p>
 */
private String mergeAdjacentEmTags(String text) {
    if (text == null) return null;
    return text.replace("</em><em>", "");
}

IK分词器碎片问题:中文分词器IK可能将"索引"切分为"索"+"引"两个子token,导致ES返回 <em>索</em><em>引</em>。mergeAdjacentEmTags()方法将相邻的</em><em>标签合并为空,得到<em>索引</em>。

7.8 索引管理

// ==================== 索引管理 ====================

/**
 * 索引单个文档(通过 REST 调用 kb-document 获取文档详情)
 */
@Override
public void indexDocument(Long documentId) {
    if (documentId == null) {
        return;
    }
    log.info("索引文档:documentId={}", documentId);

    try {
        RestTemplate restTemplate = new RestTemplate();
        HttpHeaders headers = new HttpHeaders();
        headers.set("X-User-Id", "1");
        HttpEntity<Void> entity = new HttpEntity<>(headers);

        String url = kbDocumentBaseUrl + "/documents/" + documentId;
        ResponseEntity<String> response =
                restTemplate.exchange(url, HttpMethod.GET, entity, String.class);

        String body = response.getBody();
        if (body == null) {
            log.warn("kb-document 返回空响应:documentId={}", documentId);
            return;
        }

        Map<String, Object> respMap = objectMapper.readValue(body,
                new TypeReference<Map<String, Object>>() {});
        @SuppressWarnings("unchecked")
        Map<String, Object> docData = (Map<String, Object>) respMap.get("data");
        if (docData == null) {
            log.warn("文档数据为空:documentId={}", documentId);
            return;
        }

        // 构建索引对象并写入 ES
        DocumentIndex docIndex = buildDocumentIndexFromMap(docData);
        elasticsearchOperations.save(docIndex);
        log.info("文档索引成功:documentId={}, title={}",
                documentId, docIndex.getTitle());

    } catch (Exception e) {
        log.error("索引文档失败:documentId={}, error={}",
                documentId, e.getMessage(), e);
    }
}

/**
 * 从 kb-document API 响应数据构建 ES 文档索引对象
 */
private DocumentIndex buildDocumentIndexFromMap(Map<String, Object> docData) {
    Long docId = toLong(docData.get("id"));

    return DocumentIndex.builder()
            .id(docId != null ? String.valueOf(docId) : null)
            .title((String) docData.get("title"))
            .summary((String) docData.get("summary"))
            .content((String) docData.get("content"))
            .categoryId(toLong(docData.get("categoryId")))
            .categoryName((String) docData.get("categoryName"))
            .creatorName(toCreatorName(docData))
            .docStatus(toInt(docData.get("status")))
            .viewCount(toInt(docData.get("viewCount")))
            .likeCount(toInt(docData.get("likeCount")))
            .commentCount(toInt(docData.get("commentCount")))
            .isPublic(toInt(docData.get("isPublic")) == 1)
            .publishAt(formatPublishTime(getString(docData, "publishTime")))
            .createdAt(formatPublishTime(getString(docData, "createTime")))
            .updatedAt(formatPublishTime(getString(docData, "updateTime")))
            .build();
}

@Override
public void rebuildIndex() {
    log.info("重建索引开始:从 kb-document 同步所有已发布文档");

    try {
        // 1. 删除旧索引
        if (esClient.indices().exists(
                ExistsRequest.of(e -> e.index(INDEX_NAME))).value()) {
            esClient.indices().delete(
                    DeleteIndexRequest.of(d -> d.index(INDEX_NAME)));
            log.info("旧索引删除成功");
        }

        // 2. 创建新索引(带显式 mapping)
        CreateIndexRequest createRequest = CreateIndexRequest.of(c -> c
                .index(INDEX_NAME)
                .settings(s -> s
                        .numberOfShards("1")
                        .numberOfReplicas("0")
                        .refreshInterval(ri -> ri.time("5s")))
                .mappings(m -> m
                        .properties("title", p -> p.text(t ->
                                t.fields("keyword", f -> f.keyword(k -> k))))
                        .properties("summary", p -> p.text(t -> t))
                        .properties("content", p -> p.text(t -> t))
                        .properties("categoryName", p -> p.keyword(k -> k))
                        .properties("tagNames", p -> p.keyword(k -> k))
                        .properties("creatorName", p -> p.keyword(k -> k))
                        .properties("viewCount", p -> p.integer(i -> i))
                        .properties("likeCount", p -> p.integer(i -> i))
                        .properties("commentCount", p -> p.integer(i -> i))
                        .properties("publishAt", p -> p.keyword(k -> k))
                        .properties("createdAt", p -> p.keyword(k -> k))
                        .properties("updatedAt", p -> p.keyword(k -> k))));
        esClient.indices().create(createRequest);

        // 3. 分页从 kb-document 拉取已发布文档并索引
        RestTemplate restTemplate = new RestTemplate();
        // ... 分页调用 /documents/page?current=X&size=50&status=1
        // ... 逐个 buildDocumentIndexFromMap + elasticsearchOperations.save

        log.info("索引重建完成");

    } catch (Exception e) {
        log.error("重建索引失败:{}", e.getMessage(), e);
        throw new BusinessException("重建索引失败: " + e.getMessage());
    }
}

7.9 创建SearchHistoryService

创建 kb-search/src/main/java/com/knowledge/base/search/service/impl/SearchHistoryServiceImpl.java:

package com.knowledge.base.search.service.impl;

import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.knowledge.base.search.entity.SearchHistory;
import com.knowledge.base.search.mapper.SearchHistoryMapper;
import com.knowledge.base.search.service.SearchHistoryService;
import com.knowledge.base.search.vo.SearchHistoryVO;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import org.springframework.util.StringUtils;

import java.time.LocalDateTime;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.stream.Collectors;

/**
 * 搜索历史Service实现
 *
 * @author 苏三
 * @since 1.0.0
 */
@Slf4j
@Service
@RequiredArgsConstructor
public class SearchHistoryServiceImpl implements SearchHistoryService {

    private final SearchHistoryMapper searchHistoryMapper;

    @Override
    public List<SearchHistoryVO> getSearchHistory(Long userId) {
        // 按 keyword 分组,取每组最新的记录,返回前20条
        List<SearchHistory> histories = searchHistoryMapper.selectList(
                new LambdaQueryWrapper<SearchHistory>()
                        .eq(SearchHistory::getUserId, userId)
                        .orderByDesc(SearchHistory::getCreateTime));

        // 按 keyword 去重,每个关键词取搜索次数最多的
        Map<String, SearchHistory> grouped = histories.stream()
                .collect(Collectors.toMap(
                        SearchHistory::getKeyword,
                        h -> h,
                        (a, b) -> a.getSearchCount() >= b.getSearchCount() ? a : b));

        return grouped.values().stream()
                .sorted((a, b) -> b.getCreateTime().compareTo(a.getCreateTime()))
                .limit(20)
                .map(h -> SearchHistoryVO.builder()
                        .id(h.getId())
                        .keyword(h.getKeyword())
                        .searchCount(h.getSearchCount())
                        .createTime(h.getCreateTime())
                        .build())
                .collect(Collectors.toList());
    }

    @Override
    public void saveSearchHistory(Long userId, String keyword) {
        if (userId == null || !StringUtils.hasText(keyword)) {
            return;
        }

        // UPSERT: 同一用户同一关键词,更新搜索次数和时间
        SearchHistory existHistory = searchHistoryMapper.selectOne(
                new LambdaQueryWrapper<SearchHistory>()
                        .eq(SearchHistory::getUserId, userId)
                        .eq(SearchHistory::getKeyword, keyword));

        if (existHistory != null) {
            existHistory.setSearchCount(existHistory.getSearchCount() + 1);
            existHistory.setCreateTime(LocalDateTime.now());
            searchHistoryMapper.updateById(existHistory);
        } else {
            SearchHistory history = new SearchHistory();
            history.setUserId(userId);
            history.setKeyword(keyword);
            history.setSearchCount(1);
            history.preInsert();
            searchHistoryMapper.insert(history);
        }
    }

    @Override
    public List<String> getHotSearch() {
        // 最近7天,按搜索次数降序,取前10
        LocalDateTime sevenDaysAgo = LocalDateTime.now().minusDays(7);

        List<SearchHistory> histories = searchHistoryMapper.selectList(
                new LambdaQueryWrapper<SearchHistory>()
                        .ge(SearchHistory::getCreateTime, sevenDaysAgo)
                        .orderByDesc(SearchHistory::getSearchCount)
                        .last("LIMIT 10"));

        return histories.stream()
                .map(SearchHistory::getKeyword)
                .distinct()
                .collect(Collectors.toList());
    }

    @Override
    public Boolean clearSearchHistory(Long userId) {
        return searchHistoryMapper.delete(
                new LambdaQueryWrapper<SearchHistory>()
                        .eq(SearchHistory::getUserId, userId)) > 0;
    }

    @Override
    public Boolean deleteSearchHistory(Long historyId, Long userId) {
        return searchHistoryMapper.delete(
                new LambdaQueryWrapper<SearchHistory>()
                        .eq(SearchHistory::getId, historyId)
                        .eq(SearchHistory::getUserId, userId)) > 0;
    }
}

八、Feign客户端设计

8.1 为什么用Feign

kb-search和kb-ai是两个独立的微服务,kb-search需要通过内部REST调用kb-ai的混合搜索接口。使用OpenFeign替代RestTemplate有以下优势:

对比项RestTemplateFeign
调用方式手动构造URL和请求声明式接口,像本地方法调用
类型安全返回String,手动JSON解析强类型DTO,自动序列化/反序列化
服务发现手动拼接IP:端口集成Nacos,自动负载均衡
代码量大量样板代码只需接口+注解

8.2 创建Feign接口

创建 kb-search/src/main/java/com/knowledge/base/search/feign/RagSearchFeignClient.java:

package com.knowledge.base.search.feign;

import com.knowledge.base.common.result.Result;
import org.springframework.cloud.openfeign.FeignClient;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;

import java.util.List;

/**
 * kb-ai RAG混合搜索Feign客户端
 *
 * @author 苏三
 * @since 1.0.0
 */
@FeignClient(
        name = "kb-ai",           // 服务名,对应Nacos注册名
        path = "/rag",            // 基础路径
        contextId = "ragSearchFeignClient"
)
public interface RagSearchFeignClient {

    /**
     * 混合搜索 (BM25 + kNN + RRF融合)
     *
     * @param request 搜索请求
     * @return 搜索结果列表
     */
    @PostMapping("/search")
    Result<List<RagSearchItemVO>> search(@RequestBody RagSearchRequest request);
}

8.3 创建请求和响应DTO

创建 kb-search/src/main/java/com/knowledge/base/search/feign/RagSearchRequest.java:

package com.knowledge.base.search.feign;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

/**
 * RAG混合搜索请求
 */
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class RagSearchRequest {

    /** 查询文本 */
    private String query;

    /** 返回Top-K结果数 */
    @Builder.Default
    private int topK = 10;

    /** 是否启用LLM重排序 */
    @Builder.Default
    private boolean enableRerank = true;
}

创建 kb-search/src/main/java/com/knowledge/base/search/feign/RagSearchItemVO.java:

package com.knowledge.base.search.feign;

import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

/**
 * RAG混合搜索结果项(匹配 kb-ai 的 RagSearchResultVO)
 */
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class RagSearchItemVO {

    /** 块ID */
    private String chunkId;

    /** 来源文档ID */
    private Long documentId;

    /** 来源文档标题 */
    private String documentTitle;

    /** 块文本内容 */
    private String content;

    /** 所属章节标题 */
    private String heading;

    /** 融合/重排序得分 */
    private double score;

    /** BM25得分 */
    private double bm25Score;

    /** 向量相似度得分 */
    private double vectorScore;

    /** 文档发布时间 */
    private String publishTime;
}

8.4 启用Feign

在启动类上添加@EnableFeignClients注解:

package com.knowledge.base.search;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.openfeign.EnableFeignClients;

/**
 * 搜索服务启动类
 */
@EnableFeignClients(basePackages = "com.knowledge.base.search.feign")
@SpringBootApplication(scanBasePackages = "com.knowledge.base")
public class SearchApplication {

    public static void main(String[] args) {
        SpringApplication.run(SearchApplication.class, args);
    }
}

8.5 添加Feign依赖

在kb-search/pom.xml中添加:

<!-- OpenFeign + LoadBalancer(调用 kb-ai 混合搜索) -->
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-openfeign</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-loadbalancer</artifactId>
</dependency>

九、控制器层

9.1 创建SearchController

创建 kb-search/src/main/java/com/knowledge/base/search/controller/SearchController.java:

package com.knowledge.base.search.controller;

import com.knowledge.base.common.result.PageResult;
import com.knowledge.base.common.result.Result;
import com.knowledge.base.search.dto.SearchRequestDTO;
import com.knowledge.base.search.service.SearchHistoryService;
import com.knowledge.base.search.service.SearchService;
import com.knowledge.base.search.vo.SearchHistoryVO;
import com.knowledge.base.search.vo.SearchResultVO;
import com.knowledge.base.search.vo.SearchSuggestVO;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.validation.Valid;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.*;

import java.util.List;
import java.util.Map;
import java.util.concurrent.CompletableFuture;

/**
 * 搜索Controller
 *
 * @author 苏三
 * @since 1.0.0
 */
@Slf4j
@RestController
@RequestMapping("")
@RequiredArgsConstructor
@Tag(name = "搜索服务", description = "搜索相关接口")
public class SearchController {

    private final SearchService searchService;
    private final SearchHistoryService searchHistoryService;

    /**
     * 全文搜索
     */
    @PostMapping
    @Operation(summary = "全文搜索", description = "执行全文搜索")
    public Result<PageResult<SearchResultVO>> search(
            @Valid @RequestBody SearchRequestDTO dto,
            HttpServletRequest request) {
        PageResult<SearchResultVO> result = searchService.search(dto);

        // 异步保存搜索历史(不影响搜索响应速度)
        Long userId = getUserId(request);
        String keyword = dto.getKeyword();
        CompletableFuture.runAsync(() -> {
            try {
                searchHistoryService.saveSearchHistory(userId, keyword);
            } catch (Exception e) {
                log.warn("保存搜索历史失败:keyword={}, error={}",
                        keyword, e.getMessage());
            }
        });
        return Result.success(result);
    }

    /**
     * 搜索建议
     */
    @GetMapping("/suggest")
    @Operation(summary = "搜索建议", description = "获取搜索建议")
    public Result<List<SearchSuggestVO>> suggest(
            @RequestParam String keyword,
            @RequestParam(defaultValue = "10") Integer size) {
        List<SearchSuggestVO> suggestions = searchService.suggest(keyword, size);
        return Result.success(suggestions);
    }

    /**
     * 热门搜索
     */
    @GetMapping("/hot")
    @Operation(summary = "热门搜索", description = "获取系统热门搜索关键词")
    public Result<List<String>> hotSearch() {
        List<String> hotSearches = searchHistoryService.getHotSearch();
        return Result.success(hotSearches);
    }

    /**
     * 搜索历史
     */
    @GetMapping("/history")
    @Operation(summary = "搜索历史", description = "获取当前用户搜索历史")
    public Result<List<SearchHistoryVO>> searchHistory(HttpServletRequest request) {
        Long userId = getUserId(request);
        List<SearchHistoryVO> history = searchHistoryService.getSearchHistory(userId);
        return Result.success(history);
    }

    /**
     * 清空搜索历史
     */
    @DeleteMapping("/history")
    @Operation(summary = "清空搜索历史", description = "清空当前用户搜索历史")
    public Result<Boolean> clearSearchHistory(HttpServletRequest request) {
        Long userId = getUserId(request);
        Boolean success = searchHistoryService.clearSearchHistory(userId);
        return Result.success(success);
    }

    /**
     * 重建索引
     */
    @PostMapping("/index/rebuild")
    @Operation(summary = "重建索引", description = "重建搜索索引")
    public Result<String> rebuildIndex() {
        searchService.rebuildIndex();
        return Result.success("索引重建任务已提交");
    }

    /**
     * 索引文档(供kb-document内部调用)
     */
    @PostMapping("/index/document")
    @Operation(summary = "索引文档", description = "从文档数据直接索引到ES")
    public Result<Boolean> indexDocument(@RequestBody Map<String, Object> docData) {
        searchService.indexDocumentData(docData);
        return Result.success(true);
    }

    /**
     * 删除文档索引(供kb-document内部调用)
     */
    @DeleteMapping("/index/document/{documentId}")
    @Operation(summary = "删除文档索引", description = "从ES删除文档索引")
    public Result<Boolean> deleteDocumentIndex(@PathVariable Long documentId) {
        searchService.deleteDocument(documentId);
        return Result.success(true);
    }

    /**
     * 获取用户ID(从请求头解析)
     */
    private Long getUserId(HttpServletRequest request) {
        String userId = request.getHeader("X-User-Id");
        if (userId != null) {
            return Long.parseLong(userId);
        }
        return 1L; // 默认用户
    }
}

9.2 RESTful API设计

方法路径说明关键参数
POST/全文搜索(关键词/混合)keyword, searchMode, topK, enableRerank
POST/advanced高级搜索keyword + 分类/标签/时间筛选
GET/suggest搜索自动补全keyword, size
GET/hot热门搜索词-
GET/history用户搜索历史- (X-User-Id头部)
DELETE/history清空搜索历史- (X-User-Id头部)
POST/index/rebuild重建ES索引-
POST/index/document索引文档(内部调用)docData(Map)
DELETE/index/document/{id}删除文档索引(内部调用)documentId

9.3 异步保存搜索历史

搜索响应的速度直接影响用户体验,因此搜索历史的保存采用异步方式:

// 关键:在进入异步方法之前,从 request 中提取 userId 和 keyword
Long userId = getUserId(request);
String keyword = dto.getKeyword();

// 使用 CompletableFuture 异步执行,不阻塞搜索响应
CompletableFuture.runAsync(() -> {
    try {
        searchHistoryService.saveSearchHistory(userId, keyword);
    } catch (Exception e) {
        log.warn("保存搜索历史失败:keyword={}, error={}", keyword, e.getMessage());
    }
});

注意事项: 必须先提取userId和keyword再传入lambda,因为Tomcat可能在方法返回后回收HttpServletRequest对象。


十、kb-ai混合搜索集成

10.1 kb-ai的RAG检索架构

kb-ai模块实现了完整的RAG(Retrieval-Augmented Generation)混合检索管线:

image

10.2 向量检索的实现

kb-ai中向量检索使用ES的script_score查询:

// 使用 cosineSimilarity 计算查询向量与文档向量的相似度
esClient.search(s -> s
    .index(KB_CHUNK_INDEX)
    .query(q -> q.scriptScore(ss -> ss
        .query(qq -> qq.matchAll(m -> m))
        .script(sc -> sc
            .source("cosineSimilarity(params.query_vector, 'embedding') + 1.0")
            .params("query_vector", JsonData.of(queryEmbedding)))))
    .size(hybridTopK), Map.class);

10.3 RRF融合算法

// RRF (Reciprocal Rank Fusion)
// score(d) = Σ( 1 / (C + rank_r(d)) )
// 其中 C=60 为平滑常数

Map<String, RRFScore> rrfScores = new LinkedHashMap<>();

// 合并BM25排序结果
for (int i = 0; i < bm25Results.size(); i++) {
    String id = bm25Results.get(i).getId();
    double bm25Score = 1.0 / (RRF_C + i + 1);
    rrfScores.put(id, new RRFScore(bm25Score, 0.0));
}

// 合并kNN排序结果
for (int i = 0; i < knnResults.size(); i++) {
    String id = knnResults.get(i).getId();
    double knnScore = 1.0 / (RRF_C + i + 1);
    rrfScores.compute(id, (k, v) -> {
        if (v == null) return new RRFScore(0.0, knnScore);
        v.rrfScore += knnScore;
        v.knnScore = knnScore;
        return v;
    });
}

10.4 kb-ai的RagSearchController

创建 kb-ai/src/main/java/com/knowledge/base/ai/controller/RagSearchController.java:

@Slf4j
@RestController
@RequestMapping("/rag/search")
@RequiredArgsConstructor
@Tag(name = "RAG检索", description = "知识库RAG检索接口")
public class RagSearchController {

    private final RagRetrievalService ragRetrievalService;

    @PostMapping
    @Operation(summary = "RAG检索", description = "基于RAG的知识库检索,不生成回答")
    public Result<List<RagSearchResultVO>> search(
            @Valid @RequestBody RagSearchRequestDTO requestDTO) {
        List<RagSearchResultVO> results = ragRetrievalService.retrieve(
                requestDTO.getQuery(),
                requestDTO.getTopK(),
                requestDTO.isEnableRerank());
        return Result.success(results);
    }
}

十一、前端实现

11.1 TypeScript类型定义

在 src/types/index.ts 中添加搜索相关类型:

// 文档块结果
export interface ChunkResult {
  chunkId: string;
  content: string;
  heading?: string;
  score: number;
  bm25Score: number;
  vectorScore: number;
}

// 搜索结果
export interface SearchResult {
  id: string;
  title: string;
  summary?: string;
  highlights?: string[];
  categoryName?: string;
  tagNames?: string[];
  creatorName?: string;
  teamName?: string;
  viewCount?: number;
  likeCount?: number;
  commentCount?: number;
  publishAt?: string;
  score: number;
  bm25Score?: number;
  vectorScore?: number;
  rerankScore?: number;
  chunks?: ChunkResult[];  // 混合搜索模式的块级结果
}

// 分页搜索结果
export interface SearchResponse {
  records: SearchResult[];
  total: number;
  current: number;
  size: number;
}

11.2 API服务层

创建 src/services/search.service.ts:

import { http } from './request';
import { SearchResponse } from '@/types';

export interface SearchParams {
  keyword: string;
  searchMode?: 'keyword' | 'hybrid';
  topK?: number;
  enableRerank?: boolean;
  page?: number;
  pageSize?: number;
  sortBy?: 'relevance' | 'time' | 'views';
}

export const searchService = {
  // 智能搜索(keyword / hybrid)
  search: (params: SearchParams) => {
    return http.post<SearchResponse>('/search', {
      keyword: params.keyword,
      searchMode: params.searchMode || 'keyword',
      topK: params.topK || 10,
      enableRerank: params.enableRerank ?? true,
      current: params.page || 1,
      size: params.pageSize || 10,
      sortField: params.sortBy,
    });
  },

  // 搜索建议(自动补全)
  suggestions: (keyword: string) => {
    return http.get<SearchSuggestVO[]>('/search/suggest', {
      params: { keyword, size: 8 },
    });
  },

  // 热门搜索
  hotSearch: () => {
    return http.get<string[]>('/search/hot');
  },

  // 搜索历史
  history: () => {
    return http.get<SearchHistoryVO[]>('/search/history');
  },

  // 清除搜索历史
  clearHistory: () => {
    return http.delete('/search/history');
  },
};

export default searchService;

11.3 页面组件核心逻辑

创建 src/pages/SearchPage.tsx,核心功能包括:

1. 搜索模式切换

// 状态:keyword 或 hybrid
const [searchMode, setSearchMode] = useState<'keyword' | 'hybrid'>('hybrid');

// 切换模式后自动重新搜索
const isFirstRender = useRef(true);
useEffect(() => {
  if (isFirstRender.current) {
    isFirstRender.current = false;
    return;
  }
  if (query.trim()) {
    performSearch(query);
  }
}, [searchMode]);

2. 防抖搜索建议(300ms)

const fetchSuggestions = useCallback(async (keyword: string) => {
  if (keyword.trim().length < 1) {
    setSuggestions([]);
    setShowSuggestions(false);
    return;
  }
  const data = await searchService.suggestions(keyword);
  setSuggestions(data.map((s: any) => ({ text: s.text || s })));
  setShowSuggestions(true);
}, []);

const handleInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
  const value = e.target.value;
  setQuery(value);
  if (suggestTimer.current) clearTimeout(suggestTimer.current);
  suggestTimer.current = setTimeout(() => fetchSuggestions(value), 300);
};

3. 搜索方法

const performSearch = async (keyword: string, currentPage = 1) => {
  const q = keyword || query;
  if (!q.trim()) return;

  setLoading(true);
  setSearched(true);
  setShowSuggestions(false);

  const response = await searchService.search({
    keyword: q,
    searchMode,
    topK: 10,
    enableRerank: true,
    page: currentPage,
    pageSize,
  });
  setResults(response.records || []);
  setTotal(response.total || 0);
  // 刷新搜索历史
  loadHistory();
  loadHotSearches();
};

4. 关键字高亮渲染

// 后端返回的高亮文本包含 <em> 标签,用 dangerouslySetInnerHTML 渲染
<h3
  className="result-title"
  dangerouslySetInnerHTML={{ __html: result.title || '未命名文档' }}
/>

// 摘要:优先检测后端已高亮的 <em> 标签,否则用客户端高亮
<div
  className="result-excerpt"
  dangerouslySetInnerHTML={{
    __html: result.summary.includes('<em>')
      ? result.summary
      : highlightKeyword(result.summary)
  }}
/>

// 客户端高亮辅助函数
const highlightKeyword = (text: string): string => {
  if (!text || !query) return text;
  const regex = new RegExp(`(${query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')})`, 'gi');
  return text.replace(regex, '<mark>$1</mark>');
};

5. 混合搜索得分展示

{searchMode === 'hybrid' && (
  <div className="score-breakdown">
    {result.bm25Score !== undefined && (
      <span className="score-chip bm25">
        BM25 {(result.bm25Score * 100).toFixed(0)}
      </span>
    )}
    {result.vectorScore !== undefined && (
      <span className="score-chip vector">
        向量 {(result.vectorScore * 100).toFixed(0)}
      </span>
    )}
    {result.rerankScore !== undefined && (
      <span className="score-chip rerank">
        重排 {(result.rerankScore * 100).toFixed(0)}
      </span>
    )}
  </div>
)}

6. Chunk展开/折叠

{searchMode === 'hybrid' && result.chunks && result.chunks.length > 0 && (
  <div className="result-chunks" onClick={(e) => { e.stopPropagation(); toggleChunks(result.id); }}>
    <div className="chunks-toggle">
      相关片段 ({result.chunks.length})
      <span className={`toggle-arrow ${expandedChunks.has(result.id) ? 'expanded' : ''}`}>
        &#9654;
      </span>
    </div>
    {expandedChunks.has(result.id) && result.chunks.map((chunk, idx) => (
      <div key={chunk.chunkId || idx} className="chunk-item">
        {chunk.heading && <div className="chunk-heading">{chunk.heading}</div>}
        <div
          className="chunk-content"
          dangerouslySetInnerHTML={{
            __html: (() => {
              const text = chunk.content.length > 300
                ? chunk.content.slice(0, 300) + '...' : chunk.content;
              return text.includes('<em>') ? text : highlightKeyword(text);
            })()
          }}
        />
      </div>
    ))}
  </div>
)}

11.4 CSS样式设计

创建 src/pages/SearchPage.css,核心样式要点:

搜索框聚焦效果

.search-box-wrapper {
  background: #ffffff;
  border-radius: 16px;
  padding: 8px;
  display: flex;
  box-shadow: 0 20px 25px -5px rgba(0, 0, 0, 0.1);
  border: 2px solid #e2e8f0;
  transition: all 0.3s;
}

.search-box-wrapper:focus-within {
  border-color: #2563eb;
  box-shadow: 0 0 0 4px rgba(37, 99, 235, 0.1);
}

搜索模式切换按钮

.mode-btn {
  padding: 8px 18px;
  border-radius: 20px;
  border: 1px solid #e2e8f0;
  background: #ffffff;
  color: #64748b;
  cursor: pointer;
  transition: all 0.2s;
}

.mode-btn.active {
  background: #2563eb;
  color: #ffffff;
}

.mode-btn.hybrid.active {
  background: linear-gradient(135deg, #6366f1, #4f46e5);
}

高亮样式(em和mark统一处理)

.result-excerpt mark,
.result-excerpt em,
.result-title em {
  background: #fef3c7;
  color: #0f172a;
  padding: 0 2px;
  border-radius: 2px;
  font-style: normal;
}

得分徽章

.score-chip.bm25  { background: #eff6ff; color: #2563eb; }
.score-chip.vector { background: #ecfeff; color: #0891b2; }
.score-chip.rerank { background: #fef9c3; color: #a16207; }

十二、配置文件

12.1 kb-search的application.yml

server:
  port: 8083

spring:
  application:
    name: kb-search
  datasource:
    url: jdbc:mysql://localhost:3306/kb_search?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai
    username: root
    password: root
    driver-class-name: com.mysql.cj.jdbc.Driver
  data:
    redis:
      host: localhost
      port: 6379
      database: 2
  elasticsearch:
    uris: http://117.72.88.11:9200
    username: elastic
    password: susan123
  cloud:
    nacos:
      discovery:
        server-addr: 117.72.88.11:8848
        namespace: KNOWLEDGE_BASE
      config:
        server-addr: 117.72.88.11:8848
        namespace: KNOWLEDGE_BASE

mybatis-plus:
  mapper-locations: classpath*:/mapper/**/*.xml
  configuration:
    map-underscore-to-camel-case: true

# kb-document服务地址(用于索引同步)
kb-document:
  base-url: http://localhost:8082

测试

按顺序启动下面这些微服务:

kb-gateway

kb-auth

kb-ai

kb-document

kb-search

启动前端

cd knowledge-base-frontend

npm run dev

浏览器访问

http://localhost:3002/search

image

关键字搜索:

image

混合智能搜索:

image

image

总结

15.1 已完成功能

功能实现方式说明
关键词搜索ES multi\_match BM25多字段加权匹配 (title2, summary1.5, content)
混合智能搜索Feign → kb-aiBM25 + kNN向量 + RRF融合 + LLM重排序
搜索高亮ES原生highlight标题/摘要完整字段,内容3片段
高亮碎片修复mergeAdjacentEmTags()合并IK分词器产生的相邻em标签
搜索建议ES prefix querytitle.keyword前缀匹配
搜索历史MySQL + MyBatis PlusUPSERT逻辑,异步保存
热门搜索MySQL聚合查询最近7天,按搜索次数降序
索引同步REST调用kb-document创建/更新/删除文档后自动更新ES索引
索引重建分页拉取 + 批量写入删除旧索引→创建新索引→全量同步
异常回退try-catch + fallback混合搜索失败自动回退到关键词搜索
元数据补充ES terms批量查询混合搜索结果补充分类、作者、统计信息

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

  • Elasticsearch的全文检索(multi\_match、highlight、prefix)实现
  • Spring Data Elasticsearch和ES原生客户端的配合使用
  • BM25 + kNN向量 + RRF混合检索的整体架构
  • OpenFeign微服务间调用的声明式实现
  • React前端搜索页面的完整实现(防抖建议、高亮渲染、chunk展开)
  • 搜索历史UPSERT和异步保存的设计模式
  • 各种边界情况(IK分词语高亮碎片、时间字段反序列化、请求对象回收)的处理方案
最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏