Token truy cập người dùng

Token truy cập người dùng là gì?

User Access Tokens là cách được khuyến nghị để xác thực ứng dụng hoặc notebook với các dịch vụ của Hugging Face. Bạn có thể quản lý các access token của mình trong cài đặt.

Token truy cập cho phép các ứng dụng và notebook thực hiện các hành động cụ thể được quy định bởi phạm vi của các vai trò được hiển thị bên dưới:

• fine-grained: các token có vai trò này có thể được sử dụng để cung cấp quyền truy cập chi tiết vào các tài nguyên cụ thể, chẳng hạn như một mô hình cụ thể hoặc các mô hình trong một tổ chức cụ thể. Loại token này hữu ích trong các môi trường sản xuất, vì bạn có thể sử dụng token của riêng mình mà không cần chia sẻ quyền truy cập vào tất cả tài nguyên của mình.

• read: các token có vai trò này chỉ có thể được sử dụng để cung cấp quyền đọc cho các kho mã mà bạn có thể đọc. Điều này bao gồm các kho công khai và riêng tư do bạn hoặc một tổ chức mà bạn là thành viên sở hữu. Sử dụng vai trò này nếu bạn chỉ cần đọc nội dung từ Hugging Face Hub (ví dụ: khi tải xuống các mô hình riêng tư hoặc thực hiện suy luận).

• write: các token có vai trò này cấp thêm quyền ghi cho các kho mà bạn có quyền ghi. Sử dụng token này nếu bạn cần tạo hoặc đẩy nội dung vào một kho (ví dụ: khi huấn luyện một mô hình hoặc chỉnh sửa thẻ mô hình).

Nếu bạn là thành viên của một tổ chức với vai trò đọc/ghi/quản trị, thì Token truy cập người dùng của bạn sẽ có khả năng đọc/ghi các tài nguyên theo quyền của token (đọc/ghi) và tư cách thành viên tổ chức (đọc/ghi/quản trị).

Cách quản lý User Access Tokens?

Để tạo một access token, hãy vào phần cài đặt của bạn, sau đó nhấp vào tab Access Tokens. Nhấp vào nút New token để tạo một User Access Token mới.

Chọn một vai trò và một tên cho token của bạn và voilà - bạn đã sẵn sàng!

Bạn có thể xóa và làm mới User Access Tokens bằng cách nhấp vào nút Manage.

Cách sử dụng User Access Tokens?

Có rất nhiều cách để sử dụng User Access Token nhằm truy cập Hugging Face Hub, mang lại cho bạn sự linh hoạt cần thiết để xây dựng các ứng dụng tuyệt vời trên nền tảng này.

Token truy cập người dùng có thể là:

• được sử dụng thay cho mật khẩu để truy cập Hugging Face Hub bằng git hoặc bằng xác thực cơ bản.
• được truyền dưới dạng bearer token khi gọi Inference Providers.
• được sử dụng trong các thư viện Python của Hugging Face, chẳng hạn như transformers hoặc datasets:

from transformers import AutoModel

access_token = "hf_..."

model = AutoModel.from_pretrained("private/model", token=access_token)

Hãy cố gắng không để lộ token của bạn! Mặc dù bạn luôn có thể xoay vòng (rotate) token, nhưng trong khoảng thời gian đó, bất kỳ ai cũng có thể đọc hoặc ghi vào các kho lưu trữ riêng tư của bạn, điều này rất tệ. Xem Thu hồi token bị lộ nếu một token đã bị phơi bày.

Thực hành tốt nhất

Chúng tôi khuyến nghị bạn tạo một token truy cập cho mỗi ứng dụng hoặc mục đích sử dụng. Ví dụ, bạn có thể có một token riêng cho:

• Một máy cục bộ.
• Một notebook Colab.
• Một máy chủ suy luận tùy chỉnh tuyệt vời.

Nhờ đó, bạn có thể vô hiệu hóa một token mà không ảnh hưởng đến các cách sử dụng khác của mình.

Chúng tôi cũng khuyến nghị chỉ sử dụng các token chi tiết (fine-grained) cho mục đích triển khai thực tế. Nếu bị lộ, mức độ ảnh hưởng sẽ được giảm thiểu, và chúng có thể được chia sẻ trong tổ chức của bạn mà không gây tác động đến tài khoản của bạn.

Ví dụ, nếu ứng dụng production của bạn cần quyền đọc đối với một model gated, một thành viên trong tổ chức của bạn có thể yêu cầu quyền truy cập vào model đó và sau đó tạo một token fine-grained với quyền đọc đối với model đó. Token này sau đó có thể được sử dụng trong ứng dụng production của bạn mà không cần cấp cho nó quyền truy cập vào tất cả các model private của bạn.

Đối với các pipeline CI/CD

Nếu bạn chỉ cần quyền truy cập từ một workflow CI/CD (GitHub Actions, GitLab CI, CircleCI, …), bạn có thể hoàn toàn tránh việc lưu trữ access token dưới dạng CI secret. Xem Trusted Publishers, cơ chế này trao đổi identity token OpenID Connect (OIDC) của nhà cung cấp CI của bạn lấy một Hub token có thời hạn ngắn ngay khi bắt đầu mỗi lần chạy — có phạm vi theo repo (để phát hành models, datasets, Spaces hoặc kernels, hoặc để kéo chúng ở chế độ chỉ đọc) hoặc phạm vi theo user (để đọc các gated repos mà bạn có quyền truy cập và nhận rate limits của tài khoản bạn).

Đối với các tổ chức Enterprise

Nếu tổ chức của bạn cần cấp phát token cho các thành viên một cách tự động mà không yêu cầu mỗi người dùng tự tạo token riêng, hãy xem OAuth Token Exchange. Tính năng dành cho gói Enterprise này rất lý tưởng để xây dựng các nền tảng nội bộ, pipeline CI/CD hoặc các tích hợp tùy chỉnh cần truy cập tài nguyên Hugging Face thay mặt cho các thành viên trong tổ chức.

Thu hồi token bị lộ

Nếu một trong các token của bạn bị lộ, hãy xóa hoặc làm mới nó từ tab Access Tokens trong cài đặt của bạn.

Nếu bạn tìm thấy token truy cập Hugging Face của người khác, bạn có thể vô hiệu hóa nó bằng endpoint POST /api/credentials/revoke. Bạn không cần bất kỳ quyền nào đối với tài khoản hoặc tổ chức sở hữu token đó.

# LEAKED_HF_TOKEN should contain the raw token value to revoke
curl -X POST "https://huggingface.co/api/credentials/revoke" \
  -H "Content-Type: application/json" \
  -d "{\"credentials\": [\"${LEAKED_HF_TOKEN}\"]}"

Bạn có thể truyền nhiều giá trị token trong mảng credentials trong một lần gọi duy nhất, điều này rất tiện lợi cho các pipeline quét bí mật báo cáo kết quả theo lô.

Mọi token đã gửi mà khớp với một token hiện có sẽ bị vô hiệu hóa ngay lập tức và ngừng hoạt động ở mọi nơi — khác với thu hồi ở cấp tổ chức, vốn chỉ cắt quyền truy cập của token vào một tổ chức duy nhất. Chủ sở hữu của token sẽ được thông báo qua email và cần tạo một token mới để khôi phục quyền truy cập.

Endpoint luôn phản hồi 202 Accepted, bất kể token nào bạn đã gửi có tồn tại hay không, do đó phản hồi của nó không thể được dùng để dò xem một token có hợp lệ hay không. Việc gửi lại cùng một token là vô hại: các lần gọi lặp lại không làm gì và chủ sở hữu chỉ được thông báo một lần.

Để tránh rò rỉ giá trị token trong lịch sử shell hoặc nhật ký, hãy truyền chúng qua biến môi trường hoặc tệp, và tránh dán token thô trực tiếp vào dòng lệnh.

Tokens trong các tổ chức có chính sách quản lý token

Các tổ chức sử dụng gói Team và Enterprise có thể áp dụng các chính sách token ảnh hưởng đến cách token của bạn hoạt động khi truy cập tài nguyên của tổ chức đó.

Khi token của bạn cần được phê duyệt (tổ chức Team & Enterprise)

Khi bạn tạo một token chi tiết được giới hạn phạm vi trong một tổ chức yêu cầu phê duyệt của quản trị viên, token sẽ tự động chuyển sang trạng thái Chờ xử lý. Token không thể truy cập các tài nguyên của tổ chức đó cho đến khi một quản trị viên phê duyệt. Bạn sẽ nhận được thông báo qua email khi token của bạn được phê duyệt hoặc từ chối.

Bạn có thể kiểm tra trạng thái từ trang danh sách token của mình, một token đang chờ sẽ hiển thị biểu tượng đồng hồ cát màu cam bên cạnh huy hiệu quyền của nó, và một token bị từ chối hoặc thu hồi sẽ hiển thị biểu tượng dấu chấm than màu đỏ. Một banner lỗi màu đỏ cũng sẽ xuất hiện trên trang chỉnh sửa của token nếu token của bạn bị từ chối hoặc thu hồi.

Nếu bạn là quản trị viên của tổ chức, các token chi tiết (fine-grained) do bạn tạo và được giới hạn phạm vi trong tổ chức đó sẽ được tự động phê duyệt — không cần bước xem xét.

Khi token của bạn bị từ chối (tổ chức Team & Enterprise)

Nếu token của bạn bị từ chối, bạn sẽ nhận được thông báo qua email. Token vẫn còn trong tài khoản của bạn và vẫn có thể được sử dụng cho các tài nguyên bên ngoài tổ chức. Một token bị từ chối có thể được phê duyệt sau đó bởi quản trị viên, khôi phục quyền truy cập mà bạn không cần tạo token mới.

Khi cố gắng sử dụng một token bị từ chối với các tài nguyên của tổ chức, bạn sẽ nhận được lỗi 403.

Khi token của bạn bị thu hồi (tổ chức Enterprise)

Việc thu hồi là vĩnh viễn. Khác với việc từ chối, một token đã bị thu hồi không thể được khôi phục. Nếu token của bạn đã bị thu hồi, bạn phải xóa nó và tạo một token mới. Nếu tổ chức yêu cầu phê duyệt của quản trị viên, token mới sẽ bắt đầu ở trạng thái chờ.

Khi cố gắng sử dụng một token đã bị thu hồi đối với các tài nguyên của tổ chức, bạn sẽ nhận được lỗi 403 với thông báo: “Token của bạn đã bị quản trị viên tổ chức thu hồi, bạn không còn quyền truy cập vào các tài nguyên của tổ chức. Vui lòng liên hệ với họ để biết thêm thông tin.”

Việc thu hồi chỉ ảnh hưởng đến tổ chức đã thực hiện thu hồi. Token vẫn hoạt động bình thường cho tất cả các tài nguyên khác mà nó được cấp phạm vi.

Khi tổ chức của bạn chỉ cho phép các token chi tiết (các tổ chức Team & Enterprise)

Nếu tổ chức của bạn đã thiết lập chính sách yêu cầu token chi tiết, các token đọc/ghi sẽ bị từ chối với lỗi 403 khi được sử dụng đối với các tài nguyên của tổ chức đó.