knowlyr-datacheck 0.2.0

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

DataCheck

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

快速开始 · 质量规则 · 分布分析 · MCP Server · Data Pipeline 生态

---

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

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

核心能力 / Core Capabilities

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

质量仪表盘预览 / Sample Dashboard

┌───────────────┬──────────────┬────────────┐
│ 通过率 92%    │ 评级 🟢 优秀 │ 错误 8 条 │
├───────────────┴──────────────┴────────────┤
│ ⚠ required_fields : 3  │ ⚠ duplicate_rows : 2│
│ 🔍 语言分布: zh 68% / en 32%                │
└────────────────────────────────────────────┘

完整示例: `examples/reports/demo_quality_report.md`

检查项目 / 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

# 输出报告
knowlyr-datacheck check data.json -o report.md

# 采样检查 (大数据集)
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

在 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]

---

分布分析 / 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"]
    }
  }
}

---

命令参考

命令	功能
knowlyr-datacheck check <file>	检查数据文件 (JSON/JSONL/CSV)
knowlyr-datacheck check <file> -s <schema>	使用 Schema 检查
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 validate <dir>	验证 DataRecipe 输出
knowlyr-datacheck compare <files...>	对比多个文件分布
knowlyr-datacheck rules	列出所有规则

---

API 使用

from datacheck import DataChecker, QualityReport, RuleSet

# 创建检查器
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")

# 生成报告
report = QualityReport(result)
report.save("report.md")

---

项目架构

src/datacheck/
├── checker.py        # 核心检查器 (JSON/JSONL/CSV 加载、采样、近似重复检测)
├── rules.py          # 规则定义、预设规则集、YAML 配置加载
├── text_rules.py     # 文本质量规则 (PII、乱码、重复文本、n-gram)
├── report.py         # 报告生成 (Markdown / JSON)
├── cli.py            # CLI 命令行
└── mcp_server.py     # MCP Server (4 工具)

---

License

MIT

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