Kotaemon支持自定义停用词表，提升检索精度

Kotaemon支持自定义停用词表，提升检索精度

在企业级知识库系统中，一个看似简单的“公司”二字，可能正是压垮检索准确率的最后一根稻草。用户搜索“最新财报”，返回的却是上百份标题含“本公司公告”的文档；客服机器人反复误解“我们公司的产品”中的“公司”为关键词，导致意图识别偏差——这类问题背后，往往是传统停用词机制与业务场景脱节所致。

Kotaemon 作为面向知识增强型应用的智能代理框架，在最新版本中引入了自定义停用词表功能，让开发者和运维人员能够真正掌控文本预处理的“话语权”。这一改动虽小，却直击信息检索系统在垂直领域落地时的核心痛点：如何在通用语言规则与特定业务语义之间取得平衡。

不同于大多数框架将停用词固化于代码或依赖第三方库的做法，Kotaemon 将其设计为可配置、可热更新、可分层控制的运行时组件。这意味着金融系统的“股份”、医疗系统的“患者编号”、法律文书中的“以下简称”，都可以根据需要灵活过滤或保留，而不必动一行代码。

整个流程始于一次普通的查询请求。当用户输入“请提供本公司最新的股份回购计划”时，系统首先通过分词器（如 Jieba 或 BERT tokenizer）将其拆解为 token 序列。此时，“公司”、“股份”等词是否应被保留，不再由全局默认规则决定，而是交由一个动态加载的停用词过滤模块来判断。

这个模块的核心逻辑并不复杂：读取用户指定的文件（支持.txt每行一词，也支持 JSON 数组），构建成哈希集合（HashSet），然后在分词后遍历每个 token 进行快速查找与剔除。关键在于其实现方式的高度工程化——O(1) 查询性能、UTF-8 全字符兼容、大小写敏感开关、多格式解析……这些细节共同构成了稳定高效的前置过滤能力。

class StopWordFilter: def __init__(self, filepath: str, use_default: bool = True, case_sensitive: bool = False): self.case_sensitive = case_sensitive self.stopwords: Set[str] = set() if use_default: self.stopwords.update(self._load_default()) self.load_from_file(filepath) def load_from_file(self, filepath: str): with open(filepath, 'r', encoding='utf-8') as f: if filepath.endswith('.json'): custom_words = json.load(f) else: custom_words = [line.strip() for line in f if line.strip()] if not self.case_sensitive: custom_words = [w.lower() for w in custom_words] self.stopwords.update(custom_words) def filter_tokens(self, tokens: List[str]) -> List[str]: if self.case_sensitive: return [t for t in tokens if t not in self.stopwords] else: return [t for t in tokens if t.lower() not in self.stopwords]

上面这段代码展示了该功能的骨架。它不仅封装了加载逻辑，还通过布尔参数实现了策略组合：是否启用默认词表、是否区分大小写。更重要的是，这种设计允许它以依赖注入的方式无缝集成进RetrievalPipeline，与其他组件保持松耦合。

实际部署中，这一机制嵌入在完整的检索流水线前端：

+-------------------+ | User Query | +-------------------+ ↓ +-------------------+ | Tokenizer | —— 如 Jieba / BertTokenizer +-------------------+ ↓ +----------------------------+ | StopWordFilter Module | ← 加载 custom_stopwords.txt +----------------------------+ ↓ +---------------------------+ | Normalization & Stemming| +---------------------------+ ↓ +--------------------------+ | Embedding Encoder | —— 如 BGE / Sentence-BERT +--------------------------+ ↓ +-------------------------+ | Vector Search Engine | —— 如 FAISS / Milvus +-------------------------+

在这个链条中，停用词过滤的位置至关重要——太早会干扰分词，太晚则噪声已进入向量空间。Kotaemon 的选择是紧随分词之后，确保后续所有处理阶段接收的都是“干净”的 token 流。

举个典型例子：某金融机构希望屏蔽内部文档中频繁出现但无检索价值的术语。他们在finance_stopwords.txt中列出：

公司 有限公司 官网 网站 公告

配合如下配置：

preprocessing: stopword_enabled: true stopword_file: "configs/finance_stopwords.txt" use_default: true case_sensitive: false

当原始查询被分词为["请", "提供", "本", "公司", "最新", "的", "股份", "回购", "计划"]后，经过过滤仅剩下["提供", "最新", "回购", "计划"]。这些关键词更能反映用户真实意图，从而引导向量编码器生成更具判别性的 embedding，最终在 FAISS 或 Milvus 中命中真正相关的政策文件。

实测数据显示，该优化使 Precision@5 从 62% 提升至 79%，平均响应时间下降约 15%。这不仅是算法层面的胜利，更是对“数据质量决定模型上限”这一原则的又一次验证。

当然，灵活性也带来了新的挑战。比如，过度删除可能导致语义断裂：“关于公司治理结构的建议”若把“公司”滤掉，剩下“治理结构建议”虽仍可理解，但上下文完整性受损。因此，Kotaemon 团队建议将停用词数量控制在 500 以内，并辅以白名单机制保护关键实体（如品牌名、人名）不被误删。

另一个常被忽视的问题是安全性。直接读取外部文件存在路径穿越风险，例如传入../../etc/passwd。为此，系统需对配置路径做白名单校验，并可选启用签名机制防止非法篡改。同时，调试日志会记录每次过滤行为：“Filtered out 3 stopwords: [‘公司’, ‘的’, ‘官网’]”，便于事后追溯与分析。

更进一步，Kotaemon 支持按数据源维度设置不同停用策略。这意味着同一个服务实例下，财务知识库可以屏蔽“公告”，而人力资源库则保留“员工公告”作为有效关键词，实现多租户场景下的个性化治理。

从工程实践角度看，最佳落地路径通常是渐进式的：先使用默认词表 + 极少量高频干扰词进行测试，再结合 A/B 测试观察 Precision 和 Recall 的变化趋势。一旦确认正向收益，便可逐步扩展词表规模，并建立每月迭代的维护机制。

未来，团队计划引入智能推荐停用词功能——基于历史查询日志分析哪些高频词长期未能带来有效点击或转化，自动提示用户考虑将其加入停用列表。这将进一步降低人工维护成本，推动系统向“自适应”方向演进。

说到底，停用词从来不只是语言学问题，而是业务语义的映射。Kotaemon 之所以强调“可定制”，正是因为它深知：没有放之四海皆准的最优词表，只有不断贴近场景的持续调优。把这份控制权交给用户，看似简单，实则是对系统实用性最深刻的尊重。

这种高度集成的设计思路，正引领着智能问答与知识检索系统向更可靠、更高效的方向演进。