datajuicer/data-juicer · 上手攻略

仓库：datajuicer/data-juicer
链接：https://github.com/datajuicer/data-juicer
分类：ai · data-processing
作者：Jay
更新：2026-07-14

这是什么

Data-Juicer（简称 DJ）是一个为 foundation model 时代打造的数据操作系统，专注于将混乱的原始数据转化为 AI 可用的精炼数据。它把数据处理看成是可组合的基础设施，提供模块化的构建块来完成清洗、合成和分析，覆盖 AI 全生命周期的数据处理需求。

用大白话说：它是一个超大型数据处理工具箱，内置 200+ 算子（Operator），可以处理文本、图片、音频、视频乃至多模态数据，从你的笔记本到千节点集群都能跑，配以 YAML 配置文件（叫做 Recipe）实现可版本化管理的数据处理流水线。

解决什么问题

大模型预训练数据清洗：海量网页语料去重、质量过滤、格式标准化
Agent 交互轨迹处理：清洗工具调用轨迹、结构化上下文、去标识化、质量门控
RAG 数据准备：知识提取、规范化、语义分块、去重、数据画像分析
多模态数据处理：图像、音频、视频的筛选、增强和标注
数据质量分析：对数据集做全局质量评估和可视化报告

核心价值：用 YAML 配置替代手写 Python 清洗脚本，一条命令跑完整个数据处理流程，还能水平扩展到分布式集群。

快速安装

方式一：pip 安装（推荐）

uv pip install py-data-juicer
# 或传统 pip
pip install py-data-juicer

方式二：Docker（免配置环境）

docker pull datajuicer/data-juicer

方式三：在线体验（零安装）

JupyterLab Playground（含教程）：直接浏览器里体验
Ask DJ Copilot：用对话方式问 Data-Juicer 相关问题

验证安装

dj-process --config demos/process_simple/process.yaml

核心用法

方式一：YAML Recipe（推荐的生产用法）

Data-Juicer 的核心是 YAML 配置文件，定义输入数据、算子链和输出：

# process.yaml
project_name: 'my-data-cleaning'

# 输入：HuggingFace 格式或本地 JSONL
dataset_path: './data/raw.jsonl'

# 处理算子链
process:
  - TextLengthFilter:
      min_len: 100
      max_len: 5000
  - AlphanumericFilter
  - WhitespaceNormalizationMapper
  - DuplicateWordsFilter:
      lang: en

# 输出
export_path: './data/cleaned.jsonl'

运行：

dj-process --config process.yaml

方式二：Python API（适合嵌入代码）

from data_juicer.core.data import NestedDataset
from data_juicer.ops.filter import TextLengthFilter, AlphanumericFilter
from data_juicer.ops.mapper import WhitespaceNormalizationMapper

# 从 JSONL 加载
ds = NestedDataset.from_jsonl('./data/raw.jsonl')

# 用算子链处理
res_ds = ds.process([
    TextLengthFilter(min_len=10, max_len=5000),
    AlphanumericFilter(),
    WhitespaceNormalizationMapper()
])

# 导出
res_ds.to_jsonl('./data/cleaned.jsonl')

方式三：HuggingFace Dataset 直接处理

from datasets import load_dataset
from data_juicer.core.data import NestedDataset

# 直接加载 HuggingFace dataset
raw_ds = load_dataset("my-org/my-dataset", split="train")
ds = NestedDataset.from_huggingface(raw_ds)

res_ds = ds.process([TextLengthFilter(min_len=50)])

常用算子速查

类型	算子	用途
文本过滤	`TextLengthFilter`	按长度过滤
文本过滤	`AlphanumericFilter`	过滤乱码/非字母内容
文本过滤	`LanguageIDSFilter`	按语言过滤
去重	`SimilarityDeduplicator`	近似重复去重
去重	`DocumentLineDeduplicator`	跨文档行级去重（去除模板句等）
映射	`WhitespaceNormalizationMapper`	空格标准化
映射	`LowercaseMapper`	转小写
映射	`LlamaFixerMapper`	修复 llama 格式问题
LLM 算子	`LlamaConditionFilter`	用 LLM 做质量判断过滤
LLM 算子	`LlamaExtractMapper`	用 LLM 提取关键信息

完整算子列表见官方 Operators 文档。

典型适用场景

场景 1：大模型预训练数据清洗

用 Recipe 配置去重+质量过滤流水线，处理 5TB 数据在 1280 核集群上仅需 2.8 小时（官方数据）。典型配置：

process:
  - SimilarityDeduplicator: {}
  - TextLengthFilter:
      min_len: 100
  - LanguageIDSFilter:
      lang: en
  - AlphanumericFilter: {}

场景 2：RAG 知识库构建

对原始文档做分块、去重、质量过滤，然后导出为 RAG 可用格式：

ds = NestedDataset.from_jsonl('raw_docs.jsonl')
res = ds.process([
    MarkdownRemovalMapper,        # 去除 markdown 标记
    WhitespaceNormalizationMapper,
    TextLengthFilter(min_len=20, max_len=1000),
    SemanticChunkMapper(chunk_size=500)  # 语义分块（需额外配置）
])

场景 3：Agent 工具调用轨迹清洗

Agent 交互数据往往包含 JSON 格式的 tool_call，需要结构化提取和质量筛选：

from data_juicer.ops.filter import InteractionQualityFilter

ds = NestedDataset.from_jsonl('agent_traces.jsonl')
res = ds.process([
    JsonLoaderMapper,              # 解析 JSON 结构
    InteractionQualityFilter(),    # 过滤低质量交互
])

场景 4：多模态数据筛选

处理图文对数据：

from data_juicer.ops.filter import ImageAspectRatioFilter, ImageTextMatchingFilter

ds = NestedDataset.from_parquet('image_text_pairs.parquet')
res = ds.process([
    ImageAspectRatioFilter(min_ratio=0.5, max_ratio=2.0),
    ImageTextMatchingFilter(),     # 图文匹配度过滤
])

分布式扩展

Data-Juicer 内置 Ray 支持，可以轻松扩展到多节点集群：

# 单机（默认）
dj-process --config process.yaml

# 分布式（需提前启动 Ray 集群）
dj-process --config process.yaml --executor Ray --workers 50

官方称：在 50 个 Ray 节点（6400 核）上处理 70B 样本仅需 2 小时。

坑与注意

⚠️ 默认安装精简后，扩展功能需要额外依赖

v1.5.2 以后，默认依赖被精简，Ray、音频处理、spaCy、av 等都移到了按需安装的 extras：

# 完整安装（包含所有可选依赖）
uv pip install "py-data-juicer[all]"

# 分开按需安装
uv pip install "py-data-juicer[ray]"      # 分布式
uv pip install "py-data-juicer[audio]"    # 音频处理
uv pip install "py-data-juicer[video]"    # 视频处理

如果遇到某个算子报 ModuleNotFoundError，很可能是缺对应 extras。

⚠️ 大规模数据注意分区配置

处理 PB 级数据时，需要关注 Ray 的 override_num_blocks 参数以控制并行度，避免 OOM。

⚠️ LLM 算子需要额外配置

llm_* 系列算子（LlamaConditionFilter、LlamaExtractMapper 等）需要配置 LLM 推理端点，需要一个能调用的模型服务（如 OpenAI API 或私有模型），配置方式参见 LLM Ops 文档。

⚠️ 中文文档部分过时

官方文档有中文版（https://datajuicer.github.io/data-juicer/zh_CN/main/），但英文版更新更快，部分中文页面可能落后于最新版本。

⚠️ v1.5.x 版本 API 变化

从 v1.4 到 v1.5 有较多破坏性变更（如 LLM 算子统一改为 llm_* 前缀命名），升级前建议看 CHANGELOG。

与同类对比

工具	特点	适合场景
Data-Juicer（本文）	200+ 算子；YAML Recipe；多模态；Ray 分布式；Alibaba PAI 集成	大模型预训练数据；多模态处理；需要可复现流水线
OpenRefine	GUI 界面；侧重清洗和转换；轻量	小规模数据分析；非程序员友好
Pandas + Python脚本	灵活；需自己实现所有逻辑	一次性处理；简单场景
Apache Spark	超大规模分布式；学习曲线陡	超大规模 ETL；已有 Spark 团队
DataTrove（Scale AI）	专注 LLM 数据；开源	大模型数据清洗

Data-Juicer 的优势在于算子化 + YAML 化 + 分布式三位一体，特别适合需要版本化管理、可复现数据流水线的 AI 研发团队。

一句话推荐

Data-Juicer 是目前 AI 数据处理领域最完整的开源工具链之一——200+ 算子覆盖多模态，YAML Recipe 让数据处理流程可版本化管理，配合 Ray 可从笔记本无缝扩展到千节点集群，是大模型数据工程师的必备利器。