做了十几个知识库项目后,我把入库前的文档摸底流程产品化了

过去两年做企业大模型应用,知识库类型的项目咨询占比算是最高的,有公众号、知乎这些平台上来的,也有线下转介绍的。大家上来普遍会先问报价:有大概几千份文档,做一套知识库多少钱?早期我会根据文档数量大概估一个工时,结果后来很多项目做起来发现完全不是那么回事。同样是两千份,有的企业文档结构清晰、格式统一,清洗入库一周搞定;而有的企业文档里夹杂着扫描件、合并单元格、论坛爬虫数据,光清洗就得折腾半个月。数据治理这部分往往会占到整个工程量的大头,但之前都是 case by case 地处理,繁琐且重复。报价报低了,干起来又累又亏;报价报高了,尤其是远程来的咨询,没有信任基础,很多事儿就不了了之了。

后来我改成让客户先发一些脱敏后的样例文档过来,跑一遍预检再报价。但这个做法也有些问题。大部分客户挑选的样例往往不能代表全貌,要么挑的太简单,要么挑的太复杂,总之讲不清楚实际情况。基于样例做报价和 POC,还是会有偏差。再后来和一些信任关系比较好的线下客户合作,签完保密协议之后能直接接触到全量文档。拿到全量数据之后,我会先做一遍整体的文档分布分析和入库前的质量检查,看看格式分布、扫描件占比、敏感信息、文档长度分布这些。这样才能给出靠谱的工作量评估,把握一期需求边界、哪些二期处理、和老板对齐预期。

做了十几个项目之后,这套流程跑熟了,我开始想着能不能把这些逻辑产品化。先把数据治理这部分尽快抽象出来,整理成一个可复用的工具包。后续还会陆续把分块策略、检索策略、检索效果评测这些也做一些抽象,整理一些经验给大家参考。这个工具包我规划了三种使用场景(内部治理、产品交付、售前咨询),这篇主要讲的是第一步数据质量评估模块,也就是入库预处理。

这篇试图说清楚:

这个工具包的三种使用场景,技术选型和第一版功能,在实际使用过程中发现了哪些属于过度开发、哪些应该砍掉,功能收敛之后的设计原则,几个值得展开的技术细节,以及产品体验上的一些打磨。

以下,enjoy:

1

   

三种使用场景

关于这个工具包的使用场景,一方面是开头提到的售前场景,客户不愿意给原始数据,那就让他在本地跑一遍,生成一份脱敏报告发过来,我拿着报告就能给出靠谱的报价。另一方面是日常做项目交付的时候,拿到客户的文档包,得先跑一遍摸清楚数据情况,然后才能决定怎么清洗、怎么分块、哪些需要特殊处理。这套流程以前每个项目都要重新搭一遍,现在抽象成工具包之后,新项目直接跑就行。

当然,这两个场景都是解决我自己做项目的问题。但我意识到其他在做知识库项目的朋友可能也有类似的需求。比如企业内部的 IT 团队,想盘点一下历史文档资产,看看哪些能直接入库、哪些需要 OCR、哪些可能有敏感信息。这类需求其实挺普遍的,只是大家以前都在各自写脚本,没有一个现成的工具可以直接用。

所以这个工具包封装的不只是几个脚本,更有价值的地方是背后的一套工作流,文档该怎么分类、扫描件该怎么识别、敏感信息该怎么检测、统计报告该展示哪些指标。这些都是过去十几个项目踩坑之后沉淀下来的经验。把这些经验封装成工具,一方面自己用着省事,另一方面或许也能给有类似需求的盆友提供一些参考。

2

   

快速原型与踩坑

2.1

   

技术选型与第一版功能

技术选型上没什么特别的,后端用 FastAPI + Python,主要是文档处理的库生态丰富;前端用原生 HTML/CSS/JS,轻量,不需要 Node 构建工具;进度推送用 SSE,比 WebSocket 简单,单向推送足够了;图表用 ECharts,开箱即用,深色主题支持也好。

第一版做了挺多功能。递归扫描文件夹、识别各种格式、统计格式分布,这些是基础。PDF 会自动判断是文字型还是扫描型。敏感信息检测支持手机号、邮箱、身份证、银行卡。重复文件用 MD5 去重。还做了一个风险评分,0-100 分,红黄绿三档分级。前端是仪表盘风格的可视化报告,看起来挺像那么回事。

当时的心态就是功能越多越好,尽量全面。但跑起来之后发现了很多问题。

2.2

   

暴露的几个问题

首当其冲的是是评分逻辑不对。很多正常的 Word 文档被标记成"中风险",扣了 30 分。查下来发现是 .doc 格式(老版 Word)用 python-docx 解析会失败,我把"解析失败"等同于"文件有问题",这个逻辑是错的。后来加了 .doc 格式的单独处理逻辑,在 macOS 上用 textutil 提取文本(Windows 可用 LibreOffice headless / antiword / Tika 作为后备),同时区分"解析失败"和"文件损坏",前者只轻微扣分。

其次是敏感信息检测误报率太高。有次测试显示"银行卡检测出 53 个",但实际文档里根本没有银行卡号。原因是正则匹配 16 位数字,财务表格里的合同编号、发票号全部中招。这个问题当时没想到好的解法,先搁置了。

还有统计颗粒度不够的问题。既然叫做入库预处理,那肯定得知道文档长度的分布,P50 是多少、P90 是多少,这样才能决定分块策略。于是我又加了长度分布统计、长度区间直方图、预计 chunk 数和 token 数、还有分块策略建议。但这时候的心态变成了想到什么就加什么。功能越堆越多,但隐约感觉哪里不对。直到后来找了两个真实项目里分别测试了下,又发现一堆问题。

2.3

   

几个过度开发的功能

先说敏感信息检测。前端展示的是"手机号: 524,邮箱: 58,银行卡: 53"这样的统计数字。看完之后只知道这些敏感信息在哪些文件里,不知道是真的敏感信息还是误报,更不知道下一步该怎么处理。说白了,就是把初筛结果当成最终结论呈现了,但初筛结果本身是不可操作的。

再说分块建议。我做了一个功能,根据文档长度分布,推荐一个 chunk size,比如"推荐 300 字"。但仔细想想,这个功能完全是画蛇添足。分块策略本身取决于很多因素,像业务场景、embedding 模型的上下文窗口、检索时的精度要求。这些业务背景信息在使用这个工具包的时候,实际上我作为用户,实际上可能还没有了解的很全面,这种做法是在试图用脚本代替业务判断,肯定不对。

还有风险评分。最开始设计了一套评分逻辑,0-100 分,红黄绿三档。但测试的时候发现两个文件显示"文件损坏",实际上用 Office 打开完全正常。查下来发现一个是 ~$ 前缀的临时文件(确实打不开),另一个是老格式文件(Python 库解析失败,但 Office 能打开)。原始脚本里把"解析失败"等同于"损坏",这个逻辑本身就是错的。更尴尬的是,扫描型 PDF 因为"解析成功、无敏感信息"反而得了 100 分,根本不在风险清单里,但扫描件明明需要 OCR 处理。

想到这里我意识到,问题的本质是在堆功能,还没有理清核心逻辑。

2.4

   

功能分类与取舍

于是我把所有功能拆开来,做了些分类:哪些是准确的?哪些是不准确的?哪些是主观的?

准确的功能应该保留。格式分布统计、PDF 文字型/扫描型分流、文档长度分布、MD5 重复检测——这些都是客观的、可验证的,输出就是输出,没有歧义。

不准确的功能需要改进。敏感信息检测的问题不是不能做,而是不能只给一个统计数字,得展示具体在哪个文件、哪个位置、前后文是什么,让人能判断是不是误报。风险评分的问题是用评分来划分风险,逻辑不如规则分类清晰,不如直接按"扫描件"、"解析失败"、"含敏感信息"这些规则来分类。

主观的功能应该删除。健康评分没有业界标准,不同业务场景标准完全不同,给一个分数反而误导。推荐 chunk size 更是开玩笑,这本身也不是脚本能决定的事。预计 chunk 数和 token 数依赖的假设太多,参考价值很低。

这轮优化下来,功能列表砍掉了一小半,但剩下的每一个都变得更具象了。

3

   

功能收敛与设计原则

经过前面的试错,我重新梳理了产品定位。整体的处理流程大概是这样的:

核心逻辑其实很简单:这个工具的最终目的,是服务于下游的分块策略和检索策略。所以输出的不应该是一份静态的文档质检报告,而应该是一份可操作的配置清单,告诉下游系统每份文档应该走什么处理管线。

3.1

   

最终保留的功能

想清楚定位之后,功能列表就变得很聚焦:格式分布统计。扫描文件夹后,统计每种格式有多少份,占比多少。这是最基础的数据,100% 准确,没有歧义。

PDF 页面类型识别。判断 PDF 是文字型、扫描型还是混合型。文字型可以直接提取文本,扫描型需要先做 OCR。核心逻辑是按页判断——每页字符数低于阈值就算扫描页,扫描页占比超过 70% 就标记整个文件为扫描型。这是一条启发式,用于分流与估算,不保证严格正确;因此所有阈值可配置,且输出‘待确认’列表。

# …
— 以上为试看内容(约 40%),开通会员后阅读全文 —