HF URI'leri

HF URI, Hugging Face Hub üzerindeki bir konumu tanımlayan URI benzeri bir dizgedir. Kütüphane ve CLI boyunca, hf://... dizgeleri şunlara işaret etmek için kullanılır:

• bir model, veri seti, space veya kernel deposu (isteğe bağlı olarak bir revizyona sabitlenmiş);
• böyle bir depodaki bir dosya veya alt klasör;
• a bucket veya bir bucket içindeki alt klasör.

Bir HF mount, bir HF URI'sini yerel bir bağlama yolu ve isteğe bağlı :ro / :rw bayrağı ile sarar; Spaces ve Jobs hacimleri tarafından kullanılır.

Bu sayfa, HF URI'lerinin ve HF bağlamalarının kanonik sözdizimini belgelemektedir. Kütüphanenin her yerinde aynı ayrıştırıcı kullanıldığından, bir bağlamda geçerli olan bir URI (ör. HfFileSystem), başka bir bağlamda da aynı şekilde ayrıştırılır.

parse_hf_uri() ayrıca Hugging Face web URL'lerini de kabul eder (ör. https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv) böylece web sitesinden bir bağlantıyı kopyalayıp yapıştırabilirsiniz. Aşağıdaki Web URL'leri bölümüne bakın.

HF URI sözdizimi

hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]

HF yerleştirme sözdizimi

hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]:<MOUNT_PATH>[:ro|:rw]

Bir mount, :<MOUNT_PATH> ile takip edilen bir HF URI'si ve isteğe bağlı bir :ro / :rw bayrağıdır.

HF URI nedir

Aşağıdakiler tüm geçerli HF URI'leridir:

# Models (type prefix is optional, but the id is always 'namespace/name')
hf://my-org/my-model                            # implicit type prefix
hf://models/my-org/my-model                     # explicit type prefix
hf://models/my-org/my-model/config.json         # file inside a model repo
hf://models/my-org/my-model@v1.0/config.json    # pinned to a revision

# Datasets, Spaces, Kernels (type prefix is required)
hf://datasets/my-org/my-dataset
hf://datasets/my-org/my-dataset@dev/train.csv
hf://spaces/my-user/my-space
hf://kernels/my-org/my-kernel

# Special revisions (preserved as-is)
hf://datasets/my-org/my-dataset@refs/pr/10/data.csv
hf://datasets/my-org/my-dataset@refs/convert/parquet/data.parquet

# Buckets (always 'namespace/name', no revision)
hf://buckets/my-org/my-bucket
hf://buckets/my-org/my-bucket/sub/folder

Aşağıdakiler geçerli HF bağlamaları (hacim tanımları)dır:

hf://my-org/my-model:/data
hf://datasets/my-org/my-dataset:/mnt:ro
hf://datasets/my-org/my-dataset/train:/mnt:rw    # mount a sub-folder
hf://buckets/my-org/my-bucket:/storage:rw

HF URI olmayan şeyler

Ayrıştırıcı bilinçli olarak katıdır. Aşağıdakiler reddedilir:

Web URL'leri

Kolaylık olması için parse_hf_uri(), tarayıcınızdan kopyalayıp yapıştırdığınız Hugging Face web URL'lerini de kabul eder. Bunlar, CLI veya kütüphaneye doğrudan yapıştırıldığında “olduğu gibi çalışması” için standart hf:// biçimine dönüştürülür:

>>> from huggingface_hub import parse_hf_uri
>>> parse_hf_uri("https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv")
HfUri(type='dataset', id='my-org/my-dataset', revision='main', path_in_repo='train.csv')

huggingface.co adreslerinden (ve hf.co kısaltılmış alan adından, staging sunucusundan ve özel bir HF_ENDPOINT sunucusundan) gelen URL'ler, https:// şeması olsun ya da olmasın tanınır. Sorgu dizgeleri (?download=true) ve parçalar (#L10) yok sayılır.

Başka bir Hub dağıtımından (ör. kendi barındırdığınız veya proxy'li bir Hub) bir URL ayrıştırmak için, temel URL'sini endpoint olarak iletin. Bu durumda, varsayılanların yanı sıra bu host da tanınır ve ayrıştırma öncesinde bir yol öneki (ör. http://localhost:8080/hf) kaldırılır:

>>> parse_hf_uri("https://hub.my-company.com/datasets/my-org/my-dataset", endpoint="https://hub.my-company.com")
HfUri(type='dataset', id='my-org/my-dataset', revision=None, path_in_repo='')

Desteklenen URL biçimleri

Aşağıdaki tablo desteklenen rotaları listeler. Kısa tutmak için yalnızca URL yolu gösterilmektedir (hosttan sonraki kısım, örn. huggingface.co); tanınan host ima edilir.

Revizyon, blob/resolve/raw/tree/blame hemen ardından gelen tek segmentten alınır. / içermelerine rağmen özel referanslar (refs/pr/N, refs/convert/...) özenle eşleştirilir; / içeren diğer tüm dal/etiket adları URL kodlamalı olmalıdır (feature%2Ffoo).

Ayrıştırılmayan URL'ler

Bir URL belirsizse veya Hub'da somut bir konuma işaret etmiyorsa reddedilir (asla tahmin edilmez):

Aşağıdaki yollar, son satırda konak kendisinin reddetme nedeni olması dışında, yine konak olmadan gösterilmektedir.

Bir web URL'sini görüntüleme

HfUri.to_url(), bir URL'nin ayrıştırılmasının tersidir: bir HF URI için taranabilir web URL'sini oluşturur.

>>> uri = parse_hf_uri("hf://datasets/my-org/my-dataset@v1/train.csv")
>>> uri.to_url()
'https://huggingface.co/datasets/my-org/my-dataset/blob/v1/train.csv'

Yol veya revizyon ayarlanmadığında depo / bucket açılış sayfasına, yalnızca revizyon ayarlandığında klasör görüntüleyicisine (/tree/<rev>), depo dosyaları için dosya görüntüleyicisine (/blob/<rev>/<path>, revizyon varsayılan olarak main) ve bucket dosyaları için ağaç rotasına (/tree/<path>) işaret eder. Yoldaki özel karakterler (boşluklar, #, …) yüzde kodlanır. Özel bir hedefe gitmek için endpoint=... parametresini iletin.

Python'da ayrıştırma

URI'leri ayrıştırma

parse_hf_uri() merkezi URI ayrıştırıcısıdır. Saf bir dize ayrıştırıcısıdır (ağ çağrısı içermez) ve dondurulmuş bir HfUri veri sınıfı döndürür.

>>> from huggingface_hub import parse_hf_uri
>>> parse_hf_uri("hf://datasets/my-org/my-dataset@refs/pr/3/train.json")
HfUri(type='dataset', id='my-org/my-dataset', revision='refs/pr/3', path_in_repo='train.json')

HfUri, HfUri.to_uri() ile gidiş-dönüş yapılabilir; bu yöntem her zaman kanonik biçimi (açık bir tür önekiyle) üretir:

>>> uri = parse_hf_uri("hf://my-org/my-model@v1/config.json")
>>> uri.to_uri()
'hf://models/my-org/my-model@v1/config.json'

type ve id alanlarını doğrudan kullanın. is_repo ve is_bucket boole özellikleri, gerektiğinde depo URI'leri ile varlık kovası URI'leri arasında ayrım yapar.

Montların ayrıştırılması

parse_hf_mount, bir montaj spesifikasyonunu (yerel bir montaj yolu ve isteğe bağlı :ro/:rw bayrağı içeren bir HF URI) ayrıştırır ve dondurulmuş bir HfMount dataclass döndürür. Arka planda parse_hf_uri() kullanır.

>>> from huggingface_hub.utils import parse_hf_mount
>>> parse_hf_mount("hf://buckets/my-org/my-bucket/sub/dir:/mnt:ro")
HfMount(source=HfUri(type='bucket', id='my-org/my-bucket', revision=None, path_in_repo='sub/dir'), mount_path='/mnt', read_only=True)

HfMount, HfMount.to_uri üzerinden çift yönlü dönüştürülebilir:

>>> mount = parse_hf_mount("hf://my-org/my-model:/data:ro")
>>> mount.to_uri()
'hf://models/my-org/my-model:/data:ro'

Referans

>>> from huggingface_hub import parse_hf_uri
>>> parse_hf_uri("hf://datasets/my-org/my-dataset@v1/train.csv").to_url()
'https://huggingface.co/datasets/my-org/my-dataset/blob/v1/train.csv'

hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]

>>> from huggingface_hub.utils import parse_hf_uri
>>> parse_hf_uri("hf://my-org/my-model")
HfUri(type='model', id='my-org/my-model', revision=None, path_in_repo='')
>>> parse_hf_uri("hf://datasets/my-org/my-dataset@refs/pr/3/train.json")
HfUri(type='dataset', id='my-org/my-dataset', revision='refs/pr/3', path_in_repo='train.json')
>>> parse_hf_uri("https://huggingface.co/datasets/my-org/my-dataset/blob/main/train.csv")
HfUri(type='dataset', id='my-org/my-dataset', revision='main', path_in_repo='train.csv')

hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]:<MOUNT_PATH>[:ro|:rw]

hf://[<TYPE>/]<ID>[@<REVISION>][/<PATH>]:<MOUNT_PATH>[:ro|:rw]

>>> from huggingface_hub.utils import parse_hf_mount
>>> parse_hf_mount("hf://my-org/my-model:/data:ro")
HfMount(source=HfUri(type='model', id='my-org/my-model', revision=None, path_in_repo=''), mount_path='/data', read_only=True)
>>> parse_hf_mount("hf://buckets/my-org/my-bucket/sub/dir:/mnt:rw")
HfMount(source=HfUri(type='bucket', id='my-org/my-bucket', revision=None, path_in_repo='sub/dir'), mount_path='/mnt', read_only=False)