前言

企业智能知识库系统的检索需求不同于简单的数据库 LIKE 查询。

随着知识文档的积累,用户需要:

  1. 中文分词精准匹配:"人工智能应用" 匹配到 "AI 技术在实际业务中的应用" —— 需要分词器理解中文语义
  2. 相关度排序:标题命中比内容命中更相关,摘要命中权重居中
  3. 关键词高亮:搜索结果中预匹配词高亮,帮助用户快速定位
  4. 语义理解:用户搜索 "怎么提高效率" → 向量检索匹配到包含 "工作效率提升方法" 的文档
  5. 实时索引同步:文档发布/更新/删除后立即同步到搜索引擎

本系统的检索架构采用 Elasticsearch 8.x + IK 中文分词(关键词搜索) + 向量嵌入(混合智能搜索) 双模设计。kb-search 服务提供全文检索、搜索建议、热门搜索和搜索历史管理;kb-ai 服务提供 BM25 + kNN 向量 + RRF 融合 + LLM 重排序的混合智能搜索能力。

1. 先结论:一次搜索请求走了什么链路

以用户在搜索框输入"知识图谱应用",选择"关键词搜索"模式为例:

用户在 SearchPage 输入 "知识图谱应用",按回车
  → 前端 POST /search { keyword: "知识图谱应用", searchMode: "keyword", current: 1, size: 10 }
  → SearchController.search(dto)
       ├── searchService.search(dto)
       │     └── searchMode = "keyword" → searchKeyword(dto)
       │           ├── 构建 ES native query(co.elastic.clients)
       │           │     └── multi_match: "知识图谱应用"
       │           │           fields: ["title^2", "summary^1.5", "content"]
       │           │           filter: docStatus = 1(仅已发布文档)
       │           ├── ES 返回 hits(BM25 评分排序)
       │           │     ├── hit_1: title="知识图谱在金融领域的应用" → score 18.5
       │           │     ├── hit_2: title="企业知识管理方案" → content中含"知识图谱" → score 12.3
       │           │     └── ...
       │           ├── 提取 highlight 片段
       │           │     ├── title: "<em>知识图谱</em>在金融领域的<em>应用</em>"
       │           │     ├── content fragments: ["本文介绍<em>知识图谱</em>的构建...", ...]
       │           │     └── mergeAdjacentEmTags() 合并 IK 分词造成的碎片化标签
       │           └── 组装 SearchResultVO 列表 → 分页结果
       └── searchHistoryService.saveSearchHistoryAsync(userId, keyword)
             → 异步保存搜索历史到 MySQL kb_search_history 表

  → 前端收到响应,渲染搜索结果卡片:
       ├── 标题(含 <em> 高亮标签渲染为黄色标记)
       ├── 摘要/正文高亮片段
       ├── 元数据(分类、作者、发布时间、浏览量)
       └── 相关度得分(带颜色标识:>80% 绿色, >60% 琥珀色, >40% 橙色, 其余灰色)

2. Elasticsearch 集群与索引设计

2.1 ES 客户端配置

kb-search 和 kb-ai 各自维护独立的 ES 客户端 Bean:

// kb-search/.../config/ElasticsearchConfig.java
@Configuration
public class ElasticsearchConfig {

    @Value("${spring.elasticsearch.host:117.72.88.11}")
    private String host;

    @Value("${spring.elasticsearch.port:9200}")
    private int port;

    @Bean
    public ElasticsearchClient elasticsearchClient() {
        RestClient restClient = RestClient.builder(
                new HttpHost(host, port, "http")).build();
        ElasticsearchTransport transport = new RestClientTransport(
                restClient, new JacksonJsonpMapper());
        return new ElasticsearchClient(transport);
    }

    // kb-ai 另有独立的 ElasticsearchConfig,条件创建(rag.enabled=true)
}

2.2 两个 ES 索引

索引所属服务用途关键字段
kb_documentkb-search (8083)文档全文检索title, summary, content (ik\_max\_word), 元数据字段
kb_chunkkb-ai (8086)RAG 语义检索content, embedding (dense\_vector 1024d), document\_title

2.3 kb\_document 索引——文档实体

// kb-search/.../entity/DocumentIndex.java
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Document(indexName = "kb_document", createIndex = false)
public class DocumentIndex {

    @Id
    private String id;

    @Field(type = FieldType.Text, analyzer = "ik_max_word")
    private String title;                     // 标题(IK 分词)

    @Field(type = FieldType.Text, analyzer = "ik_max_word")
    private String summary;                   // 摘要(IK 分词)

    @Field(type = FieldType.Text, analyzer = "ik_max_word")
    private String content;                   // 正文(IK 分词)

    @Field(type = FieldType.Long)
    private Long categoryId;

    @Field(type = FieldType.Keyword)
    private String categoryName;

    @Field(type = FieldType.Long)
    private List<Long> tagIds;

    @Field(type = FieldType.Keyword)
    private List<String> tagNames;

    @Field(type = FieldType.Long)
    private Long creatorId;

    @Field(type = FieldType.Keyword)
    private String creatorName;

    @Field(type = FieldType.Long)
    private Long teamId;

    @Field(type = FieldType.Keyword)
    private String teamName;

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

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

    @Field(type = FieldType.Keyword)
    private String publishAt;

    @Field(type = FieldType.Keyword)
    private String createdAt;

    @Field(type = FieldType.Keyword)
    private String updatedAt;
}

2.4 kb\_chunk 索引——向量检索

kb-ai 服务的 kb_chunk 索引同时存储文本和向量:

// kb-ai/.../rag/entity/KbChunkDoc.java
@Document(indexName = "kb_chunk", createIndex = false)
public class KbChunkDoc {
    @Id
    private String chunkId;
    private Long documentId;
    private String documentTitle;    // text + keyword 子字段
    private String content;          // text
    private String heading;          // keyword
    private Integer chunkIndex;
    private Integer totalChunks;
    private Long categoryId;
    private Long authorId;
    private Long teamId;
    private Integer docStatus;
    private Date publishTime;
    private Date indexedAt;
    // embedding 字段通过低级 ES client 操作:dense_vector(1024d, cosine)
}

索引创建时的 mappings 配置:

// VectorIndexServiceImpl.createIndexIfNotExists()
.properties("content", p -> p.text(t -> t))
.properties("embedding", p -> p.denseVector(dv -> dv
    .dims(1024)                         // Qwen text-embedding-v3 输出维度
    .index(true)
    .similarity("cosine")))             // 余弦相似度

2.5 索引设置

参数kb\_documentkb\_chunk
分片数 (shards)13
副本数 (replicas)01
刷新间隔 (refresh\_interval)5s5s
分词器ik\_max\_word(中文)standard(默认)
日期格式keyword(字符串存储,避免日期格式解析冲突)date

设计考量:

决策理由
publishAt/createdAt 使用 keyword 而非 date避免 MySQL datetime 格式与 ES date 解析不一致导致的映射异常
title 同时建 keyword 子字段用于搜索建议的 prefix 查询
kb\_document 1 分片 0 副本单机 ES,减少资源浪费;可随数据量增长调整
kb\_chunk 3 分片 1 副本向量检索开销大,多分片分散查询负载

3. 关键词搜索:BM25 + IK 分词 + 多字段加权

3.1 IK 分词器

中文搜索的核心挑战是分词。ES 内置的 standard 分词器对中文按字切分,无法理解词级语义。因此系统引入 **IK Analysis 插件**(ik_max_word 模式),将中文文本切分为有意义的词组:

输入:"企业智能知识库系统之全文检索设计"
standard → [企, 业, 智, 能, 知, 识, 库, 系, 统, 之, 全, 文, 检, 索, 设, 计]
ik_max_word → [企业, 智能, 知识库, 知识, 库系统, 系统, 全文检索, 全文, 检索, 设计]

在 DocumentIndex 实体中,title、summary、content 三个字段均标注了 analyzer = "ik_max_word",写入时按此分词建立倒排索引。

3.2 多字段加权查询

// SearchServiceImpl.searchKeyword() 第 119 行
SearchResponse<Map> response = esClient.search(s -> {
    s.index(INDEX_NAME)
     .from((dto.getCurrent() - 1) * dto.getSize())
     .size(dto.getSize());

    // 有关键词时:multi_match 加权 + 已发布过滤
    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)))));
    }

    return s;
}, Map.class);

查询结构解析:

bool query:
  ├── must: multi_match("知识图谱应用", fields=["title^2", "summary^1.5", "content"])
  │       └── title 命中权重 × 2,summary 命中权重 × 1.5,content 默认权重
  └── filter: term(docStatus = 1)
            └── 只返回已发布文档,不参与评分

filter 子句不参与 \_score 计算,确保只有已发布文档被返回,同时保持排序由 must 子句的 BM25 评分主导。

3.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))); // 3个片段
  • title 和 summary:numberOfFragments(0) 返回字段全文,适合短文本
  • content:fragmentSize(150) + numberOfFragments(3) 返回 3 个 150 字符的上下文片段

3.4 高亮后处理

由于 IK 分词器可能将一个词切分为多个 token,ES highlight 可能产生碎片化的 <em> 标签:

原文:知识图谱在金融领域的应用
IK 分词:[知识图谱, 在, 金融, 领域, 的, 应用]
ES 高亮:<em>知识图谱</em>在<em>金融</em><em>领域</em>的<em>应用</em>

系统使用 mergeAdjacentEmTags() 合并相邻标签:

// SearchServiceImpl.java 第 680 行
private String mergeAdjacentEmTags(String text) {
    return text.replace("</em><em>", "");
    // 结果:<em>知识图谱</em>在<em>金融领域</em>的<em>应用</em>
}

当 ES 未返回高亮时(如通配符搜索),使用简单正则兜底:

// SearchServiceImpl.java 第 692 行
private String highlightSimple(String text, String keyword) {
    String escaped = Pattern.quote(keyword);
    return text.replaceAll("(?i)" + escaped, "<em>$0</em>");
}

4. 混合智能搜索:BM25 + kNN + RRF + LLM 重排序

4.1 总体流程

混合智能搜索入口在 kb-search 的 searchHybrid() 方法中,通过 Feign 调用 kb-ai 服务的 /rag/search 接口:

图片.png

4.2 查询 embedding

// RagRetrievalServiceImpl.retrieve() 第 48 行
public List<RagSearchResultVO> retrieve(String query, int topK, boolean enableRerank) {
    // 1. 创建索引(如果不存在)
    vectorIndexService.createIndexIfNotExists();

    // 2. 生成查询向量(失败时降级为 BM25-only 搜索)
    float[] queryEmbedding = null;
    try {
        queryEmbedding = embeddingService.embed(query);
        // 调用 Qwen text-embedding-v3 → 输出 1024 维浮点向量
    } catch (Exception e) {
        log.warn("查询嵌入失败,降级为 BM25-only 搜索:{}", e.getMessage());
    }

    // 3. 混合搜索(BM25 + kNN + RRF),取 2 倍 topK 作为候选
    int candidateK = Math.max(topK * 2, hybridTopK);
    List<RagSearchResultVO> candidates = vectorIndexService.searchHybrid(
            query, queryEmbedding, candidateK, hybridTopK, rrfC);

    // 4. LLM 重排序(可选)
    if (enableRerank && candidates.size() > topK) {
        candidates = rerank(candidates, query, topK);
    }
    return candidates;
}

关键设计——embedding 失败降级:如果 Qwen embedding 服务不可达,queryEmbedding 为 null,kNN 搜索的 script_score 查询不执行,仅执行 BM25 搜索。整个搜索流程不会因 AI 服务故障而阻断。

4.3 BM25 + kNN 并行搜索

// VectorIndexServiceImpl.searchHybrid() 第 124 行
// BM25 和 kNN 并行执行
CompletableFuture<List<RagSearchResultVO>> bm25Future =
    CompletableFuture.supplyAsync(() -> searchBM25(query, topK));

CompletableFuture<List<RagSearchResultVO>> knnFuture =
    CompletableFuture.supplyAsync(() -> {
        if (queryEmbedding == null) return List.of();
        return searchKnn(queryEmbedding, topK);
    });

// 等待两个结果并 RRF 融合
List<RagSearchResultVO> bm25Results = bm25Future.get(5, TimeUnit.SECONDS);
List<RagSearchResultVO> knnResults = knnFuture.get(5, TimeUnit.SECONDS);
List<RagSearchResultVO> fused = rrfFusion(bm25Results, knnResults, rrfC);

kNN 搜索使用 ES script_score 查询,计算余弦相似度:

{
  "script_score": {
    "query": { "match_all": {} },
    "script": {
      "source": "cosineSimilarity(params.query_vector, 'embedding') + 1.0",
      "params": { "query_vector": [0.12, -0.34, ..., 0.78] }
    }
  }
}

+ 1.0 将余弦相似度从 [-1, 1] 映射到 [0, 2],确保分数为正数,便于 RRF 融合。

4.4 RRF(Reciprocal Rank Fusion)融合

RRF 是一种简单有效的多路召回融合算法,不需要归一化分数:

RRF_score(d) = SUM_{r ∈ {bm25, knn}} 1 / (C + rank_r(d))

其中 C = 60(可配置)。RRF 只使用排名而非原始分数,避免了 BM25 和余弦相似度两种不同量纲分数直接相加的问题。

// VectorIndexServiceImpl.java
private List<RagSearchResultVO> rrfFusion(
        List<RagSearchResultVO> bm25Results,
        List<RagSearchResultVO> knnResults, int C) {
    Map<String, Double> rrfScores = new ConcurrentHashMap<>();

    // 收集 BM25 排名
    for (int i = 0; i < bm25Results.size(); i++) {
        String id = bm25Results.get(i).getChunkId();
        rrfScores.merge(id, 1.0 / (C + i + 1), Double::sum);
    }

    // 收集 kNN 排名
    for (int i = 0; i < knnResults.size(); i++) {
        String id = knnResults.get(i).getChunkId();
        rrfScores.merge(id, 1.0 / (C + i + 1), Double::sum);
    }

    // 按 RRF 分数降序排列
    return rrfScores.entrySet().stream()
        .sorted(Map.Entry.<String, Double>comparingByValue().reversed())
        .map(e -> buildResult(e.getKey(), e.getValue(), bm25Results, knnResults))
        .collect(Collectors.toList());
}

4.5 LLM 重排序

对于融合后的候选集,可选调用 LLM 进行精排:

// RagRetrievalServiceImpl.rerank() 第 89 行
private List<RagSearchResultVO> rerank(List<RagSearchResultVO> candidates,
                                        String query, int topK) {
    ChatLanguageModel model = modelProvider.getDefaultModel();

    List<ScoredChunk> scored = new ArrayList<>();
    for (RagSearchResultVO candidate : candidates) {
        String prompt = """
            你是一个搜索相关性评估专家。请根据查询和文档片段的相关程度打分。
            评分范围 1-10(1=完全不相关,10=完全相关)。
            只输出一个数字。

            查询:%s
            文档片段:%s
        """.formatted(query, candidate.getContent());

        String response = model.generate(UserMessage.from(prompt)).content().text();
        int score = parseRelevanceScore(response);  // 正则提取 1-10 数字
        scored.add(new ScoredChunk(candidate, score));
    }

    return scored.stream()
        .sorted(Comparator.comparingInt(ScoredChunk::getScore).reversed())
        .limit(topK)
        .map(ScoredChunk::getCandidate)
        .collect(Collectors.toList());
}

每个候选 chunk 单独调用一次 LLM,获得 1-10 的相关性评分。这种"逐条打分"模式比让 LLM 直接排序更稳定——LLM 在比较任务上容易出现位置偏差。

4.6 混合搜索的自动降级

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

如果 kb-ai 服务不可达或 Feign 调用超时,自动降级为关键词搜索。用户体验不中断。


5. 搜索建议、热门搜索与搜索历史

5.1 搜索建议(Prefix 查询)

// SearchServiceImpl.suggest() 第 429 行
public List<SearchSuggestVO> suggest(String keyword, Integer size) {
    // 使用 prefix 查询匹配 title.keyword 子字段
    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());
}

title.keyword 是 title 字段的 keyword 子字段,存储完整原始字符串。prefix 查询匹配前缀,如输入 "知识图谱" → 匹配 "知识图谱在金融领域的应用" 等标题。

5.2 热门搜索

热门搜索基于 MySQL kb_search_history 表中最近 7 天的搜索记录统计:

<!-- SearchHistoryMapper.xml -->
<select id="selectHotKeywordsByUserId" resultType="string">
    SELECT keyword FROM kb_search_history
    WHERE user_id = #{userId}
      AND created_at >= DATE_SUB(NOW(), INTERVAL 7 DAY)
    GROUP BY keyword
    ORDER BY COUNT(*) DESC, MAX(created_at) DESC
    LIMIT #{limit}
</select>

5.3 搜索历史实体

// kb-search/.../entity/SearchHistory.java
@Data
@EqualsAndHashCode(callSuper = true)
@TableName("kb_search_history")
public class SearchHistory extends BaseEntity {
    @TableField("user_id")
    private Long userId;
    @TableField("keyword")
    private String keyword;
    @TableField("search_count")
    private Integer searchCount;
}
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 DEFAULT 0 COMMENT '搜索次数',
  `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '搜索时间',
  PRIMARY KEY (`id`),
  KEY `idx_user_id` (`user_id`),
  KEY `idx_keyword` (`keyword`(100)),
  KEY `idx_create_time` (`created_at`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

历史保存采用异步方式,不阻塞搜索主流程:

// SearchHistoryServiceImpl
public void saveSearchHistoryAsync(Long userId, String keyword) {
    CompletableFuture.runAsync(() -> {
        // ON DUPLICATE KEY UPDATE: 同用户同关键词则增加搜索次数
        searchHistoryMapper.insertOrUpdate(userId, keyword);
    });
}

6. 索引同步:文档 CRUD 触发实时索引

6.1 同步 Trigger 调用链

图片.png

6.2 文档操作触发索引

DocumentServiceImpl 中的每个文档操作完成后,通过异步调用触发三种索引同步:

// kb-document/.../DocumentServiceImpl.java
// 创建文档后(status=1 时触发)
triggerRagReindex(document.getId());     // Feign → kb-ai RAG 向量索引
triggerKAGBuild(document.getId());       // Feign → kb-ai KAG 图谱构建
triggerSearchIndex(document, content);    // Feign → kb-search ES 索引

// 更新文档后(内容变化或草稿→发布时触发)
if (contentChanged || draftToPublished) {
    triggerRagReindex(docId);
    triggerKAGBuild(docId);
    triggerSearchIndex(syncDoc, content);    // 更新 ES 索引
}

// 发布→下架时触发删除
if (publishedToUnpublished) {
    triggerRagDelete(docId);
    triggerKAGDelete(docId);
    triggerSearchDelete(docId);              // 从 ES 删除
}

// 删除文档时触发三个索引的删除
triggerRagDelete(documentId);
triggerKAGDelete(documentId);
triggerSearchDelete(documentId);

6.3 Feign 接口——文档到搜索的桥梁

// kb-document/.../feign/SearchIndexFeignClient.java
@FeignClient(name = "kb-search", path = "/index", contextId = "searchIndexFeignClient")
public interface SearchIndexFeignClient {

    @PostMapping("/document")
    Result<Boolean> indexDocument(@RequestBody Map<String, Object> docData);

    @DeleteMapping("/document/{documentId}")
    Result<Boolean> deleteDocumentIndex(@PathVariable("documentId") Long documentId);
}
// kb-document/.../feign/RagFeignClient.java
@FeignClient(name = "kb-ai", path = "/rag/reindex", contextId = "ragFeignClient")
public interface RagFeignClient {
    @PostMapping("/{docId}")
    Result<String> reindexDocument(@PathVariable("docId") Long docId);

    @DeleteMapping("/{docId}")
    Result<String> removeFromIndex(@PathVariable("docId") Long docId);
}
// kb-document/.../feign/KAGFeignClient.java
@FeignClient(name = "kb-ai", path = "/kag/build", contextId = "kagFeignClient")
public interface KAGFeignClient {
    @PostMapping("/{docId}")
    Result<String> buildGraph(@PathVariable("docId") Long docId);

    @DeleteMapping("/{docId}")
    Result<String> deleteGraph(@PathVariable("docId") Long docId);
}

6.4 kb-search 的索引数据接收

// SearchController.java
@PostMapping("/index/document")
public Result<Boolean> indexDocument(@RequestBody Map<String, Object> docData) {
    searchService.indexDocumentData(docData);
    return Result.success(true);
}

// SearchServiceImpl.indexDocumentData()
public void indexDocumentData(Map<String, Object> docData) {
    DocumentIndex docIndex = buildDocumentIndexFromMap(docData);
    elasticsearchOperations.save(docIndex);
}

buildDocumentIndexFromMap() 从 kb-document 传来的 Map 中提取字段,构建 DocumentIndex 对象后写入 ES。使用 elasticsearchOperations.save() 的 upsert 语义——文档 ID 已存在则更新,不存在则新增。

6.5 异步触发确保主流程不受影响

// DocumentServiceImpl 中的所有索引触发均使用 CompletableFuture
private void triggerSearchIndex(Document doc, String content) {
    CompletableFuture.runAsync(() -> {
        try {
            Map<String, Object> data = buildDocDataMap(doc, content);
            searchIndexFeignClient.indexDocument(data);
        } catch (Exception e) {
            log.warn("搜索索引同步失败(不影响文档操作):docId={}, error={}",
                    doc.getId(), e.getMessage());
        }
    }, asyncTaskExecutor);
}

索引同步的失败不影响文档 CRUD 操作的结果返回。异常被捕获并仅记录日志——搜索索引的最终一致性由后续的定时全量重建保证。


7. 索引管理与重建

7.1 单文档索引与删除

// SearchServiceImpl.indexDocumentData()
public void indexDocumentData(Map<String, Object> docData) {
    DocumentIndex docIndex = buildDocumentIndexFromMap(docData);
    elasticsearchOperations.save(docIndex);   // upsert 语义
}

// SearchServiceImpl.deleteDocument()
public void deleteDocument(Long documentId) {
    elasticsearchOperations.delete(String.valueOf(documentId), DocumentIndex.class);
}

7.2 全量索引重建

POST /index/rebuild 接口用于重建整个 kb_document 索引:

// SearchServiceImpl.rebuildIndex() 第 576 行
public void rebuildIndex() {
    // 1. 删除旧索引
    if (esClient.indices().exists(ExistsRequest.of(e -> e.index(INDEX_NAME))).value()) {
        esClient.indices().delete(DeleteIndexRequest.of(d -> d.index(INDEX_NAME)));
    }

    // 2. 创建新索引(显式 mappings 和 settings)
    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("docStatus", p -> p.integer(i -> i))
                    // ... 其他字段
            ));
    esClient.indices().create(createRequest);

    // 3. 分页从 kb-document 拉取所有已发布文档并逐条索引
    long current = 1;
    long pageSize = 50;
    while (hasMore) {
        // GET /documents/page?current={current}&size={pageSize}&status=1
        String pageUrl = kbDocumentBaseUrl + "/documents/page?current=" + current
                + "&size=" + pageSize + "&status=1";
        ResponseEntity<String> response = restTemplate.exchange(pageUrl, ...);
        // 解析响应,逐条调用 elasticsearchOperations.save()
    }
}

重建流程:

  1. 删除旧索引 → 创建新索引(含完整 mappings)
  2. 通过 REST API 分页拉取 kb-document 中的已发布文档(status=1)
  3. 逐条写入 ES(elasticsearchOperations.save())

这种方式确保了索引的 mappings 始终与代码一致,避免了动态映射导致的不一致问题(如日期格式冲突)。

7.3 RAG 索引重建(kb\_chunk)

kb-ai 服务中的 RAG 索引重建通过 RabbitMQ 异步进行:

接口MQ 路由键功能
POST /rag/reindex/{docId}rag.reindex.{instanceId}.by_ids重索引单个文档
POST /rag/reindex/batchrag.reindex.{instanceId}.by_ids批量重索引
POST /rag/reindex/allrag.reindex.{instanceId}.all全量重索引
DELETE /rag/reindex/{docId}rag.reindex.{instanceId}.delete删除文档向量

消费者 ReindexConsumer 处理消息:

  1. 加载文档详情 → 分块(ChunkingService) → 生成向量(EmbeddingService) → 批量写入 ES(VectorIndexService)

进度通过 Redis key rag:reindex:progress:{taskId} 追踪(1 小时 TTL)。


8. 搜索 REST API

kb-search 服务在 / 路径下提供搜索接口:

方法路径功能说明
POST/search全文搜索支持 keyword/hybrid 双模式
POST/search/advanced高级搜索预留分类/标签/团队筛选字段
GET/search/suggest?keyword=xxx搜索建议prefix 匹配标题
GET/search/hot热门搜索近 7 天高频关键词 TOP 10
GET/search/history搜索历史当前用户历史记录
DELETE/search/history清空历史清空当前用户搜索历史
POST/index/rebuild重建索引全量重建 kb\_document 索引
POST/index/document索引文档kb-document 内部调用
DELETE/index/document/{id}删除索引kb-document 内部调用

SearchRequestDTO

@Data
public class SearchRequestDTO {
    @NotBlank(message = "搜索关键词不能为空")
    private String keyword;              // 搜索关键词

    // 高级筛选(当前未接入查询构建,预留字段)
    private List<Long> categoryIds;
    private List<Long> tagIds;
    private List<Long> teamIds;
    private Long creatorId;
    private Integer docStatus;
    private String startTime;
    private String endTime;
    private String sortField;
    private String sortOrder;

    // 分页
    private Integer current = 1;
    private Integer size = 10;

    // 搜索模式
    private String searchMode = "keyword";  // keyword | hybrid
    private int topK = 10;                  // 混合搜索 Top-K
    private boolean enableRerank = true;    // 是否启用 LLM 重排序
}

SearchResultVO

@Data
@Builder
public class SearchResultVO {
    private Long id;
    private String title;            // 标题(高亮后)
    private String summary;          // 摘要(高亮后)
    private List<String> highlights; // 内容高亮片段
    private String categoryName;
    private List<String> tagNames;
    private String creatorName;
    private String teamName;
    private Integer viewCount;
    private Integer likeCount;
    private Integer commentCount;
    private String publishAt;
    private Float score;             // BM25 相关度得分(关键词搜索)

    // 混合搜索特有
    private Double bm25Score;
    private Double vectorScore;
    private Double rerankScore;
    private List<ChunkResult> chunks; // 文档块明细
}

9. 前端搜索页面

9.1 搜索服务层

// src/services/search.service.ts
export const searchService = {
  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) => http.get('/search/suggest', { params: { keyword } }),
  hotSearch: () => http.get('/search/hot'),
  history: () => http.get('/search/history'),
  clearHistory: () => http.delete('/search/history'),
};

9.2 SearchPage 功能特性

SearchPage.tsx 是一个完整的搜索页面组件:

特性实现
搜索输入防抖输入(300ms),触发 suggestions API 显示自动补全下拉
模式切换"关键词搜索" vs "混合智能搜索",选混合模式时显示 topK 和重排开关
热门搜索卡片展示热门关键词(有 API 数据时用 API,否则用默认兜底列表)
搜索历史显示当前用户最近搜索记录,一键清空
结果卡片标题(<em> 高亮)+ 摘要 + 内容高亮片段 + 分类/作者/时间元数据
混合搜索展示每个结果含 BM25/Vector/Rerank 三种得分 + 可展开的 chunk 列表
得分色卡>80% 绿色、>60% 琥珀色、>40% 橙色、<40% 灰色
排序相关度 / 最新 / 浏览量 三种排序
分页Ant Design Pagination
空状态引导用户换个关键词或切换到混合搜索模式
功能开关读取 enableFullTextSearch 配置,关闭时展示 "搜索功能已禁用"

10. 总结

维度评价
双模检索关键词搜索(BM25 + IK 分词)+ 混合智能搜索(BM25 + kNN + RRF + LLM Rerank),满足从精确匹配到语义理解的多种需求
中文分词IK ik_max_word 分词器实现词级中文语义匹配,告别按字切分的 "企/业/智/能/知/识/库"
多字段加权title^2(标题最重要)> summary^1.5(摘要次之)> content(正文兜底),合理的相关度排序
高亮后处理mergeAdjacentEmTags() 合并 IK 分词造成的碎片化高亮标签,前端渲染美观
自动降级混合搜索失败自动回退到关键词搜索,embedding 失败自动降级为 BM25-only,服务可用性不受 AI 组件影响
索引实时同步文档 CRUD → Feign 异步触发 → ES 实时索引,搜索所见即所得
全量重建/index/rebuild 接口支持一键重建索引,分页拉取 + 逐条写入,适合索引结构变更后的全量迁移
搜索建议prefix 查询标题实现输入联想,300ms 防抖减少 ES 查询压力
搜索历史异步保存不阻塞搜索主流程 + ON DUPLICATE KEY UPDATE 合并同关键词记录
向量检索1024 维 Qwen text-embedding-v3 向量 + cosine 相似度,支持语义级 "意思相近" 的匹配

技术栈总结

搜索引擎:Elasticsearch 8.x(co.elastic.clients Java Client + Spring Data Elasticsearch)
中文分词:IK Analysis 插件(ik_max_word 模式)
关键词检索:BM25 算法(multi_match 多字段加权 + multi_filter 状态过滤)
语义检索:Qwen text-embedding-v3(1024 维向量)+ cosine 相似度
融合算法:RRF(Reciprocal Rank Fusion,C=60)
重排序:LLM 逐条相关性评分(1-10 分)
索引同步:Feign 同步(fire-and-forget) + RAG 异步(RabbitMQ DLQ)
搜索历史:MySQL kb_search_history + CompletableFuture.runAsync 异步写入
索引管理:REST API 驱动分页全量重建
前端:React + Zustand + Ant Design(SearchPage, Pagination, Drawer)
最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏