# Instalasi

Transformers bekerja dengan [PyTorch](https://pytorch.org/get-started/locally/). Telah diuji pada Python 3.11+ dan PyTorch 2.6+.

## Lingkungan virtual

[uv](https://docs.astral.sh/uv/) adalah manajer paket dan proyek Python berbasis Rust yang sangat cepat, dan secara default memerlukan [virtual environment](https://docs.astral.sh/uv/pip/environments/) untuk mengelola berbagai proyek serta menghindari masalah kompatibilitas antar dependensi.

Itu dapat digunakan sebagai pengganti langsung untuk [pip](https://pip.pypa.io/en/stable/), tetapi jika Anda lebih memilih menggunakan pip, hapus `uv` dari perintah di bawah ini.

> [!TIP]
> Lihat dokumentasi [instalasi](https://docs.astral.sh/uv/guides/install-python/) uv untuk menginstal uv.

Buat lingkungan virtual untuk menginstal Transformers.

```bash
uv venv .env
source .env/bin/activate
```

## Python

Install Transformers dengan perintah berikut.

[uv](https://docs.astral.sh/uv/) adalah manajer paket dan proyek Python berbasis Rust yang cepat.

Untuk menginstal Transformers dengan PyTorch untuk GPU NVIDIA (CUDA), instal driver CUDA yang sesuai untuk [PyTorch](https://pytorch.org/get-started/locally).

Jalankan perintah di bawah untuk memeriksa apakah sistem Anda mendeteksi GPU NVIDIA.

```bash
nvidia-smi
```

```bash
uv pip install "transformers[torch]"
```

Untuk menginstal Transformers dengan PyTorch pada perangkat NVIDIA Spark (seperti laptop RTX Spark) yang berjalan di ARM64, instal PyTorch dari indeks PyPI NVIDIA. Perangkat ini memerlukan build ARM64 PyTorch dari NVIDIA, yang tidak tersedia di indeks PyPI default maupun indeks wheel PyTorch standar.

Jalankan perintah di bawah untuk memeriksa apakah sistem Anda mendeteksi GPU NVIDIA.

```bash
nvidia-smi
```

Install PyTorch dari indeks PyPI NVIDIA, lalu install Transformers.

```bash
uv pip install torch --index-url https://pypi.nvidia.com
uv pip install transformers
```

Untuk menginstal versi CPU-only dari Transformers, jalankan perintah berikut.

```bash
uv pip install torch --index-url https://download.pytorch.org/whl/cpu
uv pip install transformers
```

Untuk menginstal Transformers dengan PyTorch untuk Intel GPU (XPU), instal [driver Intel GPU (XPU) yang sesuai untuk PyTorch](https://www.intel.com/content/www/us/en/developer/articles/tool/pytorch-prerequisites-for-intel-gpu/2-13.html) dan tambahkan URL indeks PyTorch Intel GPU (XPU).

Setelah menginstal driver, jalankan perintah di bawah ini untuk [memeriksa apakah sistem Anda mendeteksi GPU Intel](https://dgpu-docs.intel.com/driver/verification.html).

```bash
xpu-smi
```

```bash
uv pip install "transformers[torch]" --extra-index-url https://download.pytorch.org/whl/xpu
```

Uji apakah instalasi berhasil dengan perintah berikut. Perintah ini seharusnya mengembalikan label dan skor untuk teks yang diberikan.

```bash
python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('hugging face is the best'))"
[{'label': 'POSITIVE', 'score': 0.9998704791069031}]
```

### Instalasi dari sumber

Menginstal dari sumber akan menginstal versi *terbaru* alih-alih versi *stabil* dari pustaka. Hal ini memastikan Anda memiliki perubahan terbaru di Transformers dan berguna untuk bereksperimen dengan fitur terbaru atau memperbaiki bug yang belum dirilis secara resmi dalam versi stabil.

Kekurangannya adalah bahwa versi terbaru tidak selalu stabil. Jika Anda mengalami masalah, silakan buka [GitHub Issue](https://github.com/huggingface/transformers/issues) agar kami dapat memperbaikinya secepat mungkin.

Instal dari sumber dengan perintah berikut.

```bash
uv pip install git+https://github.com/huggingface/transformers
```

Periksa apakah instalasi berhasil dengan perintah di bawah. Perintah ini seharusnya mengembalikan label dan skor untuk teks yang diberikan.

```bash
python -c "from transformers import pipeline; print(pipeline('sentiment-analysis')('hugging face is the best'))"
[{'label': 'POSITIVE', 'score': 0.9998704791069031}]
```

### Instalasi yang dapat diedit

[Instalasi yang dapat diedit](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs) berguna jika Anda mengembangkan secara lokal dengan Transformers. Ini menautkan salinan lokal Transformers Anda ke [repository](https://github.com/huggingface/transformers) Transformers, bukan menyalin file-filenya. File-file tersebut ditambahkan ke jalur impor Python.

```bash
git clone https://github.com/huggingface/transformers.git
cd transformers
uv pip install -e .
```

> [!WARNING]
> Anda harus menyimpan folder Transformers lokal untuk terus menggunakannya.

Perbarui versi lokal Transformers Anda dengan perubahan terbaru di repositori utama menggunakan perintah berikut.

```bash
cd ~/transformers/
git pull
```

## conda

[conda](https://docs.conda.io/projects/conda/en/stable/#) adalah manajer paket yang tidak bergantung pada bahasa. Instal Transformers dari channel [conda-forge](https://anaconda.org/conda-forge/transformers) di lingkungan virtual yang baru Anda buat.

```bash
conda install conda-forge::transformers
```

## Persiapan

Setelah instalasi, Anda dapat mengatur lokasi cache Transformers atau menyiapkan pustaka untuk penggunaan offline.

### Direktori cache

Saat Anda memuat model pretrained dengan [from_pretrained()](/docs/transformers/main/id/main_classes/model#transformers.PreTrainedModel.from_pretrained), model diunduh dari Hub dan di-cache secara lokal.

Jika Anda meneruskan commit hash, Transformers menggunakan cache lokal untuk file pada commit tersebut dan tidak memeriksa ulang Hub untuk setiap file (termasuk file yang diketahui tidak ada). Ini adalah perilaku default ketika tidak ada revisi yang ditentukan.

Jika Anda meneruskan branch atau tag, Transformers akan menghubungi Hub sekali di awal proses load untuk memilih commit, lalu menggunakan cache dengan cara yang sama untuk file pada commit tersebut.

Direktori default yang diberikan oleh variabel lingkungan shell `HF_HUB_CACHE` adalah `~/.cache/huggingface/hub`. Di Windows, direktori default adalah `C:\Users\username\.cache\huggingface\hub`.

Cache model di direktori yang berbeda dengan mengubah path pada variabel lingkungan shell berikut (diurutkan berdasarkan prioritas).

1. [HF_HUB_CACHE](https://hf.co/docs/huggingface_hub/package_reference/environment_variables#hfhubcache) (default)
2. [HF_HOME](https://hf.co/docs/huggingface_hub/package_reference/environment_variables#hfhome)
3. [XDG_CACHE_HOME](https://hf.co/docs/huggingface_hub/package_reference/environment_variables#xdgcachehome) + `/huggingface` (hanya jika `HF_HOME` tidak disetel)

### Mode offline

Untuk menggunakan Transformers di lingkungan offline atau yang terisolasi oleh firewall, file yang diunduh dan di-cache harus disiapkan terlebih dahulu. Unduh repositori model dari Hub dengan metode [snapshot_download](https://huggingface.co/docs/huggingface_hub/main/en/package_reference/file_download#huggingface_hub.snapshot_download).

> [!TIP]
> Lihat panduan [Unduh file dari Hub](https://hf.co/docs/huggingface_hub/guides/download) untuk lebih banyak opsi mengunduh file dari Hub. Anda dapat mengunduh file dari revisi tertentu, mengunduh dari CLI, dan bahkan memfilter file mana yang akan diunduh dari sebuah repositori.

```py
from huggingface_hub import snapshot_download

snapshot_download(repo_id="meta-llama/Llama-2-7b-hf", repo_type="model")
```

Setel variabel lingkungan `HF_HUB_OFFLINE=1` untuk mencegah panggilan HTTP ke Hub saat memuat model.

Opsi lain untuk hanya memuat file yang sudah di-cache adalah dengan mengatur `local_files_only=True` di [from_pretrained()](/docs/transformers/main/id/main_classes/model#transformers.PreTrainedModel.from_pretrained).

```py
from transformers import LlamaForCausalLM

model = LlamaForCausalLM.from_pretrained("./path/to/local/directory", local_files_only=True)
```

Mode offline (atau `local_files_only=True`) tetap dapat mengubah branch atau tag menjadi commit jika pemetaan tersebut telah disimpan di cache oleh pemuatan online sebelumnya. Jika pemetaan tidak pernah disimpan, Transformers akan mempertahankan branch atau tag yang Anda minta dan melanjutkan dengan pemuatan offline reguler. Anda akan mendapatkan hasil cache yang sama atau error file tidak ditemukan seperti pada pemuatan offline biasa.