# huggingface_hub v1.0 sürümüne geçiş

v1.0 sürümü, `huggingface_hub` kütüphanesi için önemli bir kilometre taşıdır. API kararlılığına ve kütüphanenin olgunluğuna olan bağlılığımızı simgeler. Kütüphaneyi daha sağlam ve kullanımı daha kolay hale getirmek için çeşitli iyileştirmeler ve kırıcı değişiklikler yaptık.

Bu kılavuz, mevcut kodunuzu yeni sürüme taşımak için size yardımcı olmak üzere hazırlanmıştır. Herhangi bir sorunuz veya geri bildiriminiz varsa, lütfen [GitHub'da bir sorun açarak](https://github.com/huggingface/huggingface_hub/issues) bize bildirin.

## Python 3.9+

`huggingface_hub` artık Python 3.9 veya daha yüksek bir sürüm gerektirir. Python 3.8 artık desteklenmemektedir.

## HTTPX geçişi

`huggingface_hub` kütüphanesi artık HTTP istekleri için `requests` yerine [`httpx`](https://www.python-httpx.org/) kullanıyor. Bu değişiklik, performansı iyileştirmek ve senkron ile asenkron istekleri aynı şekilde desteklemek amacıyla yapıldı. Bu nedenle hem `requests` hem de `aiohttp` bağımlılıkları kaldırıldı.

### Kırıcı değişiklikler

Bu, kütüphanenin tamamını etkileyen önemli bir değişikliktir. Bu değişikliği mümkün olduğunca şeffaf hale getirmeye çalışsak da, bazı durumlarda kodunuzu güncellemeniz gerekebilir. Süreç boyunca getirilen kırıcı değişikliklerin listesi aşağıdadır:

- **Proxy yapılandırması**: "yöntem başına" proxy'ler artık desteklenmiyor. Proxy'ler, `HTTP_PROXY` ve `HTTPS_PROXY` ortam değişkenleri kullanılarak küresel olarak yapılandırılmalıdır.
- **Özel HTTP arka ucu**: `configure_http_backend` fonksiyonu kaldırıldı. Artık HTTP istemcilerini yapılandırmak için [set_client_factory()](/docs/huggingface_hub/main/tr/package_reference/utilities#huggingface_hub.set_client_factory) ve [set_async_client_factory()](/docs/huggingface_hub/main/tr/package_reference/utilities#huggingface_hub.set_async_client_factory) kullanmalısınız.
- **Hata yönetimi**: HTTP hataları artık `requests.HTTPError` sınıfından değil, `httpx.HTTPError` sınıfından türetilmektedir. `from huggingface_hub.utils import HfHubHTTPError` ile içe aktarılan [HfHubHTTPError](/docs/huggingface_hub/main/tr/package_reference/utilities#huggingface_hub.errors.HfHubHTTPError) sınıfını yakalamayı öneririz; bu sınıf v0.x sürümünde `requests.HTTPError` sınıfının, v1.x sürümünde ise `httpx.HTTPError` sınıfının bir alt sınıfıdır. `huggingface_hub` hatasını yakalamak, kodunuzun kütüphanenin hem eski hem de yeni sürümleriyle uyumlu olmasını sağlar.
- **SSLError**: `httpx`'in `SSLError` kavramı yoktur. Artık genel bir `httpx.ConnectError`'dır.
- **`LocalEntryNotFoundError`**: Bu hata artık `HTTPError`'dan devralmıyor. Artık `EntryNotFoundError` (yeni) tanımlıyoruz ve hem `LocalEntryNotFoundError` (dosya yerel önbellekte bulunamazsa) hem de `RemoteEntryNotFoundError` (dosya Hub'daki depoda bulunamazsa) bu sınıftan devralıyor. Sadece uzak hata `HTTPError`'dan devralıyor.
- **`InferenceClient`**: `InferenceClient` artık bir bağlam yöneticisi olarak kullanılabilir. Bu, bir dil modelinden token akışı sırasında bağlantının düzgün şekilde kapatılmasını sağlamak için özellikle faydalıdır.
- **`AsyncInferenceClient`**: `AsyncInferenceClient` yapıcısından `trust_env` parametresi kaldırıldı. Ortam değişkenleri varsayılan olarak `httpx` tarafından güvenilirdir. Ortama açıkça güvenmek istemiyorsanız, bunu [set_async_client_factory()](/docs/huggingface_hub/main/tr/package_reference/utilities#huggingface_hub.set_async_client_factory) ile yapılandırmanız gerekir.

Daha fazla ayrıntı için, `httpx`'i tanıtan [PR #3328](https://github.com/huggingface/huggingface_hub/pull/3328)'i kontrol edebilirsiniz.

### Neden `httpx`?

`requests`'ten `httpx`'e geçiş, kütüphanenin performansını, güvenilirliğini ve sürdürülebilirliğini artıran birkaç önemli iyileştirme getirir:

**İş Parçacığı Güvenliği ve Bağlantı Yeniden Kullanımı**: `httpx` tasarım gereği iş parçacığı güvenlidir (thread-safe), bu da aynı istemcinin birden fazla iş parçacığı arasında güvenle yeniden kullanılmasına olanak tanır. Bu bağlantı yeniden kullanımı, her HTTP isteği için yeni bağlantılar kurma maliyetini azaltarak özellikle Hub'a sık istekler yapıldığında performansı artırır.

**HTTP/2 Desteği**: `httpx`, aynı sunucuya birden fazla istek gönderirken (tam olarak bizim kullanım senaryomuz) daha iyi verimlilik sağlayan yerel HTTP/2 desteği sunar. Bu, HTTP/1.1'e kıyasla daha düşük gecikme süresi ve azaltılmış kaynak tüketimi anlamına gelir.

**Birleşik Senkron/Asenkron API**: `requests` (senkron) ve `aiohttp` (asenkron) bağımlılıklarının ayrı ayrı kullanıldığı önceki kurulumumuzun aksine, `httpx` hem senkron hem de asenkron istemcileri aynı davranışla sunar. Bu, `InferenceClient` ve `AsyncInferenceClient` sınıflarının tutarlı işlevselliğe sahip olmasını sağlar ve bu iki uygulama arasında daha önce var olan ince davranış farklılıklarını ortadan kaldırır.

**Yenilenmiş SSL Hata Yönetimi**: `httpx`, SSL hatalarını daha zarif bir şekilde ele alarak bağlantı sorunlarını ayıklamayı daha kolay ve güvenilir hale getirir.

**Geleceğe Yönelik Mimari**: `httpx` aktif olarak sürdürülmekte ve modern Python uygulamaları için tasarlanmıştır. Buna karşılık `requests` bakım modundadır ve thread-safety iyileştirmeleri veya HTTP/2 desteği gibi önemli güncellemeler almayacaktır.

**Daha İyi Ortam Değişkeni İşleme**: `httpx`, hem senkron hem de asenkron bağlamlarda ortam değişkenlerinin daha tutarlı işlenmesini sağlayarak, `requests`'in varsayılan olarak yerel ortam değişkenlerini okurken `aiohttp`'in bunu yapmadığı önceki tutarsızlıkları ortadan kaldırır.

`httpx`'e geçiş, `huggingface_hub`'ü modern, verimli ve sürdürülebilir bir HTTP altyapısıyla konumlandırır. Çoğu kullanıcı sorunsuz bir deneyim yaşasa da, temel iyileştirmeler tüm Hub etkileşimleri için daha iyi performans ve güvenilirlik sağlar.

## `hf_transfer`

Hub'daki tüm depolar artık Xet destekli olduğundan ve `hf_xet` dosya indirme/yükleme için varsayılan yöntem haline geldiğinden, `hf_transfer` isteğe bağlı paketine olan desteği kaldırdık. Bu nedenle `HF_HUB_ENABLE_HF_TRANSFER` ortam değişkeni yok sayılır. Bunun yerine [`HF_XET_HIGH_PERFORMANCE`](../package_reference/environment_variables) kullanın.

## `Repository` sınıfı

`Repository` sınıfı v1.0 sürümünde kaldırıldı. Bu sınıf, depoları yönetmek için `git` komut satırı arayüzünün ince bir sarmalayıcısıydı. `git` aracını terminalde doğrudan kullanmaya devam edebilirsiniz ancak özellikle büyük dosyalarla çalışırken daha akıcı bir deneyim için önerilen yaklaşım, `huggingface_hub` kütüphanesindeki HTTP tabanlı API'yi kullanmaktır.

İşte eski `Repository` sınıfından yeni `HfApi` sınıfına geçiş haritası:

| `Repository` yöntemi                        | `HfApi` metodu                                        |
| ------------------------------------------ | ----------------------------------------------------- |
| `repo.clone_from`                          | `snapshot_download`                                   |
| `repo.git_add` + `git_commit` + `git_push` | [upload_file()](/docs/huggingface_hub/main/tr/package_reference/hf_api#huggingface_hub.HfApi.upload_file), [upload_folder()](/docs/huggingface_hub/main/tr/package_reference/hf_api#huggingface_hub.HfApi.upload_folder), [create_commit()](/docs/huggingface_hub/main/tr/package_reference/hf_api#huggingface_hub.HfApi.create_commit) |
| `repo.git_tag`                             | `create_tag`                                          |
| `repo.git_branch`                          | `create_branch`                                       |

## `HfFolder` sınıfı

`HfFolder`, kullanıcı erişim jetonunu yönetmek için kullanılıyordu. Yeni bir jeton kaydetmek için [login()](/docs/huggingface_hub/main/tr/package_reference/authentication#huggingface_hub.login), silmek için [logout()](/docs/huggingface_hub/main/tr/package_reference/authentication#huggingface_hub.logout) ve mevcut jetonla ilişkili kullanıcıyı kontrol etmek için [whoami()](/docs/huggingface_hub/main/tr/package_reference/hf_api#huggingface_hub.HfApi.whoami) kullanın. Son olarak, bir betikte kullanıcının jetonunu almak için `get_token()` kullanın.

## `InferenceApi` sınıfı

`InferenceApi`, Inference API ile etkileşime girmek için kullanılan bir sınıftı. Bunun yerine artık [InferenceClient](/docs/huggingface_hub/main/tr/package_reference/inference_client#huggingface_hub.InferenceClient) sınıfını kullanmanız önerilir.

## Diğer kullanımdan kaldırılan özellikler

Bazı yöntemler ve parametreler v1.0 sürümünde kaldırılmıştır. Aşağıda listelenenler, v0.x sürümünde zaten bir uyarı mesajıyla kullanımdan kaldırılmıştı.

- `constants.hf_cache_home` kaldırıldı. Bunun yerine `HF_HOME` kullanın.
- `use_auth_token` parametreleri tüm yöntemlerden kaldırıldı. Bunun yerine `token` kullanın.
- `get_token_permission` yöntemi kaldırıldı.
- `update_repo_visibility` yöntemi kaldırıldı. Bunun yerine `update_repo_settings` kullanın.
- `is_write_action` parametresi, `build_hf_headers` içinden ve `write_permission` de `login` içinden kaldırılmıştır. "Yazma izni" kavramı kaldırılmış olup, ince tanecikli tokenler önerilen yaklaşım haline geldiği için artık geçerli değildir.
- `login` içindeki `new_session` parametresi, daha iyi açıklık için `skip_if_logged_in` olarak yeniden adlandırıldı.
- `resume_download`, `force_filename` ve `local_dir_use_symlinks` parametreleri `hf_hub_download` ve `snapshot_download` işlevlerinden kaldırıldı.
- `library`, `language`, `tags` ve `task` parametreleri `list_models` içinden kaldırıldı.

## CLI önbellek komutları

CLI üzerinden önbellek yönetimi, Docker ilhamlı bir iş akışını takip edecek şekilde yeniden tasarlandı. Kullanımı durdurulan `huggingface-cli` kaldırıldı; bunun yerine v0.34'te tanıtılan `hf`, daha net bir kaynak-aksiyon CLI'ı olarak kullanılıyor. Eski `hf cache scan` ve `hf cache delete` komutları da v1.0'da kaldırıldı ve aşağıdaki yeni üçlü ile değiştirildi:

- `hf cache ls`, önbellek girdilerini kısa bir tablo, JSON veya CSV çıktısıyla listeler. Bireysel revizyonları incelemek için `--revisions` kullanın, `size>1GB` veya `accessed>30d` gibi `--filter` ifadeleri ekleyin ve yalnızca tanımlayıcılara ihtiyacınız olduğunda bunları `--quiet` ile birleştirin.
- `hf cache rm`, seçilen önbellek girdilerini siler. Bir veya daha fazla depo kimliği (örneğin `model/bert-base-uncased`) veya revizyon özetlerini iletin ve isteğe bağlı olarak önizleme için `--dry-run` veya onay istemini atlamak için `--yes` ekleyin. Bu, önceki komuttaki etkileşimli TUI ve `--disable-tui` iş akışlarının ikisini de değiştirir.
- `hf cache prune`, referanssız revizyonları tek seferde silme işlemini gerçekleştirir. `hf cache rm` komutunda olduğu gibi `--dry-run` veya `--yes` seçeneklerini ekleyebilirsiniz.

Son olarak, `[cli]` ek paketi kaldırıldı - CLI artık çekirdek `huggingface_hub` paketiyle birlikte dağıtılıyor.

## TensorFlow ve Keras 2.x desteği

v1.0 sürümünde tüm TensorFlow ile ilgili kod ve bağımlılıklar kaldırılmıştır. Bu, aşağıdaki kırıcı değişiklikleri içerir:

- `huggingface_hub[tensorflow]` artık desteklenen bir ek bağımlılık değildir
- `split_tf_state_dict_into_shards` ve `get_tf_storage_size` yardımcı işlevleri kaldırıldı.
- `tensorflow`, `fastai` ve `fastcore` sürümleri artık yerleşik başlıklarda yer almamaktadır.

Keras 2.x entegrasyonu de kaldırıldı. Bu, `KerasModelHubMixin` sınıfını ve `save_pretrained_keras`, `from_pretrained_keras` ile `push_to_hub_keras` yardımcı programlarını içerir. Keras 2.x, eski ve bakımı yapılmayan bir kütüphanedir. Önerilen yaklaşım, Hub ile sıkı bir şekilde entegre olan Keras 3.x’ü kullanmaktır (yani Hub’a yükleme/itme için yerleşik yöntemler içerir). Yine de Keras 2.x ile çalışmak istiyorsanız, `huggingface_hub` paketini v0.x sürümüne geri almanız gerekir.

## `upload_file` ve `upload_folder` dönüş değerleri

[upload_file()](/docs/huggingface_hub/main/tr/package_reference/hf_api#huggingface_hub.HfApi.upload_file) ve [upload_folder()](/docs/huggingface_hub/main/tr/package_reference/hf_api#huggingface_hub.HfApi.upload_folder) işlevleri artık Hub'da oluşturulan commit'in URL'sini döndürür. Önceki sürümlerde dosya veya klasörün URL'sini döndürüyorlardı. Bu değişiklik, [create_commit()](/docs/huggingface_hub/main/tr/package_reference/hf_api#huggingface_hub.HfApi.create_commit), [delete_file()](/docs/huggingface_hub/main/tr/package_reference/hf_api#huggingface_hub.HfApi.delete_file) ve [delete_folder()](/docs/huggingface_hub/main/tr/package_reference/hf_api#huggingface_hub.HfApi.delete_folder) işlevlerinin dönüş değerleriyle uyumlu hale gelmek için yapılmıştır.