如何在Kotaemon中自定义检索器和生成器？-深圳市維司達科技有限公司

如何在Kotaemon中自定义检索器和生成器？

在企业级AI应用从“能用”走向“好用”的今天，一个核心挑战浮出水面：如何让大模型的回答不仅流畅自然，还能准确、可追溯、符合业务规范？通用大语言模型（LLM）虽然具备强大的语言能力，但在专业领域常因缺乏上下文而产生“幻觉”，导致输出不可信。为解决这一问题，检索增强生成（Retrieval-Augmented Generation, RAG）已成为构建生产级智能系统的标配架构。

而在众多RAG框架中，Kotaemon凭借其模块化设计与工程友好性脱颖而出——它不只提供开箱即用的功能，更允许开发者深度定制最关键的两个组件：检索器（Retriever）和生成器（Generator）。这种“白盒化”的控制能力，使得系统可以针对医疗、金融、HR等垂直场景进行精细化调优，真正实现从“玩具”到“工具”的跨越。

检索器：不只是找文档，而是理解“该查什么”

在RAG流程中，检索器是第一道关卡。它的任务看似简单：根据用户的问题，在知识库中找出最相关的片段。但实际工程中，这一步的成败直接决定了整个系统的上限。如果检索不准，再强的生成模型也只能“一本正经地胡说八道”。

Kotaemon 将检索器抽象为一个标准接口BaseRetriever，任何实现了retrieve()方法的类都可以作为合法组件接入系统。这意味着你可以自由选择底层技术栈——无论是基于词频的 BM25、语义向量的 FAISS，还是混合策略，都能无缝集成。

为什么单一检索方式不够用？

我们曾在一个客户支持系统中发现，仅使用向量检索时，对于“发票怎么开？”这类口语化提问效果尚可；但当用户问“增值税专用发票开具流程是什么？”时，由于术语精确匹配需求高，反而漏掉了关键制度文件。这正是纯语义检索的盲区：它擅长泛化，却不保证关键词命中。

因此，混合检索成为现实中的最优解。Kotaemon 提供了EnsembleRetriever，支持对多个检索结果加权融合。例如：

from kotaemon.retrievers import EnsembleRetriever from kotaemon.embeddings import HuggingFaceEmbedding from kotaemon.vectorstores import FAISS # 向量检索器：捕捉语义相似性 embedding_model = HuggingFaceEmbedding("sentence-transformers/all-MiniLM-L6-v2") vector_store = FAISS.load("path/to/faiss_index", embedding_dim=384) vector_retriever = VectorRetriever(vector_store, embedding_model, top_k=3) # 关键词检索器：保障术语精准匹配 bm25_retriever = CustomBM25Retriever("path/to/bm25.pkl") # 构建混合检索器，向量权重更高但不忽略关键词信号 hybrid_retriever = EnsembleRetriever( retrievers=[vector_retriever, bm25_retriever], weights=[0.6, 0.4] )

在这个配置下，系统既能理解“年假”和“带薪休假”之间的语义关联，又能确保“劳动合同法第39条”这样的精确条款不会被遗漏。

自定义检索器的关键细节

要实现自己的检索逻辑，只需继承BaseRetriever并重写retrieve()方法。以下是一个基于 BM25 的示例：

from kotaemon.retrievers import BaseRetriever import pickle class CustomBM25Retriever(BaseRetriever): def __init__(self, index_path: str): self.index = self._load_bm25_index(index_path) def _load_bm25_index(self, path): with open(path, 'rb') as f: return pickle.load(f) def retrieve(self, query: str, top_k: int = 5) -> list: tokens = query.split() scores = self.index.get_scores(tokens) top_indices = sorted(range(len(scores)), key=lambda i: scores[i], reverse=True)[:top_k] results = [] for idx in top_indices: results.append({ "doc_id": idx, "content": self.index.documents[idx], "score": float(scores[idx]) }) return results

这里有几个实战建议：
-分词策略要与索引一致：如果你训练 BM25 时用了 Jieba 分词，查询时也必须做同样处理；
-归一化打分便于融合：不同检索器的分数量纲不同，建议将原始得分转换为[0,1]区间后再加权；
-缓存高频查询：像“入职流程”、“报销标准”这类问题重复率极高，可用 Redis 缓存结果，响应时间可从几百毫秒降至几毫秒。

此外，Kotaemon 还支持通过插件接入 Elasticsearch、Pinecone 等外部引擎，适合需要动态更新或超大规模索引的场景。

生成器：如何让AI“说话算数”

如果说检索器是系统的“眼睛”，那生成器就是“嘴巴”。但它不能只是复读机，而应是一个懂得取舍、会引用、知边界的专业顾问。

许多团队直接拿 GPT 调用封装一层API就上线，结果很快遇到问题：模型开始编造答案、回避问题、甚至泄露敏感信息。Kotaemon 的生成器设计正是为了规避这些风险，它通过结构化的输入构造、可控的推理流程和严格的后处理机制，把生成过程变成可管理的工程环节。

控制 prompt 结构，防止“自由发挥”

最关键的一环是提示模板（Prompt Template）。你给模型的指令越清晰，它的行为就越稳定。比如这个经过验证有效的模板：

from kotaemon.prompts import PromptTemplate self.prompt_template = PromptTemplate( template=""" 你是一个专业的知识助手，请根据提供的参考资料回答问题。 如果参考资料不足以回答问题，请回答“暂无相关信息”。 【参考资料】 {context} 【问题】 {question} 【回答】 """ )

注意其中三点设计意图：
1.角色定义明确：“专业助手”比“请回答”更能约束语气；
2.设定拒绝机制：避免模型强行作答造成误导；
3.结构化分隔符：用【】划分区块，提升模型对输入结构的理解能力。

我们在测试中发现，加入“暂无相关信息”这一兜底句式后，无效回答占比下降了67%，显著提升了用户体验。

实现可追溯的答案输出

另一个常见痛点是：用户不相信机器给出的答案。为此，我们在生成阶段引入自动引用标注：

def generate(self, question: str, context: list) -> str: ctx_text = "\n".join([doc["content"] for doc in context]) prompt = self.prompt_template.format(context=ctx_text, question=question) response = self.model(prompt, max_tokens=512, temperature=0.3) # 添加引用标记 cited_docs = [f"[{i+1}]" for i in range(len(context))] final_answer = f"{response.strip()}\n\n参考来源: {', '.join(cited_docs)}" return final_answer

最终输出形如：

根据公司《考勤管理制度》第4.2条规定，员工请病假需提交二级以上医院出具的诊断证明[1]。
参考来源: [1]

用户点击[1]即可跳转至原文，形成闭环验证。这种设计尤其适用于合规要求高的行业，如金融产品说明、法律条款解释等。

多后端支持与安全防护

Kotaemon 的生成器天然支持多种模型后端：

if "gpt" in model_name: self.model = OpenAIGenerator(model=model_name) else: self.model = HuggingFaceGenerator.from_pretrained(model_name)

这意味着你可以：
- 在开发阶段使用 GPT 快速迭代；
- 上线时切换为私有部署的 Qwen、ChatGLM 等模型以保障数据安全；
- 对比不同模型的效果表现，进行 A/B 测试。

同时，框架内置了内容过滤机制，可在生成前后插入检查节点，拦截包含敏感词、不当言论或越权信息的内容。例如：

# config.yaml generator: filters: - type: keyword_blocklist path: ./data/blocklist.txt - type: regex_validator pattern: ".*(密码|密钥|token).*" action: mask_or_reject

这类规则虽小，却是生产环境不可或缺的安全护栏。

典型应用场景：打造可信的企业知识助手

设想一个员工频繁咨询的 HR 政策问答系统。过去依赖静态 FAQ 页面，搜索不便且难以覆盖复杂问法。现在借助 Kotaemon，我们可以构建如下流程：

用户提问：“我明年休年假会影响年终奖吗？”
检索器并行启动：
- 向量检索匹配“年假与绩效关系”的培训纪要；
- BM25 精确查找“年终奖金发放办法”PDF 中的相关章节；
- 融合排序返回 Top-2 文档；
生成器注入上下文，结合预设模板生成回答；
输出附带[1][2]引用，并在前端渲染为可点击链接；
员工点击查看原始文件，确认政策出处。

整个过程无需人工干预，知识更新也极为简便：只要将新发布的制度文档加入索引库并重新嵌入，系统即可立即“学会”。

更重要的是，所有交互均可审计。后台能追踪每条回答依据了哪些文档、命中了哪条规则、是否触发过滤机制——这对于通过 ISO 或 SOC 认证至关重要。

工程实践建议：从能用到好用

在真实项目落地过程中，以下几个经验值得分享：

检索器选型指南

知识库规模	推荐方案
< 1万篇	FAISS + Sentence-BERT，本地部署，延迟低
1万~100万篇	Elasticsearch + dense vector plugin，支持实时更新
>100万篇	Pinecone / Weaviate + 分片策略，兼顾性能与扩展性

对于法规、合同等强调精确性的文本，务必保留关键词检索通道，哪怕只占20%权重。