huggingface/transformers: chạy mô hình AI văn bản, ảnh, âm thanh — hướng dẫn cài đặt và dùng

Tóm tắt nhanh
huggingface/transformers là thư viện Python mã nguồn mở định nghĩa và chạy các mô hình AI hiện đại cho văn bản, hình ảnh, âm thanh, video và đa phương thức. Bạn dùng nó để tải mô hình có sẵn trên Hugging Face Hub rồi chạy chỉ với vài dòng code. Cài đặt khá dễ nếu bạn đã có Python 3.11+ và PyTorch 2.6+.
Transformers là thư viện Python của Hugging Face, đóng vai trò "bộ định nghĩa mô hình" cho các mô hình AI hiện đại: văn bản, thị giác máy tính, âm thanh, video và đa phương thức. Bạn dùng nó để tải một mô hình có sẵn về máy rồi chạy, hoặc để huấn luyện thêm cho mô hình theo dữ liệu của mình.
Vấn đề nó giải quyết rất thực tế. Mỗi mô hình AI thường do một nhóm khác nhau viết, cách gọi mỗi nơi một kiểu. Transformers gom tất cả về một cách dùng thống nhất. Theo README, một mô hình đã được hỗ trợ ở đây thì sẽ tương thích với phần lớn công cụ huấn luyện (Axolotl, Unsloth, DeepSpeed, FSDP, PyTorch-Lightning...), các engine chạy mô hình (vLLM, SGLang, TGI...) và các thư viện lân cận như llama.cpp hay mlx.
Repo hiện có khoảng 168.937 sao và 35.236 fork, giấy phép Apache-2.0, vẫn được cập nhật trong vài tháng gần đây. Điểm đáng giá nhất: Hugging Face Hub có hơn 1 triệu checkpoint dùng được với thư viện này, và bạn chạy thử một mô hình chỉ bằng ba dòng code. Bài này hợp với lập trình viên mới, dân phân tích dữ liệu, hoặc người làm kinh doanh có chút nền Python và muốn tự thử AI.
huggingface/transformers
Thư viện Python của Hugging Face để tải và chạy hàng loạt mô hình AI về văn bản, ảnh, âm thanh, đa phương thức, dùng cho cả suy luận lẫn huấn luyện.
I.Transformers làm được gì
Dưới đây là những việc chính, theo tư liệu của repo.
A.Chạy mô hình nhanh bằng Pipeline
Pipeline là lớp bậc cao giúp bạn chạy mô hình mà không phải tự xử lý đầu vào. Bạn chỉ nói rõ tác vụ (task) và tên mô hình, nó lo phần chuẩn bị dữ liệu và trả kết quả đúng dạng. Lợi ích: người mới có thể thử một mô hình trong vài phút, không cần hiểu bên trong.
B.Nhiều loại dữ liệu trong một thư viện
README liệt kê các nhóm tác vụ như sau:
- Âm thanh: nhận dạng giọng nói (Whisper, Parakeet), phân loại âm thanh, chuyển văn bản thành giọng nói (CSM), sinh nhạc (MusicGen).
- Thị giác: phân loại ảnh (DINO v2), phát hiện vật thể (RT-DETRv2), ước lượng độ sâu, tách vùng ảnh (SAM).
- Đa phương thức: hỏi đáp về ảnh (Llava, BLIP), đọc tài liệu và OCR (LayoutLMv3, GOT-OCR2), hỏi đáp trên bảng (TAPAS).
- Ngôn ngữ: sinh văn bản (Llama, Qwen), tóm tắt (BART), dịch (T5), hỏi đáp (Mixtral).
Tức là một thư viện, bạn làm được từ chatbot đến đọc hoá đơn hay chuyển giọng nói thành chữ.
C.Kho mô hình khổng lồ trên Hub
Bạn không phải huấn luyện từ đầu. README nhấn mạnh việc chia sẻ mô hình đã huấn luyện giúp giảm thời gian tính toán và chi phí. Mô hình được tải về và lưu đệm (cache) lần đầu, những lần sau dùng lại.
D.Huấn luyện và tuỳ biến
Thư viện hỗ trợ cả huấn luyện. README nói bạn có thể huấn luyện mô hình hiện đại "trong 3 dòng code", và mỗi kiến trúc đều có ví dụ để tái tạo kết quả của tác giả gốc. Mã trong từng file mô hình được giữ đơn giản có chủ ý để nhà nghiên cứu sửa nhanh.
E.Chat ngay trên dòng lệnh
README có ghi lệnh transformers chat, nhưng cần transformers serve đang chạy. Mình sẽ nhắc kỹ hơn ở phần dùng thực tế.
II.Cần chuẩn bị gì
Theo README, bạn cần:
- Python 3.11 trở lên.
- PyTorch 2.6 trở lên. Lệnh cài
transformers[torch]ở bên dưới đã kéo PyTorch theo. - Một môi trường ảo (virtual environment) tạo bằng
venvhoặcuv. Đây là khuyến nghị của README, không bắt buộc về mặt kỹ thuật nhưng giúp máy bạn gọn gàng. - Kết nối Internet để tải mô hình từ Hugging Face Hub trong lần chạy đầu.
Về hệ điều hành, README chỉ ghi lệnh kích hoạt môi trường ảo cho kiểu macOS/Linux. Tư liệu không nói rõ về yêu cầu GPU hay dung lượng RAM tối thiểu, và cũng không nói cần tài khoản hay API key để chạy các ví dụ cơ bản. Tuỳ mô hình bạn chọn (nhỏ hay lớn) mà nhu cầu phần cứng khác nhau, nên hãy đọc trang mô hình trên Hub trước khi tải.
Mô hình lớn có thể nặng hàng chục GB và chạy chậm nếu không có card đồ hoạ. Lần đầu mới dùng, bạn nên thử mô hình nhỏ (ví dụ các bản có chữ 0.5B, 1.5B trong README) trước khi thử bản lớn.
III.Cài đặt từng bước
- Kiểm tra PythonCần Python 3.11 trở lên
- Tạo môi trường ảoDùng venv hoặc uv để cô lập thư viện
- Kích hoạt môi trườngChạy lệnh activate trong terminal
- Cài transformersDùng pip hoặc uv pip cài gói kèm PyTorch
- Chạy thử pipelineChạy đoạn code sinh văn bản đầu tiên
A.Bước 1: Mở terminal và kiểm tra Python
Trên Windows, bạn mở PowerShell hoặc Terminal. Trên macOS/Linux, mở Terminal. Gõ lệnh sau để xem phiên bản Python:
python --versionNếu số hiện ra thấp hơn 3.11, bạn cần cài Python mới hơn trước. README không hướng dẫn phần này, bạn xem trang chủ Python để tải.
B.Bước 2: Tạo môi trường ảo
Môi trường ảo là một thư mục riêng chứa thư viện của dự án, không làm lộn xộn Python chung của máy. README ghi hai cách, bạn chọn một.
Cách dùng venv:
python -m venv .my-env
source .my-env/bin/activateCách dùng uv (công cụ quản lý Python viết bằng Rust, nhanh hơn):
uv venv .my-env
source .my-env/bin/activateChỗ người mới hay vấp: lệnh source .my-env/bin/activate là dành cho macOS/Linux. Trên Windows PowerShell, lệnh kích hoạt phổ thông của Python là:
.my-env\Scripts\Activate.ps1Kích hoạt xong, đầu dòng lệnh thường hiện thêm (.my-env). Mỗi lần mở terminal mới, bạn phải kích hoạt lại.
C.Bước 3: Cài Transformers
Dùng pip:
pip install "transformers[torch]"Hoặc dùng uv:
uv pip install "transformers[torch]"Phần [torch] báo cho pip cài kèm PyTorch. Lệnh này có thể mất vài phút vì PyTorch khá nặng. Hãy giữ nguyên dấu ngoặc kép.
D.Bước 4 (tuỳ chọn): Cài từ mã nguồn
Nếu bạn muốn bản mới nhất hoặc muốn đóng góp cho dự án, README hướng dẫn cài từ mã nguồn. Lưu ý bản mới nhất có thể chưa ổn định.
git clone https://github.com/huggingface/transformers.git
cd transformers
# pip
pip install '.[torch]'
# uv
uv pip install '.[torch]'Lệnh git clone tải mã về, cd transformers vào thư mục vừa tải, rồi lệnh pip cài thư viện từ chính thư mục đó (dấu chấm nghĩa là "thư mục hiện tại"). Bạn cần có Git trên máy. Người chỉ muốn dùng thì không cần bước này.
IV.Kiểm tra đã chạy được chưa
Cách kiểm tra theo README là chạy thử đoạn Quickstart. Tạo một file, ví dụ thu.py, rồi dán nội dung sau:
from transformers import pipeline
pipeline = pipeline(task="text-generation", model="Qwen/Qwen2.5-1.5B")
pipeline("the secret to baking a really good cake is ")Chạy file bằng python thu.py. Lần đầu, thư viện sẽ tải mô hình về nên bạn chờ một lúc. Kết quả đúng sẽ có dạng một danh sách chứa khoá generated_text, nội dung là câu bạn đưa vào được viết tiếp. README minh hoạ kết quả bắt đầu bằng "the secret to baking a really good cake is 1) to use the right ingredients...". Nội dung cụ thể mỗi lần có thể khác, miễn là có văn bản được sinh ra và không báo lỗi.
Lưu ý: lệnh pipeline(...) ở dòng cuối chỉ tự in kết quả khi bạn chạy trong môi trường tương tác như Jupyter hay Python shell. Nếu chạy file .py, bạn bọc thêm print(...) quanh lời gọi để thấy kết quả.
V.Dùng vào việc thật
Các tình huống dưới đây bám đúng những ví dụ có trong README.
A.Chép lời cuộc họp thành văn bản
Bối cảnh: bạn là nhân viên văn phòng, có file ghi âm họp và muốn có bản chữ. README có ví dụ nhận dạng giọng nói với mô hình Whisper:
from transformers import pipeline
pipeline = pipeline(task="automatic-speech-recognition", model="openai/whisper-large-v3")
pipeline("https://huggingface.co/datasets/Narsil/asr_dummy/resolve/main/mlk.flac")Bạn thay đường dẫn ví dụ bằng đường dẫn file âm thanh của mình. Kết quả là một từ điển có khoá text chứa lời đã được chép ra. README chỉ minh hoạ với một file mẫu tiếng Anh, nên chất lượng với tiếng Việt chưa có thông tin trong tư liệu, bạn nên thử trên đoạn ngắn trước.
B.Hỏi đáp về một bức ảnh
Bối cảnh: chủ shop có nhiều ảnh sản phẩm và muốn máy mô tả nhanh trong ảnh có gì. README có ví dụ hỏi đáp trên ảnh (visual question answering):
from transformers import pipeline
pipeline = pipeline(task="visual-question-answering", model="Salesforce/blip-vqa-base")
pipeline(
image="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/tasks/idefics-few-shot.jpg",
question="What is in the image?",
)Kết quả là câu trả lời ngắn, ví dụ README cho ra statue of liberty. Bạn đổi image và question theo ảnh của mình. Mô hình này nhận câu hỏi tiếng Anh theo ví dụ của README.
Muốn thử AI mà không phải viết cả hệ thống, bạn chỉ cần một pipeline và một cái tên mô hình.
Ông T
C.Phân loại ảnh hàng loạt
Bối cảnh: lập trình viên mới muốn biết một tấm ảnh thuộc loại gì. README có ví dụ phân loại ảnh với DINOv2:
from transformers import pipeline
pipeline = pipeline(task="image-classification", model="facebook/dinov2-small-imagenet1k-1-layer")
pipeline("https://huggingface.co/datasets/Narsil/image_dummy/raw/main/parrots.png")Kết quả là danh sách nhãn kèm điểm tin cậy (score). Với ảnh mẫu, nhãn cao nhất là macaw với điểm gần 1. Bạn có thể đưa vào một vòng lặp để xử lý nhiều ảnh, nhưng phần vòng lặp là code của bạn, README không có sẵn.
D.Làm chatbot nhỏ với lịch sử hội thoại
Bối cảnh: dev muốn thử một chatbot có "tính cách". README hướng dẫn dựng lịch sử chat gồm vai trò system và user rồi đưa vào pipeline:
import torch
from transformers import pipeline
chat = [
{"role": "system", "content": "You are a sassy, wise-cracking robot as imagined by Hollywood circa 1986."},
{"role": "user", "content": "Hey, can you tell me any fun things to do in New York?"}
]
pipeline = pipeline(task="text-generation", model="meta-llama/Meta-Llama-3-8B-Instruct", dtype=torch.bfloat16, device_map="auto")
response = pipeline(chat, max_new_tokens=512)
print(response[0]["generated_text"][-1]["content"])Dòng system định hình cách mô hình trả lời, dòng user là câu hỏi. Mô hình 8B này khá lớn so với ví dụ đầu, nên máy yếu có thể chạy rất chậm hoặc thiếu bộ nhớ. Nếu chỉ muốn thử trò chuyện trên dòng lệnh, README gợi ý khi transformers serve đang chạy, bạn gõ:
transformers chat Qwen/Qwen2.5-0.5B-InstructCách bật transformers serve README chỉ dẫn sang trang tài liệu về serving trên trang chủ dự án, nên bạn xem ở đó.
VI.Lỗi hay gặp và cách xử lý
A.Báo không tìm thấy lệnh pip hoặc python
Thường do chưa cài Python, hoặc chưa thêm vào PATH. Bạn mở terminal mới, gõ python --version. Nếu vẫn lỗi, cài lại Python và nhớ tick tuỳ chọn thêm vào PATH khi cài (nếu trình cài đặt có).
B.Cài xong nhưng import báo thiếu torch
Nguyên nhân hay gặp là bạn cài transformers mà thiếu phần [torch], hoặc cài ở môi trường này nhưng chạy code ở môi trường khác. Hãy chắc là môi trường ảo đã được kích hoạt (thấy (.my-env) ở đầu dòng) rồi chạy lại lệnh pip install "transformers[torch]".
C.Phiên bản Python hoặc PyTorch quá cũ
README yêu cầu Python 3.11+ và PyTorch 2.6+. Nếu pip báo không tìm được phiên bản phù hợp, nhiều khả năng Python của bạn quá cũ. Tạo môi trường ảo mới bằng Python đúng phiên bản.
D.Hết bộ nhớ hoặc chạy cực chậm
Đây là chuyện rất dễ gặp khi tải mô hình lớn. Hãy đổi sang mô hình nhỏ hơn (ví dụ bản 0.5B hoặc 1.5B như trong README), đóng bớt ứng dụng khác. Tư liệu không nêu yêu cầu cụ thể về RAM hay GPU, nên bạn đọc trang mô hình trên Hub để biết kích thước.
E.Tải mô hình không được hoặc bị từ chối truy cập
Một số mô hình trên Hub có thể yêu cầu bạn đăng nhập hoặc đồng ý điều khoản trước khi tải. README không nói chi tiết phần này, vì vậy nếu gặp lỗi quyền truy cập, bạn mở trang của mô hình trên Hub để xem hướng dẫn. Không dán key hay mật khẩu của bạn vào code rồi chia sẻ công khai.
VII.Có nên dùng không
Điểm mạnh:
- Cách dùng thống nhất cho rất nhiều loại mô hình, chạy thử chỉ vài dòng.
- Kho mô hình rất lớn trên Hub, hỗ trợ văn bản, ảnh, âm thanh, video.
- Tương thích rộng với các công cụ huấn luyện và engine chạy mô hình khác.
- Mã nguồn mở, giấy phép Apache-2.0, cộng đồng lớn và vẫn được cập nhật.
Giới hạn, đúng như README tự nói ở phần "khi nào không nên dùng":
- Đây không phải bộ khối xây dựng mạng nơ-ron theo kiểu module hoá. Mã trong từng file mô hình cố ý không trừu tượng hoá nhiều.
- API huấn luyện được tối ưu cho các mô hình PyTorch do chính Transformers cung cấp. Nếu bạn cần vòng lặp huấn luyện tổng quát, README khuyên dùng thư viện khác như Accelerate.
- Người hoàn toàn chưa biết Python sẽ cần làm quen terminal và môi trường ảo trước.
Nếu bạn chỉ muốn trò chuyện với AI mà không đụng code, một ứng dụng chat sẵn có sẽ hợp hơn. Còn nếu bạn muốn tự chạy mô hình trong code của mình, thử nghiệm nhiều loại tác vụ, hoặc học cách AI hoạt động, Transformers là điểm khởi đầu rất đáng thử.
Câu hỏi thường gặp
Transformers có miễn phí không?
Thư viện là mã nguồn mở với giấy phép Apache-2.0, bạn cài và dùng không mất phí. Chi phí khác (điện, phần cứng, hoặc điều khoản của từng mô hình) tư liệu chưa nói rõ. Bạn nên xem trang của từng mô hình trên Hugging Face Hub.
Có cần GPU để chạy không?
Tư liệu không nêu GPU là bắt buộc hay không. Ví dụ đơn giản dùng mô hình nhỏ như Qwen2.5-1.5B, còn ví dụ chat dùng mô hình 8B kèm `device_map="auto"`. Mô hình càng lớn càng cần phần cứng mạnh, nên bạn bắt đầu bằng mô hình nhỏ.
Chạy được trên Windows không?
README chỉ ghi lệnh kích hoạt môi trường ảo cho macOS/Linux và không nói riêng về Windows. Cài đặt bằng pip bằng lệnh `pip install "transformers[torch]"` là cách phổ thông, nhưng tư liệu chưa xác nhận chi tiết cho Windows. Bạn có thể dùng lệnh kích hoạt môi trường ảo kiểu PowerShell của Python thay thế.
Yêu cầu phiên bản Python là gì?
README ghi Transformers chạy với Python 3.11 trở lên và PyTorch 2.6 trở lên. Bạn nên tạo môi trường ảo bằng venv hoặc uv để cài cho gọn.
Dữ liệu của mình có an toàn không?
Mô hình được tải về và lưu đệm trên máy bạn rồi chạy tại đó theo ví dụ trong README. Tư liệu chưa có phần riêng nói về quyền riêng tư dữ liệu. Repo có file SECURITY.md, bạn nên đọc nếu quan tâm đến bảo mật.
Transformers khác gì Accelerate?
README nói API huấn luyện của Transformers tối ưu cho các mô hình PyTorch do chính nó cung cấp. Với vòng lặp học máy tổng quát, README khuyên dùng thư viện khác như Accelerate. Tư liệu không so sánh thêm.
Có dùng được với tiếng Việt không?
Tư liệu chưa nói về khả năng tiếng Việt của từng mô hình. README có bản dịch tiếng Việt và danh sách rất nhiều mô hình trên Hub. Bạn nên đọc trang mô hình để biết ngôn ngữ được hỗ trợ và thử trên dữ liệu nhỏ trước.


