开源RAG智能问答助手：文档中心轻量化设计取舍评测
从日常场景切入。
无论是内部知识库、对外官网的帮助中心，还是云厂商的产品文档，用户想快速定位某个具体答案时，迎面而来的大多是一个搜索框。
这个搜索框的本质是“找页面”，而非“直接给答案”。搜索“人脸识别计费方式”，系统返回十几篇标题包含“人脸识别”和“计费”的文档。至于哪一篇、哪一段才是精准解答，用户需要逐一打开阅读，再自行拼凑。理解问题、定位答案、归纳表述——这三项认知成本，完全转嫁给了用户。
近两年，不少文档中心尝试接入AI智能客服，方向正确。但实际体验中，我反复遇到两个工程硬伤：
最突出的痛点，一是响应延迟。许多AI客服默认启用“深度思考”模式，用户提问后，界面先是旋转加载，“正在解答，请稍候……”，等待数秒甚至十几秒才输出首段内容。对只想快速确认一个配置参数的用户来说，这种等待足以劝退。
二是重复问题反复计算。同一个高频问题，比如“如何计费”“有无免费额度”，换一个用户提问，或同一用户再次询问，系统每次都重新调用大模型从头推理。用户重复等待，企业重复消耗Token。文档问答的提问分布呈现典型长尾，头部高频问题占比极高，这部分本可实现“一次计算、多次复用”，却白白浪费了资源。
此前在公司内部主导过“官网文档中心智能问答助手”的技术架构，踩过检索质量、并发与成本控制的不少坑。近期将这套思路从业务中剥离，精简技术架构后重写并开源了一个轻量版本，命名为DocMind，提供给有相似需求的团队参考。本篇作为系列开篇，重点阐述其设计目标、整体架构以及关键工程取舍——核心不在于“它能运行”，而在于“为何如此设计”。
二、它是什么：一句话与三条设计原则
先给出一个简洁定义：
在重写与开源之前，明确了三项设计原则，后续所有取舍均围绕它们展开：
轻量可落地：不引入Redis、MongoDB等外部中间件，不强依赖Docker。单台普通机器、一条命令即可启动。每增加一个中间件，部署门槛与运维负担就抬高一截——对“快速验证”的团队极不友好。
敢于对外开放：定位是直接部署至公网的“轻量AI助手”，安全防护必须作为一等公民，而非事后补丁（该内容将在第3篇详述）。
跨语言支持：知识库可仅包含一份中文或英文文档，但须服务全球多语种用户。这是我认为最有价值、也最易被忽视的能力，也是我们公司官网全球化的核心需求。
实际运行效果如下（Demo使用一份公开产品文档作为知识源）：
注意答案下方的两个细节：响应耗时明确标注，参考来源点击即可跳转原文。这两个看似不起眼的设计背后，都蕴含着刻意的工程考量。
三、整体架构：离线建库 + 在线AI问答
抛开细节，DocMind本质是两条链路：离线建库与在线问答，简要说明如下：
3.1 离线建库：将文档站点转化为可检索知识
① 按路径前缀限定抓取范围。爬虫以起始URL的path作为前缀，仅抓取该目录下的页面。例如，直接指定文档中心的导航入口，爬虫从根地址全量爬取，支持整个文档中心的AI问答。若文档中心规模较大，也可精准选择某个产品或模块进行抓取，例如人脸识别产品入口为.../document/product/867，系统仅爬取该产品文档，避免被站点内部密集的互链拖垮。这是实用的“圈地”机制——无此约束，爬虫极易失控。
② 自动识别正文容器。网页中的导航栏、侧边目录、页脚占用大量噪声，直接全文向量化会严重污染检索质量。我的做法是按优先级依次尝试一组正文容器选择器： → → (部分文档站的自定义容器) → .markdown-body（常见markdown主题），均未命中则回退至整个。识别正文后执行空白合并与噪声行清洗。切换新文档站时，若其正文结构特殊，仅需在选择器列表中添加一条class，无需修改主流程。
③ 切片策略：当前采用固定窗口。目前使用固定长度滑动窗口：每片约800字符，相邻片重叠100字符。重叠设计旨在避免将完整语义切分至两片边界，导致检索召回遗漏。我不打算将其包装为高级策略——它简单、可预测、对多数文档足够。但局限性也明确：它不理解段落与语义边界。基于语义或标题层级的切片是后续优化方向，将在第2篇与检索质量一并讨论。
④⑤ 向量化与增量更新。切片经BGE-M3本地模型编码后写入ChromaDB，每条携带url / title / chunk_index元数据——title用于来源溯源的友好显示。重复ingest时，按页面内容哈希判定是否变更，未变则跳过，并清理已不存在的过期文档，实现增量而非全量重灌。
3.2 在线问答：从用户提问到带出处的回答
⑥ 语种识别。使用确定性规则判断提问语言（是否包含CJK字符），据此决定回答的语言基调。选择规则而非模型调用，是为节省一次往返、降低延迟与成本——能用确定性逻辑解决的问题，不必动用大模型。
⑦ 向量检索Top-3。提问经同款BGE-M3编码后，在ChromaDB中按向量距离获取最相近的3个切片。此环节蕴含本项目最关键能力之一：因BGE-M3为多语言模型，中文文档与外语问题被映射至同一语义空间，因此“中文知识库 + 外语提问”能够对应——这是第2篇的主题。
⑧ 相关度阈值闸门：未查到则明确告知。这是我最想强调的设计。检索结果的最小距离超过阈值（默认0.55），表明知识库无足够相关内容，系统直接礼貌拒答，不调用大模型。
此闸门同步解决三个问题：
- 防幻觉：缺乏上下文支撑时，宁可声明“没有相关信息”，也不让模型编造似是而非的答案。
- 省成本：无关提问被拦截在LLM之前，不产生Token消耗。
- 划边界：确保助手始终处于“文档知识范围”内，避免被诱导回答非授权问题。
对于面向公众的问答系统，“敢于拒绝”比“什么都敢答”更可靠。
⑨ 缓存：相同问题，一次计算多次复用。回到开头“重复问题重复算”的痛点——这正是重点解决之处。系统针对“完全相同的问题 + 相同对话上下文”做答案缓存：首次正常生成后，再次提问直接命中缓存返回，零Token、瞬时响应。缓存键由问题与上下文哈希生成，设置TTL，并与会话失效联动（会话清空时同步清除缓存）。
需要明确：这是精确匹配缓存，而非语义缓存——“人脸识别是什么”与“什么是人脸识别”目前被视为不同问题。升级为语义缓存是有价值的方向，但需权衡误命中风险，这一取舍留待后续。
⑩ 上下文组装与截断。将命中的切片拼接成上下文，喂给模型。超过长度上限时截断，避免过长上下文浪费Token并稀释重点。
⑪ 后处理：清理输出内容。模型产出后执行两步纠偏：一是语言一致性——回答语种与提问语种不符时触发改写（中/英之间），避免“中文提问、英文作答”的尴尬；二是去除开头冗余——大模型常用“根据提供的上下文信息……”或“Based on the provided context……”开头，Prompt中已要求避免，但模型不可靠，故在输出侧用规则确定性去除此类前缀。用Prompt降低概率、用代码兜底保证，是我处理此类“模型不老实”问题的惯用方法。
⑫ 输出、溯源与追问。通过SSE将回答推送至前端，同时附上参考来源（文档标题 + 链接）与几个推荐追问，并将结果写入缓存。
四、几个值得说明的工程取舍
4.1 “流式”实为模拟——主动选择的结果
界面上回答呈现逐字打出的打字机效果，但需坦诚说明实现方式：上游LLM调用为非流式——我先获取完整答案，再在本地切割成小片，通过SSE逐片下发，模拟流式效果。
为何不直接用真流式？因为在拿到完整答案后，还需执行两项需全文才能完成的处理：语言一致性纠偏、去除开头冗余；以及将完整答案写入缓存。真正的逐Token流式会使这些“基于全文的后处理”变得极为复杂。
代价也不回避：因需等待全文生成完毕才开始输出，界面上的“首字耗时”约等于整段生成时间（这也是Demo中首字~3s、总耗时~4s两个数字接近的原因）。因此可理解为：Demo项目真正的“快”，在于缓存命中时的秒回，而非首次生成的首字延迟——后者取决于所接上游模型的性能。
若要兼得，正确方向是“真流式 + 增量后处理”（边收Token边执行可增量的清洗），这已列入优化计划。
4.2 将“耗时”显示作为一等公民
特意将每条回答的首字/总耗时直接显示在界面上。这不仅是一个炫技的小徽章——它是对用户和自身的诚实：用户能直观感知快慢，自身也可借此快速评估“换上游模型是否值得”“缓存命中率高低”。一个系统愿不愿意公开其延迟，某种程度上反映了对自身表现的底气。
4.3 来源溯源：让AI非黑箱嘴替
每个回答均附带所依据的文档标题与链接，用户点击即可跳转原文核对。对文档问答这种“答案必须可信”的场景，可溯源不是加分项，而是底线——它把“AI说的”还原为“文档里写的，AI仅协助查找与归纳”。
4.4 轻量的理由与代价
无Redis、无MongoDB——向量库使用嵌入式ChromaDB（一个本地目录），审计/反馈与爬虫元数据各用一个SQLite文件，限流、缓存、会话历史等运行时状态采用进程内LRU + TTL容器承载。
好处是部署极简，从git clone到运行仅需几步。代价也明确：进程内状态意味着单实例——要做多副本水平扩展，这些内存态必须外移至共享存储。这是一个明确的定位取舍：DocMind服务于中小规模文档中心的“轻量落地”，而非为超大规模高可用集群设计。
4.5 为何不直接套用现成RAG框架
这个问题绕不开：LangChain、LlamaIndex、Dify等成熟方案均在，为何还需自建一套？
我的判断是：针对此具体场景，自行实现主干链路的边际成本，低于掌握一个大型框架的认知成本与约束成本。RAG的核心链路——爬取、切片、向量化、检索、阈值判断、组装、调用——本身并不复杂，代码量可控、每一步清晰可见。而通用框架为覆盖所有场景，引入了大量抽象层；当需要执行“阈值拒答”“输出侧去除冗余”“精确匹配缓存”“面向公众的多维限流”等紧贴业务的定制时，在框架的抽象中反而需绕路，甚至与默认行为对抗。
这并非表明造轮子更高明——而是在“可控、可读、可改”与“开箱即用、但内部为黑箱”之间，为此项目选择了前者。若需快速对接数十种数据源、上百种工具的复杂Agent系统，我的选择会相反。技术选型从来不是比拼谁更先进，而是看其是否匹配当前要解决问题的形态。
4.6 可观测与反馈闭环：上线仅是开始
面向公众服务的系统，仅能运行不够，还需“看得见、调得动”。此方面做了两件事：
- 审计双写：每次问答、每一条用户反馈，同时写入结构化日志（stdout JSON，便于实时
grep+jq）与独立SQLite表（支持分页、过滤、关键字检索）。每条记录携带request_id，可串联全链路追踪。需强调：审计数据绝不进入向量库——避免有人通过提问反查他人问题。 - 反馈闭环：每条回答下方提供? / ?按钮，差评可填写具体原因。这些反馈结构化入库，是后续迭代“哪些问题回答不佳、知识库何处存缺口”的一手依据。问答系统的质量并非上线时固定，而是通过此闭环持续提升。
五、跨语言：一份中文文档，服务多语种用户
这是我最看重的能力，第2篇将完整展开，此处先给出准确轮廓。
传统多语言方案通常是“将文档翻译为N种语言、维护N套知识库”，成本与一致性均为负担。DocMind走不同路线：知识库仅存储一份原始文档（源语言即为原语言），依靠BGE-M3多语言向量实现跨语言检索——外语问题与中文原文被映射至同一语义空间，因此英语、日语等提问也能命中中文文档；回答语种跟随提问语种（中英之间还做一致性纠偏兜底，Demo版本已精简，实际可基于用户原语言自动进行多语种问答）。
对于拥有海外用户或多语种团队的文档中心，这意味着：一份知识库，多语种可用，无需翻译、无需多套维护。至于“跨语言检索为何可行”“回复语种如何稳定控制”等机制细节，留给第2篇。
六、技术栈一览
| 层次 | 选型 | 说明 |
|---|---|---|
| 后端 | FastAPI + Uvicorn | 全异步，天然适配IO密集的检索+LLM调用 |
| 向量库 | ChromaDB | 嵌入式持久化，一个本地目录，无需独立服务 |
| Embedding | BAAI/bge-m3 | 本地多语言模型，跨语言检索的基础 |
| LLM | OpenAI兼容API | 默认DeepSeek，可替换任意兼容网关 |
| 存储 | 2个SQLite文件 | 审计/反馈 + 爬虫元数据，无Redis / 无MongoDB |
| 前端 | 原生HTML/JS + TailwindCSS | 无需构建步骤，一个静态页 |
整套体系的设计哲学就一句话：能不引入的依赖，就不引入。
七、快速上手（5步）
# 1) 克隆 + 安装依赖
git clone https://github.com/lukyFun/search-ai.git docmind && cd docmind
pip install -r requirements.txt
# 2) 下载 embedding 模型（国内通过 ModelScope 镜像更快）
pip install modelscope && python3 scripts/download_model_cn.py
# 3) 配置 .env：至少填写 LLM_API_KEY；
# 更换文档站只需修改 ASSISTANT_NAME / KNOWLEDGE_SCOPE / TARGET_URL 等项，无需改代码
cp .env.example .env
# 4) 启动（首次加载 BGE-M3 模型，约需 5~10 秒）
bash run.sh
# 5) 构建知识库：先 preview 验证抓取效果，再正式 ingest
python3 scripts/ingest_cli.py --mode preview --url "<你的文档入口>" --limit 5
python3 scripts/ingest_cli.py --mode ingest --url "<你的文档入口>" --limit 50
随后打开 http://localhost:8100 即可提问。换成自有文档站，通常仅修改配置、无需改动代码。
八、写在最后
DocMind想要解决的问题很朴素：让文档中心不仅能“搜”，还能“答”；不仅服务单一语言，还能覆盖全球用户；而且做到轻量、低成本。
这篇内容刻意不局限于“功能罗列”，而是将架构链路与几个关键取舍——模拟流式的代价、阈值拒答的边界、缓存的精确匹配局限、轻量的单实例代价——都坦诚讲清。因为我相信，一个系统是否可靠，不取决于它宣称了多少能力，而取决于其作者是否清楚每个决策的代价，并诚实地标注出适用边界。
系列后续两篇将深入本篇仅点到的主菜：
- 第2篇：跨语言问答的实现原理——BGE-M3多语言向量、语种自适应回复，以及“让RAG不瞎编”的检索质量工程（阈值、来源溯源、切片优化）。
- 第3篇：部署至公网——无中间件的轻量持久化、内存防OOM，以及面向公众的15层安全防护（多维限流、每日Token预算、提示注入拦截……）。