Data-Juicer 分布式任务执行问题分析与解决方案

问题背景

在使用 Data-Juicer 进行视频数据处理时，用户遇到了在 Ray 集群上执行分布式任务失败的问题。具体表现为当任务被调度到非 head 节点时会出现文件读写错误，而在 head 节点上则可以正常运行。

问题分析

通过错误日志可以观察到以下关键信息：

1. 文件路径问题：错误信息显示系统无法找到指定的输出文件路径 /root/data-juicer/outputs/demo/demo-processed-ray-videos/560_000000_000000.json，这表明 Ray 工作节点尝试访问本地文件系统时失败。

2. 模块导入问题：当非 head 节点未安装 Data-Juicer 时，会出现 No module named data-juicer 错误，这表明 Ray 工作节点需要完整的运行环境。

3. 路径解析问题：在配置文件中直接添加 local:// 前缀会导致路径解析错误，无法正确识别协议前缀。

根本原因

1. 环境一致性要求：Ray 分布式执行模式下，所有工作节点（包括 head 节点和 worker 节点）都必须安装相同版本的 Data-Juicer，否则会导致模块导入失败。

2. 文件系统共享机制：Ray 默认假设所有节点共享同一个文件系统（如 NFS）。当节点间没有共享文件系统时，直接使用本地路径会导致文件访问失败。

3. 路径协议处理：Ray 对带有协议前缀的路径有特殊处理逻辑，直接在配置文件中添加 local:// 会导致路径解析异常。

解决方案

1. 环境部署方案

确保 Ray 集群中的所有节点：

• 安装相同版本的 Data-Juicer
• 使用 pip install -v -e .[dist] 命令安装所有依赖
• 检查 Python 环境一致性

2. 文件系统处理方案

根据集群文件系统配置选择以下方案之一：

方案A：共享文件系统

• 配置 NFS 或其他共享文件系统
• 确保所有节点对共享路径有读写权限
• 使用普通路径（无需 local:// 前缀）

方案B：本地文件系统

• 修改 ray_executor.py，在代码层面为输出路径添加 local:// 前缀
• 注意这会集中所有 IO 到提交任务的节点，可能影响性能

3. 代码修改建议

对于使用本地文件系统的场景，可以在 ray_executor.py 中添加路径处理逻辑：

# 添加路径协议处理
if not self.cfg.export_path.startswith(('local://', 's3://', 'hdfs://')):
    self.cfg.export_path = 'local://' + self.cfg.export_path

最佳实践建议

1. 环境管理：使用容器化技术（如 Docker）确保所有节点环境一致
2. 文件系统选择：生产环境建议使用共享文件系统或对象存储
3. 路径处理：统一在代码中处理路径协议，而非配置文件中
4. 错误处理：增加对文件系统操作的错误捕获和重试机制
5. 性能监控：对于本地文件系统方案，需要特别关注 IO 性能指标

总结

Data-Juicer 在 Ray 集群上执行分布式任务时，需要特别注意环境一致性和文件系统访问问题。通过合理配置和代码调整，可以解决大多数分布式执行问题。对于生产环境，建议采用共享文件系统方案以获得更好的性能和可靠性。