DataRefinery是一个基于YAML配方驱动的机器学习数据准备工具，通过声明式配置实现可复现、可缓存的数据流水线，解决传统数据准备流程中的重复性和一致性问题。

DataRefinery：声明式机器学习数据准备框架\n\n## 数据准备的痛点\n\n在机器学习项目中，数据准备往往是最耗时却又最容易被忽视的环节。数据科学家常常陷入这样的困境：\n\n- 重复劳动：每次新项目都要重新编写数据清洗代码\n- 版本混乱：训练数据和推理数据使用不同的处理逻辑，导致训练-推理偏差\n- 难以复现：Notebook中的处理步骤缺乏版本控制，几个月后就无法重现\n- 协作困难：团队成员对数据处理流程的理解不一致\n\nDataRefinery项目正是针对这些痛点，提出了一种全新的解决方案——基于配方的声明式数据准备。\n\n## 核心理念：配方驱动的工作流\n\nDataRefinery的核心思想可以用一句话概括：用声明式配方（Recipe）代替命令式代码。\n\n用户只需编写一个YAML格式的配方文件，描述"想要什么样的数据"，DataRefinery会自动处理"如何得到这些数据"。这种范式转变带来了诸多好处：\n\n### 配方即文档\n\n配方文件本身就是对数据处理流程的完整描述，无需额外的文档维护。新团队成员可以通过阅读配方快速理解数据处理逻辑。\n\n### 可复现性保证\n\n相同的配方 + 相同的输入 + 相同的随机种子 = 字节级一致的结果。DataRefinery将这一承诺作为核心设计目标，确保实验的可复现性。\n\n### 智能缓存\n\nDataRefinery会自动检测配方或输入数据的变化，只在必要时重新执行处理流程。未变化的步骤会直接使用缓存结果，大幅提升迭代效率。\n\n## 技术架构深度解析\n\n### 语义缓存机制\n\nDataRefinery的缓存系统是其最精妙的设计之一。缓存地址由三部分组成：\n\n1. 配方哈希：基于配方的语义内容（忽略空白字符和键值顺序）计算\n2. 输入哈希：原始输入数据的哈希值\n3. 随机种子：控制所有随机操作的可复现性\n\n这种设计意味着：\n\n- 仅修改配方的格式（如调整缩进、键值顺序）不会触发重建\n- 任何语义上的修改都会使缓存失效\n- 更换输入数据集会自动触发重新处理\n\n### 原子化操作\n\n数据处理流程遵循"先写临时目录，成功后原子提升"的原则。这意味着：\n\n- 处理过程中断不会留下部分完成的脏数据\n- 缓存中的实例永远是完整的、可用的\n- 并发执行不会导致数据竞争问题\n\n### 配方权威性原则\n\n在DataRefinery中，配方是数据处理逻辑的唯一真相来源。命令行参数和环境变量只能控制执行上下文（如缓存根目录、日志级别、工作线程数），不能改变处理逻辑本身。\n\n唯一的例外是--seed参数，允许为临时运行指定不同的随机种子，便于进行敏感性分析。\n\n### 库与CLI的统一\n\nDataRefinery同时提供Python库和命令行工具两种使用方式，且底层使用相同的代码路径。这种设计确保了：\n\n- 交互式开发和生产部署的一致性\n- 不会因为代码路径分叉而产生行为差异\n- 用户可以根据场景选择最合适的接口\n\n## 典型工作流程\n\nDataRefinery的使用遵循四个清晰的步骤：\n\n### 1. 初始化（init）\n\n从原始数据自动生成初始配方：\n\nbash\ndatarefinery init --input my-images --output recipe.yaml\n\n\n系统会分析输入数据的结构（如图像分类任务中的文件夹层级），生成一个包含合理默认值的配方模板。\n\n### 2. 验证（validate）\n\n在正式执行前，先验证配方的正确性：\n\nbash\ndatarefinery validate recipe.yaml\n\n\n验证器会检查配方是否符合schema定义，以及是否满足各种静态约束（如必填字段、值范围、依赖关系等）。\n\n### 3. 物化（materialize）\n\n执行完整的数据处理流水线：\n\nbash\ndatarefinery --cache-root ./cache materialize recipe.yaml\n\n\n首次运行会执行完整的处理流程，并将结果存入缓存。后续如果配方和输入未变，将直接返回缓存实例。\n\n### 4. 状态检查（status）\n\n查看实例的详细信息：\n\nbash\ndatarefinery --cache-root ./cache status recipe.yaml\n\n\n可以获取记录数、数据分布、处理时间等元数据。\n\n## 缓存结构揭秘\n\n成功物化后，缓存目录的结构如下：\n\n\ncache/instances/<recipe-hash>/<input-hash>/<seed>/\n├── recipe.yaml # 实际使用的配方（规范化后的版本）\n├── manifest.json # 完整哈希、记录数、schema版本\n├── dataset/ # 准备好的数据集（如jsonl文件）\n├── fitted_statistics/ # 在训练集上拟合的统计量\n└── report/\n ├── report.md # 人类可读的摘要报告\n ├── drift.json # 用于下游漂移检测的稳定契约\n └── visualizations/ # 配方中声明的可视化图表\n\n\n这种结构清晰分离了数据、元数据和报告，便于审计和调试。\n\n## 高级特性\n\n### 多源数据整合\n\nDataRefinery支持从多个数据源整合数据。例如，图像数据存储在一个目录，标签存储在CSV文件中，可以通过image_flat类型和label_from配置实现自动关联。\n\n### 分区感知处理\n\n对于已经预分区好的数据集（如Kaggle常见的train/test划分），DataRefinery可以尊重原始分区，也可以在此基础上进行子划分（如从train中划分出validation）。\n\n### 统计量持久化\n\n数据归一化、标准化等操作需要的统计量（均值、标准差等）会在训练集上计算并持久化。推理时使用完全相同的统计量，避免训练-推理偏差。\n\n## 适用场景\n\n### 图像分类项目\n\nDataRefinery的一等公民类别是图像分类。无论是ImageFolder格式的数据，还是带有独立标签文件的平面目录，都能轻松处理。\n\n### 实验可复现性要求高的研究\n\n学术论文的实验结果需要能够被其他研究者复现。DataRefinery的可复现性保证使其成为学术研究的理想选择。\n\n### 团队协作的数据科学项目\n\n当多个数据科学家协作时，统一的数据处理规范至关重要。DataRefinery的配方文件天然适合版本控制，是团队协作的绝佳工具。\n\n### 生产环境的ML流水线\n\nDataRefinery的原子化操作和缓存机制，使其能够可靠地运行在生产环境中，作为ML流水线的一环。\n\n## 技术细节与依赖\n\nDataRefinery要求Python 3.12，使用现代Python特性提供类型安全和性能优化。项目使用pyve工具管理隔离的运行时环境和开发环境，确保依赖的清晰分离。\n\n测试覆盖率和代码质量通过GitHub Actions持续集成流程保证，Codecov提供覆盖率报告。\n\n## 与同类工具的对比\n\n相比传统的数据准备方式（如Jupyter Notebook中的自定义脚本），DataRefinery提供了：\n\n- 标准化：统一的数据处理范式\n- 可复现性：版本控制友好的配方文件\n- 效率：智能缓存避免重复计算\n- 可靠性：原子操作保证数据完整性\n\n相比其他ML数据工具（如TensorFlow Data Validation、Great Expectations），DataRefinery更专注于"准备"环节，而非"验证"环节，两者可以互补使用。\n\n## 结语\n\nDataRefinery代表了一种工程化的数据准备方法论。它提醒我们，数据准备不应该是一次性的、随意的手工作坊式工作，而应该是可复现、可维护、可协作的工程实践。\n\n对于正在寻找数据准备最佳实践的ML团队，DataRefinery提供了一个经过深思熟虑的解决方案。其声明式的设计理念、智能的缓存机制和原子化的操作保证，都值得深入研究和借鉴。

DataRefinery：声明式机器学习数据准备框架\n\n数据准备的痛点\n\n在机器学习项目中，数据准备往往是最耗时却又最容易被忽视的环节。数据科学家常常陷入这样的困境：\n\n- 重复劳动：每次新项目都要重新编写数据清洗代码\n- 版本混乱：训练数据和推理数据使用不同的处理逻辑，导致训练-推理偏差\n- 难以复现：Notebook中的处理步骤缺乏版本控制，几个月后就无法重现\n- 协作困难：团队成员对数据处理流程的理解不一致\n\nDataRefinery项目正是针对这些痛点，提出了一种全新的解决方案——基于配方的声明式数据准备。\n\n核心理念：配方驱动的工作流\n\nDataRefinery的核心思想可以用一句话概括：用声明式配方（Recipe）代替命令式代码。\n\n用户只需编写一个YAML格式的配方文件，描述"想要什么样的数据"，DataRefinery会自动处理"如何得到这些数据"。这种范式转变带来了诸多好处：\n\n配方即文档\n\n配方文件本身就是对数据处理流程的完整描述，无需额外的文档维护。新团队成员可以通过阅读配方快速理解数据处理逻辑。\n\n可复现性保证\n\n相同的配方 + 相同的输入 + 相同的随机种子 = 字节级一致的结果。DataRefinery将这一承诺作为核心设计目标，确保实验的可复现性。\n\n智能缓存\n\nDataRefinery会自动检测配方或输入数据的变化，只在必要时重新执行处理流程。未变化的步骤会直接使用缓存结果，大幅提升迭代效率。\n\n技术架构深度解析\n\n语义缓存机制\n\nDataRefinery的缓存系统是其最精妙的设计之一。缓存地址由三部分组成：\n\n1. 配方哈希：基于配方的语义内容（忽略空白字符和键值顺序）计算\n2. 输入哈希：原始输入数据的哈希值\n3. 随机种子：控制所有随机操作的可复现性\n\n这种设计意味着：\n\n- 仅修改配方的格式（如调整缩进、键值顺序）不会触发重建\n- 任何语义上的修改都会使缓存失效\n- 更换输入数据集会自动触发重新处理\n\n原子化操作\n\n数据处理流程遵循"先写临时目录，成功后原子提升"的原则。这意味着：\n\n- 处理过程中断不会留下部分完成的脏数据\n- 缓存中的实例永远是完整的、可用的\n- 并发执行不会导致数据竞争问题\n\n配方权威性原则\n\n在DataRefinery中，配方是数据处理逻辑的唯一真相来源。命令行参数和环境变量只能控制执行上下文（如缓存根目录、日志级别、工作线程数），不能改变处理逻辑本身。\n\n唯一的例外是--seed参数，允许为临时运行指定不同的随机种子，便于进行敏感性分析。\n\n库与CLI的统一\n\nDataRefinery同时提供Python库和命令行工具两种使用方式，且底层使用相同的代码路径。这种设计确保了：\n\n- 交互式开发和生产部署的一致性\n- 不会因为代码路径分叉而产生行为差异\n- 用户可以根据场景选择最合适的接口\n\n典型工作流程\n\nDataRefinery的使用遵循四个清晰的步骤：\n\n1. 初始化（init）\n\n从原始数据自动生成初始配方：\n\nbash\ndatarefinery init --input my-images --output recipe.yaml\n\n\n系统会分析输入数据的结构（如图像分类任务中的文件夹层级），生成一个包含合理默认值的配方模板。\n\n2. 验证（validate）\n\n在正式执行前，先验证配方的正确性：\n\nbash\ndatarefinery validate recipe.yaml\n\n\n验证器会检查配方是否符合schema定义，以及是否满足各种静态约束（如必填字段、值范围、依赖关系等）。\n\n3. 物化（materialize）\n\n执行完整的数据处理流水线：\n\nbash\ndatarefinery --cache-root ./cache materialize recipe.yaml\n\n\n首次运行会执行完整的处理流程，并将结果存入缓存。后续如果配方和输入未变，将直接返回缓存实例。\n\n4. 状态检查（status）\n\n查看实例的详细信息：\n\nbash\ndatarefinery --cache-root ./cache status recipe.yaml\n\n\n可以获取记录数、数据分布、处理时间等元数据。\n\n缓存结构揭秘\n\n成功物化后，缓存目录的结构如下：\n\n\ncache/instances/<recipe-hash>/<input-hash>/<seed>/\n├── recipe.yaml 实际使用的配方（规范化后的版本）\n├── manifest.json 完整哈希、记录数、schema版本\n├── dataset/ 准备好的数据集（如jsonl文件）\n├── fitted_statistics/ 在训练集上拟合的统计量\n└── report/\n ├── report.md 人类可读的摘要报告\n ├── drift.json 用于下游漂移检测的稳定契约\n └── visualizations/ 配方中声明的可视化图表\n\n\n这种结构清晰分离了数据、元数据和报告，便于审计和调试。\n\n高级特性\n\n多源数据整合\n\nDataRefinery支持从多个数据源整合数据。例如，图像数据存储在一个目录，标签存储在CSV文件中，可以通过image_flat类型和label_from配置实现自动关联。\n\n分区感知处理\n\n对于已经预分区好的数据集（如Kaggle常见的train/test划分），DataRefinery可以尊重原始分区，也可以在此基础上进行子划分（如从train中划分出validation）。\n\n统计量持久化\n\n数据归一化、标准化等操作需要的统计量（均值、标准差等）会在训练集上计算并持久化。推理时使用完全相同的统计量，避免训练-推理偏差。\n\n适用场景\n\n图像分类项目\n\nDataRefinery的一等公民类别是图像分类。无论是ImageFolder格式的数据，还是带有独立标签文件的平面目录，都能轻松处理。\n\n实验可复现性要求高的研究\n\n学术论文的实验结果需要能够被其他研究者复现。DataRefinery的可复现性保证使其成为学术研究的理想选择。\n\n团队协作的数据科学项目\n\n当多个数据科学家协作时，统一的数据处理规范至关重要。DataRefinery的配方文件天然适合版本控制，是团队协作的绝佳工具。\n\n生产环境的ML流水线\n\nDataRefinery的原子化操作和缓存机制，使其能够可靠地运行在生产环境中，作为ML流水线的一环。\n\n技术细节与依赖\n\nDataRefinery要求Python 3.12，使用现代Python特性提供类型安全和性能优化。项目使用pyve工具管理隔离的运行时环境和开发环境，确保依赖的清晰分离。\n\n测试覆盖率和代码质量通过GitHub Actions持续集成流程保证，Codecov提供覆盖率报告。\n\n与同类工具的对比\n\n相比传统的数据准备方式（如Jupyter Notebook中的自定义脚本），DataRefinery提供了：\n\n- 标准化：统一的数据处理范式\n- 可复现性：版本控制友好的配方文件\n- 效率：智能缓存避免重复计算\n- 可靠性：原子操作保证数据完整性\n\n相比其他ML数据工具（如TensorFlow Data Validation、Great Expectations），DataRefinery更专注于"准备"环节，而非"验证"环节，两者可以互补使用。\n\n结语\n\nDataRefinery代表了一种工程化的数据准备方法论。它提醒我们，数据准备不应该是一次性的、随意的手工作坊式工作，而应该是可复现、可维护、可协作的工程实践。\n\n对于正在寻找数据准备最佳实践的ML团队，DataRefinery提供了一个经过深思熟虑的解决方案。其声明式的设计理念、智能的缓存机制和原子化的操作保证，都值得深入研究和借鉴。