DataCheck

<div align="right">

English | 中文

</div>

<div align="center">

<img src="assets/icon.png" width="128" alt="data-check icon"> <br/>

<h1>DataCheck</h1>

<h3>Multi-Dimensional Data Quality Validation<br/>with Statistical Anomaly Detection</h3>

<p><strong>多维数据质量验证框架 — 规则引擎 · 异常检测 · 分布分析 · 自动修复</strong><br/> <em>Automated quality validation for LLM training data — composable rules, IQR/Z-score anomaly detection, and auto-fix pipeline</em></p>

    <br/>    

Abstract · Problem Statement · Formal Framework · Architecture · Key Innovations · Quick Start · Quality Rules · Anomaly Detection · MCP Server · Ecosystem · References

</div>

---

Abstract

训练数据质量是模型性能的隐性瓶颈——被忽略的格式错误、隐藏的 PII 泄露、未检测的重复样本，任何一个问题都可能在下游放大为系统性偏差。现有质检方案要么是一次性脚本（不可复用），要么是重量级平台（部署成本高），且普遍缺少统计异常检测和自动修复能力。

DataCheck 提出可组合规则引擎 (composable rule engine) 驱动的数据质量验证框架：9 条内置规则覆盖完整性、有效性、隐私、一致性四个质量维度，IQR / Z-score 双方法自动检测数值和长度异常，LLM 辅助评估检查指令清晰度和回复相关性。系统实现「验证 → 检测 → 分析 → 修复 → 报告」的端到端管线，输出 Markdown / JSON / HTML 三种格式的结构化质量报告。

DataCheck implements a composable rule engine for multi-dimensional data quality validation. The system provides 9 built-in rules (required fields, format, length bounds, PII detection, garbled text, near-duplicate detection via n-gram Jaccard, language consistency), IQR/Z-score statistical anomaly detection, LLM-assisted quality evaluation, auto-fix pipeline (dedup, strip whitespace, PII redaction), and report diff for tracking quality changes over time. Exposes 11 MCP tools for AI IDE integration.

---

Problem Statement

LLM 训练数据的质量验证面临三个结构性问题：

| 根本性问题 | 形式化定义 | 现有方案局限 | DataCheck 的方法 | |:---|:---|:---|:---| | 验证碎片化<br/>Validation Fragmentation | 质量检查散落在一次性脚本中，规则不可复用 $\implies$ 跨项目重复编写 | 每个团队自建质检脚本，无标准化规则引擎 | 9 条内置规则 + YAML 自定义规则 + 4 种预设规则集（default / sft / preference / llm） | | 异常不可见<br/>Anomaly Invisibility | 分布异常隐藏在大数据集中，人工审查无法覆盖 $\implies$ $\exists x \in D: \|x - \mu\| > k\sigma$ 未被发现 | 无统计异常检测，或依赖外部工具链 | IQR / Z-score 双方法自动检测数值和长度异常值，纯 Python 无依赖 | | 反馈断裂<br/>Feedback Disconnection | 质检结果与修复动作分离，修复后无法验证改进效果 | 检查和修复是独立流程，无报告对比 | 端到端管线：验证 → 修复 → 报告对比 (diff)，量化质量改进 |

DataCheck 不是通用数据清洗工具。它专注于 LLM 训练数据的质量门禁 (quality gate)——在数据进入训练管线前，确保其完整性、有效性、隐私合规性和分布合理性。

---

Formal Framework

Quality Dimensions

数据质量定义为四维向量 $Q(D) = \langle Q_c, Q_u, Q_v, Q_a \rangle$：

| 维度 | 符号 | 度量 | 对应规则 | |:---|:---|:---|:---| | 完整性 Completeness | $Q_c$ | $1 - \lvert\{x: \exists f \in F_{\text{req}}, x.f = \emptyset\}\rvert / \lvert D\rvert$ | required_fields, non_empty | | 唯一性 Uniqueness | $Q_u$ | $1 - \lvert\text{dup}(D)\rvert / \lvert D\rvert$ | duplicate, near_duplicate | | 有效性 Validity | $Q_v$ | $1 - \lvert\{x: \neg \text{valid}(x)\}\rvert / \lvert D\rvert$ | format_valid, length_bounds, score_valid | | 合规性 Compliance | $Q_a$ | $1 - \lvert\{x: \text{pii}(x) \lor \text{garbled}(x)\}\rvert / \lvert D\rvert$ | pii_detection, garbled_text |

Composite Quality Score

综合质量分为各维度的加权和：

$$\text{Score}(D) = \frac{|\{x \in D : \text{pass}(x)\}|}{|D|} \times 100\%$$

| 通过率 | 评级 | 建议 | |:---|:---|:---| | $\geq 90\%$ | Excellent | 可直接使用 | | $\geq 70\%$ | Good | 建议修复警告 | | $\geq 50\%$ | Fair | 需要处理错误 | | $< 50\%$ | Poor | 严重质量问题 |

Statistical Anomaly Detection

IQR 方法（默认）：

$$\text{outlier}(x) \iff x < Q_1 - 1.5 \cdot \text{IQR} \;\lor\; x > Q_3 + 1.5 \cdot \text{IQR}$$

其中 $\text{IQR} = Q_3 - Q_1$（四分位距）。

Z-score 方法：

$$\text{outlier}(x) \iff \left|\frac{x - \mu}{\sigma}\right| > k, \quad k = 3$$

两种方法分别应用于数值字段（直接取值）和字符串字段（取长度），样本量 $\geq 10$ 时自动启用。

Near-Duplicate Detection

基于 n-gram Jaccard 相似度的近似重复检测：

$$J(A, B) = \frac{|G_n(A) \cap G_n(B)|}{|G_n(A) \cup G_n(B)|}$$

其中 $G_n(\cdot)$ 为 n-gram 集合。当 $J(A, B) > \theta$（默认 $\theta = 0.8$）时判定为近似重复。

---

Architecture

graph LR
    D["Data Files<br/>JSON / JSONL / CSV"] --> S["Schema<br/>(Inferred or Defined)"]
    S --> R["Rule Engine<br/>9 Rules + YAML Custom"]
    R --> A["Anomaly Detector<br/>IQR / Z-score"]
    A --> L["LLM Evaluator<br/>(Optional)"]
    L --> Rep["Quality Report<br/>MD / JSON / HTML"]
    Rep --> Fix["Auto Fix<br/>Dedup · PII · Trim"]
    Fix --> Diff["Report Diff<br/>Before vs After"]

    style R fill:#0969da,color:#fff,stroke:#0969da
    style A fill:#8b5cf6,color:#fff,stroke:#8b5cf6
    style Rep fill:#2da44e,color:#fff,stroke:#2da44e
    style Fix fill:#e5534b,color:#fff,stroke:#e5534b
    style D fill:#1a1a2e,color:#e0e0e0,stroke:#444
    style S fill:#1a1a2e,color:#e0e0e0,stroke:#444
    style L fill:#1a1a2e,color:#e0e0e0,stroke:#444
    style Diff fill:#1a1a2e,color:#e0e0e0,stroke:#444

Layered Architecture

| 层 | 模块 | 职责 | |:---|:---|:---| | Rules | rules/ | 9 条内置规则 + YAML 自定义规则 + 4 种预设规则集 | | Anomaly | anomaly.py | IQR / Z-score 双方法，数值 + 长度异常检测 | | Schema | schema.py | 自动推断字段类型、约束、必填项 | | Report | report.py | Markdown / JSON / HTML 三格式报告生成 | | Fix | fix.py | 去重 · 去空白 · PII 脱敏自动修复 | | Diff | diff.py | 两次报告对比，量化质量变化 | | LLM | llm/ | Anthropic / OpenAI 指令清晰度和回复相关性评估 | | Watch | watch.py | 文件变更自动重检，防抖机制 | | Interface | cli.py · mcp_server.py | CLI + MCP 11 工具 |

---

Key Innovations

1. Composable Rule Engine

9 条内置规则覆盖四个质量维度，可通过 YAML 自定义规则扩展，无需写 Python 代码：

| 规则 | 级别 | 说明 | |:---|:---|:---| | required_fields | Error | 必填字段检查 | | non_empty | Error | 关键字段非空检查 | | format_valid | Error | 数据类型校验 | | score_valid | Error | 评分范围有效性 | | length_bounds | Warning | 文本长度边界 | | pii_detection | Warning | 邮箱 / 手机号 / 身份证号检测 | | garbled_text | Warning | 乱码 / 异常字符检测 | | repetitive_text | Warning | 文本内过度重复检测 | | language_consistency | Info | 多语言一致性（中/英/日/韩/俄/阿拉伯/泰） |

4 种预设规则集：default（通用）、sft（SFT 数据专用）、preference（偏好数据专用）、llm（LLM 质量评估）。

<details> <summary>YAML 自定义规则</summary>

# rules.yaml
rules:
  - field: instruction
    check: min_length
    value: 10
    severity: error

  - field: response
    check: max_length
    value: 10000
    severity: warning

  - field: category
    check: enum
    values: ["qa", "chat", "code", "math"]
    severity: error

knowlyr-datacheck check data.json --rules-file rules.yaml

</details>

2. Dual-Method Statistical Anomaly Detection

IQR 和 Z-score 双方法自动检测数值和长度异常值，纯 Python 实现无外部依赖。样本量 $\geq 10$ 时自动启用。

knowlyr-datacheck check data.json    # 自动包含异常检测

| 字段类型 | 检测内容 | 方法 | |:---|:---|:---| | 数值字段 | 极端值（如 score=999） | IQR / Z-score | | 字符串字段 | 异常长/短文本 | IQR / Z-score (on length) |

3. End-to-End Quality Pipeline

验证 → 修复 → 对比，完整闭环：

# 1. 初次质检
knowlyr-datacheck check data.jsonl -o report_v1.json -f json

# 2. 自动修复（去重 + 去空白 + PII 脱敏）
knowlyr-datacheck fix data.jsonl -o fixed.jsonl --strip-pii

# 3. 再次质检
knowlyr-datacheck check fixed.jsonl -o report_v2.json -f json

# 4. 对比改进
knowlyr-datacheck diff report_v1.json report_v2.json

Watch 模式支持文件变更自动重检（防抖机制，默认 2 秒）：

knowlyr-datacheck watch ./data/ --debounce 3 --ruleset sft

4. LLM-Assisted Quality Evaluation

使用 Anthropic / OpenAI 评估指令清晰度和回复相关性——超越规则检查的语义级质量评估：

knowlyr-datacheck check data.json --ruleset llm
knowlyr-datacheck check data.json --ruleset llm --llm-provider openai

5. Schema Inference and Batch Processing

从数据文件自动推断 Schema（字段类型、约束、必填项），支持批量目录扫描：

# Schema 推断
knowlyr-datacheck infer data.jsonl -o schema.json

# 批量检查（递归扫描所有数据文件）
knowlyr-datacheck check ./data/ --pattern "*.jsonl" -o report.html -f html

# 采样检查（大数据集）
knowlyr-datacheck check data.jsonl --sample 1000

---

Quick Start

pip install knowlyr-datacheck

<details> <summary>可选依赖</summary>

pip install knowlyr-datacheck[stats]    # 统计分析 (numpy, scipy)
pip install knowlyr-datacheck[mcp]      # MCP 服务器
pip install knowlyr-datacheck[llm]      # LLM 智能检查
pip install knowlyr-datacheck[yaml]     # YAML 规则配置
pip install knowlyr-datacheck[watch]    # Watch 模式
pip install knowlyr-datacheck[all]      # 全部功能

</details>

# 基础检查（支持 JSON / JSONL / CSV）
knowlyr-datacheck check data.json

# 指定 Schema + 输出报告
knowlyr-datacheck check data.json -s schema.json -o report.md

# HTML 报告
knowlyr-datacheck check data.json -o report.html -f html

# CI 集成：设定通过率阈值
knowlyr-datacheck check data.json --threshold 0.9 --strict

# 数据修复
knowlyr-datacheck fix data.jsonl -o fixed.jsonl --strip-pii

<details> <summary>Python SDK</summary>

from datacheck import DataChecker, QualityReport

checker = DataChecker()
result = checker.check_file("data.json", schema_path="schema.json")

report = QualityReport(result)
report.print_summary()
report.save("./report.md")

</details>

<details> <summary>DataRecipe 集成</summary>

# 验证 DataRecipe 分析结果中的合成数据
knowlyr-datacheck validate ./analysis_output/my_dataset/
knowlyr-datacheck validate ./analysis_output/my_dataset/ -d custom_data.json

</details>

---

Quality Rules

<details> <summary>规则详情</summary>

| 规则 ID | 级别 | 说明 | |:---|:---|:---| | required_fields | Error | 检查必填字段是否存在 | | non_empty | Error | 检查关键字段是否为空 | | format_valid | Error | 检查数据类型是否正确 | | score_valid | Error | 检查评分范围有效性 | | length_bounds | Warning | 文本长度范围检查 | | pii_detection | Warning | 邮箱 / 手机号 / 身份证号 | | garbled_text | Warning | 乱码 / 异常字符 | | repetitive_text | Warning | 文本内过度重复 | | language_consistency | Info | 多语言一致性 |

</details>

---

Anomaly Detection

IQR / Z-score 双方法，样本量 $\geq 10$ 时自动启用：

from datacheck.anomaly import detect_anomalies

anomalies = detect_anomalies(samples)
for field, info in anomalies.items():
    print(f"{field}: {info['outlier_count']} outliers, range [{info['bounds']['lower']}, {info['bounds']['upper']}]")

---

MCP Server

{
  "mcpServers": {
    "knowlyr-datacheck": {
      "command": "uv",
      "args": ["--directory", "/path/to/data-check", "run", "python", "-m", "datacheck.mcp_server"]
    }
  }
}

| Tool | Description | |:---|:---| | check_file | 检查数据文件质量 | | check_directory | 批量检查目录 | | validate_schema | 验证 Schema 格式 | | infer_schema | 从数据推断 Schema | | detect_anomalies | 统计异常检测 | | fix_data | 自动修复（去重/去空白/PII 脱敏） | | diff_reports | 两次报告对比 | | list_rules | 列出可用规则 | | validate_recipe | 验证 DataRecipe 分析结果 | | export_report | 导出质量报告 | | llm_check | LLM 质量评估 |

---

GitHub Actions

- uses: actions/setup-python@v5
  with:
    python-version: '3.12'
- run: pip install knowlyr-datacheck
- run: knowlyr-datacheck check data.json --threshold 0.9 --strict

---

CLI Reference

<details> <summary>完整命令列表</summary>

| 命令 | 功能 | |:---|:---| | knowlyr-datacheck check <file\|dir> | 检查数据质量 | | knowlyr-datacheck check ... -s schema.json | 指定 Schema | | knowlyr-datacheck check ... -o report.md | 输出报告 | | knowlyr-datacheck check ... -f html\|json\|md | 报告格式 | | knowlyr-datacheck check ... --sample 1000 | 采样检查 | | knowlyr-datacheck check ... --threshold 0.9 | 通过率阈值 | | knowlyr-datacheck check ... --ruleset sft\|preference\|llm | 预设规则集 | | knowlyr-datacheck check ... --rules-file rules.yaml | 自定义规则 | | knowlyr-datacheck infer <file> -o schema.json | Schema 推断 | | knowlyr-datacheck fix <file> -o fixed.jsonl | 自动修复 | | knowlyr-datacheck fix ... --strip-pii | PII 脱敏 | | knowlyr-datacheck diff <v1> <v2> | 报告对比 | | knowlyr-datacheck watch <file\|dir> | Watch 模式 | | knowlyr-datacheck validate <dir> | DataRecipe 结果验证 | | knowlyr-datacheck rules | 列出所有规则 |

</details>

---

Ecosystem

<details> <summary>Architecture Diagram</summary>

graph LR
    Radar["Radar<br/>Discovery"] --> Recipe["Recipe<br/>Analysis"]
    Recipe --> Synth["Synth<br/>Generation"]
    Recipe --> Label["Label<br/>Annotation"]
    Synth --> Check["Check<br/>Quality"]
    Label --> Check
    Check --> Audit["Audit<br/>Model Audit"]
    Crew["Crew<br/>Deliberation Engine"]
    Agent["Agent<br/>RL Framework"]
    ID["ID<br/>Identity Runtime"]
    Crew -.->|能力定义| ID
    ID -.->|身份 + 记忆| Crew
    Crew -.->|轨迹 + 奖励| Agent
    Agent -.->|优化策略| Crew

    style Check fill:#0969da,color:#fff,stroke:#0969da
    style Crew fill:#2da44e,color:#fff,stroke:#2da44e
    style Agent fill:#8b5cf6,color:#fff,stroke:#8b5cf6
    style ID fill:#e5534b,color:#fff,stroke:#e5534b
    style Radar fill:#1a1a2e,color:#e0e0e0,stroke:#444
    style Recipe fill:#1a1a2e,color:#e0e0e0,stroke:#444
    style Synth fill:#1a1a2e,color:#e0e0e0,stroke:#444
    style Label fill:#1a1a2e,color:#e0e0e0,stroke:#444
    style Audit fill:#1a1a2e,color:#e0e0e0,stroke:#444

</details>

| Layer | Project | Description | Repo | |:---|:---|:---|:---| | Discovery | AI Dataset Radar | 数据集竞争情报、趋势分析 | GitHub | | Analysis | DataRecipe | 逆向分析、Schema 提取、成本估算 | GitHub | | Production | DataSynth / DataLabel | LLM 批量合成 / 轻量标注 | GitHub · GitHub | | Quality | DataCheck | 规则验证 · 异常检测 · 分布分析 · 自动修复 | You are here | | Audit | ModelAudit | 蒸馏检测、模型指纹 | GitHub | | Identity | knowlyr-id | 身份系统 + AI 员工运行时 | GitHub | | Deliberation | Crew | 对抗式多智能体协商 · 持久记忆进化 · MCP 原生 | GitHub | | Agent Training | knowlyr-gym | Gymnasium 风格 RL 框架 · 过程奖励模型 · SFT/DPO/GRPO | GitHub |

---

Development

git clone https://github.com/liuxiaotong/data-check.git
cd data-check
pip install -e ".[all,dev]"
pytest

CI: GitHub Actions，Python 3.10+。Tag push 自动发布 PyPI + GitHub Release。

---

References

• Data Quality Dimensions — Wang, R.Y. & Strong, D.M., 1996. Beyond Accuracy: What Data Quality Means to Data Consumers. Journal of Management Information Systems — 数据质量的经典四维模型
• Confident Learning — Northcutt, C. et al., 2021. Confident Learning: Estimating Uncertainty in Dataset Labels. JAIR — 标签噪声检测
• Anomaly Detection — Hodge, V. & Austin, J., 2004. A Survey of Outlier Detection Methodologies. Artificial Intelligence Review — 异常检测方法综述
• Near-Duplicate Detection — Broder, A., 1997. On the Resemblance and Containment of Documents. SEQUENCES — n-gram Jaccard 近似重复检测
• Data Cleaning — Rahm, E. & Do, H.H., 2000. Data Cleaning: Problems and Current Approaches. IEEE Data Engineering Bulletin — 数据清洗问题与方法

---

License

MIT

---

<div align="center"> _{<a href="https://github.com/liuxiaotong">knowlyr</a> — multi-dimensional data quality validation with statistical anomaly detection} </div>