S3 Uyumluğu

Storage Buckets, S3-uyumlu API üzerinden erişilebilir; bu sayede AWS CLI, boto3, s5cmd ve diğer çoğu S3 SDK'si gibi mevcut S3 araçlarını, kodunuzu değiştirmeden bucket'larınızda kullanabilirsiniz. İstekler, https://s3.hf.co adresindeki bir gateway hizmeti üzerinden iletilir.

S3 API, bucket verilerine erişmenin birkaç yolu arasındadır — ayrı S3 kimlik bilgileri olmadan Hugging Face yerel erişimi için (hf CLI, hf:// yolları ve dosya sistemi bağlamaları) Erişim Desenleri bölümüne bakın.

S3 API yalnızca Storage Buckets ile çalışır. Diğer Hugging Face depo türlerini (modeller, veri kümeleri, Spaces) dışa açmaz.

S3 Kimlik Bilgileri Oluşturma

Gateway, Hugging Face User Access Token'inden türetilen AWS tarzı erişim anahtarlarıyla kimlik doğrulaması yapar.

1. Erişim Belirteçleri ayarlarınıza gidin. Henüz bir belirteciniz yoksa Yeni belirteç oluştur düğmesiyle bir belirteç oluşturun. Belirtecin izinleri, S3 kimlik bilgileri izinleri haline gelir — varlıklarınıza salt okunur erişim için Okuma, okuma ve yazma erişimi için Yazma seçeneğini seçin.

2. Listedeki belirteci bulun, açılır menüsünü açın ve S3 kimlik bilgileri oluştur seçeneğini seçin.

   

3. Oluşturulan erişim anahtar kimliğini (HFAK… önekiyle) ve gizli erişim anahtarını güvenli bir yere kopyalayın — gizli anahtar yalnızca bir kez görüntülenir.

S3 kimlik bilgileri, altındaki erişim jetonunun izinlerini devralır. İnce taneli jetonlar için, bunları yalnızca kullanmayı planladığınız ad alanlarına ve varlıklara (bucket) daraltın.

Bir organizasyonun varlık depolarına (bucket) erişen otomatik iş akışları için, Kullanıcı Erişim Belgesi yerine bir hizmet hesabı belirteçten S3 kimlik bilgileri de oluşturabilirsiniz.

Bir İstemci Yapılandırma

S3 istemcinizi gateway son noktasına yönlendirin ve birkaç zorunlu seçeneği ayarlayın. Son nokta URL'sinde Hugging Face namespace'inizi (kullanıcı adınız veya bir kuruluş adı) kullanın — bkz. aşağıdaki Addressing buckets.

İki checksum ayarı güncel istemciler için önemlidir: AWS CLI ≥ 2.23 ve güncel boto3 sürümleri varsayılan olarak sonda CRC32 checksum'ları gönderir (aws-chunked çerçeveleme yoluyla) ve gateway bunları ayrıştırmez. Bu ayarlar, istemcinin checksum'ları yalnızca bir işlemin bunları kesin olarak gerektirdiği durumlarda göndermesini söyler.

Aşağıdakiler isteğe bağlıdır ancak büyük yüklemelerin olabildiğince az çok parçalı parça kullanmasını önerir:

Örnek: AWS CLI profili

~/.aws/config dosyasına bir profil ekleyin:

[profile hf]
region = us-east-1
endpoint_url = https://s3.hf.co/<namespace>
s3 =
    addressing_style = path
    multipart_threshold = 2GB
    multipart_chunksize = 2GB
request_checksum_calculation = when_required
response_checksum_validation = when_required

Not: Yukarıdaki <namespace> ifadesini, bucket'larınızın bulunduğu kullanıcı adı veya organizasyonla değiştirin.

Profil için eşleşen kimlik bilgilerini ~/.aws/credentials dosyasına ekleyin:

[hf]
aws_access_key_id = HFAK...
aws_secret_access_key = ...

Ardından profili kullanarak herhangi bir S3 komutunu kullanın:

aws --profile hf s3 ls
aws --profile hf s3 mb s3://my-bucket
aws --profile hf s3 cp ./model.safetensors s3://my-bucket/models/model.safetensors

Kovalara Adresleme

AWS S3, küresel olarak benzersiz, tek ve düz bir varlık adı alanı kullanır ve SDK'lar, varlık adının / içermeyen düz bir dize olmasını bekler. Hugging Face varlıkları ise namespace/bucket biçiminde tanımlanır; burada namespace, kullanıcı adınız veya organizasyonunuzdur. Bu ek seviye, S3 istemcileriyle bir uyumsuzluk yaratır — birçok istemci varlık adında / kabul etmez veya bunu URL kaçış işlemine yanlış şekilde tabi tutar. Bunu aşmanın iki yolu vardır:

1. Ad alanını uç nokta URL'sine ekleyin (çoğu durum için önerilir). Bu, tüm işlemleri o ad alanına daraltır; bu nedenle istemciye geçirilen varlık adı, yalnızca HF varlık adının kendisidir. Kendi varlıklarınızda veya tek bir kuruluşun varlıklarında iyi çalışır, ancak ad alanları arasında sorun çıkarır — örneğin, kişisel bir varlıktan kuruluş varlığına sunucu tarafında kopyalama.

aws --endpoint-url https://s3.hf.co/my-org s3api get-object \
  --bucket my-bucket --key some/object.txt ./object.txt

2. Namespace'ü bucket olarak ele alın ve nesne anahtarının başına HF bucket adını ekleyin. Bu, nesne düzeyindeki işlemler (yükleme, indirme) için işe yarar ancak bucket oluşturma veya silme gibi bucket düzeyindeki işlemlerde sorunlara yol açar.

aws --endpoint-url https://s3.hf.co s3api get-object \
  --bucket my-org --key my-bucket/some/object.txt ./object.txt

Kısıtlamalar ve AWS S3'ten Farklar

Storage Buckets, S3 kavramlarının tamamını modellemediği için bazı davranışlar farklılık gösterir veya desteklenmez.

Nesne indirmeleri

Gateway şu anda tek bölgeye (single-region) hizmet vermektedir. İndirme performansını artırmak için GetObject, baytları doğrudan sunmak yerine genellikle en yakın Hugging Face CDN kenarına (edge) HTTP 302 yönlendirmesiyle yanıt verir.

Bazı SDK’lar S3 uç noktasından gelen yönlendirmeleri izlemediğinden, gateway, kendini aws-cli, botocore (boto3’ü kapsar) veya aws-sdk-rust olarak tanıtan istemcileri algılar ve bu istemciler için veriyi kendi üzerinden yönlendirir. Diğer tüm istemciler (rclone, s5cmd, curl, AWS Go SDK vb.) 302 yanıtını alır ve bunu yerel olarak izleyerek, daha hızlı indirmeler için gateway’i veri yolunun dışında tutar.

Nesne anahtarı adlandırma

Bucket nesne anahtarları S3'ten daha kısıtlıdır. Bir anahtar şunları içeremez:

• / ile başlar veya biter
• ardışık eğik çizgiler (//) içerir
• ../ dizileri içerir
• ./ ile başlayın
• .. ile biter
• geri eğik çizgiler (\) veya null baytları (\0) içerir

ListObjects

• ListObjectsV1 desteklenmiyor — ListObjectsV2 kullanın. Bazı istemcilerin (rclone gibi) yalnızca ListObjectsV2 kullanacak şekilde yapılandırılması gerekebilir.
• Ayrıştırıcı olarak yalnızca / izin verilir.

Diğer API farkları

• Nesne meta verileri: keyfi kullanıcı meta verileri (x-amz-meta-*) saklanmaz veya döndürülmez. Content-Type desteklenir.
• Desteklenmeyen özellikler: ACL'ler, varlık (bucket) politikaları, nesne etiketleme, nesne sürümleme, yaşam döngüsü kuralları, sunucu tarafı şifreleme (SSE) ve varlık bildirimleri desteklenmez. Nesneler her zaman STANDARD depolama sınıfıyla raporlanır. İlgili istek başlıkları ve parametreleri kabul edilir ancak yok sayılır.
• CopyObject: sunucu tarafı kopyalama yalnızca tek bir ad alanı içinde çalışır. Ad alanları arası kopyalama ve UploadPartCopy (mevcut bir nesnenin parçasını çok parçalı bir yükleme işlemine kopyalama) desteklenmez.
• Koşullu istekler: If-Match / If-None-Match ön koşulları PutObject ve CopyObject'ün kopya kaynağında geçerlidir, ancak GetObject üzerinde geçerli değildir.
• Parçalı yükleme süresi dolma: Tamamlanmayan veya iptal edilmeyen, devam eden parçalı yüklemeler 7 gün sonra otomatik olarak süresi dolan ve temizlenen öğelerdir.

Örnekler

Ortak görevler için gerçek dünya tarifleri. Her biri yukarıdaki istemci yapılandırması üzerine inşa edilir.

boto3 ile okuma ve yazma

boto3, yukarıdaki istemci ayarları ile geçit üzerinde çalışır. <namespace> ifadesini kullanıcı adınız veya organizasyonunuzla değiştirin:

import boto3
from botocore.config import Config

s3 = boto3.client(
    "s3",
    endpoint_url="https://s3.hf.co/<namespace>",
    aws_access_key_id="HFAK...",
    aws_secret_access_key="...",
    config=Config(
        region_name="us-east-1",
        s3={"addressing_style": "path"},
        request_checksum_calculation="when_required",
        response_checksum_validation="when_required",
    ),
)

s3.upload_file("model.safetensors", "my-bucket", "models/model.safetensors")
s3.download_file("my-bucket", "models/model.safetensors", "model.safetensors")

DuckDB ile bir kovayı sorgula

DuckDB 2.0 veya sonraki sürümlerde httpfs eklentisi hf://buckets/ yollarını doğrudan okur ve hf eklentisiyle Buckets'a yazabilir. DuckDB ile Sorgu bölümüne bakın.

Daha eski DuckDB sürümleri için veya eklenti olmadan COPY ... TO ile sorgu sonuçlarını bir kovaya geri yazmak için bunun yerine S3 geçidini kullanın:

INSTALL httpfs;
LOAD httpfs;

CREATE SECRET hf (
    TYPE s3,
    KEY_ID 'HFAK...',
    SECRET '...',
    ENDPOINT 's3.hf.co/<namespace>',
    URL_STYLE 'path',
    REGION 'us-east-1'
);

SELECT * FROM read_parquet('s3://my-bucket/data.parquet');

URL_STYLE 'path' zorunludur. Bu parametre olmadan DuckDB, sanal barındırma tarzı adresleme kullanır (my-bucket.s3.hf.co); bu adresleme biçimini gateway sunmaz ve “Could not resolve hostname” hatası alırsınız.

rclone kullanarak veri içe aktarın

rclone, iki S3 uyumlu depolama arasında veri kopyalamak için pratik bir yöntemdir; bu nedenle mevcut bir AWS S3 kovasını (veya herhangi bir S3 uyumlu kaynağı) bir Storage Bucket’a taşımak için idealdir.

Fikir, iki uzak kaynağı — kaynak kovunuz ve Hugging Face geçidini — beyan edip rclone aracının nesneleri bunlar arasında akıtmaya bırakmaktır. Her iki uzak kaynağı da ~/.config/rclone/rclone.conf dosyasına ekleyin. İlk kaynak, mevcut S3 kovunuza işaret eder; bunu kaynağınıza (burada düz AWS S3) uydurun:

[aws]
type = s3
provider = AWS
access_key_id = AKIA...
secret_access_key = ...
region = us-east-1

İkinci, Hugging Face geçidine işaret eder. Diğer herhangi bir istemcide olduğu gibi, uç noktanızı namespace ile sınırlayın, path adreslemesini kullanın, ListObjectsV2'yi zorlayın (geçidin desteklediği tek listeleme sürümü) ve yüklemelerin olabildiğince az parça kullanmasını sağlamak için büyük çok parçalı boyutlar ayarlayın:

[hf]
type = s3
provider = Other
endpoint = https://s3.hf.co/<namespace>
access_key_id = HFAK...
secret_access_key = ...
region = us-east-1
force_path_style = true
list_version = 2
upload_cutoff = 2G
chunk_size = 2G

Not: Yukarıdaki <namespace> ifadesini, bucket'larınızın bulunduğu kullanıcı adı veya organizasyonla değiştirin ve erişim token'ınızdan oluşturulan S3 kimlik bilgilerini kullanın. Hedef bucket, bu ad alanı altında zaten var olmalıdır.

Şimdi bir kaynak kovayı Storage Bucket'ınıza kopyalayın:

rclone copy aws:my-source-bucket hf:my-bucket --progress

rclone copy yalnızca hedefte eksik veya değişmiş olan nesneleri aktarır; bu nedenle yarıda kalmış bir içe aktarmayı sürdürmek veya yeni nesneleri almak için komutu yeniden çalıştırmak güvenlidir. Hedefin kaynağın birebir aynası olmasını sağlamak — yani kaynağda artık var olmayan nesneleri hedeften silmek — için bunun yerine rclone sync kullanın:

rclone sync aws:my-source-bucket hf:my-bucket --progress

Büyük aktarımlar için eşzamanlılığı artırmak üzere --transfers ve --checkers ekleyin (ör. --transfers 16 --checkers 16) ve ardından her nesnenin aktarıldığını doğrulamak için rclone check aws:my-source-bucket hf:my-bucket komutunu çalıştırın.

DVC ile sürüm verisi

DVC, küçük işaretçi dosyaları depoda tutarak ve gerçek verileri uzak bir konuma göndererek veri setlerini ve modelleri git ile sürüm altında tutar. Bir bucket, gateway üzerinden bir DVC remote olarak çalışır; böylece kodunuz ve .dvc işaretçileri git’te kalırken veriler bucket’ınızda saklanır. S3 desteğiyle DVC’yi kurun (pip install 'dvc[s3]'), ardından yukarıdaki istemci ayarlarını kullanarak remote’u ekleyin:

dvc remote add -d hf-bucket s3://my-bucket/dvc-store
dvc remote modify hf-bucket endpointurl https://s3.hf.co/<namespace>
dvc remote modify hf-bucket region us-east-1

S3 kimlik bilgilerini ortam üzerinden veya git dışında kalmaları için dvc remote modify --local ile iletin:

export AWS_ACCESS_KEY_ID=HFAK...
export AWS_SECRET_ACCESS_KEY=...

Ardından normal şekilde izleyin, gönderin ve çekin — dvc push veriyi kovaya yükler, taze bir klonlamada dvc pull ise onu geri indirir:

dvc add data/
git add data.dvc .gitignore .dvc/config && git commit -m "Track data with DVC"
dvc push

endpointurl içinde namespace ve s3:// URL'sinde yalnızca varlık adı (bare bucket name) kullanın.