upload-parity-experiments

アップロードのパリティ実験

このスキルを使って、Harbor のパリティ実験の出力を共有 Hugging Face データセットに公開し、アダプターの parity_pr フィールドに記録するディスカッション URL を取得します。

このスキルが必要な理由

• 大規模なパリティバンドルでは、Hub API のコミットループを経由するため、hf upload-large-folder の処理が遅くなったり、安定しなかったりすることがあります。
• harborframework/parity-experiments を通常の方法で git clone すると、データセットが非常に大きいため、コストがかかりすぎます。
• Hugging Face のデータセット PR ref は GitHub の PR ref とは異なり、誤用しやすくなっています。
• 10 MiB を超えるファイルは、プッシュする前に Git LFS で追跡する必要があります。

このスキルでは、--depth 1 --filter=blob:none を指定して対象の PR ref のみを取得し、現在のアダプターに必要なパスのみをチェックアウトすることで、リポジトリ全体のクローンを回避します。

前提条件

• Hugging Face の認証でディスカッションへの書き込み権限が利用できることを確認してください。classic write トークン、または https://huggingface.co/settings/tokens でグローバルな discussion.write を有効にした fine-grained トークンを使用してください。読み取り専用トークンやスコープが限定されたトークンでは、create_pr.py が HTTP 403 で失敗します。
• ユーザーが別のリポジトリを明示的に指定しない限り、対象データセットは harborframework/parity-experiments に固定してください。
• 公開したい最終ファイルがすでに含まれているローカルのアップロード元は、どれでも使用できます。

推奨ワークフロー

1. データセット PR を作成するか、既存のものを再利用します。
2. その PR ref 用のスパースなローカルワークツリーを準備します。
3. ローカルのパリティ結果をスパースチェックアウトにコピーします。
4. 10 MiB を超えるすべてのファイルが、コミット前に Git LFS で追跡されていることを確認します。
5. raw git push で PR ref に直接プッシュします。
6. ディスカッション URL を共有し、アダプターの parity_pr に記録します。

大規模なパリティバンドルでは、hf upload-large-folder より raw git を優先してください。API 側のコミットループを回避でき、パリティデータセット全体をクローンする必要もないため、raw git を使う方法の方が大幅に高速で安定しています。

1. データセット PR の作成または再利用

ユーザーがすでにパリティ 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 ref と指定されたパスのみを取得します。

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 では、一般的なバイナリ、モデル、アーカイブ、メディアの拡張子（*.bin、*.parquet、*.safetensors、画像、音声、動画、*.log、*.txt など）がすでに Git LFS で追跡されています。ほとんどのパリティ出力は自動的に対象となるため、手動での対応は不要です。対象から漏れたファイルを見つけるため、スパースチェックアウトで 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 ファイルを認識するため、この方法で追加したルールは該当アダプターのみに適用され、他の進行中のパリティ 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 を記録

次のディスカッション URL を parity_experiment.json で使用してください。

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

モニタリングと再試行

生の git push が実行中の場合は、まずライブ出力を確認してください。大規模なプッシュでは、次の処理に長い時間がかかることがよくあります。

• git-lfs pre-push
• 単一オブジェクトの LFS アップロード
• パックファイルの圧縮

確認に役立つコマンド：

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 を再利用してください。