refine all doc, improve deliverablity

Author: SunnyHaze

docs/.vuepress/public/dataflow_op_statistic.jpg

@@ -7,16 +7,24 @@ permalink: /zh/guide/intro/basicinfo/intro/
 # 简介
 近年来，大模型的发展在很大程度上依赖于大规模、高质量的训练数据。然而，目前主流的训练数据及其处理流程多未公开，公开数据资源的规模和质量仍有限，给社区在构建和优化大模型训练数据的过程中带来不小挑战。
 
-尽管已有如 Open-DataLab 等组织推动数据集的开源，数据准备仍然是一个高度依赖手工和分散实现的过程。现阶段，不同团队往往需要各自构建清洗与构造流程，缺乏统一、系统化的工具支持。已有数据处理工具（如Hadoop和Spark）大多以传统方法为核心，尚未有效集成基于大语言模型（LLMs）的智能算子，对于高效构建适用于大模型训练的数据支持仍显不足。
+尽管已有如 Open-DataLab 等组织推动数据集的开源，大模型数据准备仍然是一个高度依赖手工和分散实现的过程。现阶段，不同团队往往需要各自构建清洗与构造流程，缺乏统一、系统化的工具支持。随着大模型技术的飞速发展，Agent技术逐渐应用于各行各业，使基于大模型完成高效，低成本的数据治理成为可能。然而已有数据处理工具（如Hadoop和Spark）大多以传统方法为核心，尚未对大模型的自动化数据治理进行集成和优化，对于高效构建适用于大模型训练的数据支持仍显不足。
 
-为此，我们提出了 **DataFlow**——一个由先进算子（Operators）与多阶段数据处理 Pipeline 组成的高效数据准备系统。DataFlow 充分结合了规则方法、深度学习模型和大语言模型的能力，提供了可扩展、可重组的模块化设计，旨在提升数据清洗、增强与构建的质量与效率，助力下一代大模型的发展。
+为此，我们提出了 **DataFlow**——一个由先进算子（Operators）与多阶段数据处理流水线（Pipeline） 组成的高效数据准备系统。DataFlow 充分结合了规则方法、深度学习模型和大模型的能力，提供了可扩展、可重组的模块化设计，旨在提升数据清洗、增强与构建的质量与效率，助力下一代大模型的发展。
 
 ## DataFlow：一个高质量数据准备系统
 
-**DataFlow** 是一个用于数据评估与处理的系统，旨在对嘈杂的数据源（如 PDF 文档、纯文本、低质量问答数据）进行 **清洗、增强与评估** 以得到高质量的训练数据。得到高质量数据我们可以通过有针对性的训练（包括预训练、有监督微调、强化学习训练）提升大语言模型在通用领域（推理能力和检索能力）与特定领域（如医疗、金融、法律等）的性能。
+**DataFlow** 是一个高效完成高质量数据治理的系统，旨在对诸如 PDF 文档、纯文本、爬虫数据等低质量而嘈杂的数据进行 **修正、扩增、评估与过滤**（refine, generate, evaluate, filt） 以得到高质量的训练数据。这些数据可以通过预训练、有监督微调、强化学习训练提升大语言模型在通用领域（推理能力和检索能力）与特定领域（如医疗、金融、法律等）的性能。此外，Dataflow产出的高质量数据也可以有效赋能现有的RAG系统。
 
-具体而言，我们构建了一系列多样化的算子（Operator），这些算子基于规则方法、深度学习模型、大语言模型（LLMs）以及 LLM API 开发而成。我们将这些算子系统性地整合进六条独立的数据处理流水线（Pipeline）中，构成了完整的 **DataFlow 系统**。
+具体而言，DataFlow系统由如下部分组成：
+1. **算子（Operator）：**：我们对于多种数据治理需求进行了分析与抽象，构建了一系列多样化的算子，这些算子基于规则方法、深度学习模型、大语言模型（LLMs）以及 LLM API 开发而成。算子具有原子性，便于复用和框架级别统一优化。
+2. **流水线（Pipeline）：**：为了实现具体的数据治理功能，将算子经过有序连接即可构建完整的流水线应用于具体场景。Dataflow中预设了相当数量的流水线服务于多种领域功能，用户可灵活增删预设流水线中的算子以满足定制化需求。
+3. **提示词和提示词模板（Prompt & Prompt Template）**：针对于大模型数据治理，有些微妙的需求是不足以单独设置新算子的。这时候就需要通过替换不同的提示词模板来达成需求。这时就需要对所有的提示词和提示词模板进行注册。并建立算子到可选提示词or提示词模板的映射。便于用户查阅或由Agent调用。
+
+经过合理的编排和组装，这些经过抽象和复用的算子和提示词模板即可系统性地整合进数据处理流水线中，满足多样化的数据治理需求。
+
+此外，我们还提供了智能的**Dataflow-Agent**，能够根据自然语言需求动态组合已有的算子，自动构建新的数据处理流程，从而实现更灵活、高效的数据构建与处理能力。
+
+综上，算子，流水线，提示词和提示词模板，以及Dataflow-Agent构成了完整的 **DataFlow 数据治理系统**。
 
-此外，我们还开发了一个智能的Dataflow-Agent，能够根据需求动态组合已有的算子，自动构建新的数据处理流程，从而实现更灵活、高效的数据构建与处理能力。
 
 

docs/.vuepress/public/dataflow_operator.jpg

@@ -5,31 +5,29 @@ createTime: 2025/06/09 10:29:31
 permalink: /zh/guide/install/
 ---
 # 安装
-本节介绍如何安装DataFlow，如果你仅想快速使用DataFlow中提供的Pipeline和算子，请参考[普通用户安装](#普通用户安装)安装稳定正式版，如果你想作为开发者向DataFlow仓库贡献代码，提出Pull Request，请参考[开发者安装](#开发者安装)安装仓库中的dev版。
+本节介绍如何安装DataFlow。
+- 如果你仅想快速使用DataFlow中提供的Pipeline和算子，请参考[普通用户安装](#普通用户安装)，安装pypi发布的稳定正式版。
+- 如果你想使用我们正在开发的版本，或作为开发者向DataFlow仓库贡献代码，请参考[开发者安装](#开发者安装)，安装Github仓库中的dev版。
 
 ## 普通用户安装
-
 如果你没有GPU做本地推理环境，仅需使用API和CPU功能，则配置Python环境并安装DataFlow正式版👇
 
 ```shell
-conda create -n dataflow python=3.10 
-conda activate dataflow
-
 pip install open-dataflow
 ```
 
-
-如果想用本地GPU实现推理则需要使用如下命令：
+如果想用本地GPU实现推理，则根据你期望的后端是vllm/sglang，使用如下命令：
 ```shell
-conda create -n dataflow python=3.10 
-conda activate dataflow
-
 pip install open-dataflow[vllm]
 ```
 
-> Dataflow 支持Python>=3.10的环境。
+```shell
+pip install open-dataflow[sglang]
+```
 
-你可以用如下指令检查安装是否正确：
+> Dataflow 支持Python>=3.10的环境，具体依赖可能随着vllm和SGLang版本号有新的约束。
+
+安装完成后，你可以用如下指令检查安装是否正确：
 ```shell
 dataflow -v
 ```
@@ -44,32 +42,49 @@ You are using the latest version: 0.0.2.
 ```
 具体最新版本号最新版也可参考[Github Release](https://github.com/OpenDCAI/DataFlow/releases) 和 [Pypi官网](https://pypi.org/project/open-dataflow/).
 
-此外还有`dataflow env`指令用于查看当前硬件软件环境，用于报告Bug使用。
-
+此外，我们也提供了`dataflow env`命令行指令用于查看当前硬件软件环境。运行后，会输出类似如下的内容：
+```shell
+========================================================================================
+
+- `dataflow` version: 1.0.5
+- Platform: Linux-5.15.0-58-generic-x86_64-with-glibc2.35
+- Python version: 3.10.10
+- PyTorch version: 2.6.0+metax2.33.1.4 (GPU)
+- Torchvision version: 2.6.0+metax2.33.1.4
+- GPU type: MetaX C500
+- GPU number: 8
+- GPU memory: 63.62GB
+- vLLM version: 0.8.5
+- Git commit: 2135405b509a72cd11beed7be5f29ce50274d288
+
+========================================================================================
+```
 ## 开发者安装
 
 DataFlow开发者可以通过以下指令安装:
 
 如果不需要本地GPU推理
 ```shell
-conda create -n dataflow python=3.10
-conda activate dataflow
-
 git clone https://github.com/OpenDCAI/DataFlow
 cd DataFlow
 pip install -e .
 ```
 
-如果需要本地GPU推理：
+如果想用本地GPU实现推理，则根据你期望的后端是vllm/sglang，使用如下命令：
 ```shell
-conda create -n dataflow python=3.10
-conda activate dataflow
-
 git clone https://github.com/OpenDCAI/DataFlow
 cd DataFlow
 pip install -e .[vllm]
 ```
-你可以用如下指令检查安装是否正确：
+```shell
+git clone https://github.com/OpenDCAI/DataFlow
+cd DataFlow
+pip install -e .[sglang]
+```
+
+> Dataflow 支持Python>=3.10的环境，具体依赖可能随着vllm和SGLang版本号有新的约束。
+
+安装完成后，你可以用如下指令检查安装是否正确：
 ```shell
 dataflow -v
 ```
@@ -82,8 +97,25 @@ open-dataflow codebase version: 0.0.2
         PyPI newest version:  0.0.2
 You are using the latest version: 0.0.2.
 ```
+具体最新版本号最新版也可参考[Github Release](https://github.com/OpenDCAI/DataFlow/releases) 和 [Pypi官网](https://pypi.org/project/open-dataflow/).
 
-此外还有`dataflow env`指令用于查看当前硬件软件环境，用于报告Bug使用。
+此外，我们也提供了`dataflow env`命令行指令用于查看当前硬件软件环境。运行后，会输出类似如下的内容：
+```shell
+========================================================================================
+
+- `dataflow` version: 1.0.5
+- Platform: Linux-5.15.0-58-generic-x86_64-with-glibc2.35
+- Python version: 3.10.10
+- PyTorch version: 2.6.0+metax2.33.1.4 (GPU)
+- Torchvision version: 2.6.0+metax2.33.1.4
+- GPU type: MetaX C500
+- GPU number: 8
+- GPU memory: 63.62GB
+- vLLM version: 0.8.5
+- Git commit: 2135405b509a72cd11beed7be5f29ce50274d288
+
+========================================================================================
+```
 
 这样，你在本地对DataFlow包进行的修改都可以实时更新到你的python环境中，方便开发。当开发完成后，也可以提PR向主仓库贡献你的新算子和新流水线。
 

docs/.vuepress/public/dataflow_pipeline_graph.png

@@ -6,33 +6,53 @@ icon: solar:flag-2-broken
 ---
 
 # 快速开始
-DataFlow使用了类似[`create-react-app`](https://github.com/facebook/create-react-app)或者[`vue-cli`](https://cli.vuejs.org/)的“**代码生成**”的使用范式。即通过命令行调用，自动生成运行脚本和入口Python文件，经过用户定制化修改后（比如更换数据集，使用不同的大模型API，重新微调算子），运行该Python文件以执行相应功能。
+## 代码生成的运行方式
+DataFlow使用了类似[`create-react-app`](https://github.com/facebook/create-react-app)或者[`vue-cli`](https://cli.vuejs.org/)的“**代码生成**”的使用范式。即通过命令行调用，自动生成默认的运行脚本和入口Python文件，经过用户定制化修改后（比如更换数据集，使用不同的大模型API，重新排列算子），运行该Python文件以执行相应功能。
 
-具体来说，当参考上一节成功安装DataFLow后，请找一个空的工作路径准备体验DataFLow。切换到该路径下后执行：
+具体来说，当参考上一节成功安装DataFLow后，请找一个**空的工作路径**准备体验DataFLow。切换到该路径下后执行：
 ```shell
 dataflow init
 ```
+即会在当前工作路径生成这些文件夹：
+```shell
+$ tree -L 1
+.
+|-- api_pipelines
+|-- cpu_pipelines
+|-- dataflow_agent
+|-- example_data
+|-- gpu_pipelines
+`-- playground
+```
+其中:
+- `cpu_pipelines`,`api_pipelines`, `gpu_pipelines`这三个文件夹存放着Dataflow主要的Pipeline的实现;
+- `playground`文件夹存放着一些有趣的案例，但算子数量和规模达不到Pipeline的级别；
+- `example_data`文件夹存放着默认样例数据，上述四个文件夹都需要从这里读数据才能运行。
+- `dataflow_agnet`文件夹存放着运行Dataflow Agent所需的相关脚本。
 
-即会在当前工作路径生成三个文件夹`cpu`, `api`, `gpu`，以及一个用于存放默认样例数据的`example_data`文件夹。
 
-我们每一条预设好的Pipeline都提供了三种模式，分别放置在这三个文件夹下。根据运行Pipeline所需的算子的资源类型进行分类，参考下表：
+## Pipeline的分类
+我们每一条预设好的完整Pipeline都提供了三种模式，分别放置在这三个文件夹下。根据运行Pipeline所需的算子的资源类型进行分类，参考下表：
 
 | 用户类别   | 仅需CPU的算子 | 需要大模型API的算子 | 需要本地部署GPU的算子 |
 |:------------:|:---------:|:-------------:|:-----------:|
-|`cpu`| √       |             |           |
-|`api`| √       | √           |           |
-|`gpu`| √       | √           | √         |
+|`cpu_pipelines`| √       |             |           |
+|`api_pipelines`| √       | √           |           |
+|`gpu_pipelines`| √       | √           | √         |
+
+不同文件夹下的**同名**pipeline是包含关系。即`gpu_pipelines`文件夹下的pipeline最长，包含全部功能。去掉了需要本地部署GPU模型的算子就变成了`api_pipelines`文件夹下的pipeline。再进一步去掉了需要大模型后端的算子就变成了`ccpu_pipelinespu`下的pipeline。
 
-不同文件夹下的**同名**pipeline是包含关系。即`gpu`文件夹下的pipeline最长，包含全部功能。去掉了需要本地部署GPU模型的算子就变成了`api`文件夹下的pipeline。再进一步去掉了需要大模型后端的算子就变成了`cpu`下的pipeline。
+特别的，这里的`api_pipelines`中的pipeline是可以通过修改其中的`LLMServing`为本地GPU模型（比如Qwen-3, llama等模型）来将其部署在本地的。相比于`gpu_pipelines`，`api_pipelines`中被去掉的算子主要是因为`gpu_pipelines`中调用了一些vllm/SGLang后端无法部署的，非常规LLM的模型，比如BERT的分类模型等等。
 
-特别的，这里的`api`pipeline是可以通过修改其中的`LLMServing`为本地GPU模型（比如Qwen-3, llama等模型）来将其部署在本地的。相比于`gpu`pipeline，`api`pipeline中被去掉的算子主要是因为`gpu`中调用了一些`vllm`后端无法部署的，非常规LLM的模型。
+
+## 运行你的第一个Pipeline
 
 随后，切换到对应路径下即可看到各种我们预设好的Pipeline所对应的Python文件。
 
 对于这些文件，默认的入口数据集是存放在`exapmle_data`文件夹下的`json`文件。你可以通过修改`storage`类中的`first_entry_file_name`字段来将其指向你要处理的原始数据集。
 ```python
 self.storage = FileStorage(
-    first_entry_file_name="../example_data/AgenticRAGPipeline/pipeline_small_chunk.json",
+    first_entry_file_name="../example_data/AgenticRAGPipeline/pipeline_small_chunk.json", # 输入的入口文件json
     cache_path="./cache_local", # 缓存路径
     file_name_prefix="dataflow_cache_step", # 缓存文件的文件名
     cache_type="json",  # 中间缓存文件的文件类型
@@ -44,7 +64,6 @@ self.storage = FileStorage(
 
 特别的，如果你使用 API 方式调用，则需要向环境变量输出 `DF_API_KEY` 字段，该设计是为了避免将key写入Github仓库导致泄露的途径。在 Linux 下是：
 
-
 ```bash
 export DF_API_KEY=sh-xxxxx
 ```
@@ -82,7 +101,7 @@ llm_serving_deepseek = APILLMServing_request(
 )
 ```
 
-当修改好Python脚本后，即可运行脚本，体验DataFlow高效的数据治理功能（如下为`test`目录下的一个pipeline运行命令）：
+当修改好Python脚本后，即可运行脚本，体验DataFlow高效的数据治理功能，比如可以在`./api_pipelines`路径下运行如下文件，体验样例的强推理数据合成功能：
 ```shell
 python reasoning_pipeline_general.py
 ```