Güvenilir Yayıncılar

Bir HF_TOKEN gizli anahtarı saklamadan CI'den Hub'a gönderin.

CI işiniz, kimliğini Hugging Face'e CI sağlayıcınızdan alınan kısa ömürlü bir OpenID Connect (OIDC) jetonu ile kanıtlar ve karşılığında kısa ömürlü bir Hugging Face jetonu alır. Gizli olarak saklanması veya döndürülmesi gereken bir HF jetonu yoktur.

Trusted Publishers, PyPI'nin Trusted Publishers ve npm'in Trusted Publishing kavramlarıyla aynı fikirdir.

Hızlı örnek: GitHub Actions'tan bir model yayımlama

HF Hub üzerinde acme/awesome-model modelini yönetiyorsunuz ve harici bir acme/awesome-model-training deposunda (GitHub, GitLab veya herhangi bir OIDC uyumlu sağlayıcıda) CI ile yeni checkpoint’leri itmek istiyorsunuz — HF_TOKEN gizli anahtarı olmadan.

1. Hub'da güvenilir yayıncıyı yapılandırın

https://huggingface.co/acme/awesome-model/settings adresinde Güvenilir Yayıncılar bölümünü açın ve şunu ekleyin:

• Sağlayıcı: GitHub Actions
• Claims (tümünün değişimin başarılı olması için eşleşmesi gerekir:
  • repository = acme/awesome-model-training
  • branch = main
  • workflow = publish.yml

repository tek başına yayıncıyı bir GitHub deposuna daraltır. Onu bir dal veya iş akışı dosyasına da sabitlemek için branch ve/veya workflow ekleyin — önerilir.

2. İş akışını GitHub deponuza ekleyin

.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}"

Bu kadar. GitHub Actions üzerinde hf CLI (huggingface_hub>=1.19.0) sağlayıcıyı algılar, değişimi gerçekleştirir ve oluşan token’ı otomatik olarak kullanır. Sadece HF_OIDC_RESOURCE değerini ayarlarsınız.

Tek bir çalıştırmada birden fazla repoya yayınlama (ör. bir model ve bir veri seti)? Her adımın gönderdiği repoya göre token'ın kapsamını belirlemek için HF_OIDC_RESOURCE değerini adım başına ayarlayın.

Diğer CI sağlayıcıları

hf CLI şu an için ID token'ı yalnızca GitHub Actions üzerinde yerel olarak oluşturur. GitLab, CircleCI, Bitbucket veya başka bir sağlayıcıda ID token'ı kendiniz oluşturun (Desteklenen CI sağlayıcıları bkz.) ve HF_OIDC_ID_TOKEN üzerinden iletin — CLI bunu doğrudan takas eder:

# 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 .

Çalışan tam örnekler:

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

İki tür: depo yayıncıları ve CI/CD kimlikleri

Her iki jeton da 60 dakika sonra sona erer. Bir Hub deposunun güvenilir yayıncılarını yönetmek için Write rolüne sahip olmanız gerekir.

CI'den gated depolara erişim

Eğer yalnızca gated depoları okumanız gerekiyorsa (ör. bir işten model indirmek), belirli bir depo yerine hesabınızda Authentication settings → CI/CD Access altında bir CI/CD kimliği ekleyin ve kaynağınız olarak kullanıcı adınızı kullanın.

GitHub Actions üzerinde hf CLI bu değişimi sizin için yapar, yalnızca HF_OIDC_RESOURCE değerini ayarlayın:

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

diğer sağlayıcılarda, kimlik belirtecini kendiniz oluşturun (Diğer CI sağlayıcıları bölümüne bakın) ve HF_OIDC_ID_TOKEN üzerinden iletin:

# $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

Oluşturulan jeton, erişiminiz olan gated depoları okuyabilir ve hesabınızın hız sınırlarını kullanır. Hiçbir şey yazamaz ve özel depolarınızı okuyamaz. CI'dan özel bir depo çekmek için bunun yerine sadece okunur depo yayıncısı kullanın.

Kendisi token'a mı ihtiyacınız var (curl, git clone veya HF_TOKEN okuyan bir araç için)? hf auth token değişimi gerçekleştirir ve kısa ömürlü token'ı stdout'a basar:

Kopyalandı

      - 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"

Bu, hem CI/CD kimlikleri hem de depo yayıncıları ile çalışır — jeton, HF_OIDC_RESOURCE'in işaret ettiği kaynağa göre kapsamlandırılır.

Salt okunur depo yayıncıları

Varsayılan olarak, bir depo güvenilir yayıncısı, depoya itme (push) yapabilecek jetonlar basar. Bir iş yükü yalnızca bir depoyu çekmek (pull) gerekiyorsa (örneğin, bir CI işinden veya kendi OIDC jetonlarını veren harici bir platformdan özel bir model veya veri seti indirmek için), yayıncıyı eklerken Sadece okunur seçeneğini işaretleyin. Değiştirilen jetonlar bu durumda depodaki içeriği okuyabilir ancak yazamaz ve listede girişin yanında Sadece okunur rozeti görünür. Bu, modeller, veri setleri, Spaces, çekirdekler ve varlık kovaları (buckets) için geçerlidir.

Değiş tokuşun kendisi değişmemiştir. HF_OIDC_RESOURCE'u (veya resource'i) depoya yönlendirin.

    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

Diğer yayıncı ayarları gibi, izin oluşturulma anında sabitlenir. Değiştirmek için yayıncıyı silip yeniden ekleyin.

CI'den Inference Providers'ı Çağırma

CI/CD kimliğinden gelen jetonlar varsayılan olarak salt okunurdur. Bunların Inference Providers çağrılarını da yapmasına izin vermek için, kimliği eklerken Inference Providers çağrılarını etkinleştir seçeneğini işaretleyin — bu durumda değiştirilen jetonlar, gated-repos ek olarak inference-api kapsamını taşır ve listede girişin yanında Inference rozeti görünür.

Çalıştırma kullanımı, istekleri kendiniz yapmış gibi hesabınıza faturalandırılır — bu nedenle etkinleştirmeden önce iddiaları sıkıca sabitleyin (repository ve branch ve/veya workflow).

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

Repo yayıncıları uygun değildir — jetonları repo kapsamındadır ve Inference Providers'ı çağıramazlar. Bu yetenek oluşturulma anında sabitlenir; değiştirmek için kimliği silip yeniden ekleyin.

Desteklenen CI sağlayıcıları

Ayarlar arayüzü, aşağıdaki sağlayıcılar için hazır ayarlarla birlikte gelir, ancak herhangi bir OIDC uyumlu sağlayıcı çalışır (AWS, GCP, Buildkite, kendi IdP'niz, …).

ID token'ına sahip olduğunuzda, değişim çağrısı tüm sağlayıcılar arasında aynıdır — yalnızca Hub tarafında yapılandırdığınız claims farklıdır.

Nasıl çalışır

1. CI sağlayıcınız, işi (hangi depo, hangi dal, hangi iş akışı, …) tanımlayan kısa ömürlü bir OIDC ID token oluşturur.
2. İş akışınız, o jetonu resource (erişmek istediği depo veya kullanıcı adı) ile birlikte https://huggingface.co/oauth/token adresine POST olarak gönderir.
3. Hub, belirtecin imzasını ve iddialarını, o kaynak için yapılandırdığınız yayıncılarla karşılaştırır ve bir Hugging Face belirteci döndürür.

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

API referansı

{
  "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"
}

Güvenlik modeli

• Tokenler kısa ömürlüdür. Değişim anından itibaren 60 dakika — saat, iş akışının başladığında değil, uç noktayı çağırdığınızda başlar. Yenileme tokenı yoktur; uzun süren işler yeniden değişim yapmalıdır.
• Depo jetonları depo kapsamındadır. acme/awesome-model için bir jeton, acme/anything-else üzerinde işlem yapamaz. Push işlemleri, kaynak sağlayıcıya ve konuya atıfta bulunan sentetik bir [OIDC] sistem kullanıcısına atfedilir. Salt okunur bir yayıncıdan gelen jetonlar yalnızca o depoyu okuyabilir.
• Kullanıcı jetonları salt okunurdur. Varsayılan olarak gated-repos kapsamı — yazma, özel depolar veya hesap yönetimi yoktur. İsteğe bağlı inference-api kapsamı Inference Providers çağrılarını ekler (hesabınıza faturalandırılır), ancak yine de yazma veya özel depo erişimi yoktur.
• Bildirimler tam eşleşmeyle veya bir sağlayıcı ön ayarının gerektirdiği durumlarda önek eşleşmesiyle karşılaştırılır (GitHub'ın workflow_ref'i). Düzenli ifade kullanılmaz.
• Denetim kayıtları. Bir yayıncının eklenmesi veya kaldırılması kaydedilir ve başarılı işlemler son kullanım zamanını günceller.

Bkz.

• Kullanıcı Erişim Belirteçleri — insanlar ve tek seferlik betikler için doğru seçim
• OAuth / HF ile oturum açma — etkileşimli akışlar için kullanılan aynı /oauth/token uç noktası
• GitHub Actions ile Spaces Yönetimi
• Hub için GitHub Actions entegrasyonu