Cài đặt

Transformers hoạt động với PyTorch. Nó đã được kiểm thử trên Python 3.11+ và PyTorch 2.6+.

Môi trường ảo

uv là trình quản lý gói và dự án Python dựa trên Rust với tốc độ cực nhanh, mặc định yêu cầu môi trường ảo để quản lý các dự án khác nhau và tránh các vấn đề tương thích giữa các phụ thuộc.

Công cụ này có thể được dùng như một giải pháp thay thế trực tiếp cho pip, nhưng nếu bạn muốn dùng pip, hãy bỏ uv khỏi các lệnh bên dưới.

Tham khảo tài liệu cài đặt của uv để cài đặt uv.

Tạo một môi trường ảo để cài đặt Transformers.

uv venv .env
source .env/bin/activate

Python

Cài đặt Transformers bằng lệnh sau.

uv là trình quản lý gói và dự án Python nhanh, được xây dựng bằng Rust.

CUDA

NVIDIA Spark (ARM64)

CPU

GPU Intel (XPU)

Kiểm tra xem cài đặt có thành công hay không bằng lệnh sau. Lệnh này nên trả về nhãn và điểm số cho văn bản được cung cấp.

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

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

Việc cài đặt từ mã nguồn sẽ cài đặt phiên bản mới nhất thay vì phiên bản ổn định của thư viện. Điều này đảm bảo bạn có những thay đổi cập nhật nhất trong Transformers và hữu ích khi thử nghiệm các tính năng mới nhất hoặc khắc phục một lỗi chưa được phát hành chính thức trong phiên bản ổn định.

Nhược điểm là phiên bản mới nhất có thể không phải lúc nào cũng ổn định. Nếu bạn gặp bất kỳ vấn đề nào, vui lòng mở một GitHub Issue để chúng tôi có thể khắc phục sớm nhất có thể.

Cài đặt từ mã nguồn bằng lệnh sau.

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

Kiểm tra xem cài đặt có thành công hay không bằng lệnh bên dưới. Lệnh này nên trả về nhãn và điểm số cho văn bản được cung cấp.

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

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

Một cài đặt có thể chỉnh sửa sẽ hữu ích nếu bạn đang phát triển cục bộ với Transformers. Nó liên kết bản sao cục bộ của Transformers của bạn với kho Transformers thay vì sao chép các tệp. Các tệp này được thêm vào đường dẫn import của Python.

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

Bạn phải giữ lại thư mục Transformers cục bộ để tiếp tục sử dụng nó.

Cập nhật phiên bản Transformers cục bộ của bạn với những thay đổi mới nhất trong kho chính bằng lệnh sau.

cd ~/transformers/
git pull

conda

conda là trình quản lý gói không phụ thuộc ngôn ngữ. Cài đặt Transformers từ kênh conda-forge trong môi trường ảo mới tạo của bạn.

conda install conda-forge::transformers

Cài đặt

Sau khi cài đặt, bạn có thể cấu hình vị trí bộ nhớ đệm của Transformers hoặc thiết lập thư viện để sử dụng ngoại tuyến.

Thư mục bộ nhớ đệm

Khi bạn tải một mô hình được huấn luyện trước bằng from_pretrained(), mô hình sẽ được tải xuống từ Hub và được lưu vào bộ nhớ đệm cục bộ.

Nếu bạn truyền một commit hash, Transformers sẽ sử dụng bộ nhớ đệm cục bộ cho các tệp của commit đó và không kiểm tra lại Hub cho từng tệp (bao gồm cả các tệp được biết là thiếu). Đây là hành vi mặc định khi không chỉ định revision.

Nếu bạn truyền một nhánh hoặc thẻ, Transformers sẽ liên hệ với Hub một lần khi bắt đầu quá trình tải để chọn commit, sau đó sử dụng bộ nhớ đệm theo cách tương tự cho các tệp của commit đó.

Thư mục mặc định được chỉ định bởi biến môi trường shell HF_HUB_CACHE là ~/.cache/huggingface/hub. Trên Windows, thư mục mặc định là C:\Users\username\.cache\huggingface\hub.

Lưu trữ mô hình trong một thư mục khác bằng cách thay đổi đường dẫn trong các biến môi trường shell sau (được liệt kê theo thứ tự ưu tiên).

HF_HUB_CACHE (mặc định)
HF_HOME
XDG_CACHE_HOME + /huggingface (chỉ khi HF_HOME chưa được đặt)

Chế độ ngoại tuyến

Để sử dụng Transformers trong môi trường ngoại tuyến hoặc có tường lửa, bạn cần tải xuống và lưu trữ các tệp đã tải trước đó. Hãy tải kho mô hình từ Hub bằng phương thức snapshot_download.

Tham khảo hướng dẫn Tải tệp từ Hub để biết thêm các tùy chọn tải tệp từ Hub. Bạn có thể tải tệp từ các phiên bản cụ thể, tải từ CLI, và thậm chí lọc các tệp cần tải từ một kho lưu trữ.

from huggingface_hub import snapshot_download

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

Đặt biến môi trường HF_HUB_OFFLINE=1 để ngăn các cuộc gọi HTTP đến Hub khi tải một model.

Một lựa chọn khác để chỉ tải các tệp đã được lưu trong bộ nhớ đệm là đặt local_files_only=True trong from_pretrained().

from transformers import LlamaForCausalLM

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

Chế độ offline (hoặc local_files_only=True) vẫn có thể chuyển một nhánh hoặc tag thành một commit nếu một lần tải trực tuyến trước đó đã lưu bản ánh xạ đó vào bộ nhớ đệm. Nếu bản ánh xạ chưa bao giờ được lưu, Transformers sẽ giữ nguyên nhánh hoặc tag mà bạn yêu cầu và tiếp tục với quy trình tải offline thông thường. Bạn sẽ nhận được các lần truy cập bộ nhớ đệm hoặc lỗi thiếu tệp giống như một lần tải offline bình thường.

Update on GitHub