知序
返回
保存草稿
发布
H1
H2
H3
1
2
3
Excalidraw 图
AI 写作
AI 优化
目录
输入内容后显示目录
Markdown
# 知识库数据工程(解析、清洗、增量更新) > 导读:本文从"换了三个检索算法效果都没提升,最后发现是 PDF 解析出来一堆乱码和串行的表格"这个开发中的实际疑问出发,把文档解析、清洗规范化、分块与元数据、增量更新、多租户权限、数据质量评估逐项讲透,最后给出完整离线流水线与踩坑清单。适合正在搭建或维护 RAG 知识库的同学。 ## 一、先建立全局认知 ### Q:为什么说"喂给 RAG 的数据"比"检索算法"更决定效果? A:结论先行——**因为检索算法只能在"已经入库的候选集"里做排序。如果正确答案根本没被正确解析、分块、入库,再强的重排也召不回来;反过来,如果每个分块都干净、自包含、可溯源,一个朴素的向量检索就能有可用效果。** 用一句话概括:**RAG 是"垃圾进,垃圾出"(Garbage In, Garbage Out)的典型系统。** 具体来说,数据质量问题会以五种方式"穿透"到最终答案: | 数据问题 | 表现 | 对 RAG 的破坏 | |---|---|---| | 解析丢内容 | 表格变乱码、多栏串行、扫描件空白 | 答案压根不在库里,召回率接近 0 | | 分块不合理 | 一句话被切成两半、标题与正文分离 | 召回了但语义残缺,答不准 | | 元数据缺失 | 缺少来源、时间、部门字段 | 无法过滤、无法引用溯源、无法控时效 | | 重复与陈旧 | 同一政策多个版本都在库里 | 召回冲突内容,给出过时答案 | | 权限没打标 | 敏感与公开文档混在一起 | 越权检索,变成合规事故 | 一个反直觉的事实:**在多数企业知识库项目里,"解析 + 清洗 + 分块"的工程量远大于"换检索算法",但团队往往把精力都花在后者的调参上。** 正确顺序是先把数据管道做扎实,再谈检索优化。 ### Q:数据工程在 RAG 链路里处于什么位置? A:结论先行——**RAG 有两条链路:离线"数据加工链路"和在线"检索生成链路"。前者是一次性投入、长期受益的基础设施;后者是每次请求都要跑的实时路径。绝大多数"效果不好"的问题,应该先在离线链路上找原因。**  *图:离线链路与在线链路的完整环节* ```text ========================== 离线链路(本篇文章的主题) ========================== 数据源 采集 解析 清洗 分块 向量化 入库 ┌────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ 文件系统│───▶│ 增量扫描 │──▶│ 文本/表格 │──▶│ 去噪归一 │──▶│ 语义切分│──▶│ 嵌入模型│──▶│ 向量库 │ │ 网盘 │ │ 版本指纹 │ │ OCR │ │ 去重 │ │ 元数据 │ │ 批量 │ │ 元数据库│ │ 知识库 │ │ 变更队列 │ │ 版面分析 │ │ 标点归一 │ │ 父子块 │ │ 限流重试│ │ 对象存储│ │ 数据库 │ └──────────┘ └──────────┘ └──────────┘ └────────┘ └────────┘ └────────┘ ========================== 在线链路(用户提问时) ============================== 用户问题 ─▶ 查询改写 ─▶ 权限过滤 ─▶ 向量/关键词召回 ─▶ 重排 ─▶ 组装上下文 ─▶ LLM 生成 ─▶ 引用溯源 ``` 关键认知:**离线链路的每个环节都会"固化"成线上检索的边界**:没解析出来的内容永远召不回来,没打的权限标签永远无法过滤。 ### Q:一条合格的数据流水线要保证哪些性质? A:结论先行——**至少保证五个性质:可重放(幂等)、可增量(不必全量重跑)、可溯源(每个分块能追到原文位置)、可删除(源端删了库里也要删)、可观测(每一步都有指标)。** | 性质 | 含义 | 不满足会怎样 | |---|---|---| | 幂等 / 可重放 | 同一份输入重复跑,结果一致(用稳定 ID + 覆盖写) | 数据重复,向量库里同一文档出现多份 | | 增量 | 只处理发生变更的文档 | 每次全量重建,成本高到不敢跑 | | 可溯源 | 分块 →(doc_id, page, offset)的映射 | 无法引用、无法定位原文、无法追责 | | 可删除 | 源端删除或权限收回能传导到向量库 | 数据"泄漏式残留",合规风险 | | 可观测 | 各阶段成功率、耗时、缺页率 | 效果变差时不知道是哪一环坏了 | ## 二、文档解析 ### Q:PDF 为什么难解析?文本层、扫描件、表格、多栏分别怎么处理? A:结论先行——**因为 PDF 本质是"打印描述语言"而不是"文档结构格式":它记录的是"在坐标 (X, Y) 处画这些字符",不保证阅读顺序、不保证段落、不保证表格结构。所以"PDF 解析"本质上是一个逆向工程问题,不同类型必须用不同方法。** 不同 PDF 类型与对应策略: | PDF 类型 | 特征 | 首选方法 | 注意事项 | |---|---|---|---| | **原生文本层 PDF** | 可直接选中文本 | 文本抽取库(PyMuPDF 等)按坐标重排 | 需处理多栏、页眉页脚、跨页表格 | | **扫描件 PDF** | 页面本质是图片 | OCR(PaddleOCR / Tesseract 等) | 质量取决于扫描分辨率与倾斜度,需先做版面分析 | | **混合型** | 部分页有文本层,部分是扫描 | 逐页判断,分别走文本抽取或 OCR | 常见于"电子版正文 + 扫描附件"拼接 | | **表格密集** | 财务报表、参数表 | 专用表格抽取(camelot / tabula 类)或文档理解模型 | 复杂合并单元格容易丢结构 | | **多栏排版** | 论文、报刊 | 先做版面分析判断分栏,再按栏抽取 | 不做版面分析会串行,读起来完全错乱 | | **图文混排** | 含流程图、公式 | 文本与图片说明分离,公式需专门处理 | 图内文字丢失会导致上下文断裂 |  *图:PDF 解析决策树:按文本 / 表格 / 多栏分流* ```text PDF 解析决策树 拿到一个 PDF ├── 每页能否抽取到足够文本? │ ├── 能 → 原生文本层 → 版面分析(分栏 / 阅读顺序)→ 抽取 │ └── 不能 → 扫描件 → 图像预处理(去噪 / 纠偏 / 二值化)→ OCR → 后处理 ├── 是否含表格?→ 是 → 表格检测 → 结构化抽取 → 转 Markdown / HTML └── 是否含多栏?→ 是 → 分栏检测 → 按栏顺序拼接 ``` 工具选型思路(**具体能力与可用性需结合实际版本验证**): - **底层文本抽取**:PyMuPDF(速度快、坐标信息友好)、pdfplumber(表格与字符级信息友好)、pypdf(纯 Python、轻量)。 - **版面分析与文档理解模型**:复杂版面与表格还原上,视觉类方案通常优于纯规则方案,但**资源消耗与部署复杂度更高**。 - **OCR**:中文场景常用 PaddleOCR,通用场景可从 Tesseract 起步。**关键指标是字准率与表格还原度**,必须人工抽检。 - **一体化解析框架**:部分开源框架把版面分析、表格、公式、OCR 串成流水线;但**务必用自己的文档集测准确率**。 ### Q:Word、PPT、HTML、Markdown 各自的难点是什么? A:结论先行——**结构化格式(Word / PPT / Markdown)的难点是"结构丰富但表达随意",网页的难点是"噪声远多于正文",Markdown 的最大优势是天然接近纯文本,但要小心代码块与表格被切碎。** | 格式 | 主要难点 | 处理要点 | |---|---|---| | **Word (.docx)** | 样式不统一;用文本框或表格排版;批注与修订;图片中的文字 | 结构化读取段落与标题样式,保留标题层级用于分块;批注单独处理 | | **PPT (.pptx)** | 单页信息碎片化;大量图形化表达;备注页常有要点 | 以"页"为单元切片,合并标题 + 正文 + 备注;图形文字需 OCR | | **HTML** | 导航、广告、推荐位噪声;JS 动态渲染 | 正文抽取(trafilatura / readability 类思路);动态页面渲染后抓取 | | **Markdown** | 代码块、表格、内联公式;层级可能混乱 | 按标题切分最自然;代码块单独成块;表格保留为结构化文本 | | **Excel / CSV** | 多 sheet、合并单元格、多行表头 | 按行或按 sheet 转成"表头 + 记录"文本;超大表抽样或只留摘要 | | **图片 / 音频** | 没有文本层 | OCR 或语音转写(ASR),保留时间戳或位置作为溯源信息 | 一条通用原则:**优先保留结构信息(标题层级、列表、表格),而不是"先拼成一大段纯文本再切"。** ## 三、清洗与规范化 ### Q:页眉页脚、乱码、断行怎么处理? A:结论先行——**这三类问题的共同特征是"单个看着小,但会大面积污染每一个分块"。处理原则是"先按跨页重复模式批量删,再按版面位置做启发式判断,最后靠人工抽检兜底"。** **(1)页眉页脚与页码** 识别思路: ```text 1. 重复性检测:同一行文本在多页相同位置(顶部/底部)反复出现 → 判为页眉页脚 2. 正则匹配:页码模式("第 X 页 / 共 Y 页"、"Page X of Y"、独立成行的纯数字) 3. 版式特征:位于页面上/下约 10%~15% 区域,且字号明显小于正文 4. 白名单保护:结合长度、字号、位置,避免误删正文中真实存在的短行 ``` 注意:**不要用"删掉首行末行"的简单做法**——会误删真正的标题与脚注,多栏排版下还会错位。 **(2)乱码与编码问题** - **来源**:PDF 嵌入字体缺失(抽出来是替换字符或方框)、编码识别错误(GBK 当 UTF-8 读)、OCR 识别错误。 - **处理**:先检测编码再解码;统计每页异常字符比例,**过高就判为"解析失败"并改用 OCR 重跑,而不是把乱码入库。** - **重要设计**:解析失败必须**显式标记并告警**,不能"入库了但内容是垃圾"。 **(3)断行与段落合并** PDF 抽取常见"每行都是独立段落"或"跨行断句": ```text 处理规则(中文与英文分别处理): 1. 行尾不是句末标点(。!?.!?;;::),且下一行不以缩进/编号/标点开头 → 判定为"换行非换段",合并为一行 2. 英文注意连字符换行:"infer-\nence" → "inference" 3. 保留真正的段落边界(空行、首行缩进、标题样式) ``` 边界与风险:**规则一定有误判。** 建议在规则后补一步"人工抽检 + 快速回归",并把清洗规则**版本化**——改了要能回答"这条数据是哪一版规则洗的",并支持对存量数据定向重跑。 ### Q:怎么去重?精确去重和近似去重分别怎么做? A:结论先行——**精确去重解决"同一个文件被反复上传"(用内容哈希),近似去重解决"同一内容被转成多个版本或多个格式"(用 SimHash / MinHash 或向量相似度)。两者都要做,顺序是先精确、后近似。** | 层级 | 方法 | 适用 | 代价 | |---|---|---|---| | 文档级精确 | 文件内容哈希(如 SHA-256) | 完全相同的文件 | 几乎为零,必做 | | 文档级近似 | SimHash / MinHash + LSH 分桶 | 高度相似(不同版本、重新排版) | 需调阈值,有误判风险 | | 段落级 | 归一化后的段落文本哈希 | 跨文档重复段落(模板、免责声明) | 简单有效 | | 语义级 | 嵌入向量近邻去重,超阈值合并 | "换个说法讲同一件事" | 成本最高,易误删有用细节 |  *图:去重流水线的五级顺序:从哈希到语义* ```text 去重流水线建议顺序 新文档 → 内容哈希查重(完全重复 → 跳过) → 归一化后哈希查重(去格式后相同 → 视为重复) → SimHash / MinHash 近邻检查(超阈值 → 人工确认或按优先级保留) → 段落级去重(剔除跨文档共享的样板段落) → 语义去重(可选,只在高价值场景做) ``` 几个坑: - **"新版本"不等于"重复"**:新旧政策文件可能 95% 相似但结论相反,**简单去重掉旧版很可能保留错误答案**。正确做法是保留最新有效版本,并给旧版打上"已失效"标记,而不是物理删除。 - **阈值按业务定**:法律、财税类"差一个字意思就变",阈值要保守;营销类可以激进。 - **保留去重日志**:记录"哪条被判为与哪条重复、依据是什么",便于审计与纠错。 ### Q:术语与标点归一为什么重要? A:结论先行——**因为检索本质上依赖字面或向量层面的匹配,同一个概念的多种写法会让召回率断崖式下降。归一化不是"美化文本",而是在给检索"铺路"。** 典型问题: | 问题 | 例子 | 影响 | |---|---|---| | 全角半角混用 | `AI` vs `AI`、`(` vs `(` | 关键词匹配失败 | | 大小写不一致 | `GPT` / `gpt` / `Gpt` | 英文检索召回下降 | | 术语别名 | "大语言模型" / "大模型" / "LLM" | 向量检索可能因语境差异而漏召回 | | 标点变体 | `、` 与 `,`、`;` 与 `;` | 分句错误 | | 空白与不可见字符 | 全角空格、零宽字符、软换行 | 分块边界错乱、哈希不稳定 | | 数字与单位 | `8GB` / `8 GB` / `8G` | 关键参数匹配失败 | 处理建议: 1. **统一 Unicode 规范化**(如 NFKC),处理全角半角与兼容字符。 2. **统一大小写策略**:英文小写化**只用于索引**,**展示与向量化保留原文**(否则会损失 `BERT` 与 `bert` 的形态信息)。 3. **维护术语同词表**:"别名 → 标准术语",既用于**查询改写**(把"大模型"扩展为"大语言模型 / LLM"),也用于入库归一。 4. **清洗不可见字符**:删除零宽字符、统一换行符、压缩连续空白。 5. **不要把归一化做成"改写正文"**:正文保持原样以便引用溯源,**归一化结果放在独立字段(如 `normalized_text`)里供检索使用**。 ## 四、分块与元数据设计 ### Q:分块策略怎么选? A:结论先行——**没有万能参数,只有"按文档结构切 + 按语义边界兜底 + 用父子块兼顾精度与上下文"的组合策略。固定长度硬切是最差的选择,但作为兜底仍然必要。** 常见策略对比: | 策略 | 做法 | 优点 | 缺点 | |---|---|---|---| | 固定长度切分 | 每 N 个 token 一刀,带重叠 | 简单、可控 | 割裂语义,标题与正文分离 | | 递归字符切分 | 按 段落 → 句号 → 逗号 的优先级递归切 | 尽量保持在语义边界 | 对无标点文本(如 OCR 结果)效果差 | | 结构切分 | 按标题层级 / 表格 / 代码块切 | 与文档结构一致,便于溯源 | 依赖解析质量 | | 语义切分 | 按句子嵌入相似度找断点 | 语义完整度高 | 计算成本高,边界不稳定 | | 父子块(Parent-Child) | 子块用于检索,命中后返回父块 | 兼顾检索精度与上下文完整 | 需要两级存储与映射 | | 分层摘要 | 对长文档做多级摘要 + 原文块 | 提升长文档召回 | 引入摘要模型的误差 | 推荐的工程组合(**参数必须按业务语料实测调优,没有通用最优值**): ```text 1. 先按文档结构切出"逻辑块"(章节 / 小节 / 表格 / 代码块) 2. 逻辑块过长:按语义边界再切(段落 → 句号 → 换行),保留少量重叠 3. 逻辑块过短:向后合并到最小长度阈值(避免出现"孤块") 4. 每个子块记录:父块 ID、字符偏移、页码、标题路径 5. 检索用子块(粒度小、相似度高),生成时用父块或相邻块(上下文完整) ``` 分块大小的取舍(**定性,不做数字断言**): - **块太小**:语义不完整、模型答不准,但定位精确;**块太大**:混入无关信息、浪费上下文窗口,但上下文完整。 - **重叠(overlap)**:解决"关键句被切断"的问题,代价是索引冗余与存储放大。 - **必须带元数据**:块 ID、父块 ID、标题路径、页码、来源、时间、权限标签。 ### Q:元数据要设计哪些字段? A:结论先行——**元数据的三个用途决定了它的字段设计:过滤(权限 / 时间 / 类型)、溯源(来源 / 位置)、治理(版本 / 状态 / 质量)。任何不能服务于这三个用途的字段都不要加。** | 字段类别 | 字段示例 | 用途 | |---|---|---| | 标识 | `doc_id`、`chunk_id`、`parent_chunk_id` | 唯一标识、父子检索、幂等更新 | | 来源 | `source_system`、`source_url`、`file_name`、`file_hash` | 溯源、去重、引用 | | 位置 | `page_no`、`char_offset`、`heading_path` | 引用定位、高亮、摘要 | | 时间 | `created_at`、`updated_at`、`effective_date`、`expire_date` | 时效过滤、失效控制 | | 权限 | `tenant_id`、`dept_id`、`acl_tags`、`sensitivity_level` | 权限过滤、越权防护 | | 类型 | `doc_type`、`language`、`has_table`、`has_image` | 检索路由、策略差异化 | | 治理 | `version`、`status`(有效 / 失效 / 草稿)、`quality_score` | 版本管理、灰度、质量筛选 | | 向量相关 | `embedding_model`、`embedding_version`、`chunk_strategy_version` | 换模型或换策略时精准重建 | 关键实践: - **`embedding_model` + `embedding_version` + `chunk_strategy_version` 是"重建开关"**:换嵌入模型或改分块策略时,按这些字段精确筛选需要重建的数据,而不是全量重跑。 - **权限标签要在入库时就打上**:检索时现算权限既慢又容易出错。 - **时间字段区分"文档时间"与"入库时间"**:政策类问题要按 `effective_date` 判断,用 `created_at` 会答错。 ## 五、增量更新 ### Q:怎么判断一个文档变了? A:结论先行——**用"多级指纹"分层检测:先比元数据(路径 + 大小 + 修改时间)快速筛选,再比内容哈希确认,最后比归一化内容哈希判断"是否属于有效变更"。**  *图:变更检测五级:路径、哈希、归一化、分块、语义* ```text 变更检测分级(成本从低到高) Level 1 路径 + 大小 + mtime → 有变化则进入 L2(快,但会误报) Level 2 文件内容哈希(SHA-256) → 相同则跳过(确认级) Level 3 归一化后文本哈希 → 只改了格式或页眉 → 视为未变,跳过 Level 4 分块级哈希(每块独立) → 定位到具体哪些块变了 Level 5 语义变更检测(可选) → 判断"改动是否影响语义" 注意:mtime 不可靠(复制、恢复备份都会改它), 所以 Level 1 只能当候选筛选,不能当结论。 ``` 实际工程里最有价值的是 **Level 4(分块级哈希)**:它让"只重算变化的那几块"成为可能,把增量成本压到最低。 ### Q:局部重建怎么做? A:结论先行——**核心是让"文档 → 分块"的映射保持稳定:只要分块策略不变,一个分块的内容哈希不变就无需重新向量化;而分块策略一变,就必须整篇重建(因为分块 ID 与边界全变了)。** ```text 增量重建流程 1. 新版本文档 → 走与旧版本完全相同的解析 + 清洗 + 分块管道 2. 计算新版本每个分块的 content_hash 3. 与旧版本的分块集合做 diff: - 相同 hash → 复用旧向量(不调用嵌入模型) - 新增 hash → 只需向量化这些块 - 消失的 hash → 从向量库中删除 4. 用稳定 ID(如 hash(doc_id + chunk_index + strategy_version))做 upsert 5. 更新文档级版本号与 updated_at ``` 关键点与边界: - **分块顺序变化会导致序号变化**:`chunk_id` 里含序号时,中间插入一段内容会让后面所有分块 ID 都变,"局部重建"退化成"全量重建"。**解决办法是用内容哈希做主键,序号只作排序字段。** - **分块策略版本化是硬要求**:`strategy_version` 一变就必须全量重建,不要试图"打补丁",那会让数据变得不可解释。 - **重嵌入成本要提前预估**:换嵌入模型通常等于全量重嵌入,必须规划窗口期与限流。 ### Q:删除与失效怎么同步到向量库? A:结论先行——**删除是最容易被忽略、也最危险的一环:源端删了、库里还在,检索就会给出"已经不存在的答案"。必须把"删除"当作流水线的一等公民,与写入同等对待。**  *图:删除与失效的三种来源及对应处理* ```text 删除 / 失效的三种来源与处理 1. 源端物理删除 → 通过"全量扫描比对"或"源端事件通知"发现 → 按 doc_id 删除该文档的所有分块(向量库 + 元数据库 + 对象存储) 2. 内容被替换(新版本) → 增量 diff 得到"消失的分块"集合 → 按 chunk_id 精确删除旧块(不是整篇删再整篇插) 3. 权限回收或过期 → 不删除内容,但更新元数据:status=失效、acl_tags 收紧、生效期结束 → 检索侧通过元数据过滤自动排除 设计要点 - 必须有"孤儿数据巡检":定期比对源端清单与向量库清单, 找出"库里存在但源端已无"的文档并清理。 - 删除要幂等,并有审计日志(谁删的、何时、依据)。 - 软删除(标记 status)优先于物理删除,便于回溯与误删恢复。 ``` **常见事故**:只做"新增 / 更新",没做"删除"。运行半年后,库里堆满已废止的制度与已删除的文档,模型还会"自信"地引用它们——这比召不回来更可怕。 ## 六、多租户与权限 ### Q:权限过滤应该在哪一层做? A:结论先行——**必须在检索层(向量库或搜索引擎)做服务端强制过滤,绝不能只在应用层"过滤结果",也绝不能依赖"在提示词里告诉模型别看敏感内容"。**  *图:权限过滤:错误做法会越权,正确做法纵深防御* ```text 错误做法(会越权) 检索 Top-K → 应用层剔除没权限的 → 送给模型 ✗ 没权限的内容已经被召回,可能已进入日志或缓存 正确做法(纵深防御) 查询请求(带 tenant_id / user_id) → 服务端强制注入过滤条件(不由客户端传入) → 向量库元数据过滤:tenant_id = X AND acl 命中用户权限集合 → 只召回有权内容 → 再重排 → 组装上下文 再做一层:应用层对最终上下文二次校验(防御性复核) ``` 三条铁律: 1. **过滤条件由服务端根据登录态推导,客户端传入的一律不信任**(防参数伪造越权)。 2. **过滤必须在"召回前"生效(pre-filter)**,而不是召回后再丢弃(post-filter)——后者既浪费性能,又容易从引用、日志、缓存等旁路泄漏。 3. **没有权限标签的文档默认"不对外可见"(默认拒绝)**,而不是默认可见。 ### Q:向量库的元数据过滤怎么用才不会踩性能坑? A:结论先行——**过滤条件的"选择性"决定性能:能命中少量数据的条件(如 tenant_id)应该用分区或独立集合做物理隔离,而不是走通用过滤;过滤后候选集太小时,近似最近邻索引可能退化成低效扫描。**  *图:按维度强弱选过滤策略:物理隔离还是元数据过滤* ```text 过滤策略选择 ├── 强隔离维度(租户 / 业务线):用【独立集合 / 分区】物理隔离 │ 优点:性能好、安全性高;代价:集合数量膨胀,需要管理上限 ├── 中等选择维度(部门 / 文档类型):用元数据过滤 │ ⚠ 注意过滤后的候选比例,过低时考虑把条件下沉到分区 └── 高选择性维度(时间 / 标签):元数据过滤即可 ``` 关键点(**各向量库实现差异较大,具体参数与限制需结合所选产品与版本确认**): - **pre-filter 与 post-filter**:优先选择支持"先过滤后检索"的实现;部分系统在过滤条件过严时会退化为暴力扫描。 - **不要用高基数字段做过滤**:像"文档标题"这类几乎唯一的字段做过滤毫无意义。 - **过滤字段要建标量索引**:多数向量库需要显式为元数据过滤字段建索引才能高效过滤。 - **分区数量有上限**:按租户建集合或分区时,要预估租户规模,避免"几千个集合"的管理灾难。 ### Q:越权检索有哪些常见漏洞? A:结论先行——**越权往往不是"完全没做过滤",而是"过滤链路上某个环节被绕过":缓存、引用链接、日志、重排服务、异步任务都可能成为泄漏点。** | 漏洞点 | 场景 | 防护 | |---|---|---| | 客户端传权限参数 | 前端传 `tenant_id`,被篡改成别人的 | 服务端从登录态推导,忽略客户端参数 | | 缓存未按租户隔离 | 缓存 key 只有 query,没带租户 | 缓存 key 必须含租户或权限指纹 | | 引用链接直连原文 | 点击引用能下载无权文档 | 引用下载也走鉴权代理,不暴露原始地址 | | 重排 / 日志服务无过滤 | 重排服务拿到全量候选 | 统一在检索入口过滤,下游只接触已过滤数据 | | 异步任务越权 | 离线任务用管理员权限拉全量 | 任务按租户切分,产出物也带权限标签 | | 权限变更未回溯 | 用户调岗后旧权限仍生效 | 权限标签支持动态属性,或缩短刷新周期 | | 默认可见 | 新文档没打标 → 全员可见 | 默认拒绝 + 入库校验(无标签不允许入库) | 一条实用建议:**给向量库的查询接口做一层"唯一入口"封装,禁止业务代码直接拼过滤条件**,把权限注入逻辑固化在这一层,避免"某个新模块忘了加过滤"。 ## 七、数据质量评估 ### Q:用哪些指标衡量数据质量? A:结论先行——**把数据质量拆成两类:管道健康度(解析成功率、缺失率、时效性)和检索有效性(命中率、引用正确率、人工抽检通过率)。前者是你能直接控制的,后者是最终目的。** | 指标 | 定义 | 说明 | |---|---|---| | 解析成功率 | 成功解析的文档数 / 总文档数 | 低于阈值按文件类型下钻 | | 乱码率 | 含异常替换字符的分块占比 | 高则字体或编码有问题 | | 空块率 | 内容长度异常的分块占比 | 常见于扫描件解析失败 | | 缺页 / 缺表格率 | 页面或表格未被抽取的比例 | 与源文档页码数比对 | | 时效性 | 有效期内文档占比、最旧文档年龄 | 过期文档仍被召回要告警 | | 去重率 | 被判为重复的文档与分块占比 | 异常高说明采集源有重复 | | 覆盖率 | 向量库中文档数 / 源端应有文档数 | 反映增量同步是否漏数据 | | 孤儿率 | 库中存在但源端已无的占比 | 反映删除同步是否失效 | | **召回命中率** | 正确文档进入 Top-K 的比例 | 端到端最关键的指标 | | **引用正确率** | 模型引用的内容确实支持其结论的比例 | 直接关系"可信度" | | 人工抽检通过率 | 抽样分块的可读性与准确性评分 | 兜底的质量标准 | **注意区分"数据指标"与"效果指标"**:解析成功率 99% 不代表检索效果好(那 1% 可能恰好是最重要的文档);召回命中率高也不代表回答正确(可能是模型没用好上下文)。 ### Q:人工抽检怎么做才有效? A:结论先行——**抽检要"分层抽样 + 固定评分卡 + 结果回流到规则",否则很容易变成走过场。** ```text 抽检设计 1. 分层抽样(不要在全量里随机抽) - 按文件类型:PDF / 扫描件 / Word / PPT / HTML 各抽 - 按页面特征:含表格页、含图页、多栏页 - 按解析置信度:优先抽"低置信度、高乱码率"的样本 2. 评分卡(每项 0~2 分,标准写清楚) - 内容完整性 · 阅读顺序 · 噪声水平 · 分块质量 · 元数据正确性 3. 结果回流 - 不合格样本 → 定位规则 → 加规则 / 改规则 → 重跑并复检 - 记录每轮通过率,作为管道版本的质量基线 ``` 实践要点:**抽检要"小批量、高频次"**(如每周 20 个样本),比"一年一次抽 500 个"有效;**抽检样本要沉淀成回归集**,每次改清洗或分块规则都跑一遍。 ## 八、一条完整的离线数据流水线 ### 整体流程图  *图:离线数据流水线——采集、解析、清洗、分块、向量化与增量同步* ```text ┌───────────────────────────────────────────────────────────────────────────────┐ │ 离线数据流水线(Offline Ingestion) │ └───────────────────────────────────────────────────────────────────────────────┘ ① 采集 ② 解析 ③ 清洗 ④ 分块 ⑤ 向量化 ┌────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ ┌──────────┐ │ 文件系统 │ │ 格式识别 │ │ 页眉页脚清除 │ │ 结构切分 │ │ 批量嵌入 │ │ 网盘 │─────▶│ 文本层判断 │───▶│ 编码归一 │──▶│ 语义边界 │──▶│ 限流重试 │ │ 知识库 │ │ 版面分析 │ │ 断行合并 │ │ 父子块 │ │ 失败隔离 │ │ 数据库 │ │ OCR / 表格抽取 │ │ 去重 │ │ 元数据注入 │ │ 幂等记录 │ └────────┘ └──────────────┘ └──────────────┘ └────────────┘ └──────────┘ │ │ │ │ │ │ ▼ ▼ ▼ ▼ │ ┌────────────────────────────────────────────────────────────┐ │ │ 统一任务队列 / 工作流编排:幂等 · 可重试 · 有指标 · 可断点续跑 │ │ └────────────────────────────────────────────────────────────┘ │ │ ▼ ▼ ┌──────────────┐ ┌────────────────────────────────────────┐ │ 变更检测 │ │ ⑥ 入库:向量库(upsert / delete) │ │ - 元数据指纹 │ │ + 元数据库(结构化字段、版本) │ │ - 内容哈希 │◀──────────────────▶│ + 对象存储(原文、图片,供引用) │ │ - 分块哈希 │ └────────────────────────────────────────┘ └──────────────┘ │ ▲ ▼ ┌──────────────┐ ┌────────────────────────────────────────┐ │ ⑦ 增量同步 │◀──────────────────│ ⑦ 巡检与质量评估 │ │ - 删除 / 失效 │ │ 孤儿巡检 · 缺失比对 · 抽检 · 指标看板 │ │ - 权限变更 │ └────────────────────────────────────────┘ │ - 版本切换 │ └──────────────┘ ``` ### 各阶段代码要点(伪代码级别,重点说明"关键设计"而非可直接运行的完整实现) **① 采集与变更检测** ```python import hashlib from pathlib import Path def content_hash(path: Path) -> str: """流式计算文件哈希,避免把大文件整体读进内存""" h = hashlib.sha256() with path.open("rb") as f: for block in iter(lambda: f.read(1024 * 1024), b""): h.update(block) return h.hexdigest() def should_reprocess(record: dict, path: Path) -> bool: """多级指纹:先用轻量元数据筛,再用内容哈希确认""" stat = path.stat() if (record["size"] == stat.st_size and record["mtime"] == stat.st_mtime): return False # 快速路径:完全没动过 return content_hash(path) != record.get("hash") # 确认级判断 ``` 要点:**轻量筛选 + 确认级检测两级配合**;`mtime` 只能当候选信号不能当结论;文档量大时 `stat` 遍历本身就是成本。 **② 解析(文本层判断 + OCR 降级)** ```python def parse_pdf(path: Path) -> dict: """返回 {'blocks': [...], 'status': 'ok' | 'ocr' | 'failed'}""" pages = extract_text_pages(path) # 底层抽取,保留每页坐标信息 blocks, ocr_pages = [], [] for page in pages: text = page.text.strip() if len(text) < MIN_TEXT_CHARS: # 文本过少 → 疑似扫描页 ocr_pages.append(page.no) continue blocks.extend(reorder_reading_order(page)) # 按阅读顺序重排(处理多栏) if ocr_pages: blocks.extend(run_ocr(path, pages=ocr_pages)) return {"blocks": blocks, "status": "ok" if blocks else "failed", "ocr_pages": ocr_pages} ``` 要点:**"文本过少"的阈值要按文档类型调整**(目录页、封面页天然文本少);`status="failed"` 必须**显式落库并告警**,不能静默入库。 **③ 清洗(页眉页脚 + 断行)** ```python import re PAGE_NUM_PATTERNS = [ re.compile(r"^\s*第\s*\d+\s*页\s*(/\s*共?\s*\d+\s*页)?\s*$"), re.compile(r"^\s*Page\s+\d+\s+(of|/)\s+\d+\s*$", re.IGNORECASE), re.compile(r"^\s*[-—]?\s*\d+\s*[-—]?\s*$"), ] def detect_repeated_margins(pages, top_ratio=0.12, bottom_ratio=0.12): """跨页重复出现在顶部/底部的文本 → 判为页眉页脚""" counter = {} for page in pages: h = page.height for line in page.lines: if line.top < h * top_ratio or line.bottom > h * (1 - bottom_ratio): key = normalize(line.text) counter[key] = counter.get(key, 0) + 1 return {k for k, v in counter.items() if v >= max(3, len(pages) // 3)} def merge_broken_lines(text: str) -> str: """行尾没有句末标点 → 视为换行非换段,合并到上一行""" out = [] for ln in (line.strip() for line in text.splitlines()): if not ln: out.append("") # 保留空行作为段落边界 continue if (out and out[-1] and not re.search(r"[。!?.!?;;::]$", out[-1]) and not re.match(r"^[\-*\d((]", ln)): out[-1] += ln else: out.append(ln) return "\n".join(out) ``` 要点:**重复性阈值用"出现页数比例"而不是绝对值**;断行规则是启发式的,**必须配人工抽检**;中英文句末标点集合分别维护。 **④ 分块与元数据注入** ```python def split_document(doc: dict, strategy_version: str) -> list[dict]: chunks = [] for section in iter_sections(doc["blocks"]): # 按标题层级切出逻辑块 for piece in split_by_semantic_boundary( section.text, max_chars=MAX_CHARS, overlap=OVERLAP): content = piece.strip() if len(content) < MIN_CHARS: continue # 丢弃孤块 chunks.append({ "chunk_id": stable_id(doc["doc_id"], content, strategy_version), "doc_id": doc["doc_id"], "content": content, "heading_path": section.heading_path, "page_no": piece.page_no, "char_offset": piece.offset, "version": doc["version"], "status": "active", "acl_tags": doc["acl_tags"], # 权限标签强制继承文档级标签 "strategy_version": strategy_version, "updated_at": doc["updated_at"], }) return chunks ``` 要点:`chunk_id` 由 `doc_id + 内容哈希 + 策略版本` 决定(**不含序号**),插入内容不会让后续分块 ID 全变;`acl_tags` 必须**从文档继承**。 **⑤ 向量化(批量 + 重试 + 幂等)** ```python def embed_chunks(chunks: list[dict], existing: dict[str, list[float]], embed_fn) -> tuple[list[dict], dict]: """existing: chunk_id -> 旧向量,用于复用未变化分块的向量""" todo = [c for c in chunks if c["chunk_id"] not in existing] vectors = {} for batch in batched(todo, BATCH_SIZE): try: vecs = embed_fn([c["content"] for c in batch]) # 批量调用,注意限流 except RateLimitError: backoff_sleep() retry_batch(batch) # 限流退避重试 continue except Exception as e: log_failed(batch, e) # 失败隔离,不阻塞整批 continue for c, v in zip(batch, vecs): vectors[c["chunk_id"]] = v return todo, vectors ``` 要点:**这是增量里最省钱的一步**——只对 `chunk_id` 变化的分块调用嵌入模型;批量大小按嵌入服务的限流能力适配;**失败隔离到单个分块**,避免一个坏块卡住整篇文档。 **⑥ 入库(upsert + delete)** ```python def sync_to_store(doc_id: str, new_chunks: list[dict], old_chunk_ids: set[str], store): new_ids = {c["chunk_id"] for c in new_chunks} to_delete = old_chunk_ids - new_ids # 旧版本中已消失的分块 to_upsert = new_chunks # 新增分块(未变化分块复用旧向量) if to_upsert: store.upsert(to_upsert, vectors=...) # upsert 保证幂等 if to_delete: store.delete(filter={"doc_id": doc_id}, ids=list(to_delete)) store.update_doc_meta(doc_id, { # 更新文档级元数据 "chunk_count": len(new_chunks), "status": "active", }) ``` 要点:**先 upsert 后 delete 更安全**,避免出现"检索不到"的中间态;`upsert` 是幂等的关键;删除只删"消失的分块",而不是整篇重插。 **⑦ 增量同步与巡检** ```python def reconcile(source_docs: dict[str, dict], store): """孤儿数据巡检:库里有、源端没有 → 清理或标记失效""" for doc_id, meta in store.iter_docs(): src = source_docs.get(doc_id) if src is None: store.delete_doc(doc_id) # 源端已物理删除 audit_log("orphan_removed", doc_id) elif src["status"] != "active" and meta["status"] == "active": store.mark_inactive(doc_id) # 失效或权限回收 audit_log("marked_inactive", doc_id, src.get("reason")) ``` 要点:**巡检必须定时跑**(解析失败、任务中断、事件丢失都会造成数据不一致);**删除要有审计日志**;优先软删除(标记失效)而非物理删除。 ## 九、工程实践与踩坑清单 | 症状 | 根因 | 处理 | |---|---|---| | 扫描件召回率接近 0 | 文本层为空但未走 OCR 降级 | 加 OCR 降级;低文本量页强制 OCR | | OCR 结果错字多 | 分辨率低、页面倾斜、印章遮挡 | 图像预处理(纠偏 / 去噪 / 放大);更换 OCR 模型;标注噪声 | | 表格内容丢失或错位 | 只抽文本层,没做表格结构抽取 | 引入表格抽取;表格转 Markdown;保留行列语义 | | 多栏文档读起来串行 | 未做版面分析,按文本流直接拼 | 版面分析 + 按栏抽取 | | 页眉页脚出现在每条回答里 | 清洗规则缺失 | 跨页重复检测 + 正则清洗 | | 同一文档进了很多份 | 只按文件名判重 | 内容哈希去重;文档级 + 段落级去重 | | 旧政策仍被引用 | 版本管理缺失或删除未同步 | 补 `effective_date` / `status` 并做检索过滤;软删除旧版 | | 已删除的文档还能被检索到 | 删除未同步到向量库 | 把删除当一等公民;定期执行 reconcile | | 换了嵌入模型后效果混乱 | 库里新旧向量混用 | 按版本维度全量重建;检索侧限定同一版本 | | A 部门用户搜到 B 部门文档 | 过滤在应用层或权限未打标 | 服务端强制 pre-filter;默认拒绝;无标签不允许入库 | | 加了过滤后召回变差 | 过滤条件过严或索引退化 | 强隔离维度改用分区;为过滤字段建标量索引 | | 上下文里塞了一堆无关内容 | 分块太大或元数据缺失无法过滤 | 调小分块 + 父子块;补元数据支持过滤 | | 引用点不进去、定位不到 | 未记录页码与字符偏移 | 必须记录 `page_no` 与 `char_offset` | | 增量跑一次比全量还慢 | 分块 ID 含序号导致全量重算 | 改用内容哈希做主键;把复用率做成指标 | | 效果突然下降但没人改代码 | 上游文档源悄悄变了 | 数据管道也要做"变更告警"与质量基线 | 几条最值得记住的经验: 1. **"解析失败"必须是显式状态**:宁可进"待处理队列",也不要让垃圾内容悄悄入库——垃圾入库后极难发现、极难清理。 2. **原文要留底**:向量库只存分块,但**必须保留原始文件与解析中间结果**,否则发现解析错误后还得重新找源文件。 3. **清洗规则要版本化**:规则改了要能回答"这条数据是用哪一版规则洗的",并能定向重跑。 4. **权限标签默认拒绝**:无法确定权限的数据源宁可不入库,也不要"先默认公开"。 5. **删除与失效与写入同等重视**:知识库的"正确性",很大一部分取决于"不该在的东西在不在"。 6. **用真实文档集验收**:任何解析或分块方案都要在你自己的语料上抽检,官方 Demo 与论文指标参考价值有限。 ## 小结 - **认知**:RAG 效果的第一决定因素是数据质量,而不是检索算法;离线链路的每个缺陷都会固化成线上检索的边界。 - **解析**:PDF 按文本层 / 扫描件 / 表格 / 多栏分别处理;结构化格式优先保留结构;解析失败一律显式标记。 - **清洗**:页眉页脚按跨页重复检测,乱码按异常字符率判失败,断行按标点规则合并;去重先精确后近似;归一化结果放独立字段。 - **分块与元数据**:按结构切 + 语义边界兜底 + 父子块;元数据服务于"过滤、溯源、治理"三件事。 - **增量**:多级指纹检测变更,分块哈希实现局部重建,删除与失效必须同步;`chunk_id` 用内容哈希而非序号。 - **权限**:服务端强制 pre-filter、默认拒绝、缓存与引用链路一并隔离。 - **质量**:管道健康度(解析成功率、缺失率、时效)+ 效果指标(命中率、引用正确率)+ 人工抽检回流规则。 ## 思考题 1. 你手上有一批 5 年前的扫描版制度文档(清晰度差、可能有水印),请设计解析方案,并说明你会用什么指标判断"这批数据能不能用"。 2. 为什么建议用"内容哈希"而不是"序号"作为分块主键?请举一个"用序号会导致全量重建"的具体场景。 3. 同一份政策文档有 2022 与 2024 两个版本,内容 95% 相似。去重策略应该怎么设计,才能既避免重复又不丢失正确版本? 4. 如果"过滤必须在召回前生效",那么在一个不支持 pre-filter 的向量库上,你会怎么设计架构来同时兜住性能与安全? 5. 请设计一套"数据管道质量看板",列出你会放哪些指标、阈值怎么定、异常时如何快速定位到具体阶段。
预览
发布文章
添加摘要让读者更快了解文章内容
取消
确认发布
AI 写作助手
输入一个主题,AI 将为你生成一篇 Markdown 博客文章
AI 正在写作中...
取消
开始生成
AI 优化助手
描述你的修改需求,AI 将在原文基础上进行补充或微调
AI 正在优化中...
取消
开始优化
画布
从已有图里选
✕
图名
保存后生成 /images/excalidraw/<图名>.svg(只能用字母、数字、短横线、下划线、点)
取消
保存并插入