【ModelScope-1】数据集稀疏检出（Sparse Checkout）来下载指定目录

ModelScope 数据集稀疏检出（Sparse Checkout）完整指南

前言

从 ModelScope 下载大型数据集时，通常只需要部分目录。使用 Git 的稀疏检出（Sparse Checkout）可以只下载需要的目录，节省时间和空间。

一、什么是稀疏检出？

稀疏检出（Sparse Checkout）是 Git 的功能，允许只检出仓库中的指定目录或文件，而不是整个仓库。对于大型数据集，这能显著减少下载时间和存储占用。

二、为什么需要稀疏检出？

• 节省空间：大型数据集可能包含 TB 级数据，但通常只需要部分目录
• 节省时间：只下载需要的文件，下载速度更快
• 提高效率：避免下载不必要的数据

三、完整流程

3.1 准备工作

1. 获取 OAuth Token

   • 在 ModelScope 网页上获取 OAuth token
   • 格式通常为：ms-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

2. 确认目标目录和空间

   # 检查目标目录所在文件系统的空间
   df -h <target_directory>

3.2 克隆仓库（稀疏模式）

# 进入目标目录
cd <target_directory>

# 克隆仓库（使用 sparse 和 filter 选项）
git clone --filter=blob:none --sparse \
  https://oauth2:YOUR_TOKEN@www.modelscope.cn/datasets/USERNAME/DATASET_NAME.git \
  temp_clone

参数说明：

• --filter=blob:none：不下载文件内容，只获取元数据
• --sparse：启用稀疏检出模式
• oauth2:YOUR_TOKEN：使用 OAuth token 进行认证
• temp_clone：本地目录名（可自定义）

3.3 初始化稀疏检出

# 进入克隆的目录
cd temp_clone

# 初始化稀疏检出（cone 模式，推荐）
git sparse-checkout init --cone

--cone 模式：

• 性能更好
• 只匹配指定路径及其子目录
• 适合大多数场景

3.4 设置要检出的目录

# 设置只检出特定目录
git sparse-checkout set path/subpath

执行后，Git 会：

• 只下载指定目录下的文件
• 工作区只显示该目录
• 其他目录不会出现在本地

3.5 验证下载结果

# 查看设置的路径
git sparse-checkout list

# 检查下载的文件
ls -lh path/subpath | head

# 统计文件数量（如果是图片文件）
find path/subpath -type f -name "*.png" | wc -l

四、完整示例

示例 1：下载特定子目录

# 1. 进入目标目录
cd <target_directory>

# 2. 克隆仓库
git clone --filter=blob:none --sparse \
  https://oauth2:YOUR_TOKEN@www.modelscope.cn/datasets/USERNAME/DATASET_NAME.git \
  temp_clone

# 3. 进入目录并初始化
cd temp_clone
git sparse-checkout init --cone

# 4. 设置要下载的目录（替换为实际路径）
git sparse-checkout set path/subpath

# 5. 等待下载完成

示例 2：下载多个目录

cd <target_directory>

git clone --filter=blob:none --sparse \
  https://oauth2:YOUR_TOKEN@www.modelscope.cn/datasets/USERNAME/DATASET_NAME.git \
  temp_clone

cd temp_clone
git sparse-checkout init --cone

# 设置第一个目录
git sparse-checkout set path1/subpath1

# 添加第二个目录
git sparse-checkout add path2/subpath2

五、常用命令

查看当前设置

# 查看已设置的稀疏检出路径
git sparse-checkout list

添加更多路径

# 添加额外的目录
git sparse-checkout add another/path/to/directory

禁用稀疏检出

# 禁用稀疏检出（恢复完整检出）
git sparse-checkout disable

重新设置路径

# 如果下载中断，可以重新执行
git sparse-checkout set path/subpath

六、常见问题与解决方案

问题 1：磁盘空间不足

错误信息：

error: unable to write file
write error: no space left on device

解决方案：

# 1. 检查当前目录所在文件系统
df -h .

# 2. 如果根分区已满，移动到有空间的分区
# 例如：移动到 /data 或其他有足够空间的分区
cd <target_directory_with_space>
# 然后重新克隆

问题 2：认证失败

错误信息：

fatal: Authentication failed

解决方案：

• 检查 OAuth token 是否正确
• 确认 token 是否过期
• 重新从 ModelScope 获取 token

问题 3：下载中断

如果下载过程中断，可以：

# 重新执行 sparse-checkout set
git sparse-checkout set path/subpath

# 或者清理后重新开始
rm -rf temp_clone
# 然后重新执行完整流程

问题 4：部分文件下载失败

# 清理并重新设置
git sparse-checkout disable
git sparse-checkout set path/subpath

七、最佳实践

1. 空间检查：下载前确认目标文件系统有足够空间
2. 使用 --filter=blob:none：减少初始下载时间
3. 使用 --cone 模式：提升性能
4. 监控下载进度：大型数据集下载可能需要较长时间
5. 保留 token 安全：不要将 token 提交到代码仓库

八、技术原理

稀疏检出的工作原理

1. 元数据下载：Git 先下载所有文件的元数据（索引）
2. 路径匹配：根据 sparse-checkout 配置匹配路径
3. 选择性下载：只下载匹配路径下的文件内容
4. 工作区限制：工作区只显示匹配的文件

--filter=blob:none 的作用

• 不下载文件内容（blob），只获取对象索引
• 大幅减少初始克隆时间
• 在 sparse-checkout set 时才下载实际文件

九、变量说明

在本文档中使用的占位符：

• <target_directory>：目标工作目录，例如 /data/datasets 或 /fi-lib/workspace/project/data
• path/subpath：仓库中要下载的相对路径，例如 dataset/images 或 model/checkpoints
• YOUR_TOKEN：ModelScope OAuth token
• USERNAME：ModelScope 用户名或组织名
• DATASET_NAME：数据集仓库名称

十、总结

使用 Git 稀疏检出从 ModelScope 下载数据集的主要步骤：

1. 使用 --filter=blob:none --sparse 克隆仓库
2. 使用 git sparse-checkout init --cone 初始化
3. 使用 git sparse-checkout set path/subpath 指定要下载的目录
4. 验证下载结果

这种方法可以显著减少下载时间和存储空间，适合只需要部分数据集的场景。

---

注意事项：

• 确保有足够的磁盘空间
• 妥善保管 OAuth token
• 大型数据集下载可能需要数小时，建议使用 screen 或 tmux 保持会话

参考资源：

• Git Sparse Checkout 官方文档
• ModelScope 官方文档