1. 为什么归档系统要先想明白再动手：从"领导找不到合同"说起
今年上半年我在帮一家制造企业做文档系统预研，需求方开场只有一句话："我们希望把过去十年的合同、图纸、验收报告全部电子化，管理层要能在三分钟内调出任何一份。"这句话听起来平平无奇，但真正往下拆的时候，牵扯出来的问题足够写满半本备忘本。你要面对的不是几十份漂亮的电子文档，而是分布在个人电脑、邮箱、微信聊天记录、旧U盘里的各种扫描件、翻拍件和"不知道哪个系统导出来的PDF"。把这些东西统一变成可检索、可管理、可追溯的归档资产，这就是批量PDF/OCR归档系统功能需求文档要解决的事。
我一直认为，这种需求文档的读者不应该是"评审时走流程"的领导，而应该是将来真正要去实施它的开发团队、运维人员和档案管理员。文档的颗粒度，决定了项目能不能一次做对。与其在系统上线后不断返工，不如在一开始就把边界、指标、异常处理路径写清楚。
这篇文章会把我在实际项目中整理这套需求文档的思路、章节结构、容易出现分歧的技术选型点，以及落地时大概率踩到的坑，全部摊开来聊一遍。适合企业IT负责人、项目经理、刚接手文档电子化工作的档案管理员，以及想给自己建一套PDF知识库的个人用户参考。
2. 顶层结构：先把业务目标翻译成需求条目，再谈功能
2.1 干系人视角决定需求优先级
很多需求文档第一版最容易犯的错，是直接罗列功能点：要有OCR、要有全文检索、要能批量导入。但"要有什么功能"回答的是What，真正让项目立住的，是搞清楚每个角色希望这套系统替他们解决什么烦恼。
我把干系人拆成了四类：
- 管理层：核心诉求是"找得到"。过去合同放在谁手里、在哪个Excel里登记过，都说不清。他们需要的是从管理层视角出发的检索入口，最好只输入关键词就能定位文件，不用关心底层是扫描件还是电子版。
- 业务部门：核心诉求是"别添麻烦"。业务人员最怕流程变重，如果归档系统要求每个文件手动填十个字段才能入库，项目基本死在推广阶段。
- 档案管理员：核心诉求是"规则统一、可复核"。他们负责事后盘点、审计、抽查，需要元数据规范、命名规范、分类树可维护。
- IT运维：核心诉求是"能部署、能监控、能备份"。他们关心批量任务队列有没有断点续传，OCR服务会不会把CPU打满，存储增长量是不是可控。
需求文档开篇，应该把这四类人的诉求列成一张优先级表，再用业务目标去回应。
2.2 从业务目标倒推功能清单
我在文档里把业务目标归纳为四条：
- 存量清理：将历史积压的PDF和扫描件全部入库，预计约80万页。
- 增量归档：新产生的PDF和拍照件按既定规则自动进入归档流程。
- 秒级检索：单次检索响应时间不超过3秒，支持按文件名、全文内容、元数据组合筛选。
- 过程留痕：系统对每一次查看、下载、修改都留有日志，满足内部审计要求。
有了这四个目标，功能清单就不是拍脑袋凑出来的，而是逐条推导的。存量清理对应批量导入和预处理，增量归档对应Agent监控目录和定时扫描，秒级检索对应OCR文本提取与索引构建，过程留痕对应权限模型和审计日志。
2.3 需求文档的标准骨架
我最终使用的文档结构是下面这样的，实际做需求的人可以照这个骨架去填充：
| 章节 | 核心内容 | 关键产出物 |
|---|---|---|
| 项目背景与目标 | 现状痛点、量化目标、范围边界 | 目标清单、排外声明 |
| 术语定义 | PDF类型、OCR、元数据、双层PDF | 名词表 |
| 干系人与场景 | 四类干系人、端到端场景 | 场景用例 |
| 功能需求 | 导入、预处理、OCR、归档、检索、权限 | 功能列表与优先级 |
| 非功能需求 | 性能、容量、可用性、安全 | 指标表 |
| 接口需求 | 与OA、ERP、企业网盘的对接边界 | 接口清单 |
| 验收标准 | 可量化的验收指标、抽样方法 | 验收清单 |
这套结构的好处是，每一条功能需求都能回溯到业务目标，评审会上当有人问"为什么要做这个功能"时，可以直接翻到对应章节找到出处，而不是说一句"大家都这么做"。
3. 批量导入与PDF预处理：整个流程中最容易被低估的环节
3.1 输入源远比你想象得杂
做需求调研时，我让企业做了一次文档来源盘点，结果比预想中复杂得多：
- 本地目录和FTP共享：历史扫描件的大头，通常是共享盘里按部门乱堆的文件夹。
- 邮件附件：合同、报价单散落在个人Outlook和网页邮箱里。
- 企业网盘和IM工具：通过聊天记录传输的文件，往往还没有统一命名。
- 扫描仪一体机：直接产出整包JPEG或PDF，常有歪斜、黑边、空白页。
- 移动端拍照上传：业务人员在现场拍摄的合同页、发票、验收单，清晰度参差不齐。
每一个来源都对应一类处理策略。共享盘适合做全量扫描和断点续传，IM工具里导出的文件要先做去重，移动端拍照件则必须走图像预处理管线。需求文档里建议明确每一个输入源的具体对接方式，否则开发阶段会在"文件到底从哪里来"这件事上反复扯皮。
3.2 文本型PDF和图片型PDF必须分流
很多团队一开始会把所有PDF一股脑丢给OCR服务，结果一半文件是原本就带文本层的电子PDF，白白浪费OCR额度，另一半图片型PDF因为没做预处理，识别率又惨不忍睹。所以在预处理模块里，第一件事就是分流。
我用PyMuPDF快速判断文本层是否有效，示例如下：
import fitz doc = fitz.open("sample.pdf") for page_num in range(len(doc)): page = doc.load_page(page_num) text = page.get_text().strip() if len(text) > 10: print(f"第{page_num + 1}页：文本型PDF，走文本提取") else: print(f"第{page_num + 1}页：图片型PDF，走OCR管线")这个逻辑看起来简单，但阈值怎么定直接影响后续效果。有些PDF只有页眉页脚是文本，正文全是扫描图，如果阈值设得太低会被误判成文本型，导致正文内容全部丢失。我一般会把"有效文本占比超过页面面积的5%"作为分流水准，并且把提取到的内容长度和文件大小做交叉比对。
3.3 扫描图像处理：清晰度、方向、去噪
图片型PDF不能直接进OCR，必须先转成图像，再做预处理。我在需求文档里对图像预处理管线提出的硬性要求如下：
- 输出分辨率不低于300 DPI。OCR引擎对低分辨率非常敏感，200 DPI以下识别率会断崖式下降，这是被我反复验证过的。
- 自动纠偏。扫描件经常带0.5度到5度的倾斜，倾斜超过2度时，识别结果会出现整行错乱。
- 去黑边、去噪点、增强对比度。手机翻拍件尤其需要做阴影去除和亮度归一化。
- 复杂背景版面先做倾斜校正再送识别，大尺寸图纸（例如CAD导出的PDF、铁路规划图那种长幅面）要配置切分策略，避免等比压缩后OCR引擎只看得到全局看不清局部。
需求文档里这部分容易被写成"需支持图像增强"，但我会明确写成"需支持去噪、纠偏、二值化、对比度增强，且每类操作必须可配置开关，默认打开纠偏与去噪"，这样开发人员才知道边界在哪里。
3.4 前端展示与缩略图
归档系统逃不掉一个需求：用户在Web界面里预览PDF。热搜词里常年有人搜"vue image能显示pdf吗"、"js中pdf缩略图"，说明前端PDF展示是普遍痛点。我的建议是服务端用Poppler或libreoffice把首页转成缩略图，预览时用pdf.js在前端渲染，兼容性比依赖浏览器自带插件稳定得多。如果涉及"前端生成的PDF水印"场景，可以在服务端加水印后转成只读的Standard PDF，避免用户直接另存。
4. OCR引擎选型与识别规则设计：决定系统上限的关键决策
4.1 自建还是调用云API
OCR是这套系统里争议最大的模块。团队里有人想全用开源，有人倾向直接买云服务，需求文档里必须把选择逻辑写清楚，而不是假装不存在。
我的取舍标准是看三件事：数据敏感程度、识别准确率要求、运维成本承受力。
| 方案 | 优势 | 劣势 | 适用场景 |
|---|---|---|---|
| PaddleOCR自建 | 免费、可控、中文效果好、支持多语言模型 | 需要GPU资源、需要持续调优 | 数据不出内网、预算有限 |
| Tesseract自建 | 轻量、跨平台、历史悠久 | 中文和复杂版面效果一般 | 英文扫描件、简单版面 |
| 腾讯开源OCR方案 | 中文优化好、社区活跃 | 配套文档参差 | 中文为主、愿意折腾 |
| 百度OCR云API | 开箱即用、准确率高、按量付费 | 数据出网、有调用成本 | 合同关键字段抽取 |
在这类系统里，我通常建议采用"本地PaddleOCR为主 + 云API兜底"的混合策略。本地引擎处理常规中文扫描件，遇到置信度低于阈值或需要抽取合同金额、日期等关键字段时，再调用云端接口复核。这样成本和准确率都能兼顾，但前提是非功能性需求里要把网络隔离策略写清楚，避免数据合规风险。
4.2 多语言与语言包是一个隐蔽的大坑
热搜词里一直不缺"ocr识别不了韩文""福昕pdf编辑器ocr语言包ocr-zh-cn.fzip"这类搜索，这说明多语言问题是很多人的真实痛点。归档系统往往放的不只是中文资料，还有外文合同、英文说明书、历史文献扫描件，甚至日文韩文材料。
在使用PaddleOCR时，默认安装经常只带中文和英文模型。要识别韩文，必须确认是否加载了对应的多语言模型，并且版本要匹配。需求文档里我会写一条硬性要求：OCR引擎必须支持中文简体、中文繁体、英文、韩文、日文，且各类语言模型必须在部署文档中列出安装和验证方法。否则开发时一切正常，一测试韩文材料就全员傻眼。
4.3 合同关键字段提取：从正则到语义的渐进式方案
热搜词里有一条很典型的场景："java使用百度ocr识别上传合同文件时读取收入、单位、时间等关键字段"。这类需求比单纯全文识别难一个量级，因为它要求从非结构化文本里抽取出结构化字段。
我的建议是采用渐进式方案，不要一上来就上大模型：
- 第一层：全文OCR识别，把PDF转成带位置的文本流。
- 第二层：用正则表达式匹配已知模式，例如日期（YYYY年MM月DD日）、金额（含货币符号和千分位）、合同编号。
- 第三层：用关键词定位段落，例如"甲方""乙方""签订日期""合同总价"所在的行。
- 第四层：当规则匹配成功率低于95%时，再引入语义模型做兜底。
这套方案的逻辑是，先保证"确定性任务用确定性方法"，减少大模型带来的不可控和延迟。我见过很多团队一上来就要做全流程大模型抽取，结果准确率倒是过得去，但每份文档的调用成本和响应时间完全失控，最后又退回到规则加正则。
5. 归档结构、元数据与全文检索：检索质量取决于入库质量
5.1 目录和文件命名是第一批彩蛋
归档系统上线半年后，决定用户愿不愿意继续用的，往往是目录结构和命名规范这些"不起眼"的决策。目录层级建议控制在三级以内，例如"年度 / 业务线 / 文档类型"，超过三级用户翻起来就烦了。
文件命名我推荐统一格式：YYYYMMDD_业务类型_流水号_版本号，例如20240513_合同_A000123_V1.pdf。这里有个容易被忽略的细节：原始文件名不能丢，必须存进元数据字段里。原因很简单，业务部门会通过"原文件名"反查自己交给系统的文件，如果系统入库后直接改了名，用户会认为文件"被弄丢了"。
5.2 元数据设计越完整，检索越省力
全文检索并不能解决所有问题。用户经常说"帮我找去年和某供应商签的合同"，单纯靠全文检索也能搜到，但如果你在元数据里维护了"合作方""合同类型""经办人"，检索速度和准确性完全不一样。
我设计的核心元数据字段如下：
| 字段 | 类型 | 说明 |
|---|---|---|
| 原始文件名 | 字符串 | 入库前文件名，保留追溯 |
| 文档类型 | 枚举 | 合同、发票、验收单、图纸、报告 |
| 业务线 | 字符串 | 对应企业业务分组 |
| 关键日期 | 日期 | 合同签订时间、文件生成时间 |
| 责任部门/经办人 | 字符串 | 审计和检索都需要 |
| OCR置信度 | 浮点数 | 低于60分进人工复核队列 |
| 文档哈希 | 字符串 | 去重和完整性校验 |
实操经验：OCR置信度一定要保留。归档系统面向海量文件，不可能每一份都人工复核，但你要有办法把"识别可信度低"的文件捞出来单独处理，否则垃圾数据会永久污染检索结果。
5.3 全文检索与双层PDF
对于带文本层的PDF，直接抽取文本建索引；对于扫描件，OCR识别结果一般不直接覆盖原PDF，而是生成双层PDF——底层是原始扫描图像，上层是透明的OCR识别文本。这样你在任何标准PDF阅读器里都能复制、搜索文字，同时保留了原始图像作为凭证。涉及法律效力的合同、票据，这个能力几乎是必选项。
检索服务端建议独立搭建，索引库可以先用Elasticsearch，也可以从轻量的方案起步（比如SQLite FTS5）。真正决定检索体验的不是搜索引擎本身，而是索引字段的丰富度和分词规则。中文分词要额外注意，专业术语（比如产品型号、生僻地名）经常被通用分词器切得稀碎，需要在词典里维护术语表。
5.4 权限、版本与审计
归档系统的数据是企业的核心资产，权限模型必须写清楚。我的建议是至少三层：系统级（谁能登录）、目录级（谁能看哪个目录）、文档级（谁能看哪份文档）。同时所有外发行为要有留痕，下载行为要支持审计日志追溯到人。
版本管理这块，重点是防止"同名文件覆盖"。归档系统在检测到哈希值不同的同名文件时，应该自动保存为新版本，而不是覆盖旧版本。历史版本保留期至少要满足财务和法务的审计要求，通常不低于十年。
6. 落地时最容易翻车的六个场景：现象、排查链路、解决方案
6.1 PaddleOCR识别韩文失败：全乱码或输出为空
现象：中文材料识别正常，韩文材料整页输出乱码或直接空白。
排查链路：
- 先看加载的模型文件列表，确认是否包含韩文识别模型。PaddleOCR默认安装包在部分版本里不包含韩文字典，这是第一嫌疑人。
- 再检查调用参数，确认语言参数是否从中文切换成了韩文，有时候代码里写死了lang参数是ch。
- 最后看预处理环节有没有把韩文文本当成图片损坏处理，例如错误地转成了灰度或做了二值化。
解决：下载对应韩文模型并放到正确目录，同时在代码里增加语言自动检测或显式切换逻辑。部署验收时一定要把"外文样本识别"写进测试用例，别只测中文。
6.2 云OCR接口报file format error
现象：调用百度OCR接口时返回"error_msg":"file format error"，log_id能查到，但换个文件又可能正常。
排查链路：
- 先确认传给接口的到底是文件流还是Base64字符串，内容与参数格式是否匹配。
- 再检查Base64有没有被加上
data:image/png;base64,这类前缀，部分云接口不接受这种带前缀的字符串，部分接口又可以，取决于具体版本。 - 检查文件真实格式和扩展名是否一致。把Word改名成PDF再上传，各种接口都会报格式错误。
- 最后看文件大小和尺寸，超大图片、超长PDF有时候需要分页或压缩后再传。
解决：在调用层统一封装一个"文件规范化"入口，把所有文件转成标准PNG或JPEG，压缩到接口限制内，再决定走Base64还是URL直传。这样能减少大量莫名其妙的格式报错。
6.3 图片版PDF直接送OCR导致准确率崩塌
现象：手机翻拍的屏幕照片、低分辨率扫描件直接送识别，准确率不到50%，甚至一行字被识别成乱码。
根因：图片型PDF没有先转成足够分辨率的图像，也没做预处理。很多团队图省事，直接把PDF文件流丢给OCR服务，指望引擎自己处理，实际效果差得离谱。
解决：在OCR引擎前端强制加管线：PDF转图像（PyMuPDF渲染，DPI设定不低于300）→ 灰度化 → 纠偏 → 增强对比度 → 再送识别。这一步做完，很多"识别率差"的问题会直接消失，不需要换昂贵引擎。
6.4 OCR语言包装不进编辑器
现象：福昕等PDF编辑器的OCR语言包（例如ocr-zh-cn.fzip）下载后加载无效，语言列表里看不到中文选项。
排查链路：
- 检查语言包版本是否和编辑器版本匹配，跨大版本的语言包通常直接不认。
- 确认安装路径。语言包需要放在指定目录，放错位置编辑器根本扫不到。
- 安装后必须完全退出并重启编辑器，部分版本有缓存，不重启不生效。
解决：下载前先查版本号，安装路径优先用官方默认目录，别自定义到奇怪的盘符。这个坑虽小，但能卡掉一整天。
6.5 歪斜扫描件整页识别失败
现象：文档倾斜超过3度时，OCR结果出现大量错位，左栏文字跑到右栏，段落完全乱掉。
原因：OCR引擎虽然自带一定的旋转检测能力，但扫描件如果带的是微小角度倾斜（1到5度），引擎的版面分析经常会出错，把多栏文本混在一起。
解决：预处理模块里增加自动纠偏，通过检测文本行角度或页面边框线，计算出旋转角度并校正。关键点是纠偏要在OCR之前做，并且对90度、180度旋转方向也要做自动判断。这个功能看似小，挽救了大量老旧扫描件。
6.6 前端PDF生成与打印的兼容性问题
现象：Web页面打印成PDF时页边距丢失、字体变成方块、图片错位；Vue项目里直接引用PDF预览组件频繁报错。
解决：不要把"打印成PDF"的活交给浏览器端排版，HTML转PDF推荐服务端渲染，用标准模板加字体内嵌的方式统一输出。水印、页码也尽量在服务端加。前端展示统一用pdf.js，不要依赖系统自带插件。另外纸张尺寸要写死，避免不同打印机导致版面漂移。
7. 验收指标与后续扩展：不让需求文档停留在纸面
7.1 验收指标必须可量化
功能需求文档如果没有验收指标，开发团队和业务方会对"是否完成"各执一词。我在实际项目里会跟业务方逐条确认下面的指标：
| 指标项 | 目标值 | 验收方法 |
|---|---|---|
| PDF批量导入成功率 | 不低于99% | 用1万份混合样本跑批 |
| OCR平均单页处理时长 | 不超过3秒/页 | 百页样本计时 |
| 中文文字识别准确率 | 不低于95% | 人工标注200页样本 |
| 文档检索响应时间 | P95小于3秒 | 10万份文档压测 |
| 系统可用性 | 月度不低于99.5% | 运维监控报表 |
这里有个建议：验收样本集一定要提前准备，并且要覆盖"歪斜扫描件、手机翻拍件、多栏报纸版面、外文材料、表格图片"这些边缘情况。如果只用几份干净PDF验收，上线第一周就会被真实数据打脸。
7.2 上线后的迭代路线
归档系统不是一次性项目，它会在使用过程中不断长出新的需求。我个人认为比较自然的扩展顺序是这样的：
- 第一阶段：批量归档、OCR识别、基本检索，先把存量清完。
- 第二阶段：合同关键字段自动抽取、重复文件合并、自动标签分类。
- 第三阶段：基于OCR后的全文构建内部知识库，让业务人员可以问"去年和某供应商签了多少金额的合同"这类自然语言问题。
我在做这类需求文档时有个习惯，会把"现在不做但未来可能做"的功能单独放在一个附录里，写清楚触发条件。这样既不会让当前范围失控，又能在后续迭代时快速找回上下文。
最后再分享一点个人经验：这套系统的成败，很大程度不在OCR引擎选得有多先进，而在你有没有把"输入文件质量参差不齐"这个现实问题当成第一等大事。预处理做扎实了，哪怕用免费开源引擎也能顶住大多数业务场景；反过来，预处理糊弄过去，再贵的云API也救不回来。做需求文档时，多花时间在这条主线上，比堆砌功能列表有意义得多。
