Nhà xuất bản được tin cậy

Đẩy lên Hub từ CI mà không cần lưu bí mật HF_TOKEN.

Công việc CI của bạn xác minh danh tính với Hugging Face bằng cách sử dụng token OpenID Connect (OIDC) có thời hạn ngắn từ nhà cung cấp CI của bạn, và nhận lại một token Hugging Face có thời hạn ngắn để đổi lại. Không cần lưu trữ token HF như một bí mật hay xoay vòng token.

Trusted Publishers có cùng ý tưởng với Trusted Publishers của PyPI và Trusted Publishing của npm.

Ví dụ nhanh: phát hành một mô hình từ GitHub Actions

Bạn đang duy trì acme/awesome-model trên HF Hub và muốn CI trong kho acme/awesome-model-training được lưu trữ bên ngoài (trên GitHub, GitLab, hoặc bất kỳ nhà cung cấp nào tuân thủ OIDC) đẩy các checkpoint mới — không cần bí mật HF_TOKEN.

1. Cấu hình nhà xuất bản đáng tin cậy trên Hub

Trên https://huggingface.co/acme/awesome-model/settings, mở Trusted Publishers và thêm:

• Nhà cung cấp: GitHub Actions
• Claims (tất cả phải khớp để quá trình trao đổi thành công):
  • repository = acme/awesome-model-training
  • branch = main
  • workflow = publish.yml

repository đơn lẻ chỉ giới hạn nhà phát hành trong một repo GitHub. Thêm branch và/hoặc workflow để cố định nó vào một nhánh hoặc tệp workflow — được khuyến nghị.

2. Thêm workflow vào kho GitHub của bạn

.github/workflows/publish.yml:

name: Publish to Hugging Face

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  publish:
    runs-on: ubuntu-latest

    permissions:
      id-token: write  # required so the job can request an OIDC token
      contents: read

    steps:
      - uses: actions/checkout@v4

      - name: Install the hf CLI
        run: |
          curl -LsSf https://hf.co/cli/install.sh | bash
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"

      - name: Upload checkpoint
        env:
          # The HF repo to publish to. For non-model repos, prefix accordingly:
          #   datasets/acme/awesome-dataset, spaces/acme/awesome-space, kernels/acme/awesome-kernel
          HF_OIDC_RESOURCE: acme/awesome-model
        run: hf upload acme/awesome-model ./checkpoint . --commit-message "Publish from ${GITHUB_SHA::7}"

Đó là tất cả. Trên GitHub Actions, CLI hf (huggingface_hub>=1.19.0) sẽ phát hiện nhà cung cấp, thực hiện trao đổi và tự động sử dụng token kết quả. Bạn chỉ cần đặt HF_OIDC_RESOURCE.

Xuất bản lên nhiều kho trong một lần chạy (ví dụ: một mô hình và một tập dữ liệu)? Đặt HF_OIDC_RESOURCE cho từng bước để mỗi token được giới hạn phạm vi theo kho mà bước đó đẩy lên.

Các nhà cung cấp CI khác

CLI hf hiện chỉ tạo ID token một cách bản địa trên GitHub Actions. Trên GitLab, CircleCI, Bitbucket hoặc bất kỳ nhà cung cấp nào khác, bạn hãy tự tạo ID token (xem Các nhà cung cấp CI được hỗ trợ) và truyền nó qua HF_OIDC_ID_TOKEN — CLI sẽ trao đổi nó trực tiếp:

# GitLab CI (.gitlab-ci.yml)
publish:
  id_tokens:
    HF_ID_TOKEN:
      aud: https://huggingface.co
  script:
    - curl -LsSf https://hf.co/cli/install.sh | bash
    - export PATH="$HOME/.local/bin:$PATH"
    - HF_OIDC_ID_TOKEN="$HF_ID_TOKEN" HF_OIDC_RESOURCE="acme/awesome-model" hf upload acme/awesome-model ./checkpoint .

Các ví dụ hoạt động hoàn chỉnh:

• GitHub Actions — github.com/coyotte508/publish-to-hf
• GitLab CI — gitlab.com/coyotte508/publish-to-hf

Hai loại: nhà xuất bản kho và danh tính CI/CD

Cả hai token đều hết hạn sau 60 phút. Bạn cần vai trò Write trên một kho Hub để quản lý các nhà xuất bản được tin cậy của nó.

Truy cập các kho có kiểm soát từ CI

Nếu bạn chỉ cần đọc các repo có kiểm soát (ví dụ: tải xuống một model từ một job), hãy thêm một danh tính CI/CD trên tài khoản của bạn tại Authentication settings → CI/CD Access thay vì trên một repo cụ thể, sau đó sử dụng username của bạn làm resource.

Trên GitHub Actions, CLI hf sẽ thực hiện quá trình trao đổi cho bạn, chỉ cần đặt HF_OIDC_RESOURCE:

      - name: Download a gated model
        env:
          HF_OIDC_RESOURCE: your-hf-username
        run: hf download acme/gated-model

Trên các nhà cung cấp khác, bạn tự tạo token ID (xem Các nhà cung cấp CI khác) và truyền nó qua HF_OIDC_ID_TOKEN:

# $ID_TOKEN is the OIDC token your provider minted (e.g. $HF_ID_TOKEN on GitLab)
HF_OIDC_ID_TOKEN="$ID_TOKEN" HF_OIDC_RESOURCE="your-hf-username" hf download acme/gated-model

Token kết quả có thể đọc các repo được bảo vệ mà bạn có quyền truy cập và sử dụng giới hạn tần suất (rate limits) của tài khoản bạn. Nó không thể ghi bất kỳ nội dung nào và không thể đọc các repo riêng tư của bạn. Để kéo (pull) một repo riêng tư từ CI, hãy sử dụng repo publisher chỉ đọc thay thế.

Bạn cần chính token (cho curl, git clone, hoặc công cụ đọc HF_TOKEN)? hf auth token thực hiện việc trao đổi và in token có thời hạn ngắn ra stdout:

Đã sao chép

      - name: Get a short-lived HF token
        env:
          HF_OIDC_RESOURCE: your-hf-username  # or a repo, e.g. acme/awesome-model
        run: echo "HF_TOKEN=$(hf auth token)" >> "$GITHUB_ENV"

Cách này hoạt động với cả danh tính CI/CD và nhà xuất bản kho — token được giới hạn phạm vi theo thứ mà HF_OIDC_RESOURCE trỏ đến.

Nhà xuất bản kho chỉ đọc

Mặc định, một trusted publisher của repo sẽ tạo ra các token có thể push vào repo. Nếu workload chỉ cần pull một repo (ví dụ, để tải xuống một model hoặc dataset riêng tư từ một CI job hoặc một nền tảng bên ngoài phát hành token OIDC của riêng nó), hãy đánh dấu Read-only khi thêm publisher. Khi đó, các token được trao đổi sẽ có thể đọc nội dung của repo nhưng không thể ghi vào, và mục nhập sẽ hiển thị huy hiệu Read-only trong danh sách. Cách này hoạt động với models, datasets, Spaces, kernels và buckets.

Bản thân quá trình trao đổi không thay đổi. Chỉ định HF_OIDC_RESOURCE (hoặc resource) đến kho.

    permissions:
      id-token: write  # required so the job can request an OIDC token

    steps:
      - name: Download a private model
        env:
          HF_OIDC_RESOURCE: acme/private-model
        run: hf download acme/private-model

Giống như các cài đặt nhà xuất bản khác, quyền này được cố định khi tạo. Để thay đổi, hãy xóa nhà xuất bản và thêm lại.

Gọi các nhà cung cấp suy luận từ CI

Token từ một danh tính CI/CD mặc định chỉ có quyền đọc. Để cho phép chúng cũng gọi Inference Providers, hãy đánh dấu Allow Inference Providers calls khi thêm danh tính — token được trao đổi sau đó sẽ mang phạm vi inference-api bên cạnh gated-repos, và mục nhập sẽ hiển thị huy hiệu Inference trong danh sách.

Việc sử dụng suy luận sẽ được tính phí vào tài khoản của bạn, giống hệt như khi bạn tự thực hiện các yêu cầu — vì vậy hãy cố định chặt chẽ các yêu sách (repository và branch và/hoặc workflow) trước khi bật tính năng này.

      - name: Run inference from CI
        env:
          HF_OIDC_RESOURCE: your-hf-username
        run: |
          export HF_TOKEN="$(hf auth token)"
          python inference_script.py

Nhà xuất bản kho (Repo publishers) không đủ điều kiện — token của họ có phạm vi kho (repo-scoped) và không thể gọi Inference Providers. Khả năng này được cố định khi tạo; để thay đổi, hãy xóa danh tính và thêm lại.

Nhà cung cấp CI được hỗ trợ

Giao diện cài đặt được cung cấp kèm theo các cấu hình mẫu cho các nhà cung cấp bên dưới, nhưng bất kỳ nhà cung cấp nào tuân thủ OIDC đều hoạt động (AWS, GCP, Buildkite, IdP của bạn, …).

Khi bạn đã có token ID, lệnh gọi trao đổi là giống nhau giữa các nhà cung cấp — chỉ có các claims bạn cấu hình trên phía Hub là khác nhau.

Cách hoạt động

1. Nhà cung cấp CI của bạn tạo ra một OIDC ID token có thời hạn ngắn mô tả công việc (kho nào, nhánh nào, workflow nào, …).
2. Quy trình làm việc của bạn POST token đó đến https://huggingface.co/oauth/token, cùng với một resource (kho hoặc tên người dùng mà nó muốn truy cập).
3. Hub kiểm tra chữ ký và các yêu sách của token đối với các nhà xuất bản mà bạn đã cấu hình cho tài nguyên đó, sau đó trả về một token Hugging Face.

┌──────────┐  1. mint ID token   ┌──────────┐  2. exchange   ┌────────────┐
│ CI job   │ ─────────────────▶  │ CI OIDC  │ ──────────────▶│ huggingface│
│          │                     │ issuer   │                │  /oauth/   │
│          │ ◀──────────────────────────────────────────────│  token     │
└──────────┘        3. short-lived HF token (valid 1 h)      └────────────┘

Tham khảo API

{
  "access_token":      "hf_jwt_…",   // "hf_oauth_…" for user resources
  "token_type":        "bearer",
  "expires_in":        3600,
  "issued_token_type": "urn:ietf:params:oauth:token-type:access_token"
}

Mô hình bảo mật

• Tokens có thời hạn ngắn. 60 phút kể từ thời điểm trao đổi — đồng hồ chỉ bắt đầu chạy khi bạn gọi endpoint, không phải khi workflow bắt đầu. Không có refresh token; các tác vụ dài nên trao đổi lại.
• Token của repo có phạm vi áp dụng cho từng repo. Token cho acme/awesome-model không thể tác động đến acme/anything-else. Các thao tác push được gán cho một người dùng hệ thống tổng hợp [OIDC], kèm theo tham chiếu đến issuer và subject ban đầu. Token từ một publisher chỉ đọc chỉ có thể đọc repo đó.
• Token người dùng chỉ có quyền đọc. Phạm vi gated-repos mặc định — không ghi, không truy cập kho riêng tư, không quản lý tài khoản. Phạm vi tùy chọn inference-api thêm các cuộc gọi Inference Providers (được tính phí vào tài khoản của bạn), nhưng vẫn không có quyền ghi hay truy cập kho riêng tư.
• Các yêu cầu được khớp chính xác, hoặc theo tiền tố khi một cấu hình sẵn có của nhà cung cấp cần đến (cụ thể là workflow_ref của GitHub). Không dùng regex.
• Nhật ký kiểm toán. Việc thêm hoặc xóa một nhà xuất bản sẽ được ghi lại, và các phiên trao đổi thành công sẽ cập nhật thời gian sử dụng gần nhất.

Xem thêm

• Token truy cập người dùng — lựa chọn phù hợp cho con người và các script chạy một lần
• OAuth / Đăng nhập bằng HF — cùng một điểm cuối /oauth/token, được sử dụng cho các luồng tương tác
• Quản lý Spaces bằng GitHub Actions
• Tích hợp GitHub Actions cho Hub