Data-Juicer：面向基础模型时代的数据处理操作系统——从快速上手到架构与生态全景

• 人工智能
• 大模型
• 数据工程
• 数据清洗
• 数据增强
• 数据质检

Data-Juicer（DJ）将原始数据混乱转化为"AI 就绪"的智能：它把数据处理视为可组合的基础设施，提供模块化的积木式组件，覆盖清洗、合成、分析等整个 AI 数据生命周期。无论你是在做 web-scale 预训练语料的去重、agent 交互轨迹的整理，还是领域 RAG 索引的构建，DJ 都可以从笔记本平滑扩展到上千节点集群，且无需编写胶水代码。读完本文，你将掌握 DJ 的安装运行、CLI 与 Python 双入口、YAML Recipe 声明式流水线、底层执行器原理，以及其生态全景。

快速开始：零门槛跑通第一条数据处理流水线

安装：一条命令完成

DJ 以py-data-juicer为名发布在 PyPI 上，官方推荐的安装与运行方式极简：

uv pip install py-data-juicer dj-process --config demos/process_simple/process.yaml

第一条命令安装完整包；第二条命令直接以仓库自带的示例配置启动一个数据处理任务。在 pyproject.toml 中可以看到，dj-process正是项目为命令行入口注册的脚本别名，它指向data_juicer.tools.process_data:main（见 pyproject.toml 中[project.scripts]段），也就是说 CLI 与 Python 入口共享同一套核心逻辑。

命令行入口：dj-process 与执行器分发

dj-process的入口实现位于 tools/process_data.py，其主流程非常清晰，分为三步：

1. 加载配置：调用init_configs()解析 YAML 配置；
2. 初始化执行器：根据配置中的executor_type字段分派到不同的执行器：
   • default→DefaultExecutor（单机多进程）；
   • ray→RayExecutor（Ray 分布式）；
   • ray_partitioned→PartitionedRayExecutor（带分区的 Ray 分布式执行器，用于提升容错与可扩展性）；
3. 运行：调用executor.run()执行整条流水线。

配置解析由 data_juicer/config/config.py 中的init_configs()完成。从源码看，配置可来自四个来源（config.py 的 docstring 明确列出）：POSIX 风格命令行参数、YAML（含 JSON/JSONNet 超集）配置文件、环境变量、以及硬编码默认值。这意味着你既可以用--config指定文件，也可以用命令行参数覆盖单个配置项，灵活性很高。

Python 组合式 API：把算子当积木

除了 CLI，DJ 还提供了完全 Python 化的组合方式，官方 Quick Start 给出了一个可直接运行的最小示例：

from data_juicer.core.data import NestedDataset from data_juicer.ops.filter import TextLengthFilter from data_juicer.ops.mapper import WhitespaceNormalizationMapper ds = NestedDataset.from_dict({ "text": ["Short", "This passes the filter.", "Text with spaces"] }) res_ds = ds.process([ TextLengthFilter(min_len=10), WhitespaceNormalizationMapper() ]) for s in res_ds: print(s)

这里的关键类是NestedDataset，它定义在 data_juicer/core/data/dj_dataset.py，同时继承了 HuggingFaceDataset与 DJ 的抽象基类DJDataset，因此既保留了 HuggingFace 生态的map/filter等能力，又获得了 DJ 的process()高层接口。从源码可以看到：

• NestedDataset.process(operators, ...)按顺序逐个执行算子列表（dj_dataset.py），每个算子通过op.run()作用于当前数据集，处理结果作为下一个算子的输入，形成天然的串行流水线；
• 每完成一个算子，日志会输出[idx/op_num] OP [op_name] Done in ... Left N samples，方便实时观察数据量的逐级变化；
• process()还支持exporter、checkpointer、tracer、adapter等可选参数，分别对应导出、断点续跑、追踪与洞察挖掘等扩展能力；
• 类内部重写了map/filter，借助wrap_func_with_nested_access与nested_obj_factory把普通 dict 包装为支持嵌套键访问的NestedQueryDict，让多模态等带嵌套结构的样本读写更顺手。

为什么选择 Data-Juicer：三大核心能力

1. 模块化与可扩展架构

• 200+ 算子：覆盖文本、图像、音频、视频与多模态数据，形成庞大的"算子动物园"（operator zoo）；
• Recipe 优先：数据处理流水线以可复现的 YAML 形式组织，可以像代码一样做版本管理、分享与 fork；
• 可组合：既可以单独使用一个算子，也可以串联复杂工作流，或编排完整流水线；
• 热重载：迭代算子时无需重启整个流水线。

从源码层面看，这套可扩展性建立在注册表机制之上。data_juicer.ops.base_op中定义了OPERATORS注册表以及Mapper、Filter、Deduplicator、Selector等基础算子类别（base_op.py），任何算子只要用@OPERATORS.register_module("op_name")装饰即可被自动发现。例如 text_length_filter.py 中@OPERATORS.register_module("text_length_filter")与 whitespace_normalization_mapper.py 的注册方式完全一致，这也是 YAML 配置里直接写算子名就能生效的根本原因。

此外，config.py 中的load_custom_operators()支持从任意文件或包目录动态加载自定义算子，并内置了模块名冲突检测；结合 v1.5.5 引入的外部 OP 插件机制（第三方算子可通过 Python entry point 自动注册），生态扩展路径非常通畅。

2. 全谱系数据智能

DJ 面向整个 AI 数据生命周期：

• 基础模型（Foundation Models）：预训练、微调、强化学习（RL）以及评估级的数据治理；
• Agent 系统：工具调用轨迹清洗、上下文结构化、脱敏与质量把关。仓库内demos/agent/提供了完整的 agent 交互质量分析与坏例报告 Recipe（见 demos/agent/README.md），包含 JSONL 流水线与 HTML 报告，相关算子如agent_bad_case_signal_mapper等一应俱全；
• RAG 与分析：信息抽取、归一化、语义分块、去重与数据画像。

3. 生产级性能

• 规模：官方声明可在 50 个 Ray 节点（6400 核）上 2 小时处理 700 亿样本；
• 效率：官方声明使用 1280 核可在 2.8 小时完成 5TB 数据的去重；
• 优化：自动 OP 融合（可带来 2-10 倍加速）、自适应并行、CUDA 加速与鲁棒性保障；
• 可观测性：内置 tracing，用于调试、审计与迭代改进。

（上述性能数字均为项目官方 README 的自述数据，实际效果取决于硬件环境、数据形态与算子组合，建议以自身基准测试为准。）

以 OP 融合为例，仓库在 data_juicer/ops/op_fusion.py 中实现了融合策略（FUSION_STRATEGIES），并在此基础上演进出了FusedSequentialBatchOp（v1.5.4 引入），可在 batch 内部融合连续的算子以减少算子间开销，显著加速顺序处理。执行器侧则通过executor_type在默认、Ray 与分区 Ray 之间切换，配合 v1.5.3 引入的ray_repartition_pipeline支持数据集级 block 重分区，以及 v1.5.5 起对 Ray Data 执行路径的多项优化（移除过早执行的 eager action、迁移到公开的TaskPoolStrategy/ActorPoolStrategyAPI 等），共同构成大规模处理能力的基础。

用 YAML Recipe 声明式编排数据处理流程

DJ 的"Recipe 优先"理念落到实操上就是一份 YAML 文件。仓库自带的示例 demos/process_simple/process.yaml 结构非常典型：

# Process config example for dataset # global parameters project_name: 'demo-process' dataset_path: './demos/data/demo-dataset.jsonl' # path to your dataset directory or file np: 4 # number of subprocess to process your dataset export_path: './outputs/demo-process/demo-processed.jsonl' # process schedule # a list of several process operators with their arguments process: - language_id_score_filter: lang: 'zh' min_score: 0.8

这份配置揭示出 Recipe 的两个核心段落：

1. 全局参数：project_name标识项目；dataset_path指向数据集文件或目录（支持 JSONL、Parquet、CSV 等格式，以及hdfs://、S3 等远程路径）；np指定处理时使用的子进程数；export_path指定处理结果的输出位置。
2. process 调度段：一个算子列表，每个算子项以"算子名 + 参数字典"的形式出现。示例中只用了language_id_score_filter（按语言 ID 分数过滤，保留中文lang: 'zh'且分数不低于 0.8 的样本），实际使用中可以无限扩展，例如把text_length_filter、whitespace_normalization_mapper等按顺序写入列表即可组合出更复杂的流水线。

值得强调的是，YAML 中算子名与源码注册名是一一对应的。比如想按文本长度过滤，就把text_length_filter写入 process 列表，并在其下配置min_len（默认 10）与max_len（默认sys.maxsize），这两个参数的默认值定义在 text_length_filter.py 中。

v1.6.0 起，DJ 还增加了配置校验能力：流水线 preflight 阶段会在正式处理前捕获无效的算子设置以及执行器/数据 schema 不匹配等问题，相当于把错误暴露在数据加工之前，而不是跑了一半才失败。

深入理解一个 Filter 与一个 Mapper 的底层实现

TextLengthFilter：统计先行、批量过滤

TextLengthFilter 是一个典型的 Filter 算子，其设计体现了 DJ 的"统计-过滤"两阶段模式：

• _batched_op = True声明它支持批量处理；
• compute_stats_batched()负责统计：如果样本的 stats 中已有text_len则复用，否则计算len(text)并写入Fields.stats；
• process_batched()负责决策：根据min_len/max_len对每条样本计算保留与否的布尔值。

这种"先算统计、再按统计过滤"的解耦，让同一条统计结果可以被多个过滤器复用，也便于上游算子预计算 stats，从而避免重复计算。

WhitespaceNormalizationMapper：把一切空白统一为空格

WhitespaceNormalizationMapper 是一个典型的 Mapper：

• 对每条文本先strip()去掉首尾空白；
• 再基于VARIOUS_WHITESPACES（定义于 special_characters.py）将制表符、换行等各类空白字符统一替换为普通空格。

代码量虽少，但它代表了 Mapper 类算子的通用形态：对样本内容做就地改写而非丢弃。Filter 与 Mapper 一减一改，配合 Deduplicator、Selector、Grouper、Aggregator 等类别，共同构成 DJ 的算子分类体系（各类别算子文档可查阅 docs/operators/）。

版本演进：从 v1.5.0 到 v1.6.0 的能力跃迁

README 的 News 区完整记录了近期的版本主线，从中可以清晰看到 DJ 的演进方向：

• v1.6.0（2026-09-08）：发布 Juicer 自然语言数据精炼模型；引入 Cluster-Aware Partitioning（自动分区数基于实时 Ray 集群资源，手动partition.size目标按行边界切分）；配置校验前置；prepare_api_model支持api_backend="litellm"（通过 LiteLLM 做供应商级模型路由，原 OpenAI 兼容后端仍为默认）；统一远程导出（本地/S3/HDFS 共用文件系统分发，JSONL 导出以 ISO 格式序列化 Python 日期）；新增image_ohem_selector图像难例选择器；token 计数类过滤器限制 tokenizer 批大小以降低长输入峰值内存；修复多项鲁棒性问题。
• v1.5.5（2026-08-07）：外部 OP 插件机制；hdfs://读写支持；Ray Data 执行优化；demos/elastic_sharding/弹性多节点分片参考工作流；分布式RayAnalyzer（用 Ray 原生算子计算聚合统计，避免 pandas 物化）；内存优化（流式 n-gram 计数与分块 MinHash 置换将峰值 RSS 从 768 MiB 降至 272 MiB，结果不变）。
• v1.5.4（2026-07-17）：新增 9 个人类中心视频理解算子（人体轨迹提取、活跃说话人检测、音频 ASR、语音情感与年龄/性别检测、人脸属性/情感描述、人脸占比过滤等），用于构建 HumanVBench 风格流水线；引入FusedSequentialBatchOp批内阶段融合；修复 Ray 去重器共享状态等问题，并通过精确的平台标记解锁 ARM64 安装。
• v1.5.3（2026-06-26）：扩展 10+ 个 VLA（视觉-语言-动作）算子（DeepCalib/DroidCalib/MoGe 相机标定、原子动作分割、手部动作计算与平滑、剪辑重组、轨迹叠加、LeRobot 导出）及完整 VLA 流水线 demo；新增ray_repartition_pipeline；override_num_blocks贯通调用链以控制 PB 级数据的 block 并行度。
• v1.5.2（2026-05-29）：新增跨文档行级去重器DocumentLineDeduplicator（按全局文档频率剔除模板、版权声明、导航条等样板行）；发布 agent 数据质量工具包；精简默认依赖集（Ray、音频、spaCy、av 等移入按需 extras）；引入语义 LLM 算子（llm_extract_mapper、llm_condition_filter等统一llm_*命名）。
• v1.5.1（2026-03-17）：新增 LaTeX 算子、json[l].gz压缩格式直接加载；补充 cache、export、tracing 文档。
• v1.5.0（2026-02-12）：引入分区 Ray 执行器与算子级隔离环境，提升容错、可扩展性与依赖冲突解决能力；扩展具身 AI 视频处理算子；支持批量推理与内存/日志优化。

完整的历史动态可查阅 docs/news.md。同时，README 专门介绍了自然语言数据精炼模型Juicer：它把清洗指令、过滤规则与语义标注需求转化为结构化输出，既可在 HuggingFace/ModelScope 等平台在线体验，也支持下载后本地部署，其能力介绍与使用方式见 docs/Juicer.md。

生态、集成与社区

DJ 定位为"可插拔"的数据层，官方 README 按字母序列出了三类生态：

• 扩展项目：data-juicer-agents（DJ Copilot 与 agent 化工作流）、data-juicer-hub（社区 Recipe 与最佳实践）、data-juicer-sandbox（带反馈回路的数据-模型协同开发）；
• 框架与平台：与 AgentScope、Apache Arrow、Apache HDFS、Hudi、Iceberg、Paimon、Delta Lake、DiffSynth-Studio、EasyAnimate、Eval-Scope、HuggingFace、LanceDB、LLaMA-Factory、ModelScope、NVIDIA NeMo、Ray、RM-Gallery、Trinity-RFT 等深度协同；
• 产业与学术：被多家企业用于生产数据管线，并与多所高校开展合作。

社区方面，DJ 欢迎各类贡献：可以从 Good First Issues 入手，或参考 Developer Guide 开发新算子/优化核心基础设施，也可以向 DJ-Hub 分享 Recipe 与最佳实践。项目由阿里通义实验室发起，与阿里云 PAI、Anyscale（Ray 团队）、中山大学、NVIDIA（NeMo 团队）等共同开发，其设计思路受到 Apache Arrow、Ray、HuggingFace Datasets、BLOOM、RedPajama-Data 等项目的启发。

文档导航与引用

除本 README 外，仓库还提供了体系化的学习资料：

• docs/：安装、数据处理、分析、配置、导出、缓存、追踪、分布式等主题的中英文指南（如 docs/Installation.md、docs/ProcessData.md、docs/DatasetCfg.md、docs/GlobalConfig.md、docs/Export.md 等）；
• docs/tutorial/：DJ-Cookbook 资源归档与 awesome_llm_data 数据-模型协同开发精选清单；
• demos/：agent 质量分析、弹性分片、VLA 流水线、HPO 调优等可运行参考示例；
• tests/：覆盖算子、核心、工具与示例的测试用例，可作为"用法即文档"的补充。

如果研究工作使用了 Data-Juicer，官方建议引用以下两篇论文（完整 BibTeX 见 README.md）：

• Data-Juicer: A One-Stop Data Processing System for Large Language Models（SIGMOD 2024）；
• Data-Juicer 2.0: Cloud-Scale Adaptive Data Processing for and with Foundation Models（NeurIPS 2025）。

项目基于 Apache License 2.0 开源。从整体看，Data-Juicer 正沿着"更多模态算子、更强分布式执行、更贴近自然语言的智能精炼"三条主线持续演进，是构建 AI 数据基础设施时值得认真评估的选择。

• 人工智能
• 大模型
• 数据工程
• 数据清洗
• 数据增强
• 数据质检