# Cài đặt

Trước khi bắt đầu, bạn cần thiết lập môi trường bằng cách cài đặt các gói phù hợp.

`huggingface_hub` được kiểm thử trên **Python 3.10+**.

## Cài đặt bằng pip

Rất khuyến nghị cài đặt `huggingface_hub` trong một [môi trường ảo](https://docs.python.org/3/library/venv.html). Nếu bạn chưa quen với môi trường ảo của Python, hãy xem [hướng dẫn](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/) này. Môi trường ảo giúp quản lý các dự án khác nhau dễ dàng hơn và tránh các vấn đề tương thích giữa các phụ thuộc.

Bắt đầu bằng cách tạo một môi trường ảo trong thư mục dự án của bạn:

```bash
python -m venv .venv
```

Kích hoạt môi trường ảo. Trên Linux và macOS:

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

Kích hoạt môi trường ảo trên Windows:

```bash
.venv/Scripts/activate
```

Bây giờ bạn đã sẵn sàng để cài đặt `huggingface_hub` [từ kho PyPi](https://pypi.org/project/huggingface-hub/):

```bash
pip install --upgrade huggingface_hub
```

Khi hoàn tất, [kiểm tra cài đặt](#check-installation) đang hoạt động chính xác.

### Cài đặt các phụ thuộc tùy chọn

Một số phụ thuộc của `huggingface_hub` là [tùy chọn](https://setuptools.pypa.io/en/latest/userguide/dependency_management.html#optional-dependencies) vì chúng không bắt buộc để chạy các tính năng cốt lõi của `huggingface_hub`. Tuy nhiên, một số tính năng của `huggingface_hub` có thể không khả dụng nếu các phụ thuộc tùy chọn chưa được cài đặt.

Bạn có thể cài đặt các phụ thuộc tùy chọn thông qua `pip`:
```bash
# Install dependencies for both torch-specific and MCP-specific features.
pip install 'huggingface_hub[mcp,torch]'
```

Dưới đây là danh sách các phụ thuộc tùy chọn trong `huggingface_hub`:
- `fastai`, `torch`: các phụ thuộc để chạy các tính năng đặc thù của framework.
- `dev`: các phụ thuộc để đóng góp cho thư viện. Bao gồm `testing` (để chạy các bài kiểm thử), `typing` (để chạy trình kiểm tra kiểu) và `quality` (để chạy các trình kiểm tra mã nguồn).

### Cài đặt từ mã nguồn

Trong một số trường hợp, việc cài đặt `huggingface_hub` trực tiếp từ mã nguồn là hữu ích. Điều này cho phép bạn sử dụng phiên bản `main` mới nhất thay vì phiên bản ổn định gần nhất. Phiên bản `main` hữu ích để cập nhật các phát triển mới nhất, chẳng hạn khi một lỗi đã được sửa kể từ lần phát hành chính thức cuối cùng nhưng một bản phát hành mới vẫn chưa được tung ra.

Tuy nhiên, điều này có nghĩa là phiên bản `main` có thể không luôn ổn định. Chúng tôi nỗ lực giữ cho phiên bản `main` hoạt động, và hầu hết các vấn đề thường được giải quyết trong vòng vài giờ hoặc một ngày. Nếu bạn gặp sự cố, vui lòng mở một Issue để chúng tôi có thể khắc phục càng sớm càng tốt!

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

Khi cài đặt từ mã nguồn, bạn cũng có thể chỉ định một nhánh cụ thể. Điều này hữu ích nếu bạn muốn kiểm tra một tính năng mới hoặc một bản sửa lỗi mới mà chưa được hợp nhất:

```bash
pip install git+https://github.com/huggingface/huggingface_hub@my-feature-branch
```

Khi hoàn tất, [kiểm tra cài đặt](#check-installation) đang hoạt động chính xác.

### Cài đặt có thể chỉnh sửa

Cài đặt từ mã nguồn cho phép bạn thiết lập một [cài đặt có thể chỉnh sửa](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs). Đây là phương pháp cài đặt nâng cao hơn nếu bạn có kế hoạch đóng góp cho `huggingface_hub` và cần kiểm tra các thay đổi trong mã. Bạn cần sao chép (clone) một bản địa phương của `huggingface_hub` trên máy của mình.

```bash
# First, clone repo locally
git clone https://github.com/huggingface/huggingface_hub.git

# Then, install with -e flag
cd huggingface_hub
pip install -e .
```

Các lệnh này sẽ liên kết thư mục bạn đã clone kho mã nguồn với các đường dẫn thư viện Python của bạn. Python sẽ tìm kiếm bên trong thư mục bạn đã clone ngoài các đường dẫn thư viện thông thường. Ví dụ, nếu các gói Python của bạn thường được cài đặt trong `./.venv/lib/python3.13/site-packages/`, Python cũng sẽ tìm kiếm trong thư mục bạn đã clone `./huggingface_hub/`.

## Cài đặt Hugging Face CLI 

Sử dụng trình cài đặt một dòng của chúng tôi để thiết lập CLI `hf` mà không cần đụng chạm đến môi trường Python của bạn:

Trên macOS và Linux:

```bash
curl -LsSf https://hf.co/cli/install.sh | bash
```

Trên Windows:

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"
```

Để nâng cấp bản cài đặt hiện có, hãy chạy `hf update` — lệnh này sẽ phát hiện cách `hf` được cài đặt (trình cài đặt độc lập, Homebrew, hoặc pip) và chạy lệnh tương ứng.

## Cài đặt bằng conda

Nếu bạn quen thuộc hơn với nó, bạn có thể cài đặt `huggingface_hub` bằng cách sử dụng [kênh conda-forge](https://anaconda.org/conda-forge/huggingface_hub):

```bash
conda install -c conda-forge huggingface_hub
```

Khi hoàn tất, [kiểm tra cài đặt](#check-installation) đang hoạt động chính xác.

## Kiểm tra cài đặt

Sau khi cài đặt, hãy kiểm tra xem `huggingface_hub` có hoạt động đúng không bằng cách chạy lệnh sau:

```bash
python -c "from huggingface_hub import model_info; print(model_info('gpt2'))"
```

Lệnh này sẽ lấy thông tin từ Hub về mô hình [gpt2](https://huggingface.co/gpt2). Kết quả đầu ra sẽ có dạng như sau:

```text
Model Name: gpt2
Tags: ['pytorch', 'tf', 'jax', 'tflite', 'rust', 'safetensors', 'gpt2', 'text-generation', 'en', 'doi:10.57967/hf/0039', 'transformers', 'exbert', 'license:mit', 'has_space']
Task: text-generation
```

## Hạn chế trên Windows

Với mục tiêu dân chủ hóa ML chất lượng ở mọi nơi, chúng tôi đã xây dựng `huggingface_hub` như một thư viện đa nền tảng, đặc biệt là để hoạt động chính xác trên cả hệ thống dựa trên Unix và Windows. Tuy nhiên, có một số trường hợp mà `huggingface_hub` gặp phải một số hạn chế khi chạy trên Windows. Dưới đây là danh sách đầy đủ các vấn đề đã biết. Vui lòng cho chúng tôi biết nếu bạn gặp bất kỳ vấn đề nào chưa được tài liệu hóa bằng cách mở [một issue trên Github](https://github.com/huggingface/huggingface_hub/issues/new/choose).

- Hệ thống cache của `huggingface_hub` dựa vào symlink để lưu trữ hiệu quả các tệp đã tải xuống
từ Hub. Trên Windows, bạn phải bật chế độ developer hoặc chạy script với quyền admin để kích hoạt symlink. Nếu chúng không được kích hoạt, hệ thống cache vẫn hoạt động nhưng theo cách không được tối ưu. Vui lòng đọc phần [giới hạn của cache](./guides/manage-cache#limitations) để biết thêm chi tiết.
- Đường dẫn tệp trên Hub có thể chứa các ký tự đặc biệt (ví dụ: `"path/to?/my/file"`). Windows
nghiêm ngặt hơn đối với [ký tự đặc biệt](https://learn.microsoft.com/en-us/windows/win32/intl/character-sets-used-in-file-names), khiến việc tải xuống các tệp đó trên Windows trở nên không thể. Hy vọng đây là một trường hợp hiếm gặp. Vui lòng liên hệ với chủ sở hữu kho nếu bạn cho rằng đây là một sai sót, hoặc liên hệ với chúng tôi để tìm ra giải pháp.

## Các bước tiếp theo

Khi `huggingface_hub` đã được cài đặt đúng cách trên máy của bạn, bạn có thể muốn [cấu hình các biến môi trường](package_reference/environment_variables) hoặc [xem một trong các hướng dẫn của chúng tôi](guides/overview) để bắt đầu.