knowlyr-datacheck 0.3.0

Data quality inspection toolkit - automated validation, anomaly detection, and distribution analysis

DataCheck

数据质检工具 — 自动化质量检查、异常检测、分布分析 Automated quality checks, anomaly detection & distribution analysis for LLM datasets

快速开始 · 质量规则 · Schema 推断 · 数据修复 · 分布分析 · MCP Server · 生态

---

GitHub Topics: data-quality, anomaly-detection, data-validation, mcp, ai-data-pipeline

自动化数据质量检查，支持规则验证、重复检测、分布分析，生成可读的质量报告。

核心能力 / Core Capabilities

数据文件 + Schema → 规则检查 → 异常检测 → 分布分析 → 质量报告

质量仪表盘预览 / Sample Dashboard

通过率	评级	错误	警告	重复
92%	🟢 优秀	8 条	3 条	2 组

检查项目 / Checks

检查类型	说明
🔴 必填字段	检查是否包含所有必填字段
🔴 非空检查	检查关键字段是否为空
🔴 格式检查	检查数据类型是否正确
🟡 长度边界	检查文本长度是否合理
🟡 重复检测	检测完全重复 + 近似重复 (n-gram Jaccard)
🟡 隐私信息 (PII)	检测邮箱、手机号、身份证号
🟡 乱码检测	检测乱码、异常字符、编码错误
🟡 重复文本	检测文本内过度重复内容
🔵 语言一致性	检查文本语言是否一致

质量评级 / Rating

通过率	评级	建议
≥90%	🟢 优秀	可直接使用
≥70%	🟡 良好	建议修复警告
≥50%	🟠 一般	需要处理错误
<50%	🔴 需改进	严重质量问题

安装 / Installation

pip install knowlyr-datacheck

可选依赖：

pip install knowlyr-datacheck[stats]    # 统计分析 (numpy, scipy)
pip install knowlyr-datacheck[mcp]      # MCP 服务器
pip install knowlyr-datacheck[yaml]     # YAML 规则配置
pip install knowlyr-datacheck[all]      # 全部功能

快速开始 / Quick Start

检查数据文件 / CLI

# 基础检查 (支持 JSON / JSONL / CSV)
knowlyr-datacheck check data.json
knowlyr-datacheck check data.jsonl
knowlyr-datacheck check data.csv

# 指定 Schema
knowlyr-datacheck check data.json -s schema.json

# 输出报告 (Markdown / JSON / HTML)
knowlyr-datacheck check data.json -o report.md
knowlyr-datacheck check data.json -o report.html -f html
knowlyr-datacheck check data.json -o report.json -f json

# 采样检查 (大数据集，自动显示进度条)
knowlyr-datacheck check data.jsonl --sample 1000
knowlyr-datacheck check data.jsonl --sample-rate 0.1

# CI 集成: 自定义阈值
knowlyr-datacheck check data.json --threshold 0.9
knowlyr-datacheck check data.json --strict

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

# 数据修复 (去重 / 去空白 / PII 脱敏)
knowlyr-datacheck fix data.jsonl -o fixed.jsonl
knowlyr-datacheck fix data.jsonl -o fixed.jsonl --strip-pii

在 Python 中接入 / Python SDK

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")

输出示例

正在检查 data.json...

==================================================
  数据质量检查结果
==================================================
  总样本: 100
  通过: 92
  失败: 8
  通过率: 92.0%
  评级: 🟢 优秀
==================================================

🟡 警告: 3
⚠️  重复: 2 组

使用 DataRecipe 分析结果验证 / Validate DataRecipe Outputs

# 验证合成数据
knowlyr-datacheck validate ./analysis_output/my_dataset/

# 验证指定文件
knowlyr-datacheck validate ./analysis_output/my_dataset/ -d custom_data.json

输出示例

正在验证 ./analysis_output/my_dataset/...
✓ 报告已保存: ./analysis_output/my_dataset/12_质检报告/quality_report.md

==================================================
  数据质量检查结果
==================================================
  总样本: 1000
  通过: 956
  失败: 44
  通过率: 95.6%
  评级: 🟢 优秀
==================================================

---

质量规则 / Quality Rules

内置规则 / Built-in Rules

# 查看所有规则
knowlyr-datacheck rules

规则 ID	名称	级别	说明
required_fields	必填字段检查	🔴 错误	检查必填字段是否存在
non_empty	非空检查	🔴 错误	检查关键字段是否为空
format_valid	格式检查	🔴 错误	检查数据类型是否正确
score_valid	评分有效性	🔴 错误	检查评分是否在有效范围
length_bounds	长度边界检查	🟡 警告	检查文本长度范围
pii_detection	隐私信息检测	🟡 警告	检测邮箱、手机号、身份证号
garbled_text	乱码检测	🟡 警告	检测乱码、异常字符
repetitive_text	重复文本检测	🟡 警告	检测文本内过度重复
language_consistency	语言一致性	🔵 提示	检查语言是否一致

预设规则集 / Rule Packs

# 使用 SFT 数据规则集
knowlyr-datacheck check data.json --ruleset sft

# 使用偏好数据规则集
knowlyr-datacheck check data.json --ruleset preference

规则集	说明
default	通用规则
sft	SFT 数据专用规则 (指令质量、回复质量)
preference	偏好数据专用规则 (chosen/rejected 差异)

自定义规则配置 / Custom Rules (YAML)

通过 YAML 配置文件定义自定义规则，无需写 Python 代码：

# 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

  - field: instruction
    check: regex
    pattern: "^[A-Z\u4e00-\u9fff]"
    severity: info
    message: "指令应以大写字母或中文开头"

# 使用自定义规则
knowlyr-datacheck check data.json --rules-file rules.yaml

支持的检查类型：required、non_empty、min_length、max_length、regex、enum

需要安装 YAML 支持：pip install knowlyr-datacheck[yaml]

---

Schema 推断 / Schema Inference

自动从数据文件推断字段类型、约束和必填项：

knowlyr-datacheck infer data.jsonl -o schema.json

输出示例

{
  "sample_count": 1000,
  "fields": {
    "instruction": {
      "type": "string",
      "required": true,
      "min_length": 5,
      "max_length": 200,
      "avg_length": 68
    },
    "response": {
      "type": "string",
      "required": true,
      "min_length": 12,
      "max_length": 820,
      "avg_length": 251
    },
    "score": {
      "type": "integer",
      "required": true,
      "min_value": 1,
      "max_value": 5,
      "enum": [1, 2, 3, 4, 5]
    }
  }
}

---

数据修复 / Data Fix

自动修复常见数据质量问题：

# 基础修复 (去重 + 去空白 + 移除空样本)
knowlyr-datacheck fix data.jsonl -o fixed.jsonl

# 包含 PII 脱敏
knowlyr-datacheck fix data.jsonl -o fixed.jsonl --strip-pii

# 跳过特定修复
knowlyr-datacheck fix data.jsonl -o fixed.jsonl --no-dedup --no-trim

修复项目：

修复	说明
去重	移除完全重复样本（保留首条）
去空白	去除字符串字段首尾空白
移除空样本	移除全空/全 null 样本
PII 脱敏	替换邮箱→[EMAIL]、手机→[PHONE]、身份证→[ID]

---

分布分析 / Distribution Analysis

对比多个数据文件

knowlyr-datacheck compare seed.json synthetic.json -o comparison.md

输出示例

# 数据分布对比报告

## 文件概要

| 文件 | 样本数 |
|------|--------|
| seed.json | 50 |
| synthetic.json | 1000 |

## 字段对比

### instruction
- **seed.json**: 长度 15-200 (平均 68)
- **synthetic.json**: 长度 12-198 (平均 72)

### response
- **seed.json**: 长度 50-800 (平均 245)
- **synthetic.json**: 长度 45-820 (平均 251)

分析内容

• 长度统计: 最小值、最大值、平均值
• 唯一值比例: 检测多样性
• 值分布: 数值型字段的分布情况
• 参考对比: 与种子数据的分布差异

---

MCP Server

在 Claude Desktop / Claude Code 中直接使用。

配置

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

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

可用工具

工具	功能
check_data_quality	检查数据文件质量
validate_from_datarecipe	使用 DataRecipe 分析结果验证
compare_distributions	对比多个数据文件分布
list_quality_rules	列出所有质量检查规则

使用示例

用户: 帮我检查 ./output/synthetic.json 的质量

Claude: [调用 check_data_quality]

        ## 数据质量检查结果

        - 通过率: **95.6%**
        - 评级: **🟢 优秀**
        - 错误: 0, 警告: 44

        发现 2 组重复数据

---

Data Pipeline 生态

DataCheck 是 Data Pipeline 生态的质检组件：

graph LR
    Radar["🔍 Radar<br/>情报发现"] --> Recipe["📋 Recipe<br/>逆向分析"]
    Recipe --> Synth["🔄 Synth<br/>数据合成"]
    Recipe --> Label["🏷️ Label<br/>数据标注"]
    Synth --> Check["✅ Check<br/>数据质检"]
    Label --> Check
    Check --> Audit["🔬 Audit<br/>模型审计"]
    Audit --> Hub["🎯 Hub<br/>编排层"]
    Hub --> Sandbox["📦 Sandbox<br/>执行沙箱"]
    Sandbox --> Recorder["📹 Recorder<br/>轨迹录制"]
    Recorder --> Reward["⭐ Reward<br/>过程打分"]
    style Check fill:#0969da,color:#fff,stroke:#0969da

生态项目

层	项目	PyPI 包	说明	仓库
情报	AI Dataset Radar	knowlyr-radar	数据集竞争情报、趋势分析	GitHub
分析	DataRecipe	knowlyr-datarecipe	逆向分析、Schema 提取、成本估算	GitHub
生产	DataSynth	knowlyr-datasynth	LLM 批量合成、种子数据扩充	GitHub
生产	DataLabel	knowlyr-datalabel	轻量标注工具、多标注员合并	GitHub
质检	DataCheck	knowlyr-datacheck	规则验证、重复检测、分布分析	You are here
质检	ModelAudit	knowlyr-modelaudit	蒸馏检测、模型指纹、身份验证	GitHub
Agent	knowlyr-agent	knowlyr-sandbox / recorder / reward / hub	沙箱 + 轨迹录制 + Reward + 编排	GitHub

端到端工作流

# 1. DataRecipe: 分析数据集，生成 Schema 和样例
knowlyr-datarecipe deep-analyze tencent/CL-bench -o ./output

# 2. DataLabel: 生成标注界面，人工标注/校准种子数据
knowlyr-datalabel generate ./output/tencent_CL-bench/

# 3. DataSynth: 基于种子数据批量合成
knowlyr-datasynth generate ./output/tencent_CL-bench/ -n 1000

# 4. DataCheck: 质量检查
knowlyr-datacheck validate ./output/tencent_CL-bench/

四合一 MCP 配置

{
  "mcpServers": {
    "knowlyr-datarecipe": {
      "command": "uv",
      "args": ["--directory", "/path/to/data-recipe", "run", "knowlyr-datarecipe-mcp"]
    },
    "knowlyr-datalabel": {
      "command": "uv",
      "args": ["--directory", "/path/to/data-label", "run", "python", "-m", "datalabel.mcp_server"]
    },
    "knowlyr-datasynth": {
      "command": "uv",
      "args": ["--directory", "/path/to/data-synth", "run", "python", "-m", "datasynth.mcp_server"]
    },
    "knowlyr-datacheck": {
      "command": "uv",
      "args": ["--directory", "/path/to/data-check", "run", "python", "-m", "datacheck.mcp_server"]
    }
  }
}

---

pre-commit Hook

在提交前自动检查数据文件质量：

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/liuxiaotong/data-check
    rev: v0.2.0
    hooks:
      - id: datacheck

自动对 .json、.jsonl、.csv 文件运行质量检查。

---

命令参考

命令	功能
knowlyr-datacheck check <file>	检查数据文件 (JSON/JSONL/CSV)
knowlyr-datacheck check <file> -s <schema>	使用 Schema 检查
knowlyr-datacheck check <file> -f html -o report.html	输出 HTML 报告
knowlyr-datacheck check <file> --ruleset sft	使用指定规则集
knowlyr-datacheck check <file> --rules-file rules.yaml	使用自定义 YAML 规则
knowlyr-datacheck check <file> --sample 1000	随机抽样 1000 条检查
knowlyr-datacheck check <file> --sample-rate 0.1	随机抽样 10% 检查
knowlyr-datacheck check <file> --threshold 0.9	通过率低于 90% 时退出码 1
knowlyr-datacheck check <file> --strict	任何错误/警告都退出码 1
knowlyr-datacheck infer <file>	推断 Schema (字段类型/约束)
knowlyr-datacheck infer <file> -o schema.json	推断并保存 Schema
knowlyr-datacheck fix <file> -o <output>	修复数据 (去重/去空白/清理)
knowlyr-datacheck fix <file> -o <output> --strip-pii	修复并脱敏 PII
knowlyr-datacheck validate <dir>	验证 DataRecipe 输出
knowlyr-datacheck compare <files...>	对比多个文件分布
knowlyr-datacheck rules	列出所有规则

---

API 使用

from datacheck import DataChecker, QualityReport, RuleSet, DataFixer

# 创建检查器
checker = DataChecker()

# 检查文件 (支持 JSON/JSONL/CSV + 采样 + 进度回调)
result = checker.check_file("data.jsonl", sample_count=1000)

print(f"通过率: {result.pass_rate:.1%}")
print(f"错误: {result.error_count}")
print(f"重复: {len(result.duplicates)} 组")
print(f"近似重复: {len(result.near_duplicates)} 组")

# 使用 YAML 自定义规则
rules = RuleSet.from_config("rules.yaml")
checker = DataChecker(rules)
result = checker.check_file("data.json")

# 生成报告 (Markdown / JSON / HTML)
report = QualityReport(result)
report.save("report.md")
report.save("report.html", format="html")

# Schema 推断
schema = checker.infer_schema_file("data.jsonl", "schema.json")

# 数据修复
fixer = DataFixer()
result = fixer.fix_file("data.jsonl", "fixed.jsonl", strip_pii=True)
print(f"去重: {result.duplicates_removed}, PII 脱敏: {result.pii_redacted_count}")

---

项目架构

src/datacheck/
├── checker.py        # 核心检查器 (加载、采样、近似重复、Schema 推断)
├── rules.py          # 规则定义、预设规则集、YAML 配置加载
├── text_rules.py     # 文本质量规则 (PII、乱码、重复文本、n-gram)
├── fixer.py          # 数据修复 (去重、去空白、PII 脱敏)
├── report.py         # 报告生成 (Markdown / JSON / HTML)
├── cli.py            # CLI 命令行 (check/infer/fix/validate/compare/rules)
└── mcp_server.py     # MCP Server (4 工具)

---

License

MIT

_{knowlyr 数据工程生态 · 自动化数据质检}