本篇目标与适用场景

在 OpenClaw 的实际项目里，“模型/流程跑不起来”往往不是算法问题，而是数据预处理没做扎实：脏数据导致解析失败、重复数据造成训练偏置、格式不统一让字段映射对不上、以及编码/时间/单位混乱让统计结果失真。本篇围绕 OpenClaw数据预处理：清洗、去重、格式转换与字段映射，给出可直接照做的步骤、规则与示例。

你将完成一条稳定的预处理流水线：
1) 数据验收与质量画像 → 2) 清洗（缺失/异常/噪声/编码）→ 3) 去重（精确/近似）→ 4) 格式转换（CSV/JSONL/Parquet/文本）→ 5) 字段映射（source→OpenClaw schema）→ 6) 导出与回归检查。

系列背景提示：本篇属于《OpenClaw教程：从入门到实战的分层学习路线》中的“数据层”实操环节，默认你将数据交给后续的 OpenClaw 采集/索引/训练或任务编排模块使用。

一、预处理原则：先定义“目标schema”和质量红线

在动手清洗之前，先确定 OpenClaw 侧要消费的数据结构（schema）。即使你还没完全确定最终字段，也至少要明确：

• 主键/唯一标识：例如 doc_id 或 item_id，用于去重与增量导入。
• 核心内容字段：例如 title、content/text、url、created_at。
• 业务标签字段：例如 category、source、lang。

• 质量红线（建议写成规则）：

  • text 为空直接丢弃
  • text 长度 < 20 视为噪声
  • created_at 必须可解析成 ISO-8601
  • url 非法则置空或剔除

建议的“中间层统一schema”（示例）

在进入 OpenClaw 之前，先统一成一个稳定的中间格式（推荐 JSONL 或 Parquet）：

• doc_id: string（稳定、可复现）
• title: string
• text: string（纯文本，或 Markdown 文本）
• source: string（站点/系统名）
• url: string
• lang: string（如 zh, en）
• created_at: string（ISO-8601）
• updated_at: string（ISO-8601，可选）
• tags: array[string]（可选）
• meta: object（原始字段备份、扩展信息）

有了统一schema，清洗与映射的目标才明确：所有来源数据都要“对齐”到它。

二、数据验收：先做质量画像（Profiling）再清洗

无论数据来自爬虫、数据库导出、还是第三方供应商，先做三类统计：

1）结构统计

• 文件数、行数（记录数）
• 列数（字段数）、字段类型猜测（string/int/datetime）
• 每列缺失率、空字符串比例

2）内容统计

• text 字符长度分布（P50/P90/P99）
• 非法字符比例（控制字符、乱码）
• HTML 标签占比（决定是否需要抽取正文）

3）唯一性统计

• 候选主键的唯一率（如 url、id）
• 近似重复比例（标题相同、内容相似）

建议：验收结果写入 data_profile.json，形成可回归的“质量基线”。每次改清洗规则后都对比基线，避免误删。

三、清洗：缺失、异常、噪声与编码（可直接落地的规则）

清洗目标不是“把数据弄得很干净”，而是让数据 可解析、可对齐、可追溯。

3.1 缺失值处理：分字段策略

不要“一律填充”。按字段重要性分层：

• 硬性必填（缺失即丢弃）：text（或 content）、doc_id（无法生成则丢）
• 建议必填（缺失则尝试补全）：title（可从首段提取/截取），created_at（可用抓取时间兜底）
• 可选字段：tags、updated_at、meta

示例规则：title 补全

• 若 title 为空：取 text 前 30~60 个字符作为标题（去掉换行与多空格）

3.2 异常值处理：时间、数值、URL

时间字段（created_at）常见问题：

• 2024/1/2、2024-01-02 8:3:1、1700000000（秒级时间戳）混用

处理建议：
1) 尝试多格式解析
2) 时间戳统一转 ISO-8601（UTC 或明确时区）
3) 解析失败：若有采集时间用采集时间兜底，否则置空并标记 meta.time_parse_failed=true

URL 字段：

• 不以 http(s):// 开头的补协议（若能确定域名）
• 明显非法（空格、控制字符、无域名）直接置空

3.3 噪声清理：HTML、脚本、导航、模板段

如果原始内容是 HTML 或混杂大量模板，建议使用“分层清理”：

1) 去脚本/样式：移除 <script>, <style>
2) 抽取正文：优先使用正文抽取（如 Readability 类算法）
3) 保留结构但去噪：将 <p>, <h1> 转为换行，列表转为 -
4) 清理导航模板：例如“上一篇/下一篇/版权声明/联系我们”可用黑名单短语匹配删除

示例：模板噪声短语（可配置）

• “版权所有”
• “免责声明”
• “上一篇” “下一篇”
• “返回顶部”

3.4 文本规范化：空白、换行、全半角与控制字符

推荐最小但有效的一组规范化：

• 多空格合并为单空格
• 连续 3 个以上空行压缩为 1 个空行
• 移除控制字符（如 \u0000）
• 统一换行符为 \n
• 全角空格替换为半角空格

注意：不要随意把全角标点都替换掉，中文语料会损失信息。保持“可读性与一致性”即可。

3.5 编码与乱码：确保 UTF-8 输出

常见坑：CSV/文本文件为 GBK/GB2312/Big5，导致读入后乱码。

落地建议：

• 入库/中间层文件统一 UTF-8
• 读入时做编码探测；探测不准时以“可配置的默认编码”兜底
• 对疑似乱码（大量 �）的记录打标并人工抽样复核

四、去重：精确去重 + 近似去重（建议两段式）

在 OpenClaw 任务里，去重决定了后续检索/训练是否偏向某些重复样本。建议两段式：先精确再近似。

4.1 精确去重：用稳定主键或内容哈希

优先级建议：
1) 若有稳定业务ID：用 source + id
2) 若有 URL：对 URL 做规范化（去 fragment、排序 query 可选）后作为主键
3) 否则：用 normalized_text 的哈希作为主键

URL 规范化建议：

• 去掉 #xxx
• 移除常见追踪参数：utm_*, spm, from 等
• query 参数排序（可选，取决于业务）

文本哈希建议：

• 先做轻量 normalize（空白、换行、大小写对英文）
• 再计算 sha1/xxhash

4.2 近似去重：处理“改写/镜像/轻微差异”

近似重复常见来源：

• 同一新闻被多个站点转载（只改标题或加一段来源）
• 同一文档有多个版本（仅日期或页脚不同）

实用方案（从易到难）：
1) 标题相同 + 文本长度相近：快速过滤
2) SimHash：对文本生成指纹，汉明距离阈值（如 ≤ 3/64）视为重复
3) MinHash + LSH：适用于超大规模去重

落地建议：

• 近似去重不要“全删”，建议保留一条主版本，其余作为 meta.duplicates=[...] 或写入单独的 duplicates 文件，便于追溯。

五、格式转换：把来源数据变成可稳定消费的 JSONL/Parquet

OpenClaw 的上游数据来源可能是：CSV、Excel、数据库导出 JSON、网页抓取 HTML、甚至 PDF/OCR 文本。建议在预处理阶段统一落盘为：

• JSONL：一行一个文档，便于流式处理、增量导入、调试
• Parquet：适合大规模分析与压缩存储

5.1 CSV/Excel → JSONL（注意分隔符与引号）

常见坑：

• CSV 内嵌换行导致行错位
• 分隔符不是逗号而是 \t 或 ;
• 引号转义不规范

处理建议：

• 明确指定 delimiter/quotechar/escapechar
• 对“字段数不一致”的行写入 bad_rows.log 并跳过或修复
• 统一输出为 JSONL，每条记录附带 meta.raw_row_number

5.2 HTML → 纯文本/Markdown

如果 OpenClaw 下游是检索或问答，建议把 HTML 转为“可阅读的纯文本或轻量 Markdown”。

处理要点：

• 保留标题层级（h1/h2/h3）为 Markdown 标题
• 列表保留 -
• 表格可转为 TSV 或简化为段落（取决于检索需求）

5.3 PDF/OCR → 文本（额外的质量门槛）

PDF/OCR 常见问题：

• 页眉页脚重复
• 多栏错序
• OCR 错字

实操建议：

• 页眉页脚用“重复行检测”删除（同一行在多数页面出现）
• 按段落重排，必要时保留页码信息进 meta.pages
• OCR 置信度低的文档标记 meta.ocr_low_confidence=true，避免混入高质量语料

六、字段映射：从 source fields 对齐到 OpenClaw schema

字段映射是“让不同来源数据讲同一种语言”。建议使用可配置映射表（YAML/JSON）来驱动，而不是写死在代码里。

6.1 常见映射关系（示例）

来源 A（爬虫）可能是：

• page_title → title
• main_content → text
• publish_time → created_at
• site_name → source

来源 B（数据库导出）可能是：

• subject → title
• body → text
• ctime → created_at
• labels → tags

映射后的统一输出字段必须一致：title/text/source/url/created_at/...

6.2 映射时要处理的三类冲突

1) 同义字段冲突：content 与 body 同时存在

• 规则：优先取更“正文抽取后”的字段；把另一个放入 meta.alt_text

2) 类型冲突：tags 有时是字符串“a,b,c”，有时是数组

• 规则：统一转 array[string]，分隔符可配置

3) 单位冲突：阅读量 pv 有的为字符串“1.2万”

• 规则：统一转数值并保留原始值 meta.raw_pv

6.3 推荐的映射配置格式（示例思路）

映射配置应支持：

• from：来源字段名（可多个候选）
• to：目标字段名
• transform：转换函数（时间解析、分割、拼接、正则提取）
• default：缺失默认值
• required：是否必填

这样可以把“规则”与“代码”分离，便于在系列后续的 OpenClaw 实战任务里复用。

七、建议的流水线实现方式：分层输出与可回滚

为了避免“一步到位导致不可追溯”，建议采用分层产物：

7.1 目录与文件约定

• data/raw/：原始文件（只读，不改）
• data/stage1_parsed/：解析后结构化（修复编码/分隔符）
• data/stage2_cleaned/：清洗后（缺失/异常/噪声处理）
• data/stage3_dedup/：去重后
• data/final_openclaw/：字段映射完成、可被 OpenClaw 直接消费
• logs/：坏行、解析失败、重复记录、抽样审计

7.2 每一步都要输出“统计摘要”

每个 stage 输出：

• 输入记录数、输出记录数、丢弃数
• 丢弃原因分布（如 missing_text、time_parse_failed）
• 去重命中数（精确/近似）

这样你能快速回答：

• “为什么 100 万条数据最后只剩 62 万？”
• “是清洗太严还是原始数据太差？”

八、抽样审计与回归测试：避免清洗规则误伤

预处理最大的风险不是漏掉脏数据，而是误删好数据。建议做两种审计：

8.1 抽样审计（人工可读）

• 每一步随机抽样 100 条输出成 sample_stageX.jsonl
• 同时抽样 50 条“被丢弃的记录”输出，检查丢弃理由是否合理

8.2 回归测试（自动化）

为清洗规则写一些断言式检查：

• text 非空率 ≥ 99%（最终集）
• created_at 可解析率 ≥ 98%
• 平均文本长度不应从 800 掉到 50（防止正文抽取失败）
• 重复率下降应符合预期（如从 18% 降到 3%）

当你升级规则或更换来源时，回归测试能第一时间报警。

九、一个端到端示例：从混乱 CSV 到 OpenClaw 可用 JSONL

假设你拿到一个 articles.csv，字段：

• id, page_title, html, publish_time, site, link, labels

你可以按以下步骤做：

Step 1：解析与编码修复

• 读取 CSV（指定分隔符与编码探测）
• 将每行转成结构化记录，保留 meta.raw_row_number

Step 2：HTML 正文抽取

• html → text（先去 script/style，再抽正文，再转纯文本）
• 如果抽取后 text 长度 < 20：判为噪声，丢弃并记录原因

Step 3：时间统一

• publish_time 支持多格式解析
• 统一输出 created_at=ISO-8601
• 失败则：用采集时间兜底，并标记 meta.time_fallback=true

Step 4：精确去重

• 规范化 link 作为 url
• doc_id = sha1(source + '|' + normalized_url)
• 同 doc_id 保留 created_at 最新的一条，其余写入 duplicates_exact.jsonl

Step 5：近似去重

• 对 text 做轻量 normalize
• 生成 SimHash
• 汉明距离阈值命中：保留信息更完整的一条（如 text 更长、字段更全）

Step 6：字段映射与输出

• page_title → title
• site → source
• labels（逗号分隔）→ tags 数组
• 额外：把原始 id、原始 publish_time 写入 meta

最终输出：final_openclaw/articles.jsonl，每行符合统一schema，可直接进入 OpenClaw 后续索引/训练流程。

十、常见坑清单（按优先级排雷）

1) 先去重后清洗：会导致“同一内容不同噪声形态”无法识别重复；建议先做基础清洗再去重。
2) 把所有缺失都填默认值：会让下游误判数据真实存在，建议区分必填与可选。
3) 正文抽取过度：把关键段落删掉；要配合抽样审计与长度分布回归。
4) 字段映射写死：来源变动就崩；应使用配置驱动并保留 meta 原始字段。
5) 没有坏数据隔离区：解析失败/丢弃原因不记录，出了问题无法追溯。

小结：把预处理当作可维护的“数据产品”

OpenClaw 场景下，数据预处理不是一次性的脚本，而是一条可复用、可回滚、可审计的流水线。按“验收画像 → 清洗 → 去重 → 格式转换 → 字段映射 → 回归检查”的顺序落地，你会得到稳定的、可直接供 OpenClaw 使用的高质量数据集，并为后续实战（索引构建、检索增强、训练/评测）打下基础。