SuperBizAgent-java/mvp/issues/rag-l0-keyword-matching-quality.md

RAG L0 关键词匹配质量不足

状态：待规划
严重程度：中
发现时间：2026-07-04
范围：L0 索引、frontmatter、精确召回

---

现象

L0 当前依赖文档 frontmatter 中的关键词，并使用较粗的字符串包含逻辑做匹配。关键词质量越依赖人工维护，召回稳定性越容易波动。

如果 frontmatter 填写不完整、同义词缺失、关键词过短或过泛，L0 就可能误召回或漏召回。

---

当前实现

• KnowledgeIndexService 从 ApiDocument metadata/frontmatter 加载关键词。
• exact match 的判断类似：

query.contains(keywordLower) || keywordLower.contains(query)

• 没有分词、同义词归一、字段权重、关键词质量校验。

---

影响

• 短关键词容易误命中。
• 用户换一种说法时，L0 无法命中。
• 文档 frontmatter 质量变成检索质量的隐性前提。

---

建议修复

1. 为关键词增加最小长度、停用词、领域前缀等基础规则。
2. 区分 exactKeywords、aliases、domainTags，避免所有词混在一个匹配池。
3. 引入轻量中文分词或归一化策略，先不必上复杂搜索引擎。
4. 上传文档时校验 frontmatter 质量，缺失关键词时给出警告。
5. 在 issue 修复前，至少补一份知识库文档 frontmatter 编写规范。

---

相关文件

• src/main/java/com/superbiz/agent/service/KnowledgeIndexService.java
• src/main/java/com/superbiz/agent/service/DocumentManagementService.java
• src/main/java/com/superbiz/agent/controller/DocumentController.java