# 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](./storage-buckets-access) bölümüne bakın. > [!NOTE] > S3 API yalnızca [Storage Buckets](./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](./security-tokens)'inden türetilen AWS tarzı erişim anahtarlarıyla kimlik doğrulaması yapar. 1. [Erişim Belirteçleri ayarlarınıza](https://huggingface.co/settings/tokens) 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. > [!TIP] > Bir organizasyonun varlık depolarına (bucket) erişen otomatik iş akışları için, Kullanıcı Erişim Belgesi yerine bir [hizmet hesabı](./enterprise-service-accounts#generating-s3-credentials) 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](#addressing-buckets). | Ayar | Değer | Neden | |--------------------------------|--------------------------------|---------------------------------------------------------------| | `endpoint_url` | `https://s3.hf.co/` | Ad alanınıza (namespace) özel olarak tanımlanmış geçit | | `region` | `us-east-1` | Zorunlu; geçit şu anda tek bölge | | `s3.addressing_style` | `path` | Buckets, alt alan adları olarak değil, yol bölümleri olarak adreslenir | | `request_checksum_calculation` | `when_required` | Son istemcilerin sonda kontrol toplamı göndermesini engeller | | `response_checksum_validation` | `when_required` | Yakındaki istemcilerin yanıtlarda özet denetim değerleri (checksum) beklemesini engeller | İ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ı olmakla birlikte önerilmektedir. İstemcinin 8 MB varsayılan değeriyle büyük bir dosya birçok parçaya bölünür; 256 MB, her yükleme başına çok daha az parça anlamına gelirken her parça, geçit tarafından verimli bir şekilde işlenebilecek kadar küçük kalır: | Ayar | Değer | |--------------------------|---------| | `s3.multipart_threshold` | `256MB` | | `s3.multipart_chunksize` | `256MB` | ### Örnek: AWS CLI profili `~/.aws/config` dosyasına bir profil ekleyin: ```ini [profile hf] region = us-east-1 endpoint_url = https://s3.hf.co/ s3 = addressing_style = path multipart_threshold = 256MB multipart_chunksize = 256MB request_checksum_calculation = when_required response_checksum_validation = when_required ``` Not: Yukarıdaki `` 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: ```ini [hf] aws_access_key_id = HFAK... aws_secret_access_key = ... ``` Ardından profili kullanarak herhangi bir S3 komutunu kullanın: ```bash 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. ```bash 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. ```bash 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` dahil) 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ı](#configuring-a-client) üzerine inşa edilir. ### `boto3` ile okuma ve yazma [`boto3`](https://docs.aws.amazon.com/boto3/latest/), yukarıdaki [istemci ayarları](#configuring-a-client) ile geçit üzerinde çalışır. `` ifadesini kullanıcı adınız veya organizasyonunuzla değiştirin: ```python import boto3 from botocore.config import Config s3 = boto3.client( "s3", endpoint_url="https://s3.hf.co/", 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](./storage-buckets-access#query-with-duckdb) 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: ```sql INSTALL httpfs; LOAD httpfs; CREATE SECRET hf ( TYPE s3, KEY_ID 'HFAK...', SECRET '...', ENDPOINT 's3.hf.co/', URL_STYLE 'path', REGION 'us-east-1' ); SELECT * FROM read_parquet('s3://my-bucket/data.parquet'); ``` > [!NOTE] > `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. ### Verileri `rclone` kullanarak içe aktarın [`rclone`](https://rclone.org/), 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. > [!TIP] > Büyük bir veri seti mi taşıyorsunuz? Kaynağı bağlayıp `hf sync` komutunu çalıştırdığınızda, yinelenen veriler istemcide ayıklanır; bu nedenle genellikle rclone'a göre daha az bayt yüklenir. [Geçiş Kılavuzu](./storage-buckets-migration)'na bakın. 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: ```ini [aws] type = s3 provider = AWS access_key_id = AKIA... secret_access_key = ... region = us-east-1 ``` İkincisi Hugging Face geçidine işaret eder. Diğer herhangi bir istemcide olduğu gibi, uç noktanızı [namespace](#addressing-buckets) ile sınırlayın, `path` adreslemesini kullanın, ListObjectsV2'yi zorlayın (geçidin desteklediği tek listeleme sürümü) ve 256M parça boyutu ayarlayın. Bu, rclone'ın 5M varsayılanından çok daha büyüktür; bu sayede büyük dosyalar daha az parça halinde yüklenir ve geçidin verimli işlemesi ile rclone'ın bellek kullanımının kontrol altında tutulması için yeterince küçüktür (her aktarmada bellekte 4 parça tutar): ```ini [hf] type = s3 provider = Other endpoint = https://s3.hf.co/ access_key_id = HFAK... secret_access_key = ... region = us-east-1 force_path_style = true list_version = 2 upload_cutoff = 256M chunk_size = 256M ``` Not: Yukarıdaki `` 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](#generating-s3-credentials) kullanın. Hedef bucket, bu ad alanı altında zaten var olmalıdır. Şimdi bir kaynak kovayı Storage Bucket'ınıza kopyalayın: ```bash 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: ```bash rclone sync aws:my-source-bucket hf:my-bucket --progress ``` > [!TIP] > 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](https://dvc.org/), 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ı](#configuring-a-client) kullanarak remote’u ekleyin: ```bash dvc remote add -d hf-bucket s3://my-bucket/dvc-store dvc remote modify hf-bucket endpointurl https://s3.hf.co/ dvc remote modify hf-bucket region us-east-1 ``` [S3 kimlik bilgilerini](#generating-s3-credentials) ortam üzerinden veya git dışında kalmaları için `dvc remote modify --local` ile iletin: ```bash 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: ```bash dvc add data/ git add data.dvc .gitignore .dvc/config && git commit -m "Track data with DVC" dvc push ``` > [!NOTE] > `endpointurl` içinde [namespace](#addressing-buckets) ve `s3://` URL'sinde yalnızca varlık adı (bare bucket name) kullanın.