upload-parity-experiments

上传 Parity 实验

使用此技能，将 Harbor parity 实验输出发布到共享的 Hugging Face 数据集，并记录生成的讨论 URL，以填入适配器的 parity_pr 字段。

此技能的用途

• 对于大型 parity 包，hf upload-large-folder 可能很慢或不可靠，因为它需要通过 Hub API 提交循环来推送文件。
• 普通的 harborframework/parity-experiments git 克隆成本太高，因为该数据集非常庞大。
• Hugging Face 数据集 PR 引用与 GitHub PR 引用不同，很容易误用。
• 大于 10 MiB 的文件必须先由 Git LFS 跟踪，然后才能推送。

此技能无需完整克隆，而是通过 --depth 1 --filter=blob:none 仅获取目标 PR 引用，并且只检出当前适配器所需的路径。

前置条件

• 确保 Hugging Face 身份验证可用，且拥有讨论写入权限。可以使用经典的 write 令牌，也可以使用在 https://huggingface.co/settings/tokens 启用了全局 discussion.write 权限的细粒度令牌。只读令牌或权限范围过窄的令牌会导致 create_pr.py 失败并返回 HTTP 403。
• 除非用户明确要求使用其他仓库，否则将目标数据集固定为 harborframework/parity-experiments。
• 接受任何已包含用户想要发布的最终文件的本地上传源。

首选工作流

1. 创建或复用一个数据集 PR。
2. 为该 PR 引用准备一个稀疏本地工作树。
3. 将本地 parity 结果复制到稀疏检出目录中。
4. 确保提交前，所有大于 10 MiB 的文件都由 Git LFS 跟踪。
5. 使用原始 git push 直接推送到 PR 引用。
6. 分享讨论 URL，并将其记录为适配器的 parity_pr。

对于大型 parity 包，优先使用原始 git，而不是 hf upload-large-folder。原始 git 方式速度明显更快、可靠性更高，因为它避免了 API 端的提交循环，也无需克隆整个 parity 数据集。

1. 创建或复用数据集 PR

如果用户已经有 parity PR 编号，请复用该 PR。

否则，使用随附的辅助脚本创建一个：

uv run python scripts/create_pr.py create-pr \
  --title "Add parity experiments for <adapter_name>" \
  --description-file /path/to/pr-description.md

该脚本会输出 JSON，其中包括：

• pr_number
• discussion_url
• repo_id

2. 准备稀疏 PR 检出目录

mkdir -p /tmp/parity-experiments-pr<number>
cd /tmp/parity-experiments-pr<number>

git init
git remote add origin [email protected]:datasets/harborframework/parity-experiments
git config core.sparseCheckout true
git sparse-checkout init --cone
git sparse-checkout set adapters/<adapter_name>

git fetch --depth 1 --filter=blob:none origin refs/pr/<number>:pr/<number>
git checkout pr/<number>

此命令只获取 PR 引用和请求的路径，而不是克隆完整的数据集仓库。

3. 复制本地结果

如果本地文件夹已经包含最终的仓库根目录布局，请原样复制。

如果本地文件夹仅包含适配器子目录，请将其复制到 adapters/<adapter_name>/：

rsync -a --delete \
  --exclude '.git' \
  --exclude '.cache' \
  --exclude '.DS_Store' \
  /path/to/local-folder/ \
  adapters/<adapter_name>/

4. 确保大文件使用 Git LFS

仓库根目录的 .gitattributes 已通过 LFS 跟踪常见的二进制文件、模型、归档文件和媒体文件扩展名（*.bin、*.parquet、*.safetensors、图像、音频、视频、*.log、*.txt 等）。大多数 parity 输出都已自动涵盖，无需手动操作。扫描稀疏检出目录，找出大于 10 MiB 的文件，检查是否有遗漏：

python - <<'PY'
from pathlib import Path

for path in sorted(Path(".").rglob("*")):
    if path.is_file() and ".git" not in path.parts and path.stat().st_size > 10 * 1024 * 1024:
        print(path)
PY

如果有文件被标记，且尚未由根目录的规则涵盖，请将 LFS 规则写入 adapters/<adapter_name>/.gitattributes，切勿写入仓库根目录的 .gitattributes，因为该文件是多人共享且容易发生合并冲突的位置。在适配器目录内运行 git lfs track，以相对模式写入规则：

(cd adapters/<adapter_name> && git lfs track "<pattern>")
git add adapters/<adapter_name>/.gitattributes

Git LFS 会遵循嵌套的 .gitattributes 文件，因此以此方式添加的规则仅适用于该适配器，不会与其他正在进行的 parity PR 冲突。

5. 提交并推送

find . -name .DS_Store -delete
git add adapters/<adapter_name>
git commit -m "Add parity experiment artifacts for <adapter_name>"
GIT_SSH_COMMAND='ssh -o ServerAliveInterval=30 -o ServerAliveCountMax=10' \
  git push origin pr/<number>:refs/pr/<number>

6. 记录讨论 URL

在 parity_experiment.json 中使用此讨论 URL：

https://huggingface.co/datasets/harborframework/parity-experiments/discussions/<number>

监控与重试

运行原始 git push 时，请先检查实时输出。大型推送通常会在以下步骤耗费较长时间：

• git-lfs pre-push
• 单个对象的 LFS 上传
• packfile 压缩

有用的检查：

git ls-remote [email protected]:datasets/harborframework/parity-experiments refs/pr/<number>

ps -p <pid> -o pid=,etime=,command=

如果推送提前退出：

• 先重新运行完全相同的 git push 命令
• 如果 Hugging Face 拒绝了大于 10 MiB 的文件，请添加所需的 git lfs track 规则，重新添加该文件，然后重试
• 如果连接在推送过程中断开，请先重新运行相同的推送命令，再进行其他更改

备用方案

仅当原始 git 不可用或用户明确要求时，才将 hf upload-large-folder 用作备用方案。

你仍可使用捆绑的辅助工具创建 PR，并上传到该 PR 的修订版本：

hf upload-large-folder harborframework/parity-experiments \
  <local-folder> \
  --repo-type dataset \
  --revision refs/pr/<pr-number> \
  --exclude ".DS_Store" \
  --exclude "**/.DS_Store" \
  --num-workers 8

注意事项

• 不要误将 Harbor 仓库本身上传。只上传预期的本地结果文件夹。
• 不要回退到完整克隆 harborframework/parity-experiments。
• 不要修改仓库根目录的 .gitattributes。应将适配器专用的 LFS 规则放在 adapters/<adapter_name>/.gitattributes 中。
• 始终移除或排除 .DS_Store。
• 推送前，请确保所有大于 10 MiB 的文件都由 LFS 跟踪。
• 如果用户已有 parity PR 编号，请复用该 PR，而不要另建一个。