Dosyaları Hub'a yükle

Dosyalarınızı ve çalışmalarınızı paylaşmak, Hub'ın önemli bir parçasıdır. huggingface_hub, dosyalarınızı Hub'a yüklemek için çeşitli seçenekler sunar. Bu işlevleri bağımsız olarak kullanabilir veya kütüphanenize entegre ederek kullanıcılarınızın Hub ile etkileşimini daha pratik hale getirebilirsiniz.

Hub'a dosya yüklemek istediğinizde, Hugging Face hesabınıza giriş yapmanız gerekir. Kimlik doğrulama hakkında daha fazla ayrıntı için bu bölümü inceleyin.

Bir dosya yükle

create_repo() ile bir depo oluşturduktan sonra, upload_file() kullanarak dosyanızı deponuza yükleyebilirsiniz.

Yüklemek istediğiniz dosyanın yolunu, dosyanın depoda nereye yükleneceğini ve dosyayı eklemek istediğiniz depoyun adını belirtin. Depo türünüze bağlı olarak, depo türünü isteğe bağlı olarak dataset, model veya space olarak ayarlayabilirsiniz.

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.upload_file(
...     path_or_fileobj="/path/to/local/folder/README.md",
...     path_in_repo="README.md",
...     repo_id="username/test-dataset",
...     repo_type="dataset",
... )

Bir klasör yükleyin

upload_folder() işlevini kullanarak yerel bir klasörü mevcut bir depoya yükleyin. Yüklemek istediğiniz yerel klasörün yolunu, klasörü depoda nereye yüklemek istediğinizi ve klasörü eklemek istediğiniz depoyu belirtin. Depo türünüze bağlı olarak, depo türünü isteğe bağlı olarak dataset, model veya space olarak ayarlayabilirsiniz.

>>> from huggingface_hub import HfApi
>>> api = HfApi()

# Upload all the content from the local folder to your remote Space.
# By default, files are uploaded at the root of the repo
>>> api.upload_folder(
...     folder_path="/path/to/local/space",
...     repo_id="username/my-cool-space",
...     repo_type="space",
... )

Varsayılan olarak, hangi dosyaların commit edileceğini belirlemek için .gitignore dosyası dikkate alınır. Varsayılan olarak bir commit'te .gitignore dosyasının var olup olmadığını kontrol ederiz; eğer yoksa Hub'da mevcut olup olmadığını kontrol ederiz. Lütfen yalnızca dizinin kökünde bulunan bir .gitignore dosyasının kullanılacağını bilin. Alt dizinlerdeki .gitignore dosyalarını kontrol etmiyoruz.

Sabit bir .gitignore dosyası kullanmak istemiyorsanız, yükleyeceğiniz dosyaları filtrelemek için allow_patterns ve ignore_patterns argümanlarını kullanabilirsiniz. Bu parametreler tek bir desen veya desen listesi kabul eder. Desenler, burada belgelenen Standart Jolly Jokerler (globbing desenleri)dir. Hem allow_patterns hem de ignore_patterns sağlanırsa, her iki kısıt da uygulanır.

.gitignore dosyasının ve izin ver/yoksay desenlerinin yanı sıra, herhangi bir alt dizinde bulunan .git/ klasörü de yoksayılır.

>>> api.upload_folder(
...     folder_path="/path/to/local/folder",
...     path_in_repo="my-dataset/train", # Upload to a specific folder
...     repo_id="username/test-dataset",
...     repo_type="dataset",
...     ignore_patterns="**/logs/*.txt", # Ignore all text logs
... )

Aynı commit'te depodan silmek istediğiniz dosyaları belirtmek için delete_patterns argümanını da kullanabilirsiniz. Uzak bir klasöre dosya göndermeden önce onu temizlemek istiyorsanız ve hangi dosyaların zaten mevcut olduğunu bilmiyorsanız bu işe yarayabilir.

Aşağıdaki örnek, yerel ./logs klasörünü uzak /experiment/logs/ klasörüne yükler. Yalnızca txt dosyaları yüklenir ancak bunun öncesinde, depodaki tüm önceki günlükler silinir. Tüm bunlar tek bir commit ile yapılır.

>>> api.upload_folder(
...     folder_path="/path/to/local/folder/logs",
...     repo_id="username/trained-model",
...     path_in_repo="experiment/logs/",
...     allow_patterns="*.txt", # Upload all local text files
...     delete_patterns="*.txt", # Delete all remote text files before
... )

Dosyaların nasıl yüklendiği

hf_xet yüklendiğinde (varsayılan olarak yüklenir), upload_folder() dosyaları bir akış hattı üzerinden yükler: dosyalar Hub ile karşılaştırılır, Xet depolama altyapısına yüklenir (bu altyapı parçalama, kopya kaldırma ve yeniden deneme işlemlerini içsel olarak gerçekleştirir) ve uyumlu toplu işlemlerle taahhüt edilir; tüm bu adımlar paralel olarak çalışır. Pratikte bu şu anlama gelir:

• Herhangi bir boyutta klasörler: küçük klasörler tek bir commit ile yüklenirken, çok sayıda dosya içeren klasörler sunucu sınırlarının altında kalmak için otomatik olarak birden fazla commit'e bölünür. Bu durum gerçekleştiğinde, takip eden commit'lerin commit mesajına (part 2), (part 3), … eki eklenir.
• Yeniden başlatılabilir: Yükleme herhangi bir nedenle kesilirse, aynı çağrıyı yeniden çalıştırmanız yeterlidir. Zaten taahhüt edilen dosyalar algılanır ve atlanır, daha önce yüklenen parçalar ise yinelenme önlenir — bunları yeniden yüklemek (neredeyse) veri aktarımı gerektirmez. Yerel durum devreye girmez: farklı bir makineden bile devam edebilirsiniz. Bir istisna: create_pr=True kullanıldığında, yeniden çalıştırma yeni bir çekme isteği açar. Yükleme sırasında devam ederken bunun yerine revision="refs/pr/N" ile yeniden çalıştırmayı öneririz.
• Çift okuma yok: dosyalar, yükleme için parçalara ayrılırken tek bir okuma geçişinde özetlenir. Yükleme başlamadan önce ayrı bir “özetleme” aşaması yoktur.

Canlı bir ilerleme göstergesi, üç aşamayı takip eder:

Found 5,000 files to upload
  Preparing   ████████████████████  5,000 / 5,000 ✓
  Uploading   ██████████████░░░░░░  423 / 603 files  3.8GB · 19.7MB/s
  Committing  ██████████████████░░  4,580 / 5,000  6 commits

hf_xet yüklü değilse, upload_folder() eski davranışa geri döner: önce her şeyi özetler, HTTP üzerinden yükler, ardından tek bir commit oluşturur. Daha iyi sağlamlık için hf_xet'in her zaman yüklü tutulmasını öneririz.

CLI'den yükle

Dosyaları Hub'a doğrudan yüklemek için terminalden hf upload komutunu kullanabilirsiniz. Bu komut, dahili olarak yukarıda açıklanan upload_file() ve upload_folder() yardımcı işlevlerini kullanır.

Tek bir dosya veya tüm bir klasör yükleyebilirsiniz:

# Usage:  hf upload [repo_id] [local_path] [path_in_repo]
>>> hf upload Wauplin/my-cool-model ./models/model.safetensors model.safetensors
https://huggingface.co/Wauplin/my-cool-model/blob/main/model.safetensors

>>> hf upload Wauplin/my-cool-model ./models .
https://huggingface.co/Wauplin/my-cool-model/tree/main

local_path ve path_in_repo isteğe bağlıdır ve dolaylı olarak çıkarılabilir. local_path ayarlanmadıysa, araç, repo_id ile aynı adı taşıyan bir yerel klasör veya dosya olup olmadığını kontrol eder. Bu durum geçerliyse, içeriği yüklenir. Aksi takdirde, kullanıcıdan local_path değerini açıkça ayarlamasını isteyen bir istisna oluşturulur. Her durumda, path_in_repo ayarlanmadıysa dosyalar, depoyun kök dizinine yüklenir.

Hedef, hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] dilbilgisini izleyen tek bir hf:// URI olarak da ifade edilebilir (tam sözdizimi için HF URI referansına bakın). Bu durumda depo türü, revizyon ve path_in_repo URI'den okunur; bu yöntem --repo-type ve --revision seçenekleriyle birleştirilemez:

# Upload a single file to a dataset on a specific branch
>>> hf upload hf://datasets/Wauplin/my-cool-dataset@my-branch/data/train.csv ./train.csv
https://huggingface.co/datasets/Wauplin/my-cool-dataset/blob/my-branch/data/train.csv

Büyük dosyalarda maksimum yükleme hızı için HF_XET_HIGH_PERFORMANCE=1 ortam değişkenini ayarlayın. Bu, hf_xet'in yüksek performans modunu etkinleştirir; bu mod, kullanılabilir bant genişliğini ve CPU çekirdeklerini doyum noktasına getirir. Not: hf_transfer, hf_xet lehine kaldırıldığından, eski HF_HUB_ENABLE_HF_TRANSFER=1 bayrağı artık kullanılmamaktadır — bunun yerine HF_XET_HIGH_PERFORMANCE=1 ayarlayın.

CLI yükleme komutu hakkında daha fazla ayrıntı için lütfen CLI kılavuzuna başvurun.

Büyük bir klasör yükleyin

upload_folder() ve hf upload komutu, çok büyük klasörler dahil olmak üzere dosyaları Hub'a yüklemek için başvurulan çözümlerdir. Dosyalar Hub'a birden çok commit ile aktarılır ve işlem yarıda kalırsa otomatik olarak devam eder. Aynı çağrıyı yeniden çalıştırmanız yeterlidir; zaten yüklenmiş dosyalar atlanır.

>>> api.upload_folder(
...     repo_id="HuggingFaceM4/Docmatix",
...     repo_type="dataset",
...     folder_path="/path/to/local/docmatix",
... )

veya terminalden:

hf upload HuggingFaceM4/Docmatix --repo-type=dataset /path/to/local/docmatix

Büyük yüklemeler için ipuçları ve püf noktaları

Deponuzda büyük miktarda veriyle çalışırken dikkate almanız gereken bazı kısıtlamalar vardır. Verilerin akışının (stream) alması gereken süre göz önüne alındığında, yükleme/itme (push) işleminin sürecin sonunda başarısız olması veya hf.co üzerinde ya da yerel çalışırken performans düşüklüğü yaşamanız son derece sinir bozucu olabilir.

Hub'da depolarınızı nasıl yapılandırmanız gerektiğine dair en iyi uygulamalar için Depo kısıtlamaları ve önerileri rehberimize göz atın. Yüklemenizi olabildiğince sorunsuz hale getirmek için pratik ipuçlarıyla devam edelim.

• Küçük başlayın: Yükleme betiğinizi test etmek için küçük miktarda veriyle başlamanızı öneririz. Hata almanın az zaman aldığı durumlarda betik üzerinde tekrarlamak daha kolaydır.
• Başarısızlıkları bekleyin: Büyük miktarda verinin akışını yönetmek zordur. Ne olacağını bilemezsiniz, ancak makinenizden, bağlantınızdan veya sunucularımızdan kaynaklanıyor olsun olmasın, en az bir kez bir şeyin başarısız olacağını dikkate almak her zaman en iyisidir. Örneğin, çok sayıda dosya yüklemeyi planlıyorsanız, bir sonraki partiyi yüklemeye başlamadan önce hangi dosyaları zaten yüklediğinizi yerel olarak takip etmeniz en iyisidir. Zaten commit edilmiş bir LFS dosyasının asla iki kez yüklenmeyeceği garanti edilir, ancak bunu istemci tarafında kontrol etmek yine de biraz zaman kazandırabilir. upload_folder() tam olarak bunu sizin için yapar.
• hf_xet kullanın: Bu, Hub için yeni depolama altyapısını kullanır, Rust ile yazılmıştır ve artık herkesin kullanımına açıktır. Nitekim hf_xet, huggingface_hub kullanıldığında varsayılan olarak zaten etkinleştirilmiştir! Maksimum performans için HF_XET_HIGH_PERFORMANCE=1 değerini bir ortam değişkeni olarak ayarlayın. Yüksek performans modu etkinleştirildiğinde aracın tüm kullanılabilir bant genişliğini ve CPU çekirdeklerini kullanmaya çalışacağını unutmayın.

Gelişmiş özellikler

Çoğu durumda, dosyalarınızı Hub'a yüklemek için upload_file() ve upload_folder() yeterli olacaktır. Ancak huggingface_hub, işleri kolaylaştıran daha gelişmiş özelliklere sahiptir. Bunlara bir göz atalım!

Daha Hızlı Yüklemeler

hf_xet sayesinde daha hızlı yüklemelerden yararlanın. hf_xet, parça tabanlı kopya azaltma (deduplication) ile daha hızlı yükleme ve indirme imkanı sağlayan xet-core kütüphanesinin Python bağlamasıdır. hf_xet, huggingface_hub ile kusursuz bir şekilde entegre olur ancak LFS yerine Rust xet-core kütüphanesini ve Xet depolamayı kullanır.

hf_xet, dosyaları değişmez parçalara ayıran, bu parçaların koleksiyonlarını (bloklar veya xorblar olarak adlandırılır) uzaktan depolayan ve istendiğinde dosyayı yeniden birleştirmek için onları getiren Xet depolama sistemini kullanır. Yükleme sırasında, kullanıcının bu repoya yazma yetkisine sahip olduğu doğrulandıktan sonra hf_xet, dosyaları tarar, onları parçalarına ayırır ve bu parçaları xorblara toplar (bilinen parçalar arasında kopya azaltma yapar), ardından bu xorbları Xet içerik-adreslenebilir servisine (CAS) yükler. CAS, xorbların bütünlüğünü doğrular, xorbların meta verilerini LFS SHA256 özetleriyle birlikte kaydeder (arama/indirme desteği için) ve xorbları uzak depolamaya yazar.

Bunu etkinleştirmek için huggingface_hub'ün en son sürümünü kurmanız yeterlidir:

pip install -U "huggingface_hub"

huggingface_hub 0.32.0 sürümünden itibaren bu, hf_xet paketini de yükleyecektir.

Diğer tüm huggingface_hub API'leri herhangi bir değişiklik yapılmadan çalışmaya devam edecektir. Xet depolamanın ve hf_xet'in avantajları hakkında daha fazla bilgi edinmek için bu bölüme bakın.

Küme / Dağıtık Dosya Sistemi Yükleme Düşünceleri

Kümeden yükleme sırasında, yüklenen dosyalar genellikle dağıtık veya ağ tabanlı bir dosya sisteminde (NFS, EBS, Lustre, Fsx vb.) bulunur. Xet depolama, bu dosyaları parçalara (chunk) ayırır ve bunları bloklara (xorblara da denir) yerel olarak yazar; blok tamamlandığında yüklemeyi başlatır. Dağıtık bir dosya sisteminden yükleme sırasında performansı iyileştirmek için HF_XET_CACHE değerini yerel bir diskte (ör. yerel bir NVMe veya SSD disk) bulunan bir dizine ayarladığınızdan emin olun. Xet önbelleğinin varsayılan konumu, (~/.cache/huggingface/xet) altında HF_HOME içindedir ve bu konum, kullanıcı ana dizininde olduğu için genellikle dağıtık dosya sisteminde de yer alır.

Engellenmeyen yüklemeler

Bazı durumlarda, ana iş parçacığınızı (thread) bloklamadan veri göndermek istersiniz. Bu, bir eğitim sırasında devam ederken günlükleri ve artefaktları yüklemek için özellikle faydalıdır. Bunu yapmak için hem upload_file() hem de upload_folder() içinde run_as_future argümanını kullanabilirsiniz. Bu, yüklemenin durumunu kontrol etmek için kullanabileceğiniz bir concurrent.futures.Future nesnesi döndürür.

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> future = api.upload_folder( # Upload in the background (non-blocking action)
...     repo_id="username/my-model",
...     folder_path="checkpoints-001",
...     run_as_future=True,
... )
>>> future
Future(...)
>>> future.done()
False
>>> future.result() # Wait for the upload to complete (blocking action)
...

run_as_future=True kullanıldığında arka plan işleri kuyruğa alınır. Bu, işlerin doğru sırayla yürütüleceğinin garanti edildiği anlamına gelir.

Arka plan işleri büyük ölçüde veri yüklemek/commit oluşturmak için faydalı olsa da, run_as_future() kullanarak istediğiniz herhangi bir yöntemi kuyruğa alabilirsiniz. Örneğin, bir depo oluşturup ardından verileri arka planda yüklemek için bunu kullanabilirsiniz. Yükleme yöntemlerindeki yerleşik run_as_future argümanı, bunun etrafında oluşturulmuş bir takma addan ibarettir.

>>> from huggingface_hub import HfApi
>>> api = HfApi()
>>> api.run_as_future(api.create_repo, "username/my-model", exists_ok=True)
Future(...)
>>> api.upload_file(
...     repo_id="username/my-model",
...     path_in_repo="file.txt",
...     path_or_fileobj=b"file content",
...     run_as_future=True,
... )
Future(...)

Depolar arasında dosyaları kopyala

Hub'daki depolar arasında büyük verileri indirmeden veya yeniden yüklemeden dosya veya klasörleri kopyalamak için copy_files() kullanın. Bu, ağırlıkları model varyantları arasında çoğaltmak, veri seti dosyalarını depolar arasında kopyalamak veya dosyaları depolarınız arasında yeniden düzenlemek istediğinizde kullanışlıdır. Arka planda, CommitOperationCopy işlemleriyle bir commit oluşturur.

>>> from huggingface_hub import HfApi
>>> api = HfApi()

# Copy a single file between repos
>>> api.copy_files(
...     "hf://username/source-model/weights.safetensors",
...     "hf://username/target-model/weights.safetensors",
... )

# Copy an entire folder
>>> api.copy_files(
...     "hf://datasets/username/source-dataset/data/",
...     "hf://datasets/username/target-dataset/data/",
... )

Aynı depoyu içinde de kopyalayabilirsiniz:

# Duplicate a file in the same repo
>>> api.copy_files(
...     "hf://username/my-model/config.json",
...     "hf://username/my-model/backup/config.json",
... )

Bir klasör kopyalanırken, kaynakta sonundaki / rsync tarzı bir semantiğe sahiptir; bu, klasörün kendisi iç içe geçirilmeden içeriğinin kopyalandığı anlamına gelir. Sonunda / yoksa, klasörün kendisi hedefte iç içe geçirilir.

copy_files() ayrıca dosyaların Buckets içine kopyalanmasını da destekler. Daha fazla ayrıntı için Buckets kılavuzuna bakın.

Zamanlanmış yüklemeler

Hugging Face Hub, verileri kaydetmeyi ve sürümlemeyi kolaylaştırır. Ancak, aynı dosyayı binlerce kez güncellerken bazı kısıtlamalar vardır. Örneğin, bir eğitim sürecinin günlüklerini veya dağıtılmış bir Space'teki kullanıcı geri bildirimlerini kaydetmek isteyebilirsiniz. Bu durumlarda verileri Hub üzerinde bir veri seti olarak yüklemek mantıklıdır, ancak bunu doğru yapmak zor olabilir. Bunun ana nedeni, her güncellemeyi sürümlememek istemenizdir; aksi takdirde git deposu kullanılamaz hale gelir. CommitScheduler sınıfı bu soruna bir çözüm sunar.

Fikir, yerel bir klasörü Hub'a düzenli olarak gönderen arka plan işi çalıştırmaktır. Girdi olarak metin alan ve bu metnin iki çevirisini üreten bir Gradio Space'iniz olduğunu varsayalım. Ardından kullanıcı, tercih ettiği çeviriyi seçebilir. Her çalıştırma için sonuçları analiz etmek amacıyla girdiyi, çıktıyı ve kullanıcı tercihini kaydetmek istersiniz. Bu, CommitScheduler için mükemmel bir kullanım senaryosudur; verileri Hub'a (potansiyel olarak milyonlarca kullanıcı geri bildirimi) kaydetmek istersiniz, ancak her kullanıcının girdisini gerçek zamanlı olarak kaydetmek gerekmez. Bunun yerine, verileri yerel bir JSON dosyasında kaydedip her 10 dakikada bir yükleyebilirsiniz. Örneğin:

>>> import json
>>> import uuid
>>> from pathlib import Path
>>> import gradio as gr
>>> from huggingface_hub import CommitScheduler

# Define the file where to save the data. Use UUID to make sure not to overwrite existing data from a previous run.
>>> feedback_file = Path("user_feedback/") / f"data_{uuid.uuid4()}.json"
>>> feedback_folder = feedback_file.parent

# Schedule regular uploads. Remote repo and local folder are created if they don't already exist.
>>> scheduler = CommitScheduler(
...     repo_id="report-translation-feedback",
...     repo_type="dataset",
...     folder_path=feedback_folder,
...     path_in_repo="data",
...     every=10,
... )

# Define the function that will be called when the user submits its feedback (to be called in Gradio)
>>> def save_feedback(input_text:str, output_1: str, output_2:str, user_choice: int) -> None:
...     """
...     Append input/outputs and user feedback to a JSON Lines file using a thread lock to avoid concurrent writes from different users.
...     """
...     with scheduler.lock:
...         with feedback_file.open("a") as f:
...             f.write(json.dumps({"input": input_text, "output_1": output_1, "output_2": output_2, "user_choice": user_choice}))
...             f.write("\n")

# Start Gradio
>>> with gr.Blocks() as demo:
>>>     ... # define Gradio demo + use `save_feedback`
>>> demo.launch()

Ve tamam! Kullanıcı girdileri/çıktıları ve geri bildirimler, Hub üzerinde bir veri seti olarak kullanılabilir olacak. Benzersiz bir JSON dosya adı kullanarak, önceki bir çalıştırmadan gelen verilerin veya aynı depoya eşzamanlı olarak veri gönderen başka Spaces/replicalardan gelen verilerin üzerine yazılmayacağı garanti edilir.

CommitScheduler hakkında daha fazla ayrıntı için bilmeniz gerekenler şunlardır:

• sadece ekleme: Klasöre yalnızca içerik ekleyeceğiniz varsayılır. Mevcut dosyalara yalnızca veri eklemeli veya yeni dosyalar oluşturmalısınız. Bir dosyayı silmek veya üzerine yazmak depoyu bozabilir.
• git geçmişi: Zamanlayıcı, klasörü her every dakikada bir commit edecek. Git deposunu gereğinden fazla kirletmemek için, 5 dakika gibi asgari bir değer ayarlanması önerilir. Ayrıca zamanlayıcı, boş commit'lerden kaçınacak şekilde tasarlanmıştır. Klasörde yeni bir içerik algılanmazsa, planlanan commit atılır.
• hatalar: Zamanlayıcı arka plan iş parçacığı olarak çalışır. Sınıfı örneklediğinizde başlatılır ve stop() çağrılana veya süreç sonlanana kadar çalışır. Yükleme sırasında bir hata oluşursa (örnek: bağlantı sorunu), hata günlüğe kaydedilir ve zamanlayıcı bir sonraki planlanan commit'te yeniden dener.
• scripts: Sınırlı bir ömre sahip bir betikte (ör. eğitim) zamanlayıcıyı bir bağlam yöneticisi olarak kullanın. with bloğundan çıkıldığında son bir yükleme tetiklenir, tamamlanması beklenir ve zamanlayıcı durdurulur.
• İş parçacığı güvenliği: Çoğu durumda, bir dosyaya yazarken kilit dosyası konusunda endişelenmeden yazabileceğinizi varsayabilirsiniz. Zamanlayıcı, klasöre içerik yazarken yüklemeyi gerçekleştiriyorsa çökmez veya bozulmaz. Pratikte, yoğun yüklü uygulamalarda eşzamanlılık sorunlarının yaşanması mümkündür. Bu durumda, iş parçacığı güvenliğini sağlamak için scheduler.lock kilidini kullanmanızı öneririz. Kilit, yalnızca zamanlayıcının klasörde değişiklikleri taradığında bloklanır, veri yüklerken bloklanmaz. Kullanıcı deneyiminizi etkilemeyeceğini güvenle varsayabilirsiniz.

Space kalıcılığı demosu

Bir Space'ten Hub'daki bir Dataset'e kalıcı veri kaydetme, CommitScheduler'ın ana kullanım senaryosudur. Kullanım senaryosuna bağlı olarak verilerinizi farklı biçimlerde yapılandırmak isteyebilirsiniz. Yapı, eşzamanlı kullanıcılar ve yeniden başlatmalara karşı dayanıklı olmalıdır; bu genellikle UUID üretmeyi gerektirir. Dayanıklılığın yanı sıra, verileri daha sonra yeniden kullanım için 🤗 Datasets kütüphanesi tarafından okunabilir bir biçimde yüklemelisiniz. Farklı veri biçimlerini nasıl kaydedeceğinizi gösteren bir Space oluşturduk (kendi özel ihtiyaçlarınıza göre uyarlaması gerekebilir).

Özel yüklemeler

CommitScheduler, verilerinizin yalnızca eklemeye uygun (append-only) olduğunu ve “olduğu gibi” yüklenmesi gerektiğini varsayar. Ancak, verilerin yüklenme biçimini özelleştirmek isteyebilirsiniz. Bunu, CommitScheduler sınıfından türeyen bir sınıf oluşturup push_to_hub metodunu yeniden yazarak (istediğiniz gibi yeniden yazabilirsiniz) yapabilirsiniz. Bu metodun, arka planda bir iş parçacığında (thread) her every dakikada bir çağrılacağı garanti edilir. Eşzamanlılık (concurrency) ve hatalar konusunda endişelenmenize gerek yoktur; ancak boş commit’ler göndermek veya verilerin yinelenmesi gibi diğer konularda dikkatli olmanız gerekir.

Aşağıdaki (basitleştirilmiş) örnekte, Hub'daki repoyu aşırı yüklemeyi önlemek için tüm PNG dosyalarını tek bir arşive sıkıştırmak üzere push_to_hub işlevinin üzerine yazıyoruz:

class ZipScheduler(CommitScheduler):
    def push_to_hub(self):
        # 1. List PNG files
        png_files = list(self.folder_path.glob("*.png"))
        if len(png_files) == 0:
            return None  # return early if nothing to commit

        # 2. Zip png files in a single archive
        with tempfile.TemporaryDirectory() as tmpdir:
            archive_path = Path(tmpdir) / "train.zip"
            with zipfile.ZipFile(archive_path, "w", zipfile.ZIP_DEFLATED) as zip:
                for png_file in png_files:
                    zip.write(filename=png_file, arcname=png_file.name)

            # 3. Upload archive
            self.api.upload_file(..., path_or_fileobj=archive_path)

        # 4. Delete local png files to avoid re-uploading them later
        for png_file in png_files:
            png_file.unlink()

push_to_hub işlevini yeniden tanımladığınızda, CommitScheduler özniteliklerine ve özellikle şunlara erişebilirsiniz:

• HfApi istemcisi: api
• Klasör parametreleri: folder_path ve path_in_repo
• Depo parametreleri: repo_id, repo_type, revision
• İş parçacığı kilidi: lock

Özel zamanlayıcıların daha fazla örneği için, kullanım senaryolarınıza göre farklı uygulamalar içeren demo Space adresine göz atın.

create_commit

upload_file() ve upload_folder() işlevleri, genel olarak kullanımı pratik olan yüksek düzey API'lerdir. Daha düşük düzeyde çalışmak zorunda değilseniz, önce bu işlevleri denemenizi öneririz. Ancak commit düzeyinde çalışmak istiyorsanız, create_commit() işlevini doğrudan kullanabilirsiniz.

create_commit() tarafından desteklenen üç tür işlem vardır:

• CommitOperationAdd, bir dosyayı Hub'a yükler. Dosya zaten varsa, dosya içeriği üzerine yazılır. Bu işlem iki argüman kabul eder:

  • path_in_repo: Bir dosyanın yükleneceği depoda yol.
  • path_or_fileobj: Dosya sisteminizdeki bir dosyanın yolu veya dosya benzeri bir nesne. Hub'a yüklenecek dosyanın içeriğidir.

• CommitOperationDelete, bir depodan dosya veya klasör siler. Bu işlem, path_in_repo argümanını kabul eder.

• CommitOperationCopy, bir depoyun içinde veya depolar arasında bir dosyayı kopyalar. Bu işlem aşağıdaki argümanları kabul eder:

  • src_path_in_repo: kopyalanacak dosyanın depodaki yolu.
  • path_in_repo: dosyanın kopyalanacağı depoda yol.
  • src_revision: isteğe bağlı - farklı bir dal/revizyondan dosya kopyalamak istiyorsanız, kopyalanacak dosyanın revizyonu.
  • src_repo_id: isteğe bağlı - kopyalanacak kaynak depo (ör. "username/source-model"). Varsayılan olarak hedef depodur.
  • src_repo_type: isteğe bağlı - kaynak depoyun türü ("model", "dataset" veya "space"). src_repo_id ayarlandığında zorunludur.

Örneğin, bir Hub deposuna iki dosya yüklemek ve bir dosya silmek istiyorsanız:

1. Bir dosya eklemek veya silmek ve bir klasörü silmek için uygun CommitOperation'ı kullanın:

>>> from huggingface_hub import HfApi, CommitOperationAdd, CommitOperationDelete
>>> api = HfApi()
>>> operations = [
...     CommitOperationAdd(path_in_repo="LICENSE.md", path_or_fileobj="~/repo/LICENSE.md"),
...     CommitOperationAdd(path_in_repo="weights.h5", path_or_fileobj="~/repo/weights-final.h5"),
...     CommitOperationDelete(path_in_repo="old-weights.h5"),
...     CommitOperationDelete(path_in_repo="logs/"),
...     CommitOperationCopy(src_path_in_repo="image.png", path_in_repo="duplicate_image.png"),
... ]

2. Operasyonlarınızı create_commit() işlevine iletin:

>>> api.create_commit(
...     repo_id="lysandre/test-model",
...     operations=operations,
...     commit_message="Upload my model weights and license",
... )

upload_file() ve upload_folder() işlevlerinin yanı sıra, aşağıdaki işlevler de arka planda create_commit() işlevini kullanır:

• delete_file(), Hub'daki bir depodan tek bir dosyayı siler.
• delete_folder(), Hub'daki bir depodan tüm bir klasörü siler.
• metadata_update() bir depoyun meta verilerini günceller.

Daha ayrıntılı bilgi için HfApi referansına göz atın.

Commit öncesi LFS dosyalarını önceden yükleyin

Bazı durumlarda, commit çağrısını yapmadan önce devasa dosyaları S3'e yüklemek isteyebilirsiniz. Örneğin, bellek içinde oluşturulan birkaç shard'dan oluşan bir veri setini commit ediyorsanız, bellek taşması sorununu önlemek için shard'ları tek tek yüklemeniz gerekir. Bir çözüm, her shard'ı depoda ayrı bir commit olarak yüklemektir. Bu çözüm tamamen geçerli olsa da, onlarca commit oluşturarak git geçmişini karıştırma dezavantajına sahiptir. Bu sorunu aşmak için dosyalarınızı tek tek S3'e yükleyip sonunda tek bir commit oluşturabilirsiniz. Bunu preupload_lfs_files() ile create_commit() kombinasyonunu kullanarak yapabilirsiniz.

Bu, ileri düzey kullanıcılar için bir yöntemdir. Dosyaları önceden yükleme işleminin düşük seviye mantığını ele almak yerine, vakaların büyük çoğunluğunda upload_file(), upload_folder() veya create_commit() kullanmak en doğru yoldur. preupload_lfs_files() işlevinin temel dezavantajı, commit gerçekten oluşturulana kadar yüklenen dosyaların Hub'daki depoda erişilebilir olmamasıdır. Bir sorunuz varsa, Discord sunucumuzda veya bir GitHub issue'unda bize ulaşmaktan çekinmeyin.

Dosyaları önceden yüklemeyi gösteren basit bir örnek:

>>> from huggingface_hub import CommitOperationAdd, preupload_lfs_files, create_commit, create_repo

>>> repo_id = create_repo("test_preupload").repo_id

>>> operations = [] # List of all `CommitOperationAdd` objects that will be generated
>>> for i in range(5):
...     content = ... # generate binary content
...     addition = CommitOperationAdd(path_in_repo=f"shard_{i}_of_5.bin", path_or_fileobj=content)
...     preupload_lfs_files(repo_id, additions=[addition])
...     operations.append(addition)

>>> # Create commit
>>> create_commit(repo_id, operations=operations, commit_message="Commit all shards")

Öncelikle CommitOperationAdd nesnelerini tek tek oluştururuz. Gerçek bir senaryoda bu nesneler, oluşturulan parçaları (shards) içerir. Her dosya, bir sonraki dosya oluşturulmadan önce yüklenir. preupload_lfs_files() adımı sırasında CommitOperationAdd nesnesi değiştirilir (mutate edilir). Bu nesneyi yalnızca doğrudan create_commit() fonksiyonuna iletmek için kullanmalısınız. Nesnenin ana güncellemesi, ikili içeriğinin (binary content) kaldırılmasıdır; bu, nesneye başka bir referans saklamadığınızda çöp toplayıcı tarafından (garbage-collected) toplanacağı anlamına gelir. Zaten yüklenmiş içeriği bellekte tutmak istemediğimiz için bu beklenen bir davranıştır. Son olarak, tüm işlemleri create_commit() fonksiyonuna ileterek commit'i oluştururuz. Henüz işlenmemiş ek işlemleri (ekleme, silme veya kopyalama) da iletebilirsiniz ve bunlar doğru şekilde işlenir.