الناشرون الموثوقون

الرفع إلى Hub من CI دون تخزين سر HF_TOKEN.

يثبت وظيفتك في CI هويتها لدى Hugging Face باستخدام رمز OpenID Connect (OIDC) قصير العمر من مزوّد CI الخاص بك، ثم تحصل في المقابل على رمز Hugging Face قصير العمر. لا حاجة إلى تخزين رمز HF كسرّ أو تدويره.

المشترِكون الموثوقون هم نفس فكرة المشترِكين الموثوقين في PyPI والنشر الموثوق في npm.

مثال سريع: نشر نموذج من GitHub Actions

أنت تحافظ على acme/awesome-model على HF Hub وتريد إجراء CI في مستودع acme/awesome-model-training مستضاف خارجيًا (على GitHub أو GitLab أو أي مزوّد متوافق مع OIDC) لدفع نقاط تفتيش جديدة — دون استخدام سر HF_TOKEN.

1. تكوين الناشر الموثوق به على Hub

في https://huggingface.co/acme/awesome-model/settings، افتح Trusted Publishers وأضف:

• المُوفِّر: GitHub Actions
• Claims (يجب أن تتطابق جميع المطالبات حتى تنجح عملية التبادل:
  • repository = acme/awesome-model-training
  • branch = main
  • workflow = publish.yml

repository بمفرده يحدد نطاق الناشر إلى مستودع GitHub. أضف branch و/أو workflow لتثبيته أيضًا على فرع أو ملف سير عمل — يُنصح بذلك.

2. أضِف سير العمل إلى مستودع GitHub الخاص بك

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

هذا كل شيء. على GitHub Actions، يكتشف سطر الأوامر hf (huggingface_hub>=1.19.0) المزوّد، وينفّذ عملية التبادل، ثم يستخدم الرمز الناتج تلقائيًا. عليك فقط ضبط HF_OIDC_RESOURCE.

هل تريد النشر في مستودعات متعددة في تشغيل واحد (مثل نموذج ومجموعة بيانات)؟ اضبط HF_OIDC_RESOURCE لكل خطوة بحيث يكون نطاق كل رمز مخصصًا للمستودع الذي تدفع إليه تلك الخطوة.

مزودو CI آخرون

يُصدر hf CLI رمز المعرّف (ID token) بشكل أصلي على GitHub Actions فقط في الوقت الحالي. أما على GitLab أو CircleCI أو Bitbucket أو أي مزوّد آخر، فقم بإصدار رمز المعرّف بنفسك (انظر مزوّدو CI المدعومون) وقم بتمريره عبر HF_OIDC_ID_TOKEN — حيث يقوم CLI بتبديله مباشرةً:

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

أمثلة عمل كاملة:

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

نوعان: ناشرو المستودعات وهويات CI/CD

تنتهي صلاحية كلا الرمزَين بعد 60 دقيقة. تحتاج إلى دور Write في مستودع Hub لإدارة ناشريه الموثوقين.

الوصول إلى المستودعات المقيدة من CI

إذا كنت بحاجة فقط إلى قراءة المستودعات المقيدة (مثل تنزيل نموذج من مهمة)، أضف هوية CI/CD على حسابك تحت Authentication settings → CI/CD Access بدلاً من إضافتها على مستودع محدد، ثم استخدم اسم المستخدم الخاص بك كمورد.

على GitHub Actions، يقوم سطر الأوامر hf بالتبادل نيابةً عنك، ما عليك سوى تعيين HF_OIDC_RESOURCE:

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

على مزودي الخدمات الآخرين، أنشئ رمز المعرّف بنفسك (انظر مزودو CI الآخرين) وقم بتمريره عبر 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

يمكن للرمز الناتج قراءة المستودعات المُقيَّدة التي تملك صلاحية الوصول إليها، ويستخدم حدود معدل الاستخدام الخاصة بحسابك. وهو لا يمكنه كتابة أي شيء، ولا يمكنه قراءة مستودعاتك الخاصة. لاستخراج مستودع خاص من CI، استخدم ناشر مستودع للقراءة فقط بدلاً من ذلك.

هل تحتاج إلى الرمز نفسه (لـ curl أو git clone أو أداة تقرأ HF_TOKEN)؟ يُجري hf auth token عملية التبادل ويُطبع الرمز قصير العمر إلى stdout:

تم النسخ

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

يعمل هذا مع هويات CI/CD ونشري المستودعات على حد سواء — حيث يكون نطاق الرمز محصورًا بما يشير إليه HF_OIDC_RESOURCE.

ناشرو المستودعات للقراءة فقط

بشكل افتراضي، يصدر ناشر مستودع موثوق رموزاً (tokens) تتيح الدفع (push) إلى المستودع. إذا كان الحمل (workload) بحاجة فقط إلى سحب المستودع (على سبيل المثال، لتنزيل نموذج أو مجموعة بيانات خاصة من مهمة CI أو منصة خارجية تصدر رموز OIDC الخاصة بها)، فعليك تحديد قراءة فقط عند إضافة الناشر. يمكن للرموز المتبادلة بعد ذلك قراءة محتوى المستودع دون القدرة على الكتابة فيه، وتظهر في القائمة شارة قراءة فقط. يعمل هذا مع النماذج ومجموعات البيانات وSpaces والنوى (kernels) والدلاء (buckets).

تبقى عملية التبادل نفسها دون تغيير. وجّه HF_OIDC_RESOURCE (أو resource) إلى المستودع.

    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

مثل إعدادات الناشر الأخرى، يتم تثبيت الإذن عند الإنشاء. لتغييره، احذف الناشر وأضفه مرة أخرى.

استدعاء مزوّدي الاستدلال من CI

تكون الرموز المميزة من هوية CI/CD للقراءة فقط بشكل افتراضي. للسماح لها أيضًا باستدعاء مزودي الاستدلال، قم بتحديد السماح باستدعاءات مزودي الاستدلال عند إضافة الهوية — إذ ستحمل الرموز المميزة المتبادلة نطاق inference-api بالإضافة إلى gated-repos، وستظهر شارة الاستدلال في القائمة.

يتم احتساب رسوم الاستدلال على حسابك تمامًا كما لو كنت قد أرسلت الطلبات بنفسك — لذا ثبّت نطاق المطالبات بدقة (repository و branch و/أو workflow) قبل تفعيله.

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

لا يحق لنشري المستودعات الاستفادة من هذه الميزة — فرموزهم محددة النطاق للمستودع ولا يمكنهم استدعاء مزودي الاستدلال. يتم تحديد هذه القدرة عند الإنشاء؛ ولتغييرها، احذف الهوية وأضِفها مرة أخرى.

مزودو CI المدعومون

تأتي واجهة إعدادات المستخدم مع إعدادات مسبقة المزودين أدناه، لكن أي مزود متوافق مع OIDC يعمل (AWS، GCP، Buildkite، مزود الهوية الخاص بك، ...).

بمجرد حصولك على رمز المعرّف، تكون مكالمة التبادل متطابقة عبر جميع المزودين — والفرق الوحيد هو المطالبات التي تقوم بإعدادها على جانب Hub.

كيف يعمل

1. يُصدر مزوّد CI الخاص بك رمز تعريف OIDC قصير العمر يصف المهمة (أي المستودع، أي الفرع، أي سير العمل، …).
2. يرسل سير عملك ذلك الرمز عبر طلب POST إلى https://huggingface.co/oauth/token، مع تحديد resource (المستودع أو اسم المستخدم الذي يرغب في الوصول إليه).
3. يتحقق المركز من توقيع الرمز والمطالبات الخاصة به مقابل الناشرين الذين قمت بإعدادهم لذلك المورد، ثم يعيد رمز هافينغ فاس.

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

مرجع الواجهة البرمجية

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

نموذج الأمان

• المفاتيح قصيرة العمر. 60 دقيقة من لحظة الاستبدال — يبدأ العدّاد فقط عند استدعاء نقطة النهاية، وليس عند بدء سير العمل. لا يوجد مفتاح تحديث؛ يجب على المهام الطويلة إعادة الاستبدال.
• رموز المستودع محصورة في نطاق المستودع. لا يمكن لرمز acme/awesome-model الوصول إلى acme/anything-else. تُنسب عمليات الدفع إلى مستخدم نظام اصطناعي [OIDC]، مع الإشارة إلى المُصدر والموضوع الأصليين. لا يمكن لرموز الناشر للقراءة فقط سوى قراءة ذلك المستودع.
• رموز المستخدم للقراءة فقط. نطاق gated-repos افتراضيًا — لا كتابة، ولا مستودعات خاصة، ولا إدارة حسابات. يضيف النطاق الاختياري inference-api استدعاءات مزودي الاستدلال (تُحتسب على حسابك)، لكنه لا يزال لا يمنح صلاحية الكتابة أو الوصول إلى المستودعات الخاصة.
• تُطابَق المطالبات بشكلٍ تام، أو عبر البادئة عندما يتطلب ذلك إعداد مُقدِّم مُسبق (حقل workflow_ref في GitHub). لا تُستخدم تعبيرات منتظمة.
• سجلات التدقيق. يتم تسجيل إضافة ناشر أو إزالته، وتحديث وقت آخر استخدام عند نجاح التبادلات.

انظر أيضاً

• رموز وصول المستخدم — الخيار الصحيح للبشر والسكربتات ذات الاستخدام الواحد
• OAuth / تسجيل الدخول عبر HF — نفس نقطة النهاية /oauth/token، تُستخدم للتدفقات التفاعلية
• إدارة المساحات باستخدام GitHub Actions
• تكامل GitHub Actions مع Hub