切换Git分支后执行dvc checkout遇S3文件缺失错误求助

问题场景 #

项目结构：

myproject
-- projectA
   -- .dvc
   ...
-- ProjectB
   -- .dvc
   ...

在projectA子目录初始化DVC并创建branch-1，完成远程存储和缓存配置：

cd projectA && dvc init --subdir
dvc remote add -d awsstorage s3://mlops-artifacts
dvc remote add s3cache s3://mlops-artifacts/cache
dvc config cache.s3 s3cache

git add projectA/.dvc/config
git commit -m "configure remote storage and cache"
git push

关联S3上的数据集和模型输出：

dvc add --external awsstorage s3://mlops-artifacts/dataset
dvc add --external awsstorage s3://mlops-artifacts/output

git add projectA/dataset.dvc projectA/output.dvc
git commit -m "configure data and model output"
git push

创建branch-2后，修改数据并上传到同一S3路径，重新执行上述配置步骤。切换回branch-1执行dvc checkout时出现错误：

Error: checkout failed for following targets:
s3://mlops-artifacts/dataset/training.csv
s3://mlops-artifacts/output/model.tar

Is your cache up to date?

问题原因 #

branch-2上传的新数据覆盖了S3同一路径下的原始文件，而branch-1的.dvc文件记录的是原始文件的哈希值。当前S3路径下的文件哈希与branch-1的记录不匹配，且远程缓存s3cache中未保存原始文件的版本，导致DVC无法找到对应文件。

解决方案 #

临时修复：恢复branch-1的原始文件版本 #

如果本地保留了branch-1的原始数据集和模型文件，可通过以下步骤同步到缓存：

# 切换回branch-1
git checkout branch-1
# 将本地原始文件重新关联到S3路径并同步到缓存
dvc add dataset --out s3://mlops-artifacts/dataset
dvc add output --out s3://mlops-artifacts/output
# 推送缓存到远程缓存存储
dvc push --cache-only

完成后执行dvc checkout即可正常获取文件。

长期方案：隔离分支的外部存储路径 #

为避免分支间互相覆盖文件，给每个分支分配独立的S3存储目录：

1. 在branch-1中修改外部关联路径：

# 移除旧的外部关联文件
dvc remove dataset.dvc output.dvc
# 关联带分支标识的S3路径
dvc add --external awsstorage s3://mlops-artifacts/branch-1/dataset
dvc add --external awsstorage s3://mlops-artifacts/branch-1/output
# 提交变更到Git
git add dataset.dvc output.dvc
git commit -m "use branch-specific S3 path for data and model"
git push

2. 在branch-2中执行同样操作，使用s3://mlops-artifacts/branch-2/dataset和s3://mlops-artifacts/branch-2/output路径，实现分支间文件完全隔离。

补充配置：确保缓存保存所有版本 #

检查并配置DVC缓存，确保所有文件版本都被推送到远程缓存：

# 确认缓存远程配置正确
dvc config cache.s3 s3cache
# 推送当前分支的所有缓存文件到远程缓存
dvc push --cache-only

后续即使外部路径文件被修改，dvc checkout也能从远程缓存中恢复对应版本的文件。

内容的提问来源于stack exchange，提问作者haju