Hub Python Library documentation
Komut Satırı Arayüzü (CLI)
Komut Satırı Arayüzü (CLI)
huggingface_hub Python paketi, hf adlı yerleşik bir CLI ile birlikte gelir. Bu araç, Hugging Face Hub ile doğrudan bir terminalden etkileşim kurmanızı sağlar. Örneğin, hesabınıza giriş yapabilir, bir depo oluşturabilir, dosyaları yükleyip indirebilirsiniz vb. Ayrıca makinenizi yapılandırmak veya önbelleğinizi yönetmek için kullanışlı özellikler de sunar. Bu kılavuzda, CLI'nin ana özelliklerine ve bunların nasıl kullanılacağına bakacağız.
Bu kılavuz,
hfCLI'nin en önemli özelliklerini kapsar. Tüm komutların ve seçeneklerin tam referansı için CLI referansına bakın.
AI ajanlarıyla
hfCLI kullanıyor musunuz? Skill'i yükleyin ve Hugging Face CLI for AI Agents rehberine göz atın.# works with Claude Code, Codex, Cursor, OpenCode, Pi and any agent that loads skills from `.agents/skills` hf skills addBağımsız kurucu bunu sizin için yükler (aşağıya bakın) ve
hf updateonu yeniler.
Başlangıç
Bağımsız kurulum programı (Önerilen)
hf CLI'yi tek bir komutla kurabilirsiniz:
macOS ve Linux'ta:
>>> curl -LsSf https://hf.co/cli/install.sh | bashWindows'ta:
>>> powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"Kurucu, hf-cli becerisini da Claude Code ve ~/.agents/skills okuyan herhangi bir ajan için küresel olarak yükler. Bunu atlamak için --exclude-skill parametresini geçirin:
>>> curl -LsSf https://hf.co/cli/install.sh | bash -s -- --exclude-skill>>> powershell -ExecutionPolicy ByPass -c "& ([scriptblock]::Create((irm https://hf.co/cli/install.ps1))) -ExcludeSkill"Yüklendikten sonra, CLI'nin doğru şekilde yapılandırıldığını kontrol edebilirsiniz:
>>> hf --help
Usage: hf [OPTIONS] COMMAND [ARGS]...
Hugging Face Hub CLI
Options:
--skills Print the `hf-cli` SKILL.md to stdout (alias for `hf skills preview`).
--install-completion Install completion for the current shell.
--show-completion Show completion for the current shell, to copy it or customize the installation.
-h, --help Show this message and exit.
Main commands:
auth Manage authentication (login, logout, etc.).
buckets Commands to interact with buckets.
cache Manage local cache directory.
collections Interact with collections on the Hub.
datasets Interact with datasets on the Hub.
download Download files from the Hub.
endpoints Manage Hugging Face Inference Endpoints.
extensions Manage hf CLI extensions.
jobs Run and manage Jobs on the Hub.
models Interact with models on the Hub.
papers Interact with papers on the Hub.
repos Manage repos on the Hub.
skills Manage skills for AI assistants.
spaces Interact with spaces on the Hub.
sync Sync files between local directory and a bucket.
upload Upload a file or a folder to the Hub.
Help commands:
env Print information about the environment.
version Print information about the hf version.CLI doğru şekilde yüklendiyse, CLI'da kullanılabilir tüm seçeneklerin bir listesini görmelisiniz. command not found: hf gibi bir hata mesajı alırsanız, lütfen Yükleme kılavuzuna başvurun.
--helpseçeneği, bir komut hakkında daha fazla ayrıntı almak için çok kullanışlıdır. Tüm kullanılabilir seçenekleri ve ayrıntılarını listelemek için her zaman kullanabilirsiniz. Örneğin,hf upload --help, CLI kullanarak dosya yükleme konusunda daha fazla bilgi sağlar.
uv kullanma
hf CLI'yi kullanmanın en kolay yolu uvx ile kullanmaktır. Her zaman yalıtılmış bir ortamda en son sürümü çalıştırır - kurulum gerekmez!
Önce uv'ın yüklü olduğundan emin olun. Talimatlar için uv kurulum kılavuzu'na bakın.
Ardından CLI'yi doğrudan kullanın:
>>> uvx hf auth login
>>> uvx hf download
>>> uvx hf ...
uvx hf,hfPyPI paketini kullanır.
pip ile kurulum
CLI ayrıca çekirdek huggingface_hub paketiyle birlikte dağıtılır:
>>> pip install -U "huggingface_hub"Homebrew Kullanarak
CLI'yi Homebrew kullanarak da yükleyebilirsiniz:
>>> brew install hfDaha fazla ayrıntı için Homebrew huggingface sayfasına buradan göz atın.
Güncelleme
En son sürüme yükseltmek için şunu çalıştırın:
>>> hf updateBu komut, hf'in nasıl yüklendiğini (Homebrew, bağımsız kurucu veya pip) algılar ve eşleşen güncelleme komutunu çalıştırır. hf-cli becerisi global olarak yüklendiyse, ajanların yeni komut yüzeyini görmesi için bu da yenilenir. Yüklü değilse, kaldırılmamış olarak kalır: güncelleme, atladığınız veya kaldırdığınız durumda onu geri getirmeyecek şekilde çalışır.
Varsayılan olarak, CLI, PyPI'de daha yeni bir sürüm mevcut olduğunda stderr'e tek satırlık sarı bir uyarı da basar. Bunu susturmak için (ör. çevrimdışı CI'da) HF_HUB_DISABLE_UPDATE_CHECK=1 değerini ayarlayın.
Çıktı biçimlendirme
Çoğu hf komutu, aynı küresel biçimlendirme bayraklarını kabul eder. Bunlar, her --help sayfasındaki ayrı bir Formatting options bölümünde belgelenir ve komut bazında beyan etmeye gerek kalmadan herhangi bir komuta eklenebilir:
| Bayrak | Eşdeğer | Açıklama |
|---|---|---|
--format <value> | — | Çıktı biçimini açıkça seçin. Kabul edilen değerler: auto (varsayılan), human, agent, json, quiet. |
--json | --format json | Yapılandırılmış JSON yazdırın. jq veya diğer betiklere yönlendirmek için kullanışlıdır. |
-q, --quiet | --format quiet | Yalnızca kimlikleri yazdır (satır başına bir tane). Kimlikleri diğer komutlara aktarmak için kullanışlıdır. |
--no-truncate | — | İnsan tablolarında uzun değerleri ... ile kısaltmak yerine tam değerleri gösterin. Tablo, terminal genişliğini aşabilir. Liste/sözlük sütunları için yapılandırılmış çıktı almak üzere --format json kullanın. |
auto (varsayılan) etkileşimli bir terminal için human, CLI bir yapay zeka ajanı tarafından çağrıldığında ise agent seçer. human renkler ve düzenli tablolar ekler; agent kırpma olmadan sekmeyle ayrılmış değerler üretir; json ise kompakt bir JSON nesnesi veya dizisi yazar. İki çıktı modu bayrağının karıştırılması (ör. --json ile --format table birlikte) bir kullanım hatası oluşturur.
Human tablolar terminal genişliğine otomatik olarak uyarlanır: en geniş sütunlar yalnızca doğal genişlikleri ekranı aştığında kısaltılır (bu nedenle geniş bir terminalde genellikle ... olmadan tam değerleri görürsünüz). Genişlikten bağımsız olarak tam değerleri zorlamak için --no-truncate parametresini geçin; list/dict sütunları için yapılandırılmış çıktı almak için --format json kullanın.
# JSON output for scripting
>>> hf models ls --search bert --limit 2 --json | jq '.[].id'
# IDs only, one per line
>>> hf collections ls --owner nvidia -q
nvidia/nemotron-supervised-fine-tuning-69eab9824c9120a3a3b1e25e
nvidia/nvidia-nemotron-v3-69388dda16167bb1607171eahf auth login
Birçok durumda, Hub ile etkileşime girmek (özel depoları indirmek, dosya yüklemek, PR oluşturmak vb.) için bir Hugging Face hesabına giriş yapmış olmanız gerekir. Bunu yapmak için terminalde aşağıdaki komutu çalıştırın:
>>> hf auth loginZaten oturum açtıysanız, bu komut istemi atlanır ve bir mesaj görüntülenir. Yeniden oturum açmayı zorlamak için (ör. jetonları değiştirmek için) --force kullanın:
>>> hf auth login --forceVarsayılan olarak, komut sizi tarayıcınızla oturum açar: bir URL ve kısa bir kod basar. URL'yi açın, kodu girin, isteği onaylayın ve CLI, makinenizde bir erişim belirtecini (access token) alır ve kaydeder. Belirteç bir süre sonra sona erer ancak kullanmaya devam ettikçe otomatik olarak yenilenir.
? How would you like to log in? [Use arrows, Enter to confirm]
> Log in with your browser
Paste an access token
Open this URL in your browser:
https://huggingface.co/oauth/device
And enter the code: ABCD-EFGH
Waiting for authorization...
Token is valid.
The token `oauth-wauplin` has been saved to /home/wauplin/.cache/huggingface/stored_tokens
Your token has been saved to /home/wauplin/.cache/huggingface/token
Login successful.Ayrıca, Ayarlar sayfanızdan oluşturduğunuz bir Kullanıcı Erişim Belirteci yapıştırmayı da seçebilirsiniz; bunu etkileşimli olarak (Bir erişim belirteci yapıştır seçeneğini seçerek) veya doğrudan komut satırından yapabilirsiniz. Daha güvenli olması için, belirtecinizi komut geçmişinize yapıştırmaktan kaçınmak amacıyla bir ortam değişkeni olarak geçmenizi öneririz.
# Or using an environment variable
>>> hf auth login --token $HF_TOKEN --add-to-git-credential
Token is valid (permission: write).
The token `token_name` has been saved to /home/wauplin/.cache/huggingface/stored_tokens
Your token has been saved in your configured git credential helpers (store).
Your token has been saved to /home/wauplin/.cache/huggingface/token
Login successful
The current active token is: `token_name`Bir yapay zeka ajanı tarafından çalıştırıldığında (otomatik algılanır veya --format agent ile), komut asla kullanıcıdan girdi istemez: tarayıcı akışını çalıştırır, ajanın kullanıcısına iletebileceği düz talimatları yazdırır ve yetkilendirmeyi bekler:
>>> hf auth login --format agent
Ask the user to open https://huggingface.co/oauth/device in a browser and enter the code ABCD-EFGH. The code expires in 900 seconds. Waiting for authorization...
Login successful: logged in as wauplin (token saved as 'oauth-wauplin').hf auth login etkileşimli olduğundan --format json ve --format quiet desteklenmez: betiklenmiş, etkileşimsiz oturum açma işlemleri için --token parametresini kullanın.
Kimlik doğrulama hakkında daha fazla ayrıntı için bu bölümü inceleyin.
hf auth whoami
Giriş yapıp yapmadığınızı öğrenmek istiyorsanız hf auth whoami komutunu kullanabilirsiniz. Bu komutun herhangi bir seçeneği yoktur ve Hub'daki kullanıcı adınızı ile üye olduğunuz kuruluşları basitçe ekrana yazar:
hf auth whoami
Wauplin
orgs: huggingface,eu-test,OAuthTesters,hf-accelerate,HFSmolClusterGiriş yapmadıysanız, bir hata mesajı yazdırılır.
hf auth logout
Bu komut sizi oturumdan çıkarır. Uygulamada, makinenizde saklanan tüm jetonları siler. Belirli bir jetonu kaldırmak istiyorsanız, jeton adını bir argüman olarak belirtebilirsiniz.
Bu komut, HF_TOKEN ortam değişkeniyle oturum açtıysanız sizi çıkış yaptırmaz (bkz. referans). Bu durumda, makine yapılandırmanızda ortam değişkenini kaldırmalısınız.
hf download
Hub'dan dosyaları doğrudan indirmek için hf download komutunu kullanın. İçeride, İndirme kılavuzunda açıklanan aynı hf_hub_download() ve snapshot_download() yardımcılarını kullanır ve döndürülen yolu terminalde yazdırır. Aşağıdaki örneklerde en yaygın kullanım senaryoelerini ele alacağız. Kullanılabilir tüm seçeneklerin tam listesi için şunu çalıştırabilirsiniz:
hf download --helpTek bir dosya indirin
Bir depodan tek bir dosya indirmek için, repo_id ve dosya adını aşağıdaki gibi belirtmeniz yeterlidir:
>>> hf download gpt2 config.json
downloading https://huggingface.co/gpt2/resolve/main/config.json to /home/wauplin/.cache/huggingface/hub/tmpwrq8dm5o
(…)ingface.co/gpt2/resolve/main/config.json: 100%|██████████████████████████████████| 665/665 [00:00<00:00, 2.49MB/s]
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.jsonKomut, her zaman son satırda yerel makinenizdeki dosyanın yolunu yazdırır.
Depodaki bir alt dizinde yer alan bir dosyayı indirmek için, dosyanın depodaki yolunu posix biçiminde şu şekilde belirtmelisiniz:
>>> hf download HiDream-ai/HiDream-I1-Full text_encoder/model.safetensorsBir depoyu tamamen indirin
Bazı durumlarda, bir depodaki tüm dosyaları indirmek istersiniz. Bunu yalnızca depo kimliğini belirterek yapabilirsiniz:
>>> hf download HuggingFaceH4/zephyr-7b-beta
Fetching 23 files: 0%| | 0/23 [00:00<?, ?it/s]
...
...
/home/wauplin/.cache/huggingface/hub/models--HuggingFaceH4--zephyr-7b-beta/snapshots/3bac358730f8806e5c3dc7c7e19eb36e045bf720Birden çok dosya indir
Bir depodaki dosyaların bir alt kümesini tek bir komutla da indirebilirsiniz. Bu iki şekilde yapılabilir. İndirmek istediğiniz dosyaların kesin bir listesine zaten sahipseniz, bunları sırayla sağlayabilirsiniz:
>>> hf download gpt2 config.json model.safetensors
Fetching 2 files: 0%| | 0/2 [00:00<?, ?it/s]
downloading https://huggingface.co/gpt2/resolve/11c5a3d5811f50298f278a704980280950aedb10/model.safetensors to /home/wauplin/.cache/huggingface/hub/tmpdachpl3o
(…)8f278a7049802950aedb10/model.safetensors: 100%|██████████████████████████████| 8.09k/8.09k [00:00<00:00, 40.5MB/s]
Fetching 2 files: 100%|████████████████████████████████████████████████████████████████| 2/2 [00:00<00:00, 3.76it/s]
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10Diğer yaklaşım, --include ve --exclude kullanarak indirmek istediğiniz dosyaları filtrelemek için desenler sağlamaktır. Örneğin, stabilityai/stable-diffusion-xl-base-1.0 deposundan FP16 hassasiyetindeki dosyalar hariç tüm safetensors dosyalarını indirmek istiyorsanız:
>>> hf download stabilityai/stable-diffusion-xl-base-1.0 --include "*.safetensors" --exclude "*.fp16.*"*
Fetching 8 files: 0%| | 0/8 [00:00<?, ?it/s]
...
...
Fetching 8 files: 100%|█████████████████████████████████████████████████████████████████████████| 8/8 (...)
/home/wauplin/.cache/huggingface/hub/models--stabilityai--stable-diffusion-xl-base-1.0/snapshots/462165984030d82259a11f4367a4eed129e94a7bBir veri seti, Space veya kernel indirin
Yukarıdaki örnekler, bir model deposundan nasıl indirileceğini gösterir. Bir veri seti, Space veya kernel indirmek için --repo-type seçeneğini kullanın:
# https://huggingface.co/datasets/HuggingFaceH4/ultrachat_200k
>>> hf download HuggingFaceH4/ultrachat_200k --repo-type dataset
# https://huggingface.co/spaces/HuggingFaceH4/zephyr-chat
>>> hf download HuggingFaceH4/zephyr-chat --repo-type space
...Belirli bir revizyonu indirin
Yukarıdaki örnekler, ana dalın en son commit'inden nasıl indirileceğini gösterir. Belirli bir revizyondan (commit hash'i, dal adı veya etiket) indirmek için --revision seçeneğini kullanın:
>>> hf download bigcode/the-stack --repo-type dataset --revision v1.1
...hf:// URI kullanın
Depo türünü, revizyonu ve dosya yolunu ayrı argümanlar ve seçenekler olarak geçirmek yerine, tek bir hf:// URI'si sağlayabilirsiniz. URI, hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] dilbilgisini izleyerek her şeyi tek seferde kodlar (tam sözdizimi için HF URI referansına bakın):
# Equivalent to: hf download bigcode/the-stack --repo-type dataset --revision v1.1
>>> hf download hf://datasets/bigcode/the-stack@v1.1
# Download a single file from a specific revision
>>> hf download hf://datasets/HuggingFaceM4/FineVision@refs/pr/1/data/train.parquet
# Download a subfolder (note the trailing slash)
>>> hf download hf://datasets/HuggingFaceM4/FineVision/art/
# A bare id still works and defaults to a model repo
>>> hf download hf://openai-community/gpt2/config.jsonBir URI verildiğinde, --repo-type ve --revision de ayarlanamaz; çünkü bunlar zaten URI'nin bir parçasıdır (aksi halde bir hata oluşturulur) ve URI'de gömülü bir dosya yolu, konumsal dosya adlarıyla birleştirilemez. Yoldaki sonda yer alan /, bir alt klasörü belirtir (konumsal argümanla olduğu gibi). İçinde / bulunan dal adları, %2F olarak URL kodlamalı olmalıdır (ör. hf://my-org/my-model@feature%2Ffoo).
Yerel bir klasöre indirin
Hub'dan dosya indirmek için önerilen (ve varsayılan) yöntem, önbellek sistemini kullanmaktır. Ancak bazı durumlarda dosyaları indirip belirli bir klasöre taşımak isteyebilirsiniz. Bu, iş akışını git komutlarının sunduğu iş akışına yaklaştırmak için faydalıdır. Bunu --local-dir seçeneğini kullanarak yapabilirsiniz.
Yerel dizininizin kökünde, indirilen dosyalarla ilgili meta verileri içeren bir .cache/huggingface/ klasörü oluşturulur. Bu, dosyalar zaten güncelse yeniden indirilmelerini engeller. Meta verilerde bir değişiklik varsa, yeni dosya sürümü indirilir. Bu sayede local-dir, yalnızca en son değişiklikleri çekmek için optimize edilmiş olur.
Yerel bir dosyaya indirme işleminin nasıl çalıştığına dair daha fazla ayrıntı için download kılavuzuna göz atın.
>>> hf download adept/fuyu-8b model-00001-of-00002.safetensors --local-dir fuyu
...
fuyu/model-00001-of-00002.safetensorsKuru çalıştırma modu
Bazı durumlarda, dosyaları gerçekten indirmeden önce hangi dosyaların indirileceğini kontrol etmek isteyebilirsiniz. Bunu --dry-run parametresini kullanarak kontrol edebilirsiniz. Bu parametre, depodaki indirilecek tüm dosyaları listeler ve bunların daha önce indirilip indirilmediğini kontrol eder. Bu, kaç dosyanın indirilmesi gerektiği ve boyutları hakkında bir fikir verir.
>>> hf download openai-community/gpt2 --dry-run
[dry-run] Fetching 26 files: 100%|█████████████| 26/26 [00:04<00:00, 6.26it/s]
[dry-run] Will download 11 files (out of 26) totalling 5.6G.
File Bytes to download
--------------------------------- -----------------
.gitattributes -
64-8bits.tflite 125.2M
64-fp16.tflite 248.3M
64.tflite 495.8M
README.md -
config.json -
flax_model.msgpack 497.8M
generation_config.json -
merges.txt -
model.safetensors 548.1M
onnx/config.json -
onnx/decoder_model.onnx 653.7M
onnx/decoder_model_merged.onnx 655.2M
onnx/decoder_with_past_model.onnx 653.7M
onnx/generation_config.json -
onnx/merges.txt -
onnx/special_tokens_map.json -
onnx/tokenizer.json -
onnx/tokenizer_config.json -
onnx/vocab.json -
pytorch_model.bin 548.1M
rust_model.ot 702.5M
tf_model.h5 497.9M
tokenizer.json -
tokenizer_config.json -
vocab.json -Daha fazla ayrıntı için indirme kılavuzuna göz atın.
Önbellek dizinini belirtin
--local-dir kullanılmıyorsa, tüm dosyalar varsayılan olarak HF_HOME ortam değişkeni ile tanımlanan önbellek dizinine indirilir. --cache-dir ile özel bir önbellek belirtebilirsiniz:
>>> hf download adept/fuyu-8b --cache-dir ./path/to/cache
...
./path/to/cache/models--adept--fuyu-8b/snapshots/ddcacbcf5fdf9cc59ff01f6be6d6662624d9c745Bir belirteç belirtin
Özel veya kısıtlı depolara erişmek için bir jeton kullanmanız gerekir. Varsayılan olarak, yerel olarak kaydedilen jeton (hf auth login kullanılarak) kullanılır. Açık kimlik doğrulaması yapmak isterseniz --token seçeneğini kullanın:
>>> hf download gpt2 config.json --token=hf_****
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10/config.jsonSessiz mod
Varsayılan olarak hf download komutu ayrıntılıdır. Uyarı mesajları, indirilen dosyalarla ilgili bilgiler ve ilerleme çubukları gibi ayrıntıları görüntüler. Tüm bunları sessize almak isterseniz --quiet seçeneğini kullanın. Yalnızca son satır (yani indirilen dosyaların yolu) görüntülenir. Çıktıyı bir betikte başka bir komuta iletmek istediğinizde bu işe yarayabilir.
>>> hf download gpt2 --quiet
/home/wauplin/.cache/huggingface/hub/models--gpt2/snapshots/11c5a3d5811f50298f278a704980280950aedb10İndirme zaman aşımı
Yavaş bağlantıya sahip makinelerde, aşağıdaki gibi zaman aşımı sorunlarıyla karşılaşabilirsiniz:
`httpx2.TimeoutException: (TimeoutException("HTTPSConnectionPool(host='cdn-lfs-us-1.huggingface.co', port=443): Read timed out. (read timeout=10)"), '(Request ID: a33d910c-84c6-4514-8362-c705e2039d38)')`Bu sorunu azaltmak için HF_HUB_DOWNLOAD_TIMEOUT ortam değişkenini daha yüksek bir değere ayarlayabilirsiniz (varsayılan değer 10'dur):
export HF_HUB_DOWNLOAD_TIMEOUT=30Daha fazla ayrıntı için ortam değişkenleri referansını inceleyin. Ardından indirme komutunuzu yeniden çalıştırın.
hf upload
Dosyaları Hub'a doğrudan yüklemek için hf upload komutunu kullanın. İçeride, Upload kılavuzunda açıklanan aynı upload_file() ve upload_folder() yardımcı işlevlerini kullanır. Aşağıdaki örneklerde en yaygın kullanım senaryoelerini ele alacağız. Kullanılabilir tüm seçeneklerin listesi için şunu çalıştırabilirsiniz:
>>> hf upload --helpBir klasörün tamamını yükle
Bu komutun varsayılan kullanımı şudur:
# Usage: hf upload [repo_id] [local_path] [path_in_repo]Deponun kökünde mevcut dizini yüklemek için şunu kullanın:
>>> hf upload my-cool-model . .
https://huggingface.co/Wauplin/my-cool-model/tree/main/Depo henüz yoksa otomatik olarak oluşturulur.
Belirli bir klasörü de yükleyebilirsiniz:
>>> hf upload my-cool-model ./models .
https://huggingface.co/Wauplin/my-cool-model/tree/main/Son olarak, bir klasörü depodaki belirli bir hedefe yükleyebilirsiniz:
>>> hf upload my-cool-model ./path/to/curated/data /data/train
https://huggingface.co/Wauplin/my-cool-model/tree/main/data/trainTek bir dosya yükle
local_path parametresini makinenizdeki bir dosyaya işaret edecek şekilde ayarlayarak tek bir dosya da yükleyebilirsiniz. Bu durumda path_in_repo isteğe bağlıdır ve yerel dosyanızın adıyla varsayılan olarak doldurulur:
>>> hf upload Wauplin/my-cool-model ./models/model.safetensors
https://huggingface.co/Wauplin/my-cool-model/blob/main/model.safetensorsBelirli bir dizine tek bir dosya yüklemek istiyorsanız, path_in_repo parametresini buna göre ayarlayın:
>>> hf upload Wauplin/my-cool-model ./models/model.safetensors /vae/model.safetensors
https://huggingface.co/Wauplin/my-cool-model/blob/main/vae/model.safetensorsBirden çok dosya yükle
Bir klasörden tüm klasörü yüklemek yerine birden fazla dosyayı aynı anda yüklemek için --include ve --exclude desenlerini kullanın. Yeni dosyaları yüklerken depodaki dosyaları silmek için --delete seçeneğiyle de birleştirilebilir. Aşağıdaki örnekte, uzak dosyaları silerek ve /logs içindekiler hariç tüm dosyaları yükleyerek yerel Space'i eşitliyoruz:
# Sync local Space with Hub (upload new files except from logs/, delete removed files)
>>> hf upload Wauplin/space-example --repo-type=space --exclude="/logs/*" --delete="*" --commit-message="Sync local Space with Hub"
...Bir veri setine veya Space'e yükle
Bir veri setine veya Space'e yüklemek için --repo-type seçeneğini kullanın:
>>> hf upload Wauplin/my-cool-dataset ./data /train --repo-type=dataset
...Bir organizasyona yükle
Kişisel bir depo yerine bir organizasyona ait bir depoya içerik yüklemek için bunu repo_id içinde açıkça belirtmeniz gerekir:
>>> hf upload MyCoolOrganization/my-cool-model . .
https://huggingface.co/MyCoolOrganization/my-cool-model/tree/main/Belirli bir revizyona yükle
Varsayılan olarak dosyalar main dalına yüklenir. Dosyaları başka bir dala veya referansa yüklemek istiyorsanız --revision seçeneğini kullanın:
# Upload files to a PR
>>> hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
...Not: revision mevcut değilse ve --create-pr ayarlanmamışsa, main dalından otomatik olarak bir dal oluşturulur.
hf:// URI kullanın
hf download ile olduğu gibi, hedef, hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>] dilbilgisini izleyen tek bir hf:// URI olarak ifade edilebilir (tam sözdizimi için HF URI referansına bakın). Depo türü, revizyon ve path_in_repo değerlerinin tümü URI'den okunur:
# Equivalent to: hf upload Wauplin/my-cool-dataset ./train.csv data/train.csv --repo-type dataset --revision my-branch
>>> hf upload hf://datasets/Wauplin/my-cool-dataset@my-branch/data/train.csv ./train.csv
# Upload a whole folder to the root of a model repo
>>> hf upload hf://Wauplin/my-cool-model ./modelsBir URI verildiğinde, --repo-type ve --revision de ayarlanamaz; çünkü bunlar zaten URI'nin bir parçasıdır (aksi halde bir hata oluşturulur) ve URI'de gömülü olan bir yol, path_in_repo argümanı ile birleştirilemez.
Yükle ve PR oluştur
Bir depoya gönderme izniniz yoksa, bir PR açmanız ve yapmak istediğiniz değişikliklerden yazarları haberdar etmeniz gerekir. Bunu --create-pr seçeneğini ayarlayarak yapabilirsiniz:
# Create a PR and upload the files to it
>>> hf upload bigcode/the-stack . . --repo-type dataset --revision refs/pr/104
https://huggingface.co/datasets/bigcode/the-stack/blob/refs%2Fpr%2F104/Düzenli aralıklarla yükle
Bazı durumlarda, bir repoya düzenli güncellemeler göndermek isteyebilirsiniz. Örneğin, bir model eğitiyor ve log klasörünü her 10 dakikada bir yüklemek istiyorsanız bu işe yarar. Bunu --every seçeneğini kullanarak yapabilirsiniz:
# Upload new logs every 10 minutes
hf upload training-model logs/ --every=10Bir commit mesajı belirtin
Varsayılan mesaj yerine commit'iniz için özel bir mesaj ve açıklama belirlemek için --commit-message ve --commit-description kullanın
>>> hf upload Wauplin/my-cool-model ./models . --commit-message="Epoch 34/50" --commit-description="Val accuracy: 68%. Check tensorboard for more details."
...
https://huggingface.co/Wauplin/my-cool-model/tree/mainBir belirteç belirtin
Dosyaları yüklemek için bir jeton kullanmanız gerekir. Varsayılan olarak, yerel olarak kaydedilen jeton (hf auth login kullanılarak) kullanılır. Açık kimlik doğrulaması yapmak isterseniz --token seçeneğini kullanın:
>>> hf upload Wauplin/my-cool-model ./models . --token=hf_****
...
https://huggingface.co/Wauplin/my-cool-model/tree/mainSessiz mod
Varsayılan olarak hf upload komutu ayrıntılıdır. Uyarı mesajları, yüklenen dosyalarla ilgili bilgiler ve ilerleme çubukları gibi ayrıntıları görüntüler. Tüm bunları sessize almak isterseniz --quiet seçeneğini kullanın. Yalnızca son satır (yani yüklenen dosyalara giden URL) görüntülenir. Çıktıyı bir betikte başka bir komuta iletmek istediğinizde bu işe yarayabilir.
>>> hf upload Wauplin/my-cool-model ./models . --quiet
https://huggingface.co/Wauplin/my-cool-model/tree/mainhf buckets
Hugging Face Hub üzerindeki bucket’ları yönetmek için hf buckets kullanın. Bucket’lar, Hugging Face üzerinde Xet depolama altyapısıyla desteklenen, S3 benzeri nesne depolama alanları sağlar. Depoların (git tabanlı ve dosya geçmişini izleyen) aksine bucket’lar, içerik adreslenebilir kopya azaltma (deduplication) özelliğine sahip, büyük ölçekli dosyalar için tasarlanmış uzak nesne depolama konteynerleridir. Sürüm kontrolüne ihtiyaç duymayan eğitim checkpoint’leri, loglar, ara artefaktlar veya büyük dosya koleksiyonları gibi basit, hızlı ve değiştirilebilir depolama gerektiren kullanım senaryoları için tasarlanmıştır. Aşağıdaki örneklerde en yaygın kullanım senaryolarını adım adım ele alacağız. Kılavuzun tamamı için Buckets kılavuzu sayfasına bakın.
Bir varlık oluşturun
Yeni bir bucket oluşturmak için hf buckets create kullanın. Bucket varsayılan olarak ad alanınız altında oluşturulur:
>>> hf buckets create my-bucket--private bayrağını kullanarak özel bir varlık kutusu da oluşturabilirsiniz:
>>> hf buckets create my-bucket --privateKovaları listele ve incele
Tüm varlıklarınızı listelemek için hf buckets list (veya kısaltması hf buckets ls) kullanın. Belirli bir organizasyondaki varlıkları da listeleyebilirsiniz:
>>> hf buckets list
ID PRIVATE SIZE TOTAL_FILES CREATED_AT
-------------------- ------- ---------- ----------- ----------
username/my-bucket 32 5 2026-02-16
username/checkpoints 117609095 700 2026-02-13
username/logs 321757477 2000 2026-02-13
# Human-readable sizes
>>> hf buckets list -h
ID PRIVATE SIZE TOTAL_FILES CREATED_AT
-------------------- ------- -------- ----------- ----------
username/my-bucket 32 B 5 2026-02-16
username/checkpoints 117.6 MB 700 2026-02-13
username/logs 321.8 MB 2000 2026-02-13
# List buckets in a specific namespace
>>> hf buckets ls my-org
# Filter buckets by name
>>> hf buckets list --search "checkpoint"Belirli bir varlık hakkındaki ayrıntılı bilgiyi (JSON olarak döndürülür) almak için hf buckets info kullanın:
>>> hf buckets info username/my-bucket
{
"id": "username/my-bucket",
"private": false,
"created_at": "2026-02-16T15:28:32+00:00",
"size": 32,
"total_files": 5
}Kova görünürlüğünü değiştir
Bir kovayı özel ve herkese açık arasında geçiş yapmak için hf buckets settings kullanın:
# Make a bucket private
>>> hf buckets settings username/my-bucket --private
# Make it public again
>>> hf buckets settings username/my-bucket --publicBir varlık kovasını sil
Bir varlığı silmek için hf buckets delete kullanın. --yes parametresini geçirmediğinizde onay istenir:
>>> hf buckets delete username/my-bucket --yesDosyaları kaldır
Bir bucket'tan dosyaları kaldırmak için hf buckets remove (veya kısaltması hf buckets rm) kullanın.
Tek bir dosyayı kaldırmak için yolunu belirtin:
>>> hf buckets rm username/my-bucket/old-model.binBir önek altındaki tüm dosyaları kaldırmak için --recursive kullanın:
>>> hf buckets rm username/my-bucket/logs/ --recursiveBir önek olmadan bir varlık kovasındaki (bucket) tüm dosyaları da hedefleyebilirsiniz:
>>> hf buckets rm username/my-bucket --recursive --include "*.tmp"Gerçekten bir şey silmeden silinecek olanları önizlemek için --dry-run kullanın:
>>> hf buckets rm username/my-bucket/checkpoints/ --recursive --dry-runDosyaları görüntüle
Bir bucket kimliği ile hf buckets list kullanarak bir bucket içindeki dosyaları listeleyin:
>>> hf buckets list username/my-bucket
2048 2026-01-15 10:30:00 big.bin
5 2026-01-15 10:30:00 file.txt
2026-01-15 10:30:00 sub/Özyinelemeli bir liste için -R ve insan okunabilir dosya boyutları ile kısa tarihler için -h ekleyin. Ayrıca ASCII ağaç görünümünü --tree ile görüntüleyebilir veya metadata olmadan temiz bir ağaç için --tree --quiet kullanabilirsiniz:
# Recursive with human-readable sizes
>>> hf buckets list username/my-bucket -R -h
2.0 KB Jan 15 10:30 big.bin
5 B Jan 15 10:30 file.txt
14 B Jan 15 10:30 sub/nested.txt
4 B Jan 15 10:30 sub/deep/file.txt
# Tree with human-readable sizes
>>> hf buckets list username/my-bucket --tree -h -R
2.0 KB Jan 15 10:30 ├── big.bin
5 B Jan 15 10:30 ├── file.txt
└── sub/
├── deep/
4 B Jan 15 10:30 │ └── file.txt
14 B Jan 15 10:30 └── nested.txt
# Clean tree without metadata
>>> hf buckets list username/my-bucket --tree --quiet -R
├── big.bin
├── file.txt
└── sub/
├── deep/
│ └── file.txt
└── nested.txtÖne göre filtrelemek için öneki varlık yoluna ekleyin:
>>> hf buckets list username/my-bucket/sub -RDosyaları kopyala
hf cp komutunu, yerel makineniz, depolar ve varlıklar arasında tek bir dosyayı kopyalamak için kullanın. Kaynak ve hedef, her biri yerel bir yol, hf:// URI'si (depo veya varlık) veya - (stdin/stdout) olabilir.
hf cp,hf repos cpvehf buckets cpolarak da erişilebilir — üçü de aynı komuttur. İş akışınıza en uygun okunanı kullanın.
Bir dosya yüklemek için (yerel → depo veya kovuk):
# To a repository
>>> hf cp ./model.safetensors hf://username/my-model/model.safetensors
# To a bucket (uses the local filename when the destination ends with /)
>>> hf cp ./data.csv hf://buckets/username/my-bucket/logs/Bir dosya indirmek için (repo veya bucket → yerel):
# From a repository
>>> hf cp hf://datasets/username/my-dataset@refs/pr/1/data.csv ./data.csv
# From a bucket, to the current directory (destination omitted)
>>> hf cp hf://buckets/username/my-bucket/config.jsonAyrıca - kullanarak stdout'a akış yapabilir veya stdin'den akış alabilirsiniz:
# Download to stdout
>>> hf cp hf://buckets/username/my-bucket/config.json - | jq .
# Upload from stdin
>>> echo "hello" | hf cp - hf://username/my-model/hello.txtHub'daki iki konum arasında kopyalamak için (repo/bucket → repo/bucket):
# Repo to repo
>>> hf cp hf://username/source-model/config.json hf://username/dest-model/config.json
# Repo to bucket
>>> hf cp hf://datasets/username/my-dataset/data/train/ hf://buckets/username/my-bucket/datasets/train/
# Bucket to bucket
>>> hf cp hf://buckets/username/source-bucket/logs/ hf://buckets/username/archive-bucket/logs/İki Hub konumu arasında klasörler kopyalanırken, kaynak yolundaki sonda yer alan / karakteri, klasörün kendisinin mi yoksa yalnızca içeriğinin mi kopyalanacağını belirler (rsync tarzı):
# Without trailing slash: "logs" dir is nested => archive/logs/...
>>> hf cp hf://buckets/username/my-bucket/logs hf://buckets/username/archive-bucket/
# With trailing slash: only contents of "logs" are copied => archive/...
>>> hf cp hf://buckets/username/my-bucket/logs/ hf://buckets/username/archive-bucket/Notlar:
hf cp, yerel bir yol söz konusu olduğunda tek bir dosyayı kopyalar. Tüm dizinleri yerel olarak kopyalamak içinhf upload/hf download(depolamalar) veyahf buckets sync(variller) kullanın.- Bucket-to-repo kopyalama henüz desteklenmiyor.
- Yerelden yerele kopyalama desteklenmez (kabuğunuzdaki
cpkomutunu kullanın). - İki Hub konumu arasındaki kopyalama işlemleri yalnızca aynı depolama bölgesi içinde çalışır.
Dizinleri senkronize et
hf buckets sync komutunu, yerel makineniz ile bir bucket arasında dizinleri senkronize etmek için kullanın. Kaynağı ve hedefi karşılaştırır ve yalnızca değişen dosyaları aktarır.
Bir yerel dizini bir kovaya yüklemek için:
>>> hf buckets sync ./data hf://buckets/username/my-bucketBir kovadan yerel bir dizine indirmek için:
>>> hf buckets sync hf://buckets/username/my-bucket ./dataKaynakta bulunmayan hedef dosyaları kaldırmak için --delete kullanın:
>>> hf buckets sync ./data hf://buckets/username/my-bucket --deleteHangi dosyaların senkronize edileceğini --include ve --exclude desenlerini kullanarak filtreleyebilirsiniz:
>>> hf buckets sync ./data hf://buckets/username/my-bucket --include "*.safetensors" --exclude "*.tmp"Sadece mevcut dosyaları güncellemek (yeni olanları atlamak) için --existing kullanın. Sadece yeni dosyalar oluşturmak (mevcut olanları atlamak) için --ignore-existing kullanın:
>>> hf buckets sync ./data hf://buckets/username/my-bucket --existing
>>> hf buckets sync ./data hf://buckets/username/my-bucket --ignore-existingEkstra güvenlik için, uygulamadan önce incelemeye alınacak bir plan oluşturabilir ve ardından uygulayabilirsiniz:
# Generate a plan
>>> hf buckets sync ./data hf://buckets/username/my-bucket --plan sync-plan.jsonl
# Review and apply the plan
>>> hf buckets sync --apply sync-plan.jsonlHerhangi bir işlemi çalıştırmadan senkronizasyon planını JSONL olarak stdout'a yazdırmak için --dry-run kullanın. Bu, jq veya diğer araçlara yönlendirmek için kullanışlıdır:
>>> hf buckets sync ./data hf://buckets/username/my-bucket --dry-run | jq .
hf sync,hf buckets synciçin kullanışlı bir üst düzey takma addır. Tüm senkronizasyon seçeneklerinin ayrıntıları için Buckets kılavuzuna bakın.
hf modeller
Hub'daki modelleri listelemek ve belirli bir model hakkında ayrıntılı bilgi almak için hf models kullanın.
Modelleri listele
# List trending models
>>> hf models ls
# Search for models
>>> hf models ls --search "lora"
# Filter by author
>>> hf models ls --author Qwen
# Filter by pipeline tag
>>> hf models ls --pipeline-tag summarization
# Filter by parameter count
>>> hf models ls --num-parameters min:6B,max:128B
# Only non-gated models
>>> hf models ls --no-gated --author google
# Only models runnable by a given app
>>> hf models ls --apps llama.cpp
# Sort by downloads
>>> hf models ls --sort downloads --limit 10Bir model kimliği ile çağrıldığında, hf models ls o model deposundaki dosyaları listeler:
# List files in a model repo
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct
# List files recursively
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct -R
# Tree view with human-readable sizes
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct --tree -h
# List files at a specific revision
>>> hf models ls meta-llama/Llama-3.2-1B-Instruct --revision mainModel bilgilerini al
>>> hf models info Lightricks/LTX-2--expand parametresini kullanarak downloads, likes, tags gibi ek özellikleri alabilirsiniz.
Model kartını al
hf models card komutunu kullanarak bir modelin model kartını (README) alabilirsiniz. Varsayılan olarak, kartın tam içeriği stdout'a yazdırılır.
# Full card (metadata + text)
>>> hf models card google/gemma-4-31B-it
# Just the metadata (from the YAML frontmatter)
>>> hf models card google/gemma-4-31B-it --metadata
# Metadata as JSON (useful for scripting and agents)
>>> hf models card google/gemma-4-31B-it --metadata --format json
# Just the text body (no YAML frontmatter)
>>> hf models card google/gemma-4-31B-it --texthf datasets
Hub'daki veri setlerini listelemek ve belirli bir veri seti hakkında ayrıntılı bilgi almak için hf datasets kullanın.
Veri kümelerini listele
# List trending datasets
>>> hf datasets ls
# Search for datasets
>>> hf datasets ls --search "code"
# List official benchmark datasets
>>> hf datasets ls --filter benchmark:official
# Sort by downloads
>>> hf datasets ls --sort downloads --limit 10Bir veri seti kimliği ile çağrıldığında, hf datasets ls o veri seti deposundaki dosyaları listeler:
# List files in a dataset repo
>>> hf datasets ls HuggingFaceFW/fineweb
# List files recursively with human-readable sizes
>>> hf datasets ls HuggingFaceFW/fineweb -R -h
# Tree view
>>> hf datasets ls HuggingFaceFW/fineweb --treeBir veri seti lider tablosunu listele
Bir görev için en iyi modelleri bulmak veya modelleri benchmark puanlarına göre karşılaştırmak için, bir benchmark veri setine gönderilen model puanlarını göstermek üzere hf datasets leaderboard kullanın.
>>> hf datasets leaderboard SWE-bench/SWE-bench_Verified
>>> hf datasets leaderboard SWE-bench/SWE-bench_Verified --limit 5 --format jsonVeri seti bilgilerini alın
>>> hf datasets info HuggingFaceFW/finewebVeri seti kartını al
Bir veri setinin veri seti kartını (README) almak için hf datasets card kullanın. Varsayılan olarak, kartın tam içeriği stdout'a yazdırılır.
# Full card (metadata + text)
>>> hf datasets card HuggingFaceFW/fineweb
# Just the metadata (from the YAML frontmatter)
>>> hf datasets card HuggingFaceFW/fineweb --metadata
# Metadata as JSON (useful for scripting and agents)
>>> hf datasets card HuggingFaceFW/fineweb --metadata --format json
# Just the text body (no YAML frontmatter)
>>> hf datasets card HuggingFaceFW/fineweb --textParquet URL'lerini listele
Bir veri seti için SQL sorguları yazmadan önce, veri setine ait parquet dosya URL'lerini keşfetmek için hf datasets parquet kullanın.
Hub'daki veri setleri, uygun veri setleri için, Dataset Viewer hizmeti tarafından arka uçta otomatik olarak Parquet'e dönüştürülür.
Ayrıntılar için Parquet dönüştürme kılavuzuna bakın.
>>> hf datasets parquet cfahlgren1/hub-stats
>>> hf datasets parquet cfahlgren1/hub-stats --subset models
>>> hf datasets parquet cfahlgren1/hub-stats --split train
>>> hf datasets parquet cfahlgren1/hub-stats --format jsonVarsayılan tablo çıktısı, Hub API'sinden alt küme, bölme ve parquet dosyası URL'sini içerir.
Veri seti parquetsinde SQL çalıştır
hf datasets sql komutunu kullanarak, veri seti parquet URL'lerine karşı DuckDB ile ham SQL sorguları çalıştırın.
Önce URL'leri hf datasets parquet ile keşfedin, ardından read_parquet(...) ile doğrudan sorgulayın.
>>> hf datasets sql "SELECT COUNT(*) AS rows FROM read_parquet('https://huggingface.co/api/datasets/cfahlgren1/hub-stats/parquet/models/train/0.parquet')"
>>> hf datasets sql "SELECT * FROM read_parquet('https://huggingface.co/api/datasets/cfahlgren1/hub-stats/parquet/models/train/0.parquet') LIMIT 5" --format jsonGerekirse önce DuckDB'yi yükleyin:
# Python package
>>> pip install duckdb
# or standalone DuckDB CLI (Homebrew: macOS/Linux)
>>> brew install duckdbhf spaces
Hub'daki Spaces'leri listelemek ve belirli bir Space hakkında ayrıntılı bilgi almak için hf spaces kullanın.
Spaces'leri Listele
# List trending Spaces
>>> hf spaces ls
# Search for Spaces
>>> hf spaces ls --search "3d"
# Sort by likes
>>> hf spaces ls --sort likes --limit 10Bir Space kimliği ile çağrıldığında, hf spaces ls o Space deposundaki dosyaları listeler:
# List files in a Space repo
>>> hf spaces ls victor/deepsite
# List files recursively with tree view
>>> hf spaces ls victor/deepsite --tree -R -hSpace bilgilerini getir
>>> hf spaces info victor/deepsiteSpace kartını al
Bir Space'in kartını (README) almak için hf spaces card kullanın. Varsayılan olarak, kartın tam içeriği stdout'a yazdırılır.
# Full card (metadata + text)
>>> hf spaces card mteb/leaderboard
# Just the card metadata (from the YAML frontmatter)
>>> hf spaces card mteb/leaderboard --metadata
# Card metadata as JSON
>>> hf spaces card mteb/leaderboard --metadata --format json
# Just the text body (no YAML frontmatter)
>>> hf spaces card mteb/leaderboard --textBir Space'in duraklatılması veya yeniden başlatılması, konteynerini kaldırır; bu nedenle geçici dosya sistemine yazılan her şey kaybolur. Verilerin yeniden başlatmalar arasında kalıcı olmasını sağlamak için bir Volume veya bucket'ı
hf spaces volumes setile bağlayın (detaylar içinhf spaces volumes --helpkomutunu çalıştırın).
Bir Space'i Durdur
Kullanmadığınız bir Space'i duraklatmak için hf spaces pause komutunu kullanın (duraklatma süresi faturalandırılmaz). Daha sonra hf spaces restart komutuyla yeniden başlatın.
>>> hf spaces pause username/my-spaceBir Space'i Yeniden Başlat
Bir Space'i yeniden başlatmak için hf spaces restart komutunu kullanın. Build önbelleğini kullanmadan Space'i sıfırdan yeniden oluşturmak için --factory-reboot parametresini iletin.
>>> hf spaces restart username/my-space
>>> hf spaces restart username/my-space --factory-rebootBir Space için bekle
Bir Space'in derleme/başlatma işlemini tamamlamasını ve kararlı bir aşamaya ulaşmasını beklemek için hf spaces wait komutunu kullanın. Space RUNNING durumundaysa 0 koduyla, aksi halde sıfırdan farklı bir kodla (ör. BUILD_ERROR) çıkış yapar. Yeniden başlatma veya donanım değişikliği sonrasında betik yazımında kullanışlıdır.
>>> hf spaces wait username/my-space
# With a timeout
>>> hf spaces wait username/my-space --timeout 5m
# Chain with restart
>>> hf spaces restart username/my-space && hf spaces wait username/my-spaceKullanılabilir donanımları listele
Spaces için fiyatlar dahil olmak üzere kullanılabilir tüm donanım seçeneklerini listelemek için hf spaces hardware kullanın.
>>> hf spaces hardwareZeroGPU kotaınızı kontrol edin
ZeroGPU kotanızın ne kadarının kaldığını ve ne zaman sıfırlandığını kontrol etmek için hf spaces zero-gpu quota komutunu kullanın. Bu, ZeroGPU Spaces'i betikler, uygulamalar veya ajanlar üzerinden çağırırken kullanımınızı izlemek için faydalıdır.
>>> hf spaces zero-gpu quota
✓ ZeroGPU quota (in GPU-seconds)
remaining: 1810
base: 2400
resets_at: 2026-09-30T18:12:03+00:00
overquota_used: 0
>>> hf spaces zero-gpu quota --format json
{"remaining": 1810, "base": 2400, "resets_at": "2026-09-30T18:12:03+00:00", "overquota_used": 0}Kontenjanınız azalıyorsa, komut, günlük kontenjanın ötesinde ZeroGPU'yu kullanmaya devam edebilmeniz için faturalandırma ayarlarınızdan kredi satın almanızı önerir (yalnızca PRO, Team ve Enterprise kullanıcıları).
Space ayarlarını güncelle
Bir Space'in ayarlarını güncellemek için hf spaces settings kullanın.
>>> hf spaces settings username/my-space --sleep-time 3600
>>> hf spaces settings username/my-space --hardware t4-medium--sleep-time: Space'in uyumasından önceki saniye cinsinden boşta kalma süresi. Hiç uyumaması için-1kullanın. Yalnızca yükseltilmiş donanımlarda kullanılabilir (bkz. Spaces uyku süresi belgeleri).--hardware: donanım türü (ör.cpu-basic,t4-medium,l4x4). Tüm seçenekleri görmek içinhf spaces hardwarekomutunu çalıştırın.
Space gizli bilgilerini yönet
Bir Space'teki gizli bilgileri listelemek için hf spaces secrets ls, bir veya birden fazla gizli bilgiyi eklemek veya güncellemek için hf spaces secrets add ve bir tanesini kaldırmak için hf spaces secrets delete kullanın. .env tarzı bir dosyadan gizli bilgileri yüklemek için --secrets-file PATH parametresini iletin. Mevcut anahtarlar üzerine yazılır.
>>> hf spaces secrets ls username/my-space
>>> hf spaces secrets add username/my-space -s OPENAI_API_KEY=sk-...
>>> hf spaces secrets add username/my-space --secrets-file .env.secrets
>>> hf spaces secrets delete username/my-space OPENAI_API_KEY --yesGizli değerler yalnızca yazılabilir olduğundan
hf spaces secrets lskomutu anahtarları, açıklamaları ve güncelleme zaman damgalarını gösterir ancak gizli değerlerin kendilerini asla göstermez.
Space ortam değişkenlerini yönetme
Bir Space üzerinde gizli olmayan ortam değişkenlerini yönetmek için hf spaces variables kullanın. Gizli bilgilerden farklı olarak değişkenler okunabilir olduğundan ls hem anahtarları hem de değerleri gösterir. .env biçimindeki bir dosyadan yüklemek için add komutuna --env-file PATH parametresini iletin.
>>> hf spaces variables ls username/my-space
>>> hf spaces variables add username/my-space -e MODEL_ID=gpt2 -e MAX_TOKENS=512
>>> hf spaces variables add username/my-space --env-file .env
>>> hf spaces variables delete username/my-space MAX_TOKENS --yesBir Space'e SSH ile bağlanın (Geliştirme Modu)
Bir Space’in Dev Mode konteynerine bir SSH oturumu açmak için hf spaces ssh komutunu kullanın. Dev Mode etkinleştirilmemişse, CLI bunu etkinleştirmenizi ister (veya istemi atlamak için --auto kullanın).
SSH genel anahtarınızın ayarlarınızda kayıtlı olması gerekir. Daha fazla ayrıntı için Geliştirici Modu belgelerini inceleyin.
# SSH into a Space
>>> hf spaces ssh username/my-space
# Print the SSH command without running it
>>> hf spaces ssh username/my-space --dry-run
# Auto-enable Dev Mode if disabled
>>> hf spaces ssh username/my-space --auto
# Use a specific SSH key
>>> hf spaces ssh username/my-space -i ~/.ssh/id_ed25519hf papers
Hub'daki makalelerin listesini almak, aramak, yapılandırılmış bilgiye erişmek ve markdown içeriğini okumak için hf papers kullanın.
Makaleleri listele
# List most recent daily papers
>>> hf papers ls
# List trending papers
>>> hf papers ls --sort=trending
# List papers from a specific date
>>> hf papers ls --date=2025-01-23
# List today's papers
>>> hf papers ls --date=today
# List papers from a specific week
>>> hf papers ls --week=2025-W09
# List papers from a specific month
>>> hf papers ls --month=2025-02
# List papers submitted by a specific user
>>> hf papers ls --submitter=akhaliq
# Limit results
>>> hf papers ls --sort=trending --limit=5Makaleleri ara
# Search papers by keyword
>>> hf papers search "vision language"
# Limit search results
>>> hf papers search "diffusion models" --limit=10
# Output as JSON
>>> hf papers search "attention" --format=jsonMakale bilgilerini al
# Get structured metadata for a paper (returns JSON)
>>> hf papers info 2601.15621Makaleyi markdown olarak oku
# Read the full paper content as markdown
>>> hf papers read 2601.15621hf tartışmaları
Hub depolarındaki tartışmaları ve pull request'leri doğrudan terminalinizden yönetmek için hf discussions kullanın. Hem tartışmaları hem de PR'ları listeleyebilir, görüntüleyebilir, oluşturabilir, yorum ekleyebilir, kapatabilir, yeniden açabilir ve birleştirebilirsiniz. Hub'ın topluluk özelliklerinin nasıl çalıştığına dair kapsamlı bir kılavuz için Tartışmalar ve Pull Request'ler kılavuzu'na bakın.
Tartışmaları listele
Bir depodaki açık tartışmaları ve PR'ları listelemek için depo kimliğini hf discussions list (veya kısaltması hf discussions ls) komutuna iletin:
>>> hf discussions list username/my-modelSonuçları tür (discussion veya pull_request), durum (open, closed, merged veya all) ya da yazar bazında daraltabilirsiniz:
>>> hf discussions list username/my-model --kind pull_request --status merged
>>> hf discussions list username/my-model --author aliceBetikleme için yapılandırılmış çıktı almak için --format json veya yalnızca tartışma numaralarını (satır başına bir tane) yazdırmak için --quiet kullanın:
>>> hf discussions list username/my-model --format json
>>> hf discussions ls username/my-model --quietBir tartışma veya PR için bilgi alın
Belirli bir tartışma veya PR'yi denetlemek için depo kimliğini ve tartışma numarasını iletin:
>>> hf discussions info username/my-model 5Çıktı, tartışma meta verilerini (başlık, durum, yazar vb.) ve konuşma olaylarının tam listesini içerir. Bir çekme isteğinin farkını (diff) görüntülemek için bunun yerine hf discussions diff kullanın.
Makine tarafından okunabilir çıktı için --format json kullanın ve diğer araçlara boru hattı (pipe) ile yönlendirirken ANSI renklerini kaldırmak için NO_COLOR=1 ayarlayın.
Bir tartışma veya PR oluşturun
Yeni bir tartışma açmak için --title ile bir başlık belirtin. İsteğe bağlı olarak --body ile bir açıklama ekleyebilir veya --body-file ile bir dosyadan yükleyebilirsiniz:
>>> hf discussions create username/my-model --title "Bug report"
>>> hf discussions create username/my-model --title "Feature request" --body "Please add X"
>>> hf discussions create username/my-model --title "Report" --body-file report.mdSıradan bir tartışma yerine bir çekme isteği oluşturmak için --pull-request bayrağını ekleyin:
>>> hf discussions create username/my-model --title "Fix typo" --pull-requestBir tartışma veya PR'da yorum yapın
Bir tartışmaya veya PR'a numarasını belirterek yorum ekleyin. Yorum gövdesi --body ile satır içi olarak geçirilebilir, --body-file ile bir dosyadan okunabilir veya --body-file - kullanılarak stdin'den aktarılabilir:
>>> hf discussions comment username/my-model 5 --body "Thanks for reporting!"
>>> hf discussions comment username/my-model 5 --body-file review.md
>>> echo "LGTM" | hf discussions comment username/my-model 5 --body-file -Yorumu düzenle
Mevcut bir yorumu yerinde düzenlemek için tartışma numarasını ve yorum kimliğini iletin. Yorum kimlikleri hf discussions info ile alınabilir:
>>> hf discussions edit username/my-model 5 abc123 --body "Updated comment."
>>> hf discussions edit username/my-model 5 abc123 --body-file fixed.mdGörseller ve videolar ekleyin
hf discussions create, comment veya edit komutlarına --attach parametresini ekleyerek bir görüntü, video veya ses dosyası yükleyebilir ve Hub'da bir dosyayı yorum kutusuna sürüklediğinizde olduğu gibi gövdeye gömebilirsiniz. Gövde zaten dosyaya atıfta bulunuyorsa, örneğin  gibi, bu atıf yüklenen dosyayı işaret eder. Aksi takdirde dosya gövdenin sonuna eklenir. Eklenen bir görüntünün alt metnini ayarlamak için # işaretinden sonra ekleyin:
>>> hf discussions create username/my-model --title "Fix rendering" --pr --body "Before: " --attach ./before.png --attach "./after.png#After the fix"
>>> hf discussions comment username/my-model 5 --body "Here is a demo:" --attach demo.mp4Desteklenen biçimler PNG, JPEG, GIF, WebP, MP4, MOV, WebM, MP3 ve WAV'dir; boyut sınırı 10MB'dır (videolar için 50MB).
Kapat, yeniden aç ve birleştir
Bir tartışmayı veya PR'ı hf discussions close ile kapatabilirsiniz. Varsayılan olarak onay için size soru sorulur. Soruyu atlamak için --yes, kapatma mesajı bırakmak için --comment parametresini iletin:
>>> hf discussions close username/my-model 5
>>> hf discussions close username/my-model 5 --yes --comment "Resolved"Daha önce kapatılmış bir tartışmayı yeniden açmak için hf discussions reopen komutunu kullanın:
>>> hf discussions reopen username/my-model 5 --yesBir çekme isteğini birleştirmek için hf discussions merge komutunu kullanın:
>>> hf discussions merge username/my-model 5 --yesYeniden adlandırma ve fark
Yeni başlığı sağlayarak bir tartışmayı yeniden adlandırabilirsiniz:
>>> hf discussions rename username/my-model 5 "Updated title"Bir çekme isteğinin farkını doğrudan terminalde görüntülemek için hf discussions diff komutunu kullanın:
>>> hf discussions diff username/my-model 5hf repos
hf repos, Hugging Face Hub üzerinde depoları listeleme, oluşturma, çoğaltma, silme, taşıma, ayarlarını güncelleme ve dosyaları silme işlemlerini yapmanızı sağlar. Ayrıca dalları ve etiketleri yönetmek için alt komutlar da içerir.
Depoları listele
Depolama bilgileriyle tüm depolarınızı (modeller, veri kümeleri, uzaylar ve varlıklar) depolama kullanımına göre sıralayarak listelemek için hf repos ls komutunu kullanın. Varsayılan olarak yalnızca ilk 30 depo gösterilir:
# List all your repos (first 30)
>>> hf repos ls
REPOSITORY TYPE UPDATED VISIBILITY STORAGE % OF TOTAL
------------------------ ------- ---------- ---------- -------- ----------
username/bucket-raw bucket 2026-04-29 public 1.7 TB 72.3%
username/my-model model 2026-05-06 public 4.8 GB 18.1%
username/my-dataset dataset 2024-09-14 private 598.4 MB 5.2%
Hint: Showing 30 of 42 repos. Use `--limit 0` to list all.Depo türüne göre filtreleyin, ada göre arayın veya sınırı ayarlayın:
# List only models
>>> hf repos ls --type model
# Search by name
>>> hf repos ls --search "bert"
# List repos from an organization
>>> hf repos ls --namespace my-org
# Combine filters
>>> hf repos ls --namespace my-org --type dataset --search "train"
# List all repos (no limit)
>>> hf repos ls --limit 0Betikleme için --format json veya yalnızca kimlikler için -q kullanın. Borulama yaparken tüm depoları dışa aktarmak için --limit 0 kullanın:
>>> hf repos ls --limit 0 --format json | jq '.[].id'
>>> hf repos ls -qDepo oluşturun
>>> hf repos create Wauplin/my-cool-model
Successfully created Wauplin/my-cool-model on the Hub.
Your repo is now available at https://huggingface.co/Wauplin/my-cool-modelÖzel bir veri seti veya Space oluşturun:
>>> hf repos create my-cool-dataset --repo-type dataset --private
>>> hf repos create my-gradio-space --repo-type space --sdk gradioDepo zaten var olabilirse --exist-ok ve bir Enterprise kaynak grubunu hedeflemek için --resource-group-id kullanın.
Belirli bir bölgede bir depo oluşturun:
>>> hf repos create my-model --region usBir depoyu çoğalt
Mevcut bir model, veri seti veya Space'i hesabınıza (veya bir organizasyona) kopyalamak için hf repos duplicate kullanın. Kopyalama işlemi sunucuda gerçekleşir ve git geçmişini korur:
>>> hf repos duplicate openai/gdpval --type dataset
>>> hf repos duplicate openai/gdpval myorg/my-gdpval --type dataset --privateYeni depodaki LFS/Xet dosyaları, komut döndükten sonra arka planda kopyalanmaya devam edebilir. Bu durumda bir uyarı yazdırılır ve kopyalama işlemi tamamlanana kadar bu dosyaların yeni depodan indirilmesi başarısız olabilir.
Bir depoyu sil
>>> hf repos delete Wauplin/my-cool-modelVeri kümeleri ve Uzaylar:
>>> hf repos delete my-cool-dataset --repo-type dataset
>>> hf repos delete my-gradio-space --repo-type spaceBir depoyu taşı
>>> hf repos move old-namespace/my-model new-namespace/my-modelDepo ayarlarını güncelle
>>> hf repos settings Wauplin/my-cool-model --gated auto
>>> hf repos settings Wauplin/my-cool-model --private true
>>> hf repos settings Wauplin/my-cool-model --private false--gated:auto,manual,falsedeğerlerinden biri--private true|false: depo gizliliğini ayarlar
Bir depodan dosyaları silme
hf repos delete-files <repo_id> alt komutu, bir depodan dosya silmenizi sağlar. İşte bazı kullanım örnekleri.
Bir klasörü sil:
>>> hf repos delete-files Wauplin/my-cool-model folder/
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...Birden çok dosyayı silme:
>>> hf repos delete-files Wauplin/my-cool-model file.txt folder/pytorch_model.bin
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...Dosya kümelerini silmek için joker desenleri kullanın. Desenler, burada belgelenen Standart Jokerler (globbing desenleri)dir. Desen eşleştirme fnmatch tabanlıdır.
fnmatch'in, geleneksel Unix kabuğu kümeleme işlemlerinden farklı olarak*ile yol sınırlarını aşarak eşleşme yaptığını unutmayın. Örneğin,"data/*.json"hemdata/file.jsonhem de anddata/subdir/file.jsonile eşleşir. Yalnızca doğrudan dizindeki dosyalarla eşleşmek için bunları açıkça listelemeniz veya daha spesifik desenler kullanmanız gerekir.
>>> hf repos delete-files Wauplin/my-cool-model "*.txt" "folder/*.bin"
Files correctly deleted from repo. Commit: https://huggingface.co/Wauplin/my-cool-mo...Bir depodan dosya silmek için kimlik doğrulaması ve yetkilendirme gereklidir. Varsayılan olarak, yerel olarak kaydedilen ( hf auth login kullanılarak) token kullanılır. Kimlik doğrulamasını açıkça yapmak isterseniz --token seçeneğini kullanın:
>>> hf repos delete-files --token=hf_**** Wauplin/my-cool-model file.txthf repos branch
Hub'daki depolar için dallar oluşturmak ve silmek için hf repos branch kullanın.
# Create a branch
>>> hf repos branch create Wauplin/my-cool-model dev
# Create a branch from a specific revision
>>> hf repos branch create Wauplin/my-cool-model release-1 --revision refs/pr/104
# Delete a branch
>>> hf repos branch delete Wauplin/my-cool-model devTüm komutlar, açık kimlik doğrulaması gerekiyorsa
--repo-type(model,dataset,spacedeğerlerinden biri) ve--tokenparametrelerini kabul eder. Tüm seçenekleri görmek için herhangi bir komutta--helpkullanın.
hf önbellek
Yerel Hugging Face önbellek dizininizi yönetmek için hf cache kullanın. Önbellek, Hub'dan indirilen modelleri, veri kümelerini, Spaces'leri ve çekirdekleri saklar.
# List cached repositories
>>> hf cache ls
# List cached revisions
>>> hf cache ls --revisions
# Remove specific items from cache
>>> hf cache rm model/gpt2
# Remove unreferenced revisions
>>> hf cache prune
# Verify cached file checksums
>>> hf cache verify gpt2hf cache ls
Yerel Hugging Face önbelleğinizde nelerin saklandığını incelemek için hf cache ls komutunu kullanın. Varsayılan olarak bilgiler depoya göre toplanır:
>>> hf cache ls
ID SIZE LAST_ACCESSED LAST_MODIFIED REFS
--------------------------- -------- ------------- ------------- -----------
dataset/nyu-mll/glue 157.4M 2 days ago 2 days ago main script
model/LiquidAI/LFM2-VL-1.6B 3.2G 4 days ago 4 days ago main
model/microsoft/UserLM-8b 32.1G 4 days ago 4 days ago main
Found 3 repo(s) for a total of 5 revision(s) and 35.5G on disk.Belirli anlık görüntülere inmek için --revisions ekleyin ve önemli olanlara odaklanmak için filtreleri zincirleyin:
>>> hf cache ls --filter "size>30g" --revisions
ID REVISION SIZE LAST_MODIFIED REFS
------------------------- ---------------------------------------- -------- ------------- ----
model/microsoft/UserLM-8b be8f2069189bdf443e554c24e488ff3ff6952691 32.1G 4 days ago main
Found 1 repo(s) for a total of 1 revision(s) and 32.1G on disk.Komut, betik yazımı için birkaç çıktı biçimini destekler: --format json yapılandırılmış nesneleri yazdırır, --format csv virgülle ayrılmış satırlar yazar ve --quiet yalnızca kimlikleri yazdırır. --sort ile girdileri accessed, modified, name veya size (sıralamayı kontrol etmek için :asc veya :desc ekleyin) göre sıralayın ve --limit ile sonuçları en üst N girdiyle sınırlayın. Bunları alternatif önbellek konumlarını hedeflemek için --cache-dir ile birleştirin. Gelişmiş iş akışları için Önbelleğinizi yönetin kılavuzuna bakın.
hf cache ls --q ile seçilen önbellek girdilerini, kimlikleri hf cache rm komutuna boru (pipe) ile aktararak silin:
>>> hf cache rm $(hf cache ls --filter "accessed>1y" -q) -y
About to delete 2 repo(s) totalling 5.31G.
- model/meta-llama/Llama-3.2-1B-Instruct (entire repo)
- model/hexgrad/Kokoro-82M (entire repo)
Deleted 2 repo(s) and 2 revision(s); freed 5.31G.hf cache rm
hf cache rm, önbelleğe alınmış depoları, bireysel revizyonları veya tek dosyaları siler. Bir veya daha fazla depo kimliği (model/bert-base-uncased), hf:// URI’si veya revizyon özetini iletin:
>>> hf cache rm model/LiquidAI/LFM2-VL-1.6B
About to delete 1 repo(s) totalling 3.2G.
- model/LiquidAI/LFM2-VL-1.6B (entire repo)
Proceed with deletion? [y/N]: y
Deleted 1 repo(s) and 2 revision(s); freed 3.2G.Depo düzeyindeki hf:// URI'leri de desteklenir:
>>> hf cache rm hf://models/openai-community/gpt2 --dry-run
About to delete 1 repo(s) totalling 1.1G.
- model/openai-community/gpt2 (entire repo)
Dry run: no files were deleted.Tüm bir depoyu değil de tek bir dosyayı, örneğin bir GGUF kuantizasyonunu kaldırmak için bir hf:// dosya URI'si geçirin. Dosya, deponun önbelleğe alınmış tüm revizyonlarından kaldırılır ve blob'u, başka önbelleğe alınmış bir dosya hâlâ ona referans vermiyorsa silinir:
>>> hf cache rm hf://models/unsloth/gemma-3-27b-it-GGUF/gemma-3-27b-it-Q4_K_M.gguf --dry-run
About to delete 1 file(s) totalling 16.5G.
- model/unsloth/gemma-3-27b-it-GGUF@3f4b5c1d2e6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c/gemma-3-27b-it-Q4_K_M.gguf
Dry run: no files were deleted.Revizyon kullanılabilir durumda kalır ve silinen dosya, bir sonraki ihtiyaç duyulduğunda yeniden indirilir. Yollar tam olarak eşleşmelidir: klasörler ve glob desenleri desteklenmez ve dosya hedefleri, aynı çağrıda depolar veya revizyonlarla karıştırılamaz.
Aynı çağrıda depoları ve belirli revizyonları birleştirin. Etkiyi önizlemek için --dry-run kullanın veya onay istemini atlamak için --yes kullanın—otomatik betiklerde kullanışlıdır:
>>> hf cache rm model/t5-small 8f3ad1c --dry-run
About to delete 1 repo(s) and 1 revision(s) totalling 1.1G.
- model/t5-small:
8f3ad1c [main] 1.1G
Dry run: no files were deleted.Varsayılan önbellek konumu dışında çalışırken, komutu --cache-dir PATH ile eşleştirin.
hf cache prune
hf cache prune, önbellek çöpü tarafından işgal edilen alanı geri kazandıran pratik bir kısayoldur: her ayrılmış (referanssız) revizyon (yalnızca bir dal veya etiket üzerinden hâlâ erişilebilir olan revizyonları koruyarak), yarıda kesilen indirmelerden kalan .incomplete dosyaları ve önbellekteki hiçbir depo tarafından artık referanslanmayan paylaşılan bloblar:
>>> hf cache prune
About to delete 3 unreferenced revision(s) and 2 incomplete download(s) (2.4G total).
- model/t5-small:
1c610f6b [refs/pr/1] 820.1M
d4ec9b72 [(detached)] 640.5M
- dataset/google/fleurs:
2b91c8dd [(detached)] 937.6M
Proceed? [y/N]: y
Deleted 3 unreferenced revision(s) and 2 incomplete download(s); freed 2.4G..incomplete dosyaları, bir indirme yarıda kesildiğinde geride kalan kısmi indirmelerdir. Bunlar hf cache ls/rm tarafından takip edilmez (bu komutlar revizyon düzeyinde çalışır), bu nedenle hf cache ls bunları bir ipucuyla belirtir ve hf cache prune bunları otomatik olarak siler.
Diğer önbellek komutlarında olduğu gibi --dry-run, --yes ve --cache-dir kullanılabilir. Daha fazla örnek için Önbelleğinizi yönetin kılavuzuna bakın.
hf cache verify
Yerel dosyaları Hub üzerindeki özet denetimleriyle doğrulamak için hf cache verify komutunu kullanın. Doğrulama için bir önbellek anlık görüntüsü veya normal bir yerel dizin seçebilirsiniz.
Örnekler:
# Verify main revision of a model in cache
>>> hf cache verify deepseek-ai/DeepSeek-OCR
# Verify a specific revision
>>> hf cache verify deepseek-ai/DeepSeek-OCR --revision refs/pr/5
>>> hf cache verify deepseek-ai/DeepSeek-OCR --revision ef93bf4a377c5d5ed9dca78e0bc4ea50b26fe6a4
# Verify a private repo
>>> hf cache verify me/private-model --token hf_***
# Verify a dataset
>>> hf cache verify karpathy/fineweb-edu-100b-shuffle --repo-type dataset
# Verify files in a local directory
>>> hf cache verify deepseek-ai/DeepSeek-OCR --local-dir /path/to/repoVarsayılan olarak, komut eksik veya fazladan dosyalar hakkında uyarı verir. Bu uyarıları hatalara dönüştürmek için bayrakları kullanın:
>>> hf cache verify deepseek-ai/DeepSeek-OCR --fail-on-missing-files --fail-on-extra-filesBaşarılı olursa bir özet görürsünüz:
✅ Verified 13 file(s) for 'deepseek-ai/DeepSeek-OCR' (model) in ~/.cache/huggingface/hub/models--meta-llama--Llama-3.2-1B-Instruct/snapshots/9213176726f574b556790deb65791e0c5aa438b6 All checksums match.
Eşleşme hataları tespit edilirse, komut ayrıntılı bir liste basar ve sıfır olmayan bir durum koduyla çıkar.
hf repos tag
Hub'daki depolar için etiket oluşturma, listeleme ve silme işlemlerini hf repos tag komutunu kullanarak yapabilirsiniz.
# Create a tag
>>> hf repos tag create my-model v1.0
# List tags
>>> hf repos tag list my-model
# Delete a tag
>>> hf repos tag delete my-model v1.0Bir modele etiket ekle
Bir depoya etiket eklemek için repo_id ve tag adını belirtmeniz gerekir:
>>> hf repos tag create Wauplin/my-cool-model v1.0
You are about to create tag v1.0 on model Wauplin/my-cool-model
Tag v1.0 created on Wauplin/my-cool-modelBir modeli belirli bir revizyonda etiketleyin
Belirli bir revizyonu etiketlemek istiyorsanız --revision seçeneğini kullanabilirsiniz. Varsayılan olarak etiket, main dalında oluşturulur:
>>> hf repos tag create Wauplin/my-cool-model v1.0 --revision refs/pr/104
You are about to create tag v1.0 on model Wauplin/my-cool-model
Tag v1.0 created on Wauplin/my-cool-modelBir veri seti veya Space etiketleyin
Bir veri seti veya Space etiketlemek istiyorsanız, --repo-type seçeneğini belirtmeniz gerekir:
>>> hf repos tag create bigcode/the-stack v1.0 --repo-type dataset
You are about to create tag v1.0 on dataset bigcode/the-stack
Tag v1.0 created on bigcode/the-stackEtiketleri listele
Bir depodaki tüm etiketleri listelemek için list (veya ls) alt komutunu kullanın:
>>> hf repos tag list Wauplin/gradio-space-ci --repo-type space
Tags for space Wauplin/gradio-space-ci:
0.2.2
0.2.1
0.2.0
0.1.2
0.0.2
0.0.1Bir etiketi sil
Bir etiketi silmek için delete alt komutunu kullanın:
>>> hf repos tag delete Wauplin/my-cool-model v1.0
You are about to delete tag v1.0 on model Wauplin/my-cool-model
Proceed? [Y/n] y
Tag v1.0 deleted on Wauplin/my-cool-modelOnay adımını atlamak için -y parametresini de geçebilirsiniz.
hf env
hf env komutu, makine kurulumunuzla ilgili ayrıntıları görüntüler. GitHub üzerinde bir sorun açtığınızda, bakımcıların (maintainer) sorununuzu araştırmalarına yardımcı olmak için bu komut faydalıdır.
>>> hf env
Copy-and-paste the text below in your GitHub issue.
- huggingface_hub version: 1.0.0.rc6
- Platform: Linux-6.8.0-85-generic-x86_64-with-glibc2.35
- Python version: 3.11.14
- Running in iPython ?: No
- Running in notebook ?: No
- Running in Google Colab ?: No
- Running in Google Colab Enterprise ?: No
- Token path ?: /home/wauplin/.cache/huggingface/token
- Has saved token ?: True
- Who am I ?: Wauplin
- Configured git credential helpers: store
- Installation method: unknown
- Torch: N/A
- httpx2: 2.0.0
- hf_xet: 1.1.10
- gradio: 5.41.1
- tensorboard: N/A
- pydantic: 2.11.7
- ENDPOINT: https://huggingface.co
- HF_HUB_CACHE: /home/wauplin/.cache/huggingface/hub
- HF_ASSETS_CACHE: /home/wauplin/.cache/huggingface/assets
- HF_TOKEN_PATH: /home/wauplin/.cache/huggingface/token
- HF_STORED_TOKENS_PATH: /home/wauplin/.cache/huggingface/stored_tokens
- HF_HUB_OFFLINE: False
- HF_HUB_DISABLE_TELEMETRY: False
- HF_HUB_DISABLE_PROGRESS_BARS: None
- HF_HUB_DISABLE_SYMLINKS_WARNING: False
- HF_HUB_DISABLE_EXPERIMENTAL_WARNING: False
- HF_HUB_DISABLE_IMPLICIT_TOKEN: False
- HF_HUB_DISABLE_XET: False
- HF_HUB_DISABLE_SHARED_BLOBS: False
- HF_HUB_ETAG_TIMEOUT: 10
- HF_HUB_DOWNLOAD_TIMEOUT: 10hf jobs
Docker benzeri tanıdık bir arayüzle Hugging Face altyapısında hesaplama işleri çalıştırın.
hf jobs, Hugging Face altyapısında (GPU ve TPU dahil!) basit komutlarla her şeyi çalıştırmanızı sağlayan bir komut satırı aracıdır. docker run gibi düşünün, ancak kodu A100'lerde çalıştırmak için.
Jobs ve fiyatlandırma hakkında genel bir bakış için Hub Jobs belgelerini inceleyin. CLI ile birlikte Python API kullanımını görmek için Jobs çalıştırma ve yönetme kılavuzuna göz atın.
# Directly run Python code
>>> hf jobs run --name hello-world python:3.12 python -c 'print("Hello from the cloud!")'
# Use GPUs without any setup
>>> hf jobs run --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
... python -c "import torch; print(torch.cuda.get_device_name())"
# Run in an organization account
>>> hf jobs run --namespace my-org-name python:3.12 python -c 'print("Running in an org account")'
# Run from Hugging Face Spaces
>>> hf jobs run hf.co/spaces/lhoestq/duckdb duckdb -c 'select "hello world"'
# Run a Python script with `uv` (experimental)
>>> hf jobs uv run --name my-script my_script.pyHugging Face İşleri, ön ödemeli kredileri olan herhangi bir kullanıcı veya kuruluş için kullanılabilir.
Hızlı Başlangıç
1. İlk işinizi çalıştırın
# Run a simple Python script
>>> hf jobs run python:3.12 python -c 'print("Hello from HF compute!")'Bu komut işi çalıştırır ve günlükleri gösterir. İşin arka planda çalıştırılması ve yalnızca İş Kimliği’nin yazdırılması için --detach parametresini geçebilirsiniz. İş Kimliği’nin yalnızca kendisinin yazdırılması için -q ekleyin; bu, kimliği bir betikte yakalamak için kullanışlıdır:
>>> JOB_ID=$(hf jobs run -dq python:3.12 python train.py)
>>> hf jobs wait "$JOB_ID"2. İş durumunu kontrol edin
# List your running jobs
>>> hf jobs ls
# List all jobs
>>> hf jobs ls -a
# Inspect the status of a job
>>> hf jobs inspect <job_id>
# View logs from a job
>>> hf jobs logs <job_id>
# View resources usage stats and metrics of running jobs
>>> hf jobs stats
# View resources usage stats and metrics of some jobs
>>> hf jobs stats [job_ids]...
# Follow live stats until the jobs complete
>>> hf jobs stats -f [job_ids]...
# Cancel a job
>>> hf jobs cancel <job_id>
# Wait until one or more jobs finish (exit code 0 only if all jobs completed successfully)
>>> hf jobs wait <job_id> [<job_id>...]
# Wait for all currently running jobs
>>> hf jobs ls -q | xargs hf jobs waitAyrıştırılmamış hf jobs run ve hf jobs wait, bir Job başarısız olursa sıfır olmayan bir kodla sonlanır; bu sayede komutları && ile zincirleyebilirsiniz:
>>> hf jobs run python:3.12 python train.py && echo "training succeeded"3. GPU'da çalıştır
--flavor seçeneğiyle işleri GPU veya TPU üzerinde de çalıştırabilirsiniz. Örneğin, bir PyTorch işini A10G GPU üzerinde çalıştırmak için:
# Use an A10G GPU to check PyTorch CUDA
>>> hf jobs run --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
... python -c 'import torch; print(f"This code ran with the following GPU: {torch.cuda.get_device_name()}")'Bunu çalıştırdığınızda aşağıdaki çıktı görüntülenir!
This code ran with the following GPU: NVIDIA A10G
-- işareti, Jobs seçeneklerini komutunuza veya betiğinize aktarılan argümanlardan ayırmak için kullanılır.
Jobs, -- işaretinden sonraki seçenekleri yorumlamaz.
>>> hf jobs run --flavor cpu-basic python:3.12 -- python --helpBitti! Artık Hugging Face altyapısında kod çalıştırıyorsunuz.
Yaygın Kullanım Senaryoları
- Model Eğitimi: Altyapıyı yönetmeden GPU'larda (T4, A10G, A100) modelleri ince ayarlayın veya eğitin
- Sentetik Veri Üretimi: Güçlü donanımlarda LLM'ler kullanarak büyük ölçekli veri kümeleri oluşturun
- Veri İşleme: Yüksek CPU yapılandırmalarıyla paralel iş yükleri için devasa veri kümelerini işleyin
- Toplu Çıkarım: Optimize edilmiş GPU kurulumları kullanarak binlerce örnek üzerinde çevrimdışı çıkarım çalıştırın
- Deneysel Çalışmalar ve Karşılaştırmalar: Yeniden üretilebilir sonuçlar için tutarlı donanımda ML deneyleri çalıştırın
- Geliştirme ve Hata Ayıklama: Yerel CUDA kurulumu olmadan GPU kodunu test edin
Ortam değişkenlerini ve Gizli bilgileri iletil
İşinize ortam değişkenlerini şu şekilde iletebilirsiniz
# Pass environment variables
>>> hf jobs run -e FOO=foo -e BAR=bar python:3.12 python -c 'import os; print(os.environ["FOO"], os.environ["BAR"])'# Pass an environment from a local .env file
>>> hf jobs run --env-file .env python:3.12 python -c 'import os; print(os.environ["FOO"], os.environ["BAR"])'# Pass secrets by name - the value is read from your environment, never from the command line
>>> hf jobs run -s MY_SECRET python:3.12 python -c 'import os; print(os.environ["MY_SECRET"])'# Pass secrets from a local .env.secrets file - they will be encrypted server side
>>> hf jobs run --secrets-file .env.secrets python:3.12 python -c 'import os; print(os.environ["MY_SECRET"])'# Or pipe them in, so the values touch neither the command line nor the disk
>>> printf 'MY_SECRET=psswrd\n' | hf jobs run --secrets-file - python:3.12 python -c 'import os; print(os.environ["MY_SECRET"])'Secrets, üç formda da sunucu tarafında şifrelenir. -s MY_SECRET=psswrd de çalışır, ancak bu durumda değer kabuk geçmişinize ve süreç listesine (/proc/<pid>/cmdline Linux'ta) karışır; bu yüzden CLI, bu formu kullandığınızda stderr'e bir uyarı basar. Bu formu, gerçekten hassas olmayan değerler için kullanın. Aynı durum --token <value> için de geçerlidir: hf auth login veya HF_TOKEN ortam değişkenini tercih edin. Bir env veya secrets dosyası yalnızca sizin tarafından okunabilir olmalıdır (chmod 600) — CLI, bu koşul sağlanmıyorsa uyarı verir.
Yerel Hugging Face tokeninizi örtük olarak iletmek için
--secrets HF_TOKENkullanın. Bu sözdizimiyle gizli değer, ortam değişkeninden alınır.HF_TOKENiçin, ortam değişkeni ayarlanmamışsa Hugging Face ana klasöründeki token dosyasını okuyabilir.
Yerleşik Ortam Değişkenleri
İş konteynerinin içinde, aşağıdaki ortam değişkenleri otomatik olarak kullanılabilir:
| Değişken | Açıklama |
|---|---|
JOB_ID | Mevcut işin benzersiz tanımlayıcısı. Bu değeri, işe programatik olarak atıfta bulunmak için kullanın. |
ACCELERATOR | Mevcut hızlandırıcının türü (ör. t4-medium, a10g-small, a100x4). Hızlandırıcı yoksa boş bırakılır. |
CPU_CORES | İşin kullanımına sunulan CPU çekirdeği sayısı (ör. 2, 4, 8). |
MEMORY | İşin kullanılabilir bellek miktarı (ör. 16Gi, 32Gi). |
# Access job environment information
>>> hf jobs run python:3.12 python -c "import os; print(f'Job: {os.environ.get(\"JOB_ID\")}, CPU: {os.environ.get(\"CPU_CORES\")}, Mem: {os.environ.get(\"MEMORY\")}')"İş Zaman Aşımı
İşlerin varsayılan zaman aşımı 30 dakikadır; bu süre dolduğunda işler otomatik olarak durdurulur. Model eğitimi gibi uzun süreli görevler için --timeout seçeneğini kullanarak özel bir zaman aşımı belirleyin:
# Set timeout in seconds (default unit)
>>> hf jobs run --timeout 7200 python:3.12 python train.py
# Use time units: s (seconds), m (minutes), h (hours), d (days)
>>> hf jobs run --timeout 2h pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel python train.py
>>> hf jobs run --timeout 90m python:3.12 python process_data.py
>>> hf jobs run --timeout 1.5h python:3.12 python train.py # floats are supported--timeout seçeneği, UV betikleri ve zamanlanmış işlerle de çalışır:
# UV script with timeout
>>> hf jobs uv run --timeout 2h training_script.py
# Scheduled job with timeout
>>> hf jobs scheduled run @daily --timeout 4h python:3.12 python daily_task.pyİşiniz zaman aşımını aşarsa otomatik olarak sonlandırılır. Beklenmeyen iş sonlandırmalarını önlemek için uzun süreli görevlerde her zaman uygun bir zaman aşımı ve bazı pay bırakarak ayarlayın.
Bir İşlem'i Yeniden Deneyin ve Çalıştırın
--attempts, ilk çalıştırma dahil olmak üzere maksimum deneme sayısını belirler. Docker, UV ve zamanlanmış Job'larla birlikte çalışır. Bir Job'ı yeniden çalıştırmak, aynı kaydedilmiş spec ile yeni bir Job başlatır:
>>> hf jobs run --attempts 3 --detach python:3.12 python train.py
>>> hf jobs rerun <job_id>3 deneme sayısı, bir Job başarısız olduğunda en fazla iki yeniden denemeye izin verir. hf jobs rerun komutu da orijinal deneme sayısını yeniden kullanır. hf jobs run komutunda olduğu gibi, yeni Job'un loglarını tamamlanana kadar akış olarak görüntüler. Hemen dönmek için --detach bayrağını kullanın.
Donanım
Kullanılabilir --flavor seçenekleri:
- CPU:
cpu-basic,cpu-upgrade - GPU:
t4-small,t4-medium,l4x1,l4x4,a10g-small,a10g-large,a10g-largex2,a10g-largex4,a100-large - TPU:
v5e-1x1,v5e-2x2,v5e-2x4
(07/2025'te Hugging Face suggested_hardware belgelerinden güncellendi)
Hacimler
-v veya --volume kullanarak Job diskinde bir hacim bağlayın.
Herhangi bir Hugging Face Deposu (model/veri seti/alan) veya Depolama Kovası'nı hf:// URL şeması kullanarak bağlayabilirsiniz. Örneğin:
- model deposu bağlama:
-v hf://openai/gpt-oss-120b:/model - veri seti deposu bağlama:
-v hf://datasets/HuggingFaceFW/fineweb:/data - bir depolama kovasını bağlayın:
-v hf://buckets/username/my-bucket:/mnt - bir alanı bağlayın:
-v hf://spaces/username/my-space:/app - bir repoda alt klasör bağlama:
-v hf://datasets/org/ds/train:/data
Daha sonra bağlı birimi yerel bir dizin olarak kullanabilirsiniz:
# Docker Job with a mounted volume as input
>>> hf jobs run -v hf://datasets/HuggingFaceFW/fineweb:/dataset \
... duckdb/duckdb duckdb -c "SELECT * FROM '/dataset/**/*.parquet' LIMIT 5"
# UV Job with a mounted volume to save checkpoints when training a model
>>> hf jobs uv run -v hf://buckets/username/my-bucket:/training-outputs \
... sft.py --output-dir /training-outputs/training-v3-final ...Modeller, veri setleri ve uzaylar her zaman salt okunur olarak bağlanır. Depolama varlıkları varsayılan olarak okuma+yazma erişimine sahiptir — bu, sık sık değişen veriler için özellikle faydalıdır, çünkü dosyalar yerinde üzerine yazılabilir veya silinebilir.
Salt okunur modu etkinleştirmek için :ro kullanın:
- salt okunur bir depolama kovası bağlamak:
-v hf://buckets/username/my-bucket:/mnt:ro
Yerel verileri bağlama
-v işarecinin kaynak tarafı yerel bir dizin de olabilir. Önce jobs-artifacts Depolama Kova'nıza senkronize edilir ve oluşan kova klasörü İşe bağlanır:
>>> hf jobs uv run -v ./my-data:/data process.pyKomutun yeniden çalıştırılması yalnızca yeni veya değiştirilmiş dosyaları yükler. Yerel dizinler varsayılan olarak salt okunur olarak bağlanır. İşin (Job) hacme yazabilmesi için :rw kullanın; örneğin, İş tamamlandıktan sonra çıktıları almak için (boş bir yerel dizin de işe yarar):
>>> hf jobs uv run -v ./pdfs:/input -v ./md-out:/output:rw ocr.py
...
Hint: Volume '/output' is mounted read-write. Once the job is over, pull back its data with:
hf buckets sync hf://buckets/username/jobs-artifacts/md-out-a1b2c3d4 ./md-outEtiketler
-l veya --label kullanarak bir Job'a etiket ekleyin. Etiketler, bir Job'a metadata uygulayan anahtar=değer çiftleridir. Bir Job'a iki etiket uygulamak için etiket bayrağını (-l veya --label) tekrarlayın:
>>> hf jobs run -l my-label --label foo=bar ubuntu echo "This Job has multiple labels"my-label anahtarı bir değer belirtmediğinden, değeri varsayılan olarak boş bir dize ("") olur.
Bir Job oluştururken name etiketini eklemek için --name kullanın. Adlar, Job'ların arayüzde daha kolay bulunmasını ve tanımlanmasını sağlar; isteğe bağlıdır ve benzersiz olmak zorunda değildir. --name parametresini iletmezseniz, ad Docker görüntüsünden veya betikten otomatik olarak türetilir; bunun yanı sıra komutun ve çözümlenmiş çalışma zamanı ayarlarının (flavor, zaman aşımı, ortam değerleri, …) kısa bir özeti eklenir. Böylece aynı yapılandırma her zaman aynı adı üretir (ör. python:3.12 foo --truc → python-3-12-1a2b3c4d). Komut aynı kalsa bile bir ayarı değiştirmek adı değiştirir. Mevcut bir Job'ın adını da değiştirebilirsiniz:
>>> hf jobs run --name training-v2 python:3.12 python train.py
>>> hf jobs labels <job_id> --name training-v2hf jobs ls komutunda --status, --label ve --name seçeneklerini kullanarak Job’ları filtreleyebilirsiniz. --status bir veya birden çok durum alır, --label key=value çiftlerini alır ve --name, --label name=NAME ifadesinin kısayoludur. Bir Job’ın listelenmesi için tüm filtrelerle eşleşmesi gerekir. Job adı ayrıca kendi NAME sütunu olarak da gösterilir:
# Show completed Jobs
>>> hf jobs ls -a --status completed
# Show running or scheduling Jobs
>>> hf jobs ls --status running,scheduling
# Show Jobs named `training-v2`
>>> hf jobs ls -a --name training-v2
# Show Jobs with the `model=Qwen3-06B` label
>>> hf jobs ls -a --label model=Qwen3-06B
# Combine filters: running Jobs labelled both `env=prod` and `team=ml`
>>> hf jobs ls --status running --label env=prod --label team=mlVarsayılan olarak hf jobs ps, terminalin şişmesini önlemek için en fazla 100 Job görüntüler. Bunu değiştirmek için --limit kullanın veya tümünü göstermek için --limit 0 kullanın:
# Show up to 500 Jobs
>>> hf jobs ps -a --limit 500
# Show all Jobs (no limit)
>>> hf jobs ps -a --limit 0İş portlarını aç
Token korumalı bir port için --expose, kimlik doğrulamasız erişime izin verilmesi gereken bir port için ise --expose-public kullanın. Her iki bayrak da tekrarlanabilir ve birleştirilebilir; Docker, UV ve zamanlanmış Jobs ile çalışır.
# Start a Job with a public HTTP server
>>> hf jobs run --detach --expose-public 8000 python:3.12 python -m http.server 8000
# Replace the configuration on a running Job: port 8000 is private, 9000 is public
>>> hf jobs expose <job_id> 8000 --public 9000
# Close all exposed ports
>>> hf jobs expose <job_id> --clearhf jobs expose, token korumalı portları konumsal argümanlar olarak, herkese açık portları ise --public ile alır. Değişikliği Job'u yeniden çalıştırmadan uygular. Yerine geçen listede yer almayan portlar kapatılır.
Bir İşe SSH ile Bağlan
hf jobs run (veya hf jobs uv run) komutuna --ssh parametresini ekleyerek İş'in (Job) konteynerine SSH üzerinden erişilebilir hale getirin, ardından hf jobs ssh ile bağlantı kurun:
# Start a job with SSH enabled
>>> hf jobs run --ssh --detach python:3.12 sleep infinity
# Open an SSH session into it
>>> hf jobs ssh <job_id>
# Print the SSH command instead of running it
>>> hf jobs ssh <job_id> --dry-run
# Use a specific identity file
>>> hf jobs ssh <job_id> -i ~/.ssh/id_ed25519Yalnızca İş'in ad alanına yazma erişimine sahip kullanıcılar (İş oluşturucusu veya sahip kuruluşun üyeleri), https://huggingface.co/settings/keys adresinde kayıtlı bir SSH genel anahtarıyla kimlik doğrulaması yapılarak izin verilir.
Ağ grupları
hf jobs run (veya hf jobs uv run) komutuna --network-group <name> parametresini ekleyerek, aynı namespace ve resource group içindeki Jobs'lerin birbirine her port üzerinden erişmesini sağlayabilirsiniz. Her üye içinde $HF_NETWORK_GROUP_HOSTNAME, gruptaki tüm Job'lara çözümlenirken, --network-alias <alias> ile bir alias talep eden üyelere ${HF_NETWORK_GROUP_PREFIX}<alias> ile erişilir:
# Start a server, reachable by the other members of the group as "master"
>>> hf jobs run --detach --network-group train --network-alias master python:3.12 python -m http.server 8000
# Start a client in the same group
>>> hf jobs run --detach --network-group train python:3.12 sh -c 'curl --retry 10 --retry-connrefused "http://${HF_NETWORK_GROUP_PREFIX}master:8000/"'Üyeler hazır olmadan önce çözümlenebilir, bu nedenle yeniden denemelerle bağlantı kurun. Grup adları ve takma adları küçük harfli alfanümerik karakterler ve tirelerden oluşur, en fazla 46 ve 34 karakter olabilir.
UV Betikleri (Deneysel)
UV betiklerini (satır içi bağımlılıklara sahip Python betikleri) HF altyapısında çalıştırın. UV betikleri, özel bir yorum sözdizimi kullanarak bağımlılıklarını doğrudan dosyanın içine dahil eden Python betikleridir.
# Run a UV script (creates temporary repo)
>>> hf jobs uv run my_script.py
# Run with persistent repo
>>> hf jobs uv run --repo my-uv-scripts my_script.py
# Run with GPU
>>> hf jobs uv run --flavor t4-small ml_training.py
# Pass arguments to script
>>> hf jobs uv run process.py input.csv output.parquet
# Add dependencies
>>> hf jobs uv run --with transformers --with torch train.py
# Run a script directly from a URL
>>> hf jobs uv run https://huggingface.co/datasets/username/scripts/resolve/main/example.py
# Run a command
>>> hf jobs uv run --with lighteval python -c 'import lighteval'UV betikleri, bağımlılıklarını özel bir yorum sözdizimi kullanarak doğrudan dosya içinde barındıran Python betikleridir. Bu özellik, karmaşık proje kurulumları gerektirmeyen, kendi kendine yeten görevler için onları ideal kılar. UV betikleri hakkında daha fazla bilgi için UV belgelerini inceleyin.
Çakışan seçenekleri betiğinize iletmek için -- kullanın. Burada --help, Jobs yardımını göstermek yerine train.py dosyasına ulaşır:
>>> hf jobs uv run --flavor t4-small train.py -- --helpBu durum biçimlendirme bayrakları için de geçerlidir: hf jobs run, hf jobs uv run ve bunların scheduled varyantları, --format, --json ve -q bayraklarını nerede görürlerse orada tüketir; bu nedenle betiğiniz bunlara ihtiyaç duyuyorsa -- kullanın.
Başlatma yapılandırmasını betikle birlikte gönderin
Bazı betikler yalnızca belirli bir çalışma zamanında doğru şekilde çalışır: belirli bir görüntü, GPU türü, sistem yorumlayıcısı vb. Bir betik, bu yapılandırmayı PEP 723 başlığında isteğe bağlı bir [tool.hf-jobs] tablosu ile birlikte taşıyabilir:
# /// script
# requires-python = ">=3.11"
# dependencies = ["vllm", "datasets"]
#
# [tool.hf-jobs]
# name = "unlimited-ocr"
# image = "vllm/vllm-openai:unlimited-ocr"
# flavor = "l4x1"
# python = "/usr/bin/python3"
# timeout = "2h"
# env = { PYTHONPATH = "/usr/local/lib/python3.12/dist-packages", BATCH_SIZE = "64" }
# secrets = ["HF_TOKEN"]
# labels = { task = "ocr" }
# volumes = ["hf://datasets/org/pdfs:/input"]
# ///hf jobs uv run ocr.py in_ds out_ds komutu, yanlış yorumlayıcıya sahip bir CPU görüntüsünde sessizce çalışmak yerine, doğru çalışma zamanıyla başlatılır. Tablo, düz bir uv run komutu için görünmezdir: [tool.*] tabloları PEP 723'ün bir parçasıdır ve araçlar, kendilerine ait olmayanları görmezden gelir.
Desteklenen anahtarlar, tümü isteğe bağlıdır: image, flavor, python, timeout, name, namespace, env, secrets, labels, volumes, network_group ve network_aliases. Bunlar, aynı adlı bayraklara eşlenir (name, name etiketi olarak saklanır; volumes, -v ile aynı hf://...:/MOUNT_PATH tanımlarını alır; network_aliases, --network-alias değerlerinin bir listesidir). Bilinmeyen bir anahtar, sessizce atlanan bir niyet yerine bir hatadır — flavour gibi bir yazım hatası, bu özelliğin var olmasının önlemek istediği tam olarak o hatadır.
Tüm değerler, env ve labels değerleri dahil olmak üzere, dizeler (string) olmalıdır: -e BATCH_SIZE=64, env = { BATCH_SIZE = "64" } olarak çevrilir, env = { BATCH_SIZE = 64 } olarak değil (TOML sonuncusunu bir tamsayı olarak okur ve tablo reddedilir). Tek istisna, saniye cinsinden tamsayı bir sayıyı da kabul eden timeout'tur (timeout = 7200, timeout = "2h" ile aynıdır).
Betik değerleri varsayılanlardır: açık bir bayrak her zaman önceliklidir ve env, secrets, labels ile volumes girdi girdi birleştirilir, böylece -e ve -v betiğin bildirdiklerine ek yapabilir:
# Same script, on bigger hardware, with one extra env var
>>> hf jobs uv run --flavor a10g-large -e BATCH_SIZE=64 ocr.py in_ds out_dsnetwork_aliases istisnadır: bir Job’un iddia ettiği takma adlar bir küme oluşturur, bu nedenle --network-alias betiğin listesine eklemek yerine onu değiştirir. Zamanlanmış Job’ların hiç bir ağ grubu yoktur, bu yüzden hf jobs scheduled uv run, network_group veya network_aliases bildiren bir betiği reddeder.
secrets yalnızca gizli adları listeler: değerler her zaman betiği çalıştıran kişinin ortamından gelir, asla betiğin kendisinden gelmez (HF_TOKEN de hf auth login üzerinden çözülür). İstenen ancak yerel olarak ayarlanmamış bir gizli değer, bir Job'un sessizce boş bir değer alması yerine bir hata olarak raporlanır. --dry-run kullanıldığında bunun yerine <not set> gösterilir, böylece gizli değerleri henüz sağlanmamış bir betiğin yapılandırması görünür kalır.
Her çalıştırma, gönderdiği yapılandırmayı yankılar ve betikten gelen değerleri işaretler. Hiçbir şey başlatmadan bunu yazdırmak için --dry-run kullanın:
>>> hf jobs uv run --dry-run --flavor a10g-large ocr.py in_ds out_ds
Warning: The script's [tool.hf-jobs] table requests HF_TOKEN: the value(s) from your local environment would be sent to the Job.
Job configuration:
script ocr.py
args in_ds out_ds
image vllm/vllm-openai:unlimited-ocr (from script)
flavor a10g-large
python /usr/bin/python3 (from script)
timeout 2h (from script)
env PYTHONPATH=/usr/local/lib/python3.12/dist-packages (from script)
BATCH_SIZE=64 (from script)
secrets HF_TOKEN=*** (from script)
volumes hf://datasets/org/pdfs:/input (from script)
labels task=ocr (from script)
name=unlimited-ocr (from script)
(dry run) Job not submitted.Bu, bir URL arkasında yer alan betikler için de geçerlidir: betik, Job gönderildiğinde bir kez indirilir (başlığını okumak için) ve konteyner tarafından yeniden indirilmek yerine, yerel bir betik gibi Job'a aktarılır. URL'nin makinenizden erişilebilir olması gerekir. Yerel betikler gibi, URL betikleri de ayrılmış
/dataartefaktı bağlamasını kullanır; girdi birimlerinizi için başka bir bağlama yolu kullanın.
hf jobs scheduled uv run için bu, betiği oluşturulma anındaki içeriğine sabitler. Kaynak URL'sinin güncellenmesi artık gelecekteki çalıştırmaları değiştirmez: yeni bir sürümü almak için zamanlanmış Job'ı yeniden oluşturun.
--dry-run, hf jobs run, hf jobs scheduled run ve hf jobs scheduled uv run komutlarında da kullanılabilir. Bu seçenek, gönderimi ve yerel hacim yüklemelerini atlar. Hem Docker hem de UV İşleri için otomatik oluşturulan adlar, çözümlenmiş başlatma yapılandırmasını içerdiğinden çalışma zamanı ayarlarını veya ortam değerlerini değiştirmek adı değiştirir.
hf jobs scheduled
HF altyapısında çalışacak işleri planlayın ve yönetin.
Zamanlama, @annually, @yearly, @monthly, @weekly, @daily, @hourly veya bir CRON zamanlama ifadesi (ör. her Pazartesi saat 9:00 için "0 9 * * 1") olmalıdır.
# Schedule a job that runs every hour
>>> hf jobs scheduled run @hourly --name hourly-task python:3.12 python -c 'print("This runs every hour!")'
# Use the CRON syntax
>>> hf jobs scheduled run "*/5 * * * *" python:3.12 python -c 'print("This runs every 5 minutes!")'
# Schedule with GPU
>>> hf jobs scheduled run @hourly --flavor a10g-small pytorch/pytorch:2.6.0-cuda12.4-cudnn9-devel \
... python -c 'import torch; print(f"This code ran with the following GPU: {torch.cuda.get_device_name()}")'
# Schedule a UV script
>>> hf jobs scheduled uv run @hourly --name hourly-script my_script.pyOrtam değişkenleri, gizli bilgiler, zaman aşımı vb. iletmek için hf jobs run ile aynı parametreleri kullanın.
Planlanmış işleri yönetmek için
# List your active scheduled jobs
>>> hf jobs scheduled ls
# Same filters as `hf jobs ls`: --status, --label and --name
>>> hf jobs scheduled ls --all
>>> hf jobs scheduled ls --status suspended
>>> hf jobs scheduled ls --name hourly-task --label env=prod
# Inspect the status of a job
>>> hf jobs scheduled inspect <scheduled_job_id>
# Suspend (pause) a scheduled job
>>> hf jobs scheduled suspend <scheduled_job_id>
# Resume a scheduled job
>>> hf jobs scheduled resume <scheduled_job_id>
# Change future run times (Mondays at 9:00)
>>> hf jobs scheduled reschedule <scheduled_job_id> "0 9 * * 1"
# Trigger a scheduled job to run right now (does not change the schedule)
>>> hf jobs scheduled trigger <scheduled_job_id>
# Delete a scheduled job
>>> hf jobs scheduled delete <scheduled_job_id>hf sandbox
hf sandbox, Jobs üzerine kurulu izole bulut makineleri başlatır: bir tane oluşturun, canlı yayınlanan çıktıyla komutlar çalıştırın ve dosyaları içeri ve dışarı kopyalayın. /bin/sh içeren herhangi bir Docker görüntüsü çalışır. Python API için Sandboxes kılavuzuna, alt yapının nasıl çalıştığı için kavramsal kılavuza bakın.
Sandboxes deneyseldir ve API'leri ile davranışları haber verilmeksizin değişebilir. Paylaşılan sandboxes, aynı güven sınırındaki iş yükleri için tasarlanmıştır; birbirine güvenmeyen iş yükleri için ayrı bir sandbox kullanın.
# Create a sandbox (waits until it is ready, prints its id)
>>> hf sandbox create
✓ Sandbox ready id=687f911eaea852de79c4a50a image=python:3.12 elapsed=6.0s
# Attach labels to the underlying Job
>>> hf sandbox create --label controller-run=run-42 --label team=data-infra
# Run commands inside it (output is streamed, exit code is propagated)
>>> hf sandbox exec 687f911eaea852de79c4a50a -- python -c "print('hi')"
hi
# Copy files in and out (docker-style)
>>> hf sandbox cp data.csv 687f911eaea852de79c4a50a:/data/data.csv
>>> hf sandbox cp 687f911eaea852de79c4a50a:/app/results.json results.json
# Terminate a sandbox
>>> hf sandbox kill 687f911eaea852de79c4a50aDonanımı seçmek için --flavor (ör. a10g-small), sandbox ömrünü sınırlamak için --idle-timeout ve Job'una etiket eklemek için -l / --label kullanın. Birçok ucuz CPU sandbox'ını dağıtmak için hf sandbox pool create ile bir havuz hazırlayın ve hf sandbox create --pool <id> ile içine oluşturun (Sandboxes kılavuzu bkz.).
Ortam değişkenlerini ve gizli bilgileri bir kum havuzuna iletin
Farklı depolama özelliklerine sahip iki ayrı kanal bulunmaktadır:
| kanal | bayraklar | özel kum havuzu | havuzlanmış kum havuzu (--pool) |
|---|---|---|---|
| ortam | -e / --env, --env-file | iş metadata'ında saklanır | oluşturma sırasında hosta iletilir, iş meta verilerinde saklanmaz |
| secrets | -s / --secrets, --secrets-file | sunucu tarafında şifreli | mevcut değil — --env kullanın |
# Plain environment variables
>>> hf sandbox create -e LOG_LEVEL=debug --env-file .env
# Secrets, read from your environment by name (nothing sensitive on the command line)
>>> hf sandbox create -s OPENAI_API_KEY -s HF_TOKEN
# Secrets from a file, or piped in on stdin
>>> hf sandbox create --secrets-file .env.secrets
>>> printf 'OPENAI_API_KEY=sk-...\n' | hf sandbox create --secrets-file --s KEY=value de çalışır, ancak değer kabuk geçmişinize ve süreç listesine yazılır; bu nedenle CLI, sessiz mod dahil olmak üzere stderr üzerinden bu konuda uyarı verir. Havuzlanmış kum havuzları --secrets bayrağını kesinlikle reddeder: bir havuzda şifreli gizli veriler kanalı yoktur ve hf sandbox create --pool <id> -s KEY=value komutu, --env bayrağına bir yönlendirme içeren bir hata mesajı döndürür.
hf webhooks
hf webhooks, Hugging Face Hub üzerindeki webhook'ları doğrudan terminalden yönetmenizi sağlar. Webhook'lar, depolarda, kullanıcılarda veya organizasyonlarda olayları (push, tartışma vb.) dinlemenize ve eylemleri tetiklemenize olanak tanır; bu eylemler, uzak bir URL'ye ping göndererek veya Hugging Face altyapısında bir Job çalıştırarak gerçekleştirilebilir.
Webhook'ları listele
>>> hf webhooks ls
ID URL DISABLED DOMAINS WATCHED
wh-abc123 https://example.com/hook False repo model:bert-base-uncased
wh-def456 https://example.com/other-hook False repo org:HuggingFaceMakine tarafından okunabilir çıktı için --format json kullanın veya yalnızca kimlikleri yazdırmak için -q kullanın:
>>> hf webhooks ls --format json
>>> hf webhooks ls -qWebhook bilgilerini getir
>>> hf webhooks info wh-abc123Tüm webhook ayrıntılarını JSON olarak yazdırır.
Webhook oluşturun
Bir URL'ye yüklemeler gönderen bir webhook oluşturun:
>>> hf webhooks create --url https://example.com/hook --watch model:bert-base-uncased
>>> hf webhooks create --url https://example.com/hook --watch org:HuggingFace --watch model:gpt2 --domain repoVeya bunun yerine bir Job'u tetikleyen bir webhook oluşturun:
>>> hf webhooks create --job-id 687f911eaea852de79c4a50a --watch user:julien-cKaynak Job’un gizli bilgileri webhook’a kopyalanmaz. Tetiklenen Job’a bunları iletmek için --secrets veya --secrets-file (sözdizimi hf jobs run ile aynıdır) kullanın. Örneğin, --secrets HF_TOKEN yerel Hugging Face token’ınızı iletir:
>>> hf webhooks create --job-id 687f911eaea852de79c4a50a --watch bucket:my-org/my-bucket --secrets HF_TOKEN--watch seçeneği, type'in model, dataset, space, bucket, org veya user değerlerinden biri olduğu type:name biçimini kullanır. Birden fazla öğeyi izlemek için bu seçenek tekrarlanabilir. Olayları repo veya discussion olarak filtrelemek için --domain ve imzalama gizli anahtarını ayarlamak için --secret kullanın.
Webhook'ü güncelle
>>> hf webhooks update wh-abc123 --url https://new-url.com/hook
>>> hf webhooks update wh-abc123 --watch model:gpt2 --domain repoYalnızca sağlanan seçenekler değiştirilir. Belirtilen --watch, izlenen listenin tamamını değiştirir.
Bir İş (Job) tarafından tetiklenen bir webhook'un gizli bilgilerini (secrets) güncellemek için --job-id parametresini --secrets ile birlikte iletin. Listelenen gizli bilgiler, depolanan değerlerin yerini alır ve diğer tüm gizli bilgiler korunur:
>>> hf webhooks update wh-abc123 --job-id 687f911eaea852de79c4a50a --secrets HF_TOKENWebhook'u etkinleştir / devre dışı bırak
>>> hf webhooks enable wh-abc123
>>> hf webhooks disable wh-abc123Webhook sil
>>> hf webhooks delete wh-abc123
Are you sure you want to delete webhook 'wh-abc123'? [y/N]: y
Webhook deleted: wh-abc123Onay istemini atlamak için --yes kullanın:
>>> hf webhooks delete wh-abc123 --yesTüm komutlar, kimlik doğrulamayı geçersiz kılmak için
--tokenparametresini kabul eder. Tüm seçenekleri görmek için herhangi bir komutta--helpkullanın.
hf uç noktaları
hf endpoints komutunu kullanarak Inference Endpoints'i doğrudan terminalden listeleyebilir, dağıtabilir, açıklayabilir ve yönetebilirsiniz. Uyumluluk için eski hf inference-endpoints takma adı hâlâ kullanılabilir durumda.
# Lists endpoints in your namespace
>>> hf endpoints ls
# List the hardware you can deploy on
>>> hf endpoints hardware
# Deploy an endpoint from Model Catalog
>>> hf endpoints catalog deploy --repo openai/gpt-oss-120b --name my-endpoint
# Deploy an endpoint from the Hugging Face Hub
>>> hf endpoints deploy my-endpoint --repo gpt2 --framework pytorch --accelerator cpu --instance-size x2 --instance-type intel-icl
# List catalog entries
>>> hf endpoints catalog ls
# Show status and metadata
>>> hf endpoints describe my-endpoint
# Pause the endpoint
>>> hf endpoints pause my-endpoint
# Delete without confirmation prompt
>>> hf endpoints delete my-endpoint --yesBir organizasyonu hedeflemek için
--namespace, kimlik doğrulamayı geçersiz kılmak için--tokenekleyin.
Üzerine dağıtım yapmak için donanım bulun
hf endpoints deploy beş donanım bayrağı gerektirir (--vendor, --region, --accelerator, --instance-type ve --instance-size). hf endpoints hardware, geçerli kombinasyonları, ABD doları cinsinden saat başına kopya başına fiyatı ve ad alanınızın hızlandırıcı kota bilgilerini listeler:
>>> hf endpoints hardware --vendor aws --region eu-west-1
VENDOR REGION ACCELERATOR INSTANCE_TYPE INSTANCE_SIZE MEMORY_GB GPU_MEMORY_GB PRICE_PER_HOUR QUOTA STATUS
------ --------- ----------- ------------- ------------- --------- ------------- -------------- ----- ---------
aws eu-west-1 cpu intel-spr x1 2.0 0.033 0/60 available
aws eu-west-1 cpu intel-spr x2 4.0 0.067 0/60 available
aws eu-west-1 cpu intel-spr x4 8.0 0.134 0/60 available
aws eu-west-1 cpu intel-spr x8 16.0 0.268 0/60 available
aws eu-west-1 cpu intel-spr x16 32.0 0.536 0/60 available
aws eu-west-1 gpu nvidia-a10g x1 30.0 24 1.0 0/16 available
aws eu-west-1 gpu nvidia-t4 x1 15.0 16 0.5 1/30 available
Hint: Deploy on one of these, e.g.: hf endpoints deploy my-endpoint --repo <repo> --framework <framework> --vendor aws --region eu-west-1 --accelerator cpu --instance-type intel-spr --instance-size x1Filtre bayrakları, dağıtım bayraklarıdır (--vendor, --region, --accelerator, --instance-type); bu nedenle üzerinde filtreleme yaptığınız değerler, deploy komutuna ilettiğiniz değerlerdir. Listede yalnızca şu anda dağıtım yapabileceğiniz donanımlar yer alır: kullanılabilir bir durum ve ad alanınızda tek bir replika için yeterli hızlandırıcı kotası. Eski, geçici olarak kullanılamaz veya kota dışı olanları da görmek için --all ekleyin. --format json, her girdiye replika başına kalan özellikleri (vCPU, mimari, hızlandırıcı sayısı) ekler.
Kota, namespace başına tanımlanır ve hangi satırların listeleneceğini belirler. Bir organizasyona dağıtım yapıyorsanız,
deploykomutuna geçireceğiniz--namespacedeğerini aynı şekilde iletin — aksi halde kişisel kotanızı görürsünüz; bu da hem organizasyonun dağıtım yapabildiği donanımları gizleyebilir hem de dağıtım yapamadığı donanımları gösterebilir.
Özel bir konteyner dağıtın
Hugging Face tarafından yönetilen bir görüntü yerine kendi Docker görüntünüzü dağıtmak için --framework custom parametresini --custom-image ile birlikte iletin. Model deposu, konteyner içinde /repository konumuna bağlanır. Tırnak içinde bir başlatma dizesi iletmek için --container-args (ve isteğe bağlı olarak --container-command) kullanın, ortam değişkenlerini enjekte etmek için --env/--secrets ve erişim türünü (public, authenticated veya private) ayarlamak için --type kullanın:
>>> hf endpoints deploy nex-n2-pro \
--repo nex-agi/Nex-N2-Pro \
--framework custom \
--accelerator gpu --vendor aws --region us-east-1 \
--instance-type nvidia-h200 --instance-size x8 \
--custom-image nexagi/sglang:v0.5.12 \
--health-route /health --port 30000 \
--container-args "--reasoning-parser qwen3 --tool-call-parser qwen3_coder --mamba-scheduler-strategy extra_buffer --tp 8" \
--env MODEL_ID=/repository \
--type authenticated--container-args ve --container-command özel görüntülerle sınırlı değildir: API yüklemesinde model.args ve model.command alanlarına eşlenir ve bu alanlar yönetilen görüntüler için de geçerlidir. Mevcut bir uç noktada her iki bayrak da mevcut değeri eklemek yerine değiştirir; bu nedenle istediğiniz tam listeyi iletin ve temizlemek için boş bir dize kullanın. Katalogdan dağıtılan uç noktalar, ayarlanmış motor bayraklarıyla birlikte gelir; bunları üzerine yazmadan önce hf endpoints describe komutunu çalıştırıp kontrol edin:
>>> hf endpoints update my-endpoint \
--container-args "--enable-auto-tool-choice --tool-call-parser lfm2"Yönetilen bir motor görüntüsü dağıtın
--custom-image tek başına herhangi bir konteyneri dağıtır. API’nin yönettiği motorlardan biri olarak çalıştırmak için --engine ekleyin (vllm, sglang, tgi, tei, llamacpp, hf-serve, …); bu, --tensor-parallel-size ve --data-parallel-size dahil olmak üzere ilgili motorun ayarlarını etkinleştirir. vLLM ve SGLang varsayılan olarak tek bir hızlandırıcı kullanırken uç nokta, örneğindeki tüm hızlandırıcılara erişir; bu nedenle ikisini de ayarlanmamış bırakmak, modeli tek bir hızlandırıcıya yükleyip kalanları boşta bırakırken yine de sağlıklı raporlar. API bu yapılandırmayı artık reddeder:
>>> hf endpoints deploy gpt-oss-120b-vllm \
--repo openai/gpt-oss-120b \
--framework custom \
--accelerator gpu --vendor aws --region us-east-1 \
--instance-type nvidia-h200 --instance-size x8 \
--engine vllm --custom-image vllm/vllm-openai:v0.23.0 \
--tensor-parallel-size 8Yukarıdaki --container-args "... --tp 8" ile aynı şey değildir: --tensor-parallel-size, API’nin örneğin hızlandırıcı sayısıyla doğruladığı motorun model.image yapılandırmasına yazar; oysa --container-args yalnızca komut satırına bir bayrak ekler. Görsel alanında karşılığı olmayan motor bayrakları ve paralellik alanları bulunmayan düz özel konteynerler için --container-args kullanın.
Çalışan bir uç noktanın yeniden ayarlanabilmesi için boyutları tek başlarına iletin. model.image bütünüyle gönderilir ve url gerektirir; bu nedenle uç noktanın mevcut görüntüsü getirilir ve yerinde güncellenir:
>>> hf endpoints update gpt-oss-120b-vllm --tensor-parallel-size 4 --data-parallel-size 2hf endpoints update ayrıca --custom-image ve --engine parametrelerini de alır; bir endpoint'in görüntüsünü CLI üzerinden değiştirmenin tek yolu budur. Bu yol, model.image alanını yamalayıp (patch) değiştirmek yerine onu tamamen değiştirir; bu yüzden önce hf endpoints describe komutunu çalıştırın ve korumak istediğiniz değerleri geri aktarın.
hf uç noktaları kataloğu
Inference Endpoints Model Catalog ile etkileşime geçmek için hf endpoints catalog kullanın. Modelleri katalogdan doğrudan optimize edilmiş yapılandırmalarla dağıtın.
Her katalog modeli, bir veya daha fazla tarifle birlikte gelir: bunun için test edilmiş bir donanım ve motor kombinasyonu. hf endpoints catalog ls komutu her tarif için bir satır basar, bu nedenle hem GPU hem de Neuron tarifine sahip bir model iki kez görünür:
# List available catalog models
>>> hf endpoints catalog ls
REPO_ID TASK LICENSE ACCELERATOR ENGINE GGUF_FILE RECIPE_ID
----------------------------------- ------------------ ---------- ----------- -------- ----------------------------- -------------------------
meta-llama/Llama-3.1-8B-Instruct text-generation Llama 3.1 gpu vllm sizzling-biryani-g4xsi1ac
meta-llama/Llama-3.1-8B-Instruct text-generation Llama 3.1 neuron vllmNeuron artisanal-quinoa-yz9ynamx
bartowski/QwQ-32B-Preview-GGUF text-generation Apache 2.0 gpu llamacpp QwQ-32B-Preview-Q8_0.gguf baked-orange-m863gx7d
# Narrow it down
>>> hf endpoints catalog ls --engine vllm --task text-generation --search llama --limit 10--accelerator, --engine, --license, --task, --search ve --limit tümü sunucu tarafında filtreler.
# Deploy the default recipe of a model
>>> hf endpoints catalog deploy --repo meta-llama/Llama-3.2-1B-Instruct
# Deploy an exact recipe listed above
>>> hf endpoints catalog deploy --recipe artisanal-quinoa-yz9ynamx
# Deploy with a custom name
>>> hf endpoints catalog deploy --repo meta-llama/Llama-3.2-1B-Instruct --name my-llama-endpoint--repo ile varsayılan tarif, --accelerator (cpu, gpu, neuron) ve --gguf-file (her kuantizasyon için ayrı bir tarifi olan modeller için) ile daraltılabilir. Her iküsü de, zaten tek bir tarif belirten --recipe ile birlikte reddedilir.