Agent 这个词,25 年下半年以来已经有点烂大街了。从我下半年聊过的大几十个项目里看,绝大多数企业实际连知识库都还没整明白就去追求 Agent,纯属本末倒置。知识库未必是所有场景的前置条件,但如果你想让工作流和 Agent 真正能用,把散落在多源异构文档、业务专家脑子里的经验沉淀下来,往往是绕不开的基础工作。
知识库看起来是个老生常谈的需求,但真正做好并不容易。多源异构的非结构化数据怎么清洗、怎么切分、怎么让检索又快又准,这些工程细节是项目成败的关键。此外,知识库是一个可以持续迭代的闭环,用户反馈标注的数据,也是高价值的训练素材。
今天分享的这个落地案例,是一家工控软件厂商的售后知识库项目。他们有 4 万多家存量客户、20 多个工程师,日常大量时间都在应付微信群里的技术咨询。我用两周时间帮他们完成了从数据清洗到系统交付的全流程,目前已经在内部试点使用,检索效果和回答质量都达到了可用于生产的水平。
这篇试图说清楚:
工控行业售后场景的特殊性、为什么选择手搓而不用开源框架、1600 多份 Word 文档的数据清洗与元数据增强、从"搜到了但答错"到高召回率的检索策略迭代、前端从 Streamlit 到 Next.js 的架构升级,以及面向企业级交付的产品化思考等整个项目从需求到交付的全过程。
以下,enjoy:
1
效果预览
在深入技术细节之前,先看看POC和MVP两个版本最终交付的效果。
1.1
*POC 版本 (Streamlit)*
POC 阶段的核心目标是验证"数据清洗 + 检索精度"的可行性,用 Streamlit 快速搭建前端做功能验证。
整条链路从数据侧看,是 Word → Markdown + DOCX → 元数据增强 → 向量入库;从查询侧看,是用户问题 → Query Rewrite(解决多轮对话指代问题)→ 向量召回 → Rerank 精排 → Parent-Child 扩展(获取完整文档上下文)→ LLM 生成。这套架构在 POC 阶段就已经跑通,核心检索逻辑后续直接复用到 MVP。
1.2
*MVP 版本 (FastAPI + Next.js)*
MVP 阶段的核心目标是从"能用"到"好用",支撑部门级试点。
架构上最大的变化是前后端分离:后端用 FastAPI 封装 API,前端用 Next.js 重写交互。RAG 引擎核心代码直接从 POC 复用,没有重写。新增的主要是前端体验层的功能:SSE 流式输出实现打字机效果、SWR 缓存实现历史会话秒开、点踩时弹出输入框收集用户反馈原因、以及一个运营 Dashboard 展示调用量和满意度。数据层增加了 MinIO 做图片存储,解决了 Markdown 图片在生产环境的访问问题。
2
项目背景
2.1
*客户画像*
| 维度 | 描述 |
|---|---|
| 公司规模 | 20+ 工程师团队,4 万多家存量客户 |
| 产品形态 | 工控组态软件(类似 SCADA/HMI 类产品) |
| 交付方式 | U 盘安装包,客户自行部署到现场工控机 |
| 客户环境 | Windows 2003 / XP / 7 / 10 / 11 混杂,甚至有 Windows 98 |
| 服务模式 | 微信群答疑为主,每人日均 15-20 个群 |
2.2
*工控行业的特殊性*
工控软件的售后,跟普通 SaaS 客服有明显不同,为了方便各位理解,我从以下五个维度做了简要对比:
| 维度 | 普通 SaaS | 工控软件 |
|---|---|---|
| 运行环境 | 统一云端/最新浏览器 | Windows 2003 到 Win11 都有 |
| 硬件配置 | 标准化 PC | 工控机、触摸屏、老旧 PLC 混搭 |
| 网络条件 | 互联网 | 内网隔离、甚至空气墙 |
| 故障类型 | 功能 bug | 驱动冲突、权限问题、硬件兼容性 |
| 解决方式 | 远程热修复 | 客户自行操作或工程师上门 |
一句话总结:环境不可控,问题非标化。同样是"连不上 PLC",可能是驱动版本问题、网络配置问题、PLC 固件问题、权限问题等等。而问题的答案散落在内部论坛、产品手册、老工程师的脑子里。
2.3
*真实售后场景还原*
第一次做需求沟通的时候,对方负责人提到了一个比较典型的驱动兼容问题场景。客户在售后群里发消息:软件装好了,连 PLC 连不上,一直报通讯超时。
群里工程师的处理流程大概是这样:先初步判断可能是驱动版本问题、网络配置问题还是 PLC 固件兼容问题;然后去内部知识库搜索,找到一篇《XX 系列 PLC 连接故障排查指南》。但这篇文档是写给技术人员的,列了一堆排查步骤和参数配置,不能直接甩给客户。于是工程师得人肉翻译一遍,把关键步骤用客户能看懂的语言重新组织发到群里。结果客户回一句"按你说的改了,还是不行"。然后又得继续排查下一个可能的原因。
类似的场景还有老旧系统兼容问题。客户现场的工控机可能还跑着 Windows XP,安装时报错缺少某个运行库。这类问题工程师隔三差五就会碰到,内部论坛里其实有解决方案,但每次都得重新搜、重新解释,而且不同 Windows 版本的处理方式还不太一样。
还有一类场景涉及售前支持。销售在跟进潜在客户时,经常需要工程师帮忙回答技术问题:软件支持哪些品牌的 PLC?OPC UA 协议支持到什么程度?能不能对接客户现有的 MES 系统?这类协议覆盖率的问题,工程师自己也未必记得全,得翻产品手册、查历史项目案例。但问题是,工程师的时间大量被售后群里的重复问题占用,真正需要他们发挥专业价值的售前场景,反而容易被挤占。
2.4
*痛点总结*
梳理下来,这类场景的痛点其实挺典型的。
首先是知识碎片化。解决方案散落在内部论坛帖子、各种 Word 文档、甚至老工程师的脑子里。同一个问题,不同工程师可能给出不同的解法,而且很难沉淀下来复用。新来的工程师想找答案,全靠问老同事或者自己摸索。
其次是搜索失效。客户描述问题用的词和技术文档里的术语经常对不上。客户说"连不上",文档里写的是"通讯超时"。客户说"打不开",可能是权限问题、环境问题或者安装问题。传统的关键词搜索很难处理这种语义 gap。
第三是人力错配。高级工程师的时间被大量重复性的售后问题占用,真正高价值的售前支持反而没精力做。售前咨询往往是帮销售拿单的关键环节,但工程师被群消息淹没,响应不及时,客户体验自然也不好。
2.5
*为什么知识库是"刚需"*
对于这家客户来说,知识库不只是一个锦上添花的工具,而是业务发展的基础设施。
短期来看,知识库能直接提升售后响应效率。工程师遇到问题不用每次都重新搜、重新组织语言,系统能快速给出参考答案和相关文档。即便不能完全替代人工,也能显著减少重复劳动。
中长期来看,更重要的是数据沉淀。企业内部那些散落的非结构化文档、业务专家的经验、历史项目的案例,这些知识资产需要一个载体来承接和积累。知识库系统本身就是这个载体。工程师在使用过程中,每一次"这个答案有帮助"或"这个答案不对"的反馈,都是在帮系统调优,也是在把隐性知识显性化。
从这个角度看,工程师的角色其实是双重的:他们既是知识库的用户,也是重要的人工标注者。系统越用越准,知识越积越厚,逐步就能实现从人工响应到半自动、再到自动化的演进。一方面更好地承接现有的售前售后需求,另一方面在人力规模不变的情况下,能够支撑更大的业务体量。
3
为什么不用开源框架?
市面上主流的开源 RAG 框架的优势很明显:封装度高、开箱即用,文档上传之后几分钟就能跑起来一个可演示的 Demo。但相应的代价是灵活性和可扩展性受限,很多细节没法深度定制。
3.1
*核心考量*
对于企业级项目来说,业务方要的不只是一个能演示的原型,而是一个能长期使用、持续迭代的系统。这意味着系统要能接入客户现有的业务入口(比如企微机器人、内部 OA),要能根据实际效果调整检索策略,出了问题要能追溯到具体环节。这些需求在封装度较高的框架里往往不太好实现。
当然,这并不是说开源框架不能用。如果项目周期短、定制需求少、主要目的是快速验证可行性,用现成框架是完全合理的选择。但这个项目的情况不太一样:客户希望这套系统能逐步从效率工具演进成企业的知识基础设施,前期是提升售后响应效率,后期是沉淀业务经验、支撑更大体量的业务。这种长期迭代的诉求,决定了需要对各个环节有足够的控制力。
3.2
*具体差异*
从实际开发的角度,手搓方案和开源框架的差异主要体现在几个地方。
数据清洗这块,理论上可以线下处理好再上传到框架里,但实际操作中清洗逻辑往往要反复调整。这个项目的 1600 多份文档里有大量论坛爬取的内容,噪音类型很杂,需要针对性地写正则规则,跑完还得人工抽检。这个过程本身就是高度定制化的,跟框架关系不大。
Embedding 模型方面,主流框架其实都支持接入第三方模型。但这个项目在开发过程中切换了三次模型(从本地 Ollama 到 OpenRouter 再到最终方案),每次切换都涉及向量空间兼容性的问题,需要重新入库。这种灵活调整在框架里也能做,只是排查问题的时候会多一层黑盒。
检索策略是差异最明显的地方。这个项目用了 Parent-Child 连坐召回加本地 Rerank 的方案,检索链路比较长,中间有不少调参的空间。如果用框架的话,这部分逻辑往往被封装得比较深,想调整就得去改框架源码。
前端交付方面,客户希望有独立的 Web 界面,后续可能还要接入企微。框架自带的 Chat UI 不太满足需求,最后还是得自己用 Next.js 写一套。
3.3
*关于产品化的思考*
经常会有人问我做了这么多知识库项目,为什么没有沉淀出一个成熟的产品或框架?
我的理解是,知识库这类场景,工作量的大头在数据处理而不在框架本身。每个客户的文档结构、噪音类型、业务术语都不一样,就算有一个完美的框架,碰到几千份文档里夹杂的时间戳、下载统计、论坛回复,还是得一条条写规则清洗。这部分工作没有太多捷径可走。
真正能复用的,其实是工程经验和最佳实践。比如数据清洗的标准流程和质检方法、Embedding 和 Rerank 模型的选型决策依据、检索策略的调参方法论、反馈闭环的数据库设计模板。这些经验在不同项目间是可以迁移的。代码本身反而是相对次要的部分,因为每个项目的技术栈和部署环境都不太一样。
目前我在做的事情,是把一些通用性比较强的模块抽象出来:清洗工具链、向量入库管道、反馈数据收集框架。这些模块还不是一个完整的产品,但能显著降低后续项目的启动成本。
4
数据工程:最"脏"但最重要的活
这部分占了整个项目大约 70% 的实际工作量。很多人以为 RAG 的核心是模型或框架,但实际做下来会发现,数据质量才是决定效果的关键因素。
4.1
*原始数据摸底*
拿到数据后我先做了一轮整体盘点。这批文档来自客户内部的知识管理系统,是从内网 wiki 导出的,全部是 Word 格式。总共有 1600 多份,文档长度分布极不均匀:最短的只有几百字,属于简单的 FAQ 类型;最长的接近 3 万字,是完整的产品配置手册。统计下来,大概有 98% 的文档字数在 5000 字以内,只有约 2% 属于超长文档。这个分布特点也影响了后续的分块策略设计。
4.2
*噪音分析与采样*
数据清洗不能盲目开干,得先搞清楚噪音长什么样。我采用的是多轮抽样加人工审核的方式。
第一轮随机抽了 10 份文档,用 python-docx 提取纯文本内容,然后把这些文本丢给大模型,让它识别里面哪些内容属于噪音、哪些是真正有价值的知识。大模型在这一步很有用,它能快速发现一些不容易注意到的模式,比如论坛特有的元信息格式。第二轮又随机抽了 20 份,重点覆盖第一轮没涉及到的目录和分类。每轮抽完之后,把识别出的噪音模式整理成正则规则,跑一遍全量数据,再抽样验证清洗效果。这个过程迭代了三四轮,才基本收敛。
这批文档的噪音类型比较典型。因为是从内网 wiki 导出的,所以夹杂了大量页面元信息:页眉页脚的重复文字、上传时间戳("2024-03-15 14:30 上传")、下载统计("(1.09 MB, 下载次数: 118)")、论坛交互元素("点击文件名下载附件"、"您的浏览器不支持 video")等等。另外还有一些代码块的格式残留(比如行尾的"复制代码"按钮文字)、纯数字行、用户抱怨性质的内容("文件下载不了")——这些都不是真正的知识,需要清掉。
注:红框圈出的都是噪音信息(对比下方图片清洗后效果)
如果是其他类型的知识库场景,噪音类型可能会有所不同。比如从 PDF 转换过来的文档,常见的噪音是页码、表头重复、分栏错位;从邮件归档导出的内容,噪音可能是邮件签名、转发链、自动回复;从客服工单系统导出的数据,噪音往往是工单模板字段、系统生成的流程日志。总之,噪音分析是高度场景相关的,没有通用方案,只能针对性处理。
4.3
*噪音清洗规则*
基于多轮采样的结果,最终整理出一份相当长的正则规则清单。核心逻辑是匹配后直接跳过这一行,不进入后续处理流程。下面是部分典型的规则:
NOISE_PATTERNS = [ # 页面结构类噪音 r'.* - 汇总信息$', # 页尾汇总标题 r'^帖子列表$', # 论坛导航元素 r'^详细帖子内容$', # 论坛模板文字 r'^未知标题$', # 占位符标题 # 论坛交互类噪音 r'^共找到 \d+ 个帖子$', # 搜索结果统计 r'^【主帖内容】$', # 论坛结构标记 r'^【回复 \d+ - .*】$', # 回复区标记 r'^回复时间:.*$', # 回复时间戳 r'^暂无回复$', # 空回复提示 r'^回复列表$', # 回复区标题 # 附件与下载类噪音 r'^点击文件名下载附件$', # 附件提示 r'^附件下载$', # 下载区标题 r'^\([\d\.]+\s*(MB|KB),\s*下载次数:\s*\d+\)$', # 下载统计 r'^.*\.zip$', # 纯附件名行 r'^文件下载不了$', # 用户抱怨(非知识) # 多媒体与格式类噪音 r'^您的浏览器不支持 video 或 audio 标签$', # 多媒体兼容提示 r'复制代码$', # 代码块按钮残留 r'^-+$', # 分隔线 r'^\d+$', # 纯数字行(页码等)]# 时间戳格式多变,单独处理UPLOAD_TIME_PATTERN = re.compile( r'^\d{4}-\d{1,2}-\d{1,2} \d{1,2}:\d{1,2} 上传$')# 图片占位符的识别模式IMAGE_PLACEHOLDER_PATTERN = re.compile( r'^(.*?\.(?:png|jpg|jpeg|gif|bmp))\s*\(.*下载次数.*\)')
这些规则需要根据实际数据不断调整。一开始写得太宽松,会漏掉噪音;写得太激进,又可能误删有用内容。所以每次调规则之后,都要重新抽样验证一遍。
4.4
*双重输出:机器侧 + 用户侧*
清洗流程最终设计成一次处理、双重输出的模式:
| 输出类型 | 格式 | 用途 |
|---|---|---|
| 机器侧 | Clean Markdown | 向量化入库,用于 RAG 检索 |
| 用户侧 | Clean DOCX | 用户点击引用时跳转查看 |
之所以同时输出两种格式,是因为它们服务不同的目的。Markdown 是给机器看的,方便后续的切分和向量化,取消了原始 Word 的格式复杂性。Clean DOCX 是给用户看的,当系统返回答案并附上引用来源时,用户可以点击卡片直接打开原始文档。打开后还能看到完整的格式、表格、图片,并且标题做了高亮处理,方便快速定位。
注:清洗后的word文档
注:用于后续RAG入库的Markdown文档,包含了回填的图片链接核心代码逻辑大概是这样:
def process_file(file_path): doc = Document(file_path) clean_doc = Document() md_lines = [] # 1. 提取嵌入图片,保存到 images 目录 for element in doc.element.body.iter(): if element.tag.endswith('blip'): # 保存图片,记录路径 pass # 2. 逐段处理内容 for para in doc.paragraphs: text = para.text.strip() if is_noise(text): continue if is_image_placeholder(text): md_lines.append(f"
") clean_doc.add_picture(img_path) else: md_lines.append(text) clean_doc.add_paragraph(text) # 3. 双重保存 clean_doc.save(f"{title}_Clean.docx") save_markdown(md_lines, f"{title}.md")
这个流程跑完之后,每份原始文档会产出两个清洗版本,再加上一条元数据记录(包含文件路径、分类、标题等)。
4.5
*LLM 元数据增强*
清洗完成后,元数据里只有物理属性:文件名、路径、目录分类。这些信息对于检索来说是不够的。举个例子,用户问"MQTT 怎么配置",但文档标题可能叫《数据采集通讯模块使用说明》,光靠文件名匹配是搜不到的。
为了解决这个问题,引入了 LLM 元数据增强。基本思路是让大模型阅读每份文档的内容,然后生成三类语义信息:一句话摘要(summary)、5-8 个关键技术术语(keywords)、以及 3-5 个"这份文档能回答的问题"(questions)。
这样做的好处是多维度的。摘要可以用于结果页的快速预览,用户不用点开就能大概知道这份文档讲什么。关键词可以作为辅助召回手段,弥补向量检索在专业术语上的不足。而 questions 字段配合 HyDE(Hypothetical Document Embedding)检索策略,能显著提升问答场景的召回率,因为用户的问法和文档预设的问法往往更接近。
批量处理时用了多线程加断点续传的机制,每处理 10 条就保存一次进度,避免中途中断丢失数据。调用的是云端大模型 API,并发跑下来整体还是比较快的。
def process_item(item): # 断点续传:跳过已处理的 if item.get("summary"): return # 调用 LLM 生成元数据 result = llm.generate(prompt, content[:5000]) item["summary"] = result["summary"] item["keywords"] = result["keywords"] item["questions"] = result["questions"]
最终产出的元数据结构大概是这样:
{ "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "filename": "数据采集通讯配置.docx", "title": "数据采集通讯配置", "category": "通讯协议/MQTT", "summary": "介绍了组态软件中配置 MQTT 通讯的完整步骤,包括 Broker 连接参数和 Topic 订阅方式。", "keywords": ["MQTT", "Broker", "Topic", "QoS", "通讯配置"], "questions": [ "如何配置 MQTT 连接?", "Topic 格式怎么填写?", "QoS 级别有什么区别?" ]}
4.6
*图片处理:从 Word 提取到 MinIO 服务*
工控场景的技术文档有一个很明显的特点:图文并茂。配置步骤、界面截图、连线示意图、报错截图,这些图片本身就是知识的一部分不能丢。如果用户问“这个参数在哪里设置”,系统只给一段文字说明,体验像的文档一样,跟看原文没区别。但如果能给一张截图“就是这个位置”,用户体验完全不一样。
数据清洗阶段,我把 Word 里的嵌入图片都提取出来,保存到本地 images 目录。Markdown 版本里用标准的图片语法引用,比如
。这样 LLM 生成回答的时候,如果参考文档里有图片,它会把图片链接一起返回。
POC 阶段…