Hugging Face (الاستدلال)

توفّر Hugging Face Inference Providers موجّهًا لإكمالات المحادثة متوافقًا مع OpenAI أمام العديد من النماذج المستضافة (DeepSeek وLlama وغيرها) باستخدام رمز مميز واحد. يتواصل OpenClaw مع نقطة نهاية إكمالات المحادثة فقط؛ ولتحويل النص إلى صورة أو إنشاء التضمينات أو معالجة الكلام، استخدم عملاء استدلال HF مباشرةً.

الخاصية	القيمة
معرّف المزوّد	`huggingface`
Plugin	مضمّن (مفعّل افتراضيًا، ولا يتطلب خطوة تثبيت)
متغير بيئة المصادقة	`HUGGINGFACE_HUB_TOKEN` أو `HF_TOKEN` (رمز مميز دقيق الصلاحيات)
API	متوافقة مع OpenAI (`https://router.huggingface.co/v1`)
الفوترة	رمز HF مميز واحد؛ يتبع التسعير أسعار المزوّد مع فئة مجانية

بدء الاستخدام

إنشاء رمز مميز دقيق الصلاحيات

انتقل إلى Hugging Face Settings Tokens وأنشئ رمزًا مميزًا جديدًا دقيق الصلاحيات.

يجب تمكين صلاحية Make calls to Inference Providers للرمز المميز، وإلا فستُرفض طلبات API.

تشغيل الإعداد الأولي

اختر Hugging Face من القائمة المنسدلة للمزوّد، ثم أدخل مفتاح API عند مطالبتك بذلك:

openclaw onboard --auth-choice huggingface-api-key

اختيار نموذج افتراضي

من القائمة المنسدلة نموذج Hugging Face الافتراضي، اختر نموذجًا. تُحمّل القائمة من API الاستدلال عندما يكون رمزك المميز صالحًا؛ وإلا يعرض OpenClaw الكتالوج المضمّن أدناه. يُحفظ اختيارك في agents.defaults.model.primary:

{
  agents: {
    defaults: {
      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
    },
  },
}

التحقق من توفر النموذج

openclaw models list --provider huggingface

الإعداد غير التفاعلي

openclaw onboard --non-interactive \
  --mode local \
  --auth-choice huggingface-api-key \
  --huggingface-api-key "$HF_TOKEN"

يضبط huggingface/deepseek-ai/DeepSeek-R1 بوصفه النموذج الافتراضي.

معرّفات النماذج

تستخدم مراجع النماذج الصيغة huggingface/<org>/<model> (معرّفات بنمط Hub). كتالوج OpenClaw المضمّن:

النموذج	المرجع (مع إضافة السابقة `huggingface/`)
DeepSeek R1	`deepseek-ai/DeepSeek-R1`
DeepSeek V3.1	`deepseek-ai/DeepSeek-V3.1`
GPT-OSS 120B	`openai/gpt-oss-120b`
Llama 3.3 70B Instruct Turbo	`meta-llama/Llama-3.3-70B-Instruct-Turbo`

عندما يكون رمزك المميز صالحًا، يكتشف OpenClaw أيضًا أي نموذج آخر عبر GET https://router.huggingface.co/v1/models أثناء الإعداد الأولي وعند بدء تشغيل Gateway، ولذلك يمكن أن يتضمن كتالوجك عددًا أكبر بكثير من النماذج الأربعة المذكورة أعلاه. يمكنك إلحاق :fastest أو :cheapest بأي معرّف نموذج؛ ويوجّه موجّه HF الطلب إلى مزوّد الاستدلال المطابق. اضبط ترتيب المزوّدين الافتراضي في إعدادات مزوّدي الاستدلال.

الإعداد المتقدم

اكتشاف النماذج والقائمة المنسدلة للإعداد الأولي

يكتشف OpenClaw النماذج باستخدام:

GET https://router.huggingface.co/v1/models
Authorization: Bearer $HUGGINGFACE_HUB_TOKEN   # or $HF_TOKEN

تأتي الاستجابة بنمط OpenAI: { "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }.عند وجود مفتاح مُعدّ (من الإعداد الأولي أو HUGGINGFACE_HUB_TOKEN أو HF_TOKEN)، تُملأ القائمة المنسدلة نموذج Hugging Face الافتراضي أثناء الإعداد التفاعلي من نقطة النهاية هذه. يكرر بدء تشغيل Gateway الاستدعاء نفسه لتحديث الكتالوج. تُدمج النماذج المكتشفة مع الكتالوج المضمّن أعلاه (الذي يُستخدم للبيانات الوصفية مثل نافذة السياق والتكلفة عند تطابق المعرّف). إذا فشل الطلب أو لم يُرجع بيانات أو لم يُضبط مفتاح، يعود OpenClaw إلى الكتالوج المضمّن فقط.عطّل الاكتشاف دون إزالة المزوّد:

openclaw config set plugins.entries.huggingface.config.discovery.enabled false

أسماء النماذج والأسماء المستعارة ولواحق السياسات

الاسم من API: تستخدم النماذج المكتشفة قيم name أو title أو display_name من API عند توفرها؛ وإلا يشتق OpenClaw اسمًا من معرّف النموذج (مثلًا، يتحول deepseek-ai/DeepSeek-R1 إلى “DeepSeek R1”).
تجاوز اسم العرض: اضبط تسمية مخصصة لكل نموذج في الإعداد:

{
  agents: {
    defaults: {
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },
        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },
      },
    },
  },
}

لواحق السياسات: تمثل :fastest و:cheapest اصطلاحات لموجّه HF، وليستا شيئًا يعيد OpenClaw كتابته: تُرسل اللاحقة حرفيًا كجزء من معرّف النموذج، ويختار موجّه HF مزوّد الاستدلال المطابق. أضف كل متغير بوصفه إدخالًا مستقلًا ضمن models.providers.huggingface.models (أو في model.primary) إذا كنت تريد اسمًا مستعارًا مميزًا لكل لاحقة.
دمج الإعداد: يُحتفظ بالإدخالات الموجودة في models.providers.huggingface.models (مثلًا في models.json) عند دمج الإعداد، ولذلك تستمر أي قيم مخصصة لـname أو alias أو خيارات النموذج التي تضبطها هناك بعد إعادة التشغيل.

إعداد البيئة والبرنامج الخدمي

إذا كان Gateway يعمل بوصفه برنامجًا خدميًا (launchd/systemd)، فتأكد من إتاحة HUGGINGFACE_HUB_TOKEN أو HF_TOKEN لتلك العملية (مثلًا في ~/.openclaw/.env أو عبر env.shellEnv).

يقبل OpenClaw كلًا من HUGGINGFACE_HUB_TOKEN وHF_TOKEN. إذا ضُبط كلاهما، تكون الأولوية لـHUGGINGFACE_HUB_TOKEN.

الإعداد: DeepSeek R1 مع نموذج احتياطي

{
  agents: {
    defaults: {
      model: {
        primary: "huggingface/deepseek-ai/DeepSeek-R1",
        fallbacks: ["huggingface/openai/gpt-oss-120b"],
      },
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" },
        "huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" },
      },
    },
  },
}

الإعداد: DeepSeek بمتغيرَي الأقل تكلفة والأسرع

{
  agents: {
    defaults: {
      model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
      models: {
        "huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" },
        "huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheapest)" },
        "huggingface/deepseek-ai/DeepSeek-R1:fastest": { alias: "DeepSeek R1 (fastest)" },
      },
    },
  },
}

الإعداد: DeepSeek وLlama وGPT-OSS بأسماء مستعارة

{
  agents: {
    defaults: {
      model: {
        primary: "huggingface/deepseek-ai/DeepSeek-V3.1",
        fallbacks: [
          "huggingface/meta-llama/Llama-3.3-70B-Instruct-Turbo",
          "huggingface/openai/gpt-oss-120b",
        ],
      },
      models: {
        "huggingface/deepseek-ai/DeepSeek-V3.1": { alias: "DeepSeek V3.1" },
        "huggingface/meta-llama/Llama-3.3-70B-Instruct-Turbo": { alias: "Llama 3.3 70B Turbo" },
        "huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" },
      },
    },
  },
}

ذو صلة

اختيار النموذج

نظرة عامة على جميع المزوّدين ومراجع النماذج وسلوك تجاوز الأعطال.

اختيار النموذج

كيفية اختيار النماذج وإعدادها.

وثائق مزوّدي الاستدلال

الوثائق الرسمية لـHugging Face Inference Providers.

الإعداد

مرجع الإعداد الكامل.

Overview

Concepts and configuration

Providers

Hugging Face (الاستدلال)

بدء الاستخدام

الإعداد غير التفاعلي

معرّفات النماذج

الإعداد المتقدم

ذو صلة

اختيار النموذج

اختيار النموذج

وثائق مزوّدي الاستدلال

الإعداد

​بدء الاستخدام

​الإعداد غير التفاعلي

​معرّفات النماذج

​الإعداد المتقدم

​ذو صلة

اختيار النموذج

اختيار النموذج

وثائق مزوّدي الاستدلال

الإعداد

بدء الاستخدام

الإعداد غير التفاعلي

معرّفات النماذج

الإعداد المتقدم

ذو صلة