Expériences de parité de chargement

Utilisez cette skill pour publier les sorties d'expériences de parité Harbor dans le dataset Hugging Face partagé et capturer l'URL de discussion résultante pour le champ parity_pr de l'adaptateur.

Pourquoi cette skill existe

hf upload-large-folder peut être lent ou peu fiable pour les grands bundles de parité car il pousse via la boucle de commit de l'API Hub.
Un clone git normal de harborframework/parity-experiments est trop coûteux car le dataset est très volumineux.
Les refs de PR de dataset Hugging Face sont différents des refs de PR GitHub et sont faciles à mal utiliser.
Les fichiers plus volumineux que 10 MiB doivent être suivis par Git LFS avant le push.

Cette skill évite le clone complet en extrayant uniquement le ref de PR cible avec --depth 1 --filter=blob:none et en vérifiant uniquement les chemins nécessaires pour l'adaptateur actuel.

Prérequis

Assurez-vous que l'authentification Hugging Face est disponible avec la permission d'écriture de discussion. Soit un token classique write, soit un token à granularité fine avec discussion.write global activé sur https://huggingface.co/settings/tokens. Un token en lecture seule ou à portée étroite causera un échec de create_pr.py avec HTTP 403.
Gardez le dataset cible fixé à harborframework/parity-experiments à moins que l'utilisateur demande explicitement un autre repo.
Acceptez toute source de chargement local qui contient déjà les fichiers finaux que l'utilisateur veut publier.

Workflow préféré

Créer ou réutiliser une PR de dataset.
Préparer un worktree local épars pour ce ref de PR.
Copier les résultats de parité locaux dans l'extraction éparsée.
S'assurer que chaque fichier plus volumineux que 10 MiB est suivi par Git LFS avant de committer.
Pousser directement vers le ref de PR avec git push brut.
Partager l'URL de discussion et l'enregistrer comme parity_pr de l'adaptateur.

Pour les grands bundles de parité, préférez git brut à hf upload-large-folder. Le chemin git brut est matériellement plus rapide et plus fiable car il évite la boucle de commit côté API et ne nécessite pas de cloner l'ensemble du dataset de parité.

1. Créer ou réutiliser une PR de dataset

Si l'utilisateur a déjà un numéro de PR de parité, réutilisez-le.

Sinon, créez-en une avec l'helper intégré :

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

Le script affiche du JSON incluant :

pr_number
discussion_url
repo_id

2. Préparer une extraction de PR éparsée

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

git init
git remote add origin git@hf.co: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>

Cela extrait uniquement le ref de PR et les chemins demandés au lieu de cloner le repo de dataset complet.

3. Copier les résultats locaux

Si le dossier local contient déjà la mise en page du repo-root final, copiez-le tel quel.

Si le dossier local contient uniquement le sous-arbre d'adaptateur, copiez-le dans adapters/<adapter_name>/ :

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

4. S'assurer que les gros fichiers utilisent Git LFS

Le .gitattributes du repo-root suit déjà par LFS les extensions binaires, modèles, archives et médias communes (*.bin, *.parquet, *.safetensors, images, audio, vidéo, *.log, *.txt, etc.). La plupart des sorties de parité sont couvertes automatiquement et ne nécessitent aucune action manuelle. Scannez l'extraction éparsée pour les fichiers plus volumineux que 10 MiB afin d'attraper tout ce qui aurait pu glisser :

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

Si un fichier est signalé et n'est pas déjà couvert par la racine, écrivez la règle LFS dans adapters/<adapter_name>/.gitattributes — jamais dans le .gitattributes du repo-root, qui est un hotspot de conflit de fusion partagé. Exécutez git lfs track dans le répertoire de l'adaptateur afin que la règle soit écrite avec un motif relatif :

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

Git LFS respecte les fichiers .gitattributes imbriqués, donc les règles ajoutées de cette manière s'appliquent uniquement à cet adaptateur et ne collisionnent jamais avec d'autres PR de parité en cours.

5. Committer et pousser

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. Enregistrer l'URL de discussion

Utilisez cette URL de discussion dans parity_experiment.json :

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

Surveillance et nouvelle tentative

Quand git push brut est en cours d'exécution, vérifiez d'abord la sortie en direct. Les gros pushes passent souvent beaucoup de temps dans :

git-lfs pre-push
uploads LFS d'objets uniques
compression de packfile

Vérifications utiles :

git ls-remote git@hf.co:datasets/harborframework/parity-experiments refs/pr/<number>

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

Si le push s'arrête prématurément :

réexécutez d'abord la commande git push exacte
si Hugging Face rejette un fichier plus volumineux que 10 MiB, ajoutez les règles git lfs track nécessaires, re-ajoutez le fichier et réessayez
si la connexion s'est coupée en plein push, réexécutez la même commande de push avant de changer quoi que ce soit d'autre

Fallback

Utilisez hf upload-large-folder uniquement comme fallback quand git brut n'est pas disponible ou que l'utilisateur le demande explicitement.

Vous pouvez toujours créer la PR avec l'helper intégré et télécharger vers la révision de 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

Garde-fous

Ne téléchargez pas le repo Harbor lui-même par accident. Téléchargez uniquement le dossier de résultats locaux prévu.
Ne revenez pas à un clone complet de harborframework/parity-experiments.
Ne modifiez pas le .gitattributes du repo-root. Mettez toute règle LFS spécifique à l'adaptateur dans adapters/<adapter_name>/.gitattributes à la place.
Supprimez ou excluez toujours .DS_Store.
Avant de pousser, assurez-vous que chaque fichier plus volumineux que 10 MiB est suivi par LFS.
Si l'utilisateur a déjà un numéro de PR de parité, réutilisez-le au lieu d'en créer un autre.

upload-parity-experiments