Hub Python Library documentation

تشغيل الاستدلال على الخوادم

Hub Python Library

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

تشغيل الاستدلال على الخوادم

الاستدلال هو عملية استخدام نموذج مدرَّب لإجراء تنبؤات على بيانات جديدة. وبما أن هذه العملية قد تكون كثيفة الحساب، فإن التشغيل على خدمة مخصصة أو خارجية قد يكون خيارًا مثيرًا للاهتمام. توفر مكتبة huggingface_hub واجهة موحدة لتشغيل الاستدلال عبر خدمات متعددة للنماذج المستضافة على Hugging Face Hub:

مزودو الاستدلال: وصول موحّد ومبسّط إلى مئات نماذج تعلّم الآلة، مدعومًا بشركائنا في الاستدلال الخادمي. يستند هذا النهج الجديد إلى واجهة برمجة تطبيقات الاستدلال الخادمي السابقة لدينا، ويوفر نماذج أكثر، وأداءً محسّنًا، وموثوقية أكبر بفضل مزودين من الطراز العالمي. راجع التوثيق للحصول على قائمة بالمزودين المدعومين.
نقاط الاستدلال: منتجٌ لتسهيل نشر النماذج في بيئة الإنتاج. يتم تشغيل الاستدلال بواسطة Hugging Face على بنية تحتية مخصصة ومُدارة بالكامل لدى مزوّد الخدمات السحابية الذي تختاره.
نقاط النهاية المحلية: يمكنك أيضًا تشغيل الاستدلال باستخدام خوادم الاستدلال المحلية مثل llama.cpp وOllama وvLLM وLiteLLM أو Text Generation Inference (TGI) عن طريق توصيل العميل بهذه النقاط النهاية المحلية.

InferenceClient هو عميل بلغة بايثون يقوم بإجراء استدعاءات HTTP إلى واجهات برمجة التطبيقات الخاصة بنا. إذا كنت ترغب في إجراء استدعاءات HTTP مباشرةً باستخدام الأداة التي تفضلها (curl، postman، …)، فيرجى الرجوع إلى توثيق Inference Providers أو إلى صفحات توثيق Inference Endpoints.

لتطوير الويب، تم إصدار عميل JS. إذا كنت مهتمًا بتطوير الألعاب، فقد ترغب في الاطلاع على مشروع C# الخاص بنا.

البدء

لنبدأ بمهمة تحويل النص إلى صورة:

>>> from huggingface_hub import InferenceClient

# Example with an external provider (e.g. replicate)
>>> replicate_client = InferenceClient(
    provider="replicate",
    api_key="my_replicate_api_key",
)
>>> replicate_image = replicate_client.text_to_image(
    "A flying car crossing a futuristic cityscape.",
    model="black-forest-labs/FLUX.1-schnell",
)
>>> replicate_image.save("flying_car.png")

في المثال أعلاه، قمنا بتهيئة InferenceClient مع مزوّد طرف ثالث، وهو Replicate. عند استخدام مزوّد، يجب تحديد النموذج الذي تريد استخدامه. يجب أن يكون معرّف النموذج هو معرّف النموذج على Hugging Face Hub، وليس معرّف النموذج من مزوّد الطرف الثالث. في مثالنا، قمنا بتوليد صورة من موجه نصي. القيمة المُعادَة هي كائن PIL.Image يمكن حفظه في ملف. لمزيد من التفاصيل، راجع وثائق text_to_image().

لننظر الآن إلى مثال يستخدم واجهة chat_completion(). تستخدم هذه المهمة نموذج LLM لتوليد رد من قائمة رسائل:

>>> from huggingface_hub import InferenceClient
>>> messages = [
    {
        "role": "user",
        "content": "What is the capital of France?",
    }
]
>>> client = InferenceClient(
    provider="together",
    model="meta-llama/Meta-Llama-3-8B-Instruct",
    api_key="my_together_api_key",
)
>>> client.chat_completion(messages, max_tokens=100)
ChatCompletionOutput(
    choices=[
        ChatCompletionOutputComplete(
            finish_reason="eos_token",
            index=0,
            message=ChatCompletionOutputMessage(
                role="assistant", content="The capital of France is Paris.", name=None, tool_calls=None
            ),
            logprobs=None,
        )
    ],
    created=1719907176,
    id="",
    model="meta-llama/Meta-Llama-3-8B-Instruct",
    object="text_completion",
    system_fingerprint="2.0.4-sha-f426a33",
    usage=ChatCompletionOutputUsage(completion_tokens=8, prompt_tokens=17, total_tokens=25),
)

في المثال أعلاه، استخدمنا مزوداً من طرف ثالث (Together AI) وحددنا النموذج الذي نرغب في استخدامه ("meta-llama/Meta-Llama-3-8B-Instruct"). ثم قدمنا قائمة بالرسائل التي يجب إكمالها (وهنا سؤال واحد) وقدمنا معاملاً إضافياً إلى واجهة برمجة التطبيقات (max_token=100). المخرجات هي كائن ChatCompletionOutput يتبع مواصفة OpenAI. يمكن الوصول إلى المحتوى المولّد عبر output.choices[0].message.content. لمزيد من التفاصيل، راجع وثائق chat_completion().

صُمِّم واجهة برمجة التطبيقات (API) لتكون بسيطة. لا تتوفر جميع المعاملات والخيارات ولا تُوصف للمستخدم النهائي. اطّلع على هذه الصفحة إذا كنت مهتمًا بمعرفة المزيد عن جميع المعاملات المتاحة لكل مهمة.

استخدام مزوّد محدد

إذا كنت ترغب في استخدام مزوّد معيّن، يمكنك تحديده عند تهيئة العميل. القيمة الافتراضية هي “auto” والتي ستختار أول مزوّد متاح للنموذج، مرتّبةً حسب ترتيب المستخدم في https://hf.co/settings/inference-providers. راجع قسم المزوّدون والمهام المدعومة للحصول على قائمة بالمزوّدين المدعومين.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(provider="replicate", api_key="my_replicate_api_key")

استخدام نموذج محدد

ماذا لو أردت استخدام نموذج محدد؟ يمكنك تحديده إما كـparameter أو مباشرة على مستوى الكائن:

>>> from huggingface_hub import InferenceClient
# Initialize client for a specific model
>>> client = InferenceClient(provider="together", model="meta-llama/Llama-3.1-8B-Instruct")
>>> client.text_to_image(...)
# Or use a generic client but pass your model as an argument
>>> client = InferenceClient(provider="together")
>>> client.text_to_image(..., model="meta-llama/Llama-3.1-8B-Instruct")

عند استخدام مزوّد “hf-inference”， يأتي كل مهمة مع نموذج موصى به من بين أكثر من مليون نموذج متاح على Hub. ومع ذلك، قد يتغير هذا التوصية مع مرور الوقت، لذا يُفضّل تحديد نموذج بشكل صريح بعد أن تقرر أي نموذج ستستخدم. بالنسبة لمزوّدي الطرف الثالث، يجب عليك دائمًا تحديد نموذج متوافق مع ذلك المزوّد.

قم بزيارة صفحة النماذج على Hub لاستكشاف النماذج المتاحة من خلال مزودي الاستدلال.

استخدام نقاط الاستدلال

استخدمت الأمثلة التي رأيناها أعلاه مزودي الاستدلال. وعلى الرغم من أن هذه المزودين يثبتون فائدتهم الكبيرة في بناء النماذج الأولية واختبار الأمور بسرعة، إلا أنه عند استعدادك لنشر نموذجك في بيئة الإنتاج، ستحتاج إلى استخدام بنية تحتية مخصصة. وهنا يأتي دور نقاط نهاية الاستدلال. فهي تتيح لك نشر أي نموذج وعرضه كواجهة برمجة تطبيقات خاصة. بمجرد النشر، ستحصل على عنوان URL يمكنك الاتصال به باستخدام نفس الكود تماماً كما كان من قبل، مع تغيير معامل model فقط:

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(model="https://uu149rez6gw9ehej.eu-west-1.aws.endpoints.huggingface.cloud/deepfloyd-if")
# or
>>> client = InferenceClient()
>>> client.text_to_image(..., model="https://uu149rez6gw9ehej.eu-west-1.aws.endpoints.huggingface.cloud/deepfloyd-if")

لاحظ أنه لا يمكنك تحديد عنوان URL ومزوّد في الوقت نفسه - فهما متنافيان. تُستخدم عناوين URL للاتصال المباشر بنقاط النهاية المُنفَّذة.

استخدام نقاط النهاية المحلية

يمكنك استخدام InferenceClient لتنفيذ إكمال المحادثة مع خوادم الاستدلال المحلية (llama.cpp، vllm، litellm server، TGI، mlx، إلخ) التي تعمل على جهازك. يجب أن تكون واجهة برمجة التطبيقات متوافقة مع OpenAI API.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(model="http://localhost:8080")

>>> response = client.chat.completions.create(
...     messages=[
...         {"role": "user", "content": "What is the capital of France?"}
...     ],
...     max_tokens=100
... )
>>> print(response.choices[0].message.content)

وبنفس الطريقة التي يعمل بها عميل OpenAI المكتوب بلغة بايثون، يمكن استخدام InferenceClient لتنفيذ استدلال إكمال المحادثة مع أي نقطة نهاية متوافقة مع واجهة برمجة تطبيقات OpenAI REST.

المصادقة

يمكن تنفيذ المصادقة بطريقتين:

يتم توجيهه عبر Hugging Face : استخدم Hugging Face كوسيط للوصول إلى مزودي الخدمات من أطراف ثالثة. سيتم توجيه الطلبات عبر بنية Hugging Face التحتية باستخدام مفاتيح مزودي خدماتنا، وسيتم احتساب الاستخدام مباشرةً على حساب Hugging Face الخاص بك.

يمكنك المصادقة باستخدام رمز وصول المستخدم. يمكنك تقديم رمز Hugging Face الخاص بك مباشرةً باستخدام معامل api_key:

>>> client = InferenceClient(
    provider="replicate",
    api_key="hf_****"  # Your HF token
)

إذا لم تَمرّر api_key، فسيحاول العميل العثور على رمز محفوظ محلياً على جهازك واستخدامه. يحدث هذا عادةً إذا كنت قد سجّلت الدخول سابقاً. راجع دليل المصادقة لمعرفة التفاصيل حول تسجيل الدخول.

>>> client = InferenceClient(
    provider="replicate",
    token="hf_****"  # Your HF token
)

الوصول المباشر إلى المزوّد: استخدم مفتاح API الخاص بك للتفاعل مباشرةً مع خدمة المزوّد:

>>> client = InferenceClient(
    provider="replicate",
    api_key="r8_****"  # Your Replicate API key
)

لمزيد من التفاصيل، راجع توثيق أسعار مزودي الاستدلال.

الموفّرون والمهام المدعومة

يهدف InferenceClient إلى توفير أسهل واجهة لتشغيل الاستدلال على نماذج Hugging Face، على أي مزوّد. فهو يملك واجهة برمجة تطبيقات بسيطة تدعم أكثر المهام شيوعًا. وفيما يلي جدول يُظهر المهام التي يدعمها كل مزوّد:

المهمة	Baseten	Cerebras	Cohere	DeepInfra	fal-ai	Featherless AI	Fireworks AI	Groq	HF Inference	نوڤيتا AI	Nscale	OVHcloud AI Endpoints	الذكاء الاصطناعي العام	استنساخ	Scaleway	معًا	Wavespeed	Zai
audio_classification()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
audio_to_audio()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
automatic_speech_recognition()	❌	❌	❌	✅	✅	❌	❌	❌	✅	❌	❌	❌	❌	✅	❌	❌	❌	❌
chat_completion()	✅	✅	✅	✅	❌	✅	✅	✅	✅	✅	✅	✅	✅	❌	✅	✅	❌	✅
document_question_answering()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
feature_extraction()	❌	❌	❌	✅	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	✅	✅	❌	❌
fill_mask()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
image_classification()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
image_segmentation()	❌	❌	❌	❌	✅	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
image_to_image()	❌	❌	❌	❌	✅	❌	❌	❌	✅	❌	❌	❌	❌	✅	❌	✅	✅	❌
image_to_video()	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌	❌	✅	✅	❌
image_to_text()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
object_detection()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
question_answering()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
sentence_similarity()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
summarization()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
table_question_answering()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
text_classification()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
text_generation()	❌	❌	❌	✅	❌	✅	❌	❌	✅	✅	❌	❌	❌	❌	❌	✅	❌	❌
text_to_image()	❌	❌	❌	❌	✅	❌	❌	❌	✅	❌	✅	❌	❌	✅	❌	✅	✅	✅
text_to_speech()	❌	❌	❌	✅	✅	❌	❌	❌	✅	❌	❌	❌	❌	✅	❌	✅	❌	❌
text_to_video()	❌	❌	❌	❌	✅	❌	❌	❌	❌	✅	❌	❌	❌	✅	❌	✅	✅	❌
tabular_classification()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
tabular_regression()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
token_classification()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
translation()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
visual_question_answering()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
zero_shot_image_classification()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌
zero_shot_classification()	❌	❌	❌	❌	❌	❌	❌	❌	✅	❌	❌	❌	❌	❌	❌	❌	❌	❌

اطّلع على صفحة المهام لمعرفة المزيد حول كل مهمة.

التوافق مع OpenAI

يتبع مهمة chat_completion صياغة عميل Python الخاص بـ OpenAI. ماذا يعني ذلك بالنسبة لك؟ يعني أنه إذا كنت معتادًا على التعامل مع واجهات برمجة التطبيقات الخاصة بـ OpenAI، فستتمكن من الانتقال إلى huggingface_hub.InferenceClient للعمل مع نماذج مفتوحة المصدر من خلال تحديث سطرَي كود فقط!

- from openai import OpenAI
+ from huggingface_hub import InferenceClient

- client = OpenAI(
+ client = InferenceClient(
    base_url=...,
    api_key=...,
)


output = client.chat.completions.create(
    model="meta-llama/Meta-Llama-3-8B-Instruct",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Count to 10"},
    ],
    stream=True,
    max_tokens=1024,
)

for chunk in output:
    print(chunk.choices[0].delta.content)

وهذا كل ما في الأمر! التغييرات المطلوبة الوحيدة هي استبدال from openai import OpenAI بـ from huggingface_hub import InferenceClient واستبدال client = OpenAI(...) بـ client = InferenceClient(...). يمكنك اختيار أي نموذج LLM من Hugging Face Hub عن طريق تمرير معرّف النموذج الخاص به كـ model معامل. إليك قائمة بالنماذج المدعومة. للمصادقة، يجب عليك تمرير User Access Token صالح كـ api_key أو المصادقة باستخدام huggingface_hub (انظر دليل المصادقة).

جميع معاملات الإدخال وتنسيق المخرجات متطابقان تمامًا. على وجه الخصوص، يمكنك تمرير stream=True لاستلام الرموز (tokens) أثناء توليدها. كما يمكنك استخدام AsyncInferenceClient لتنفيذ الاستدلال باستخدام asyncio:

import asyncio
- from openai import AsyncOpenAI
+ from huggingface_hub import AsyncInferenceClient

- client = AsyncOpenAI()
+ client = AsyncInferenceClient()

async def main():
    stream = await client.chat.completions.create(
        model="meta-llama/Meta-Llama-3-8B-Instruct",
        messages=[{"role": "user", "content": "Say this is a test"}],
        stream=True,
    )
    async for chunk in stream:
        print(chunk.choices[0].delta.content or "", end="")

asyncio.run(main())

قد تتساءل عن سبب استخدام InferenceClient بدلاً من عميل OpenAI؟ هناك عدة أسباب لذلك:

يتم تكوين InferenceClient لخدمات Hugging Face. لا تحتاج إلى تقديم base_url لتشغيل النماذج مع مزودي الاستدلال. كما لا تحتاج إلى تقديم token أو api_key إذا كان جهازك مسجلاً الدخول بشكل صحيح بالفعل.
InferenceClient مصمَّم خصيصًا لكلٍّ من إطارَي Text-Generation-Inference (TGI) وtransformers، مما يضمن لك أنه سيكون دائمًا على قدم المساواة مع أحدث التحديثات.
يتم دمج InferenceClient مع خدمة Inference Endpoints لدينا، مما يسهّل إطلاق نقطة استنتاج، والتحقق من حالتها، وتنفيذ الاستنتاج عليها. راجع دليل Inference Endpoints لمزيد من التفاصيل.

InferenceClient.chat.completions.create هو ببساطة اسم مستعار لـ InferenceClient.chat_completion. راجع مرجع الحزمة الخاص بـ chat_completion() لمزيد من التفاصيل. ومعاملات base_url و api_key عند إنشاء العميل هي أيضاً أسماء مستعارة لـ model و token. تم تعريف هذه الأسماء المستعارة لتقليل التعقيد عند الانتقال من OpenAI إلى InferenceClient.

استدعاء الدوال

يتيح استدعاء الدوال لنماذج اللغة الكبيرة (LLMs) التفاعل مع أدوات خارجية، مثل الدوال أو واجهات برمجة التطبيقات (APIs) المحددة. وهذا يمكّن المستخدمين من بناء تطبيقات مصممة خصيصًا لتطبيقات محددة ومهام واقعية بسهولة. InferenceClient يطبق نفس واجهة استدعاء الأدوات كما في OpenAI Chat Completions API. فيما يلي مثال بسيط لاستدعاء الأدوات باستخدام Novita كمزود للاستدلال:

from huggingface_hub import InferenceClient

tools = [
        {
            "type": "function",
            "function": {
                "name": "get_weather",
                "description": "Get current temperature for a given location.",
                "parameters": {
                    "type": "object",
                    "properties": {
                        "location": {
                            "type": "string",
                            "description": "City and country e.g. Paris, France"
                        }
                    },
                    "required": ["location"],
                },
            }
        }
]

client = InferenceClient(provider="novita")

response = client.chat.completions.create(
    model="Qwen/Qwen2.5-72B-Instruct",
    messages=[
    {
        "role": "user",
        "content": "What's the weather like the next 3 days in London, UK?"
    }
    ],
    tools=tools,
    tool_choice="auto",
)

print(response.choices[0].message.tool_calls[0].function.arguments)

يرجى الرجوع إلى توثيق المزودين للتحقق من النماذج التي يدعمونها لاستدعاء الدوال/الأدوات.

المخرجات المهيكلة & وضع JSON

يدعم InferenceClient وضع JSON للحصول على استجابات JSON صالحة من الناحية النحوية، وStructured Outputs للحصول على استجابات مُلزمة بمخطط (schema). يوفر وضع JSON بيانات قابلة للقراءة آليًا دون بنية صارمة، بينما تضمن Structured Outputs صحة JSON والالتزام بمخطط مُعرّف مسبقًا لمعالجة موثوقة في المراحل اللاحقة.

نتبع مواصفات واجهة برمجة تطبيقات OpenAI لكل من وضع JSON وStructured Outputs. يمكنك تفعيلهما عبر الحجة response_format. فيما يلي مثال على Structured Outputs باستخدام Cerebras كمزوّد للاستدلال:

from huggingface_hub import InferenceClient

json_schema = {
    "name": "book",
    "schema": {
        "properties": {
            "name": {
                "title": "Name",
                "type": "string",
            },
            "authors": {
                "items": {"type": "string"},
                "title": "Authors",
                "type": "array",
            },
        },
        "required": ["name", "authors"],
        "title": "Book",
        "type": "object",
    },
    "strict": True,
}

client = InferenceClient(provider="cerebras")


completion = client.chat.completions.create(
    model="Qwen/Qwen3-32B",
    messages=[
        {"role": "system", "content": "Extract the books information."},
        {"role": "user", "content": "I recently read 'The Great Gatsby' by F. Scott Fitzgerald."},
    ],
    response_format={
        "type": "json_schema",
        "json_schema": json_schema,
    },
)

print(completion.choices[0].message)

يرجى الرجوع إلى توثيق المزودين للتحقق من النماذج التي يدعمونها لـ Structured Outputs و JSON Mode.

عميل غير متزامن

يُوفَّر أيضًا إصدار غير متزامن (async) للعميل، مبني على asyncio وhttpx2. جميع نقاط النهاية غير المتزامنة للواجهة البرمجية (API) متاحة عبر AsyncInferenceClient. تهيئة هذا الإصدار وواجهاته البرمجية مطابقة تمامًا للإصدار المتزامن فقط.

# Code must be run in an asyncio concurrent context.
# $ python -m asyncio
>>> from huggingface_hub import AsyncInferenceClient
>>> client = AsyncInferenceClient()

>>> image = await client.text_to_image("An astronaut riding a horse on the moon.")
>>> image.save("astronaut.png")

>>> async for token in await client.text_generation("The Huggingface Hub is", stream=True):
...     print(token, end="")
 a platform for sharing and discussing ML-related content.

لمزيد من المعلومات حول وحدة asyncio، يُرجى الرجوع إلى التوثيق الرسمي.

عميل MCP

تتضمن مكتبة huggingface_hub الآن عميلًا تجريبيًا باسم MCPClient، صُمم لتمكين نماذج اللغة الكبيرة (LLMs) من التفاعل مع الأدوات الخارجية عبر Model Context Protocol (MCP). يوسّع هذا العميل AsyncInferenceClient لدمج استخدام الأدوات بسلاسة.

يتصل MCPClient بخوادم MCP (سواءً كانت سكربتات stdio محلية أو خدمات http/sse عن بُعد) التي تعرض أدوات. ويغذي هذه الأدوات إلى نموذج LLM (عبر AsyncInferenceClient). وإذا قرر نموذج LLM استخدام أداة، فإن MCPClient يدير طلب التنفيذ إلى خادم MCP وينقل مخرجات الأداة مرة أخرى إلى نموذج LLM، وغالبًا ما يتم بث النتائج في الوقت الفعلي.

في المثال التالي، نستخدم نموذج Qwen/Qwen2.5-72B-Instruct عبر مزود الاستدلال Novita. ثم نضيف خادم MCP عن بُعد، في هذه الحالة، خادم SSE جعل أداة توليد صور Flux متاحة لنموذج اللغة.

import os

from huggingface_hub import ChatCompletionInputMessage, ChatCompletionStreamOutput, MCPClient


async def main():
    async with MCPClient(
        provider="novita",
        model="Qwen/Qwen2.5-72B-Instruct",
        api_key=os.environ["HF_TOKEN"],
    ) as client:
        await client.add_mcp_server(type="sse", url="https://huggingface.co/proxy/evalstate-flux1-schnell.hf.space/gradio_api/mcp/sse")

        messages = [
            {
                "role": "user",
                "content": "Generate a picture of a cat on the moon",
            }
        ]

        async for chunk in client.process_single_turn_with_tools(messages):
            # Log messages
            if isinstance(chunk, ChatCompletionStreamOutput):
                delta = chunk.choices[0].delta
                if delta.content:
                    print(delta.content, end="")

            # Or tool calls
            elif isinstance(chunk, ChatCompletionInputMessage):
                print(
                    f"\nCalled tool '{chunk.name}'. Result: '{chunk.content if len(chunk.content) < 1000 else chunk.content[:1000] + '...'}'"
                )


if __name__ == "__main__":
    import asyncio

    asyncio.run(main())

لتطوير أبسط، نوفر فئة Agent بمستوى أعلى. تُبسّط هذه الفئة، المسماة “Tiny Agent”، إنشاء وكلاء محادثة من خلال إدارة حلقة الدردشة والحالة، حيث تعمل في الأساس كغلاف حول MCPClient. صُممت لتكون حلقة while بسيطة مبنية مباشرة فوق MCPClient. يمكنك تشغيل هذه الوكلاء مباشرةً من سطر الأوامر:

# install latest version of huggingface_hub with the mcp extra
pip install -U huggingface_hub[mcp]
# Run an agent that uses the Flux image generation tool
tiny-agents run julien-c/flux-schnell-generator

عند التشغيل، سيُحمّل الوكيل (Agent) ويُدرج الأدوات (Tools) التي اكتشفها من خوادم MCP المتصلة به، ثم يصبح جاهزًا لاستقبال أوامرك!

نصائح متقدمة

في القسم أعلاه، اطلعنا على الجوانب الرئيسية لـ InferenceClient. دعونا نتعمق في بعض النصائح الأكثر تقدماً.

الفوترة

بصفتك مستخدمًا لمنصة HF، تحصل على رصيد شهري لتشغيل الاستدلال عبر مزوّدين مختلفين على Hub. يعتمد مقدار الرصيد الذي تحصل عليه على نوع حسابك (Free أو PRO أو Enterprise Hub). يتم احتساب رسوم عن كل طلب استدلال، وذلك وفقًا لجداول أسعار المزوّد. افتراضيًا، تُحتسب الرسوم على حسابك الشخصي. ومع ذلك، يمكن ضبط الفوترة بحيث تُحتسب رسوم الطلبات على منظمة أنت عضو فيها، وذلك ببساطة عن طريق تمرير bill_to="<your_org_name>" إلى InferenceClient. لكي يعمل هذا، يجب أن تكون منظمك مشتركة في Enterprise Hub. لمزيد من التفاصيل حول الفوترة، راجع هذا الدليل.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient(provider="fal-ai", bill_to="openai")
>>> image = client.text_to_image(
...     "A majestic lion in a fantasy forest",
...     model="black-forest-labs/FLUX.1-schnell",
... )
>>> image.save("lion.png")

يرجى ملاحظة أنه ليس من الممكن خصم رسوم من مستخدم آخر أو من منظمة لا تنتمي إليها. إذا كنت ترغب في منح شخص آخر بعض الرصيد، فيجب عليك إنشاء منظمة مشتركة معه.

مهلة

قد تستغرق استدعاءات الاستدلال وقتًا كبيرًا. افتراضيًا، ينتظر InferenceClient إلى ما لا نهاية حتى يكتمل الاستدلال. إذا كنت ترغب في مزيد من التحكم في سير عملك، يمكنك تعيين معامل timeout إلى قيمة محددة بالثواني. إذا انقضت مهلة انتهاء الوقت، يتم رفع InferenceTimeoutError، والذي يمكنك التقاطه في كودك:

>>> from huggingface_hub import InferenceClient, InferenceTimeoutError
>>> client = InferenceClient(timeout=30)
>>> try:
...     client.text_to_image(...)
... except InferenceTimeoutError:
...     print("Inference timed out after 30s.")

مدخلات ثنائية

تتطلب بعض المهام مدخلات ثنائية، على سبيل المثال عند التعامل مع ملفات الصور أو الصوت. في هذه الحالة، يحاول InferenceClient أن يكون متسامحاً قدر الإمكان ويقبل أنواعاً مختلفة:

bytes خام
كائن يشبه ملفًا، مفتوحًا كثنائي (with open("audio.flac", "rb") as f: ...)
مسار (str أو Path) يشير إلى ملف محلي
رابط (str) يشير إلى ملف بعيد (مثل https://...). في هذه الحالة، سيتم تنزيل الملف محليًا قبل إرساله إلى واجهة برمجة التطبيقات.

>>> from huggingface_hub import InferenceClient
>>> client = InferenceClient()
>>> client.image_classification("https://upload.wikimedia.org/wikipedia/commons/thumb/4/43/Cute_dog.jpg/320px-Cute_dog.jpg")
[{'score': 0.9779096841812134, 'label': 'Blenheim spaniel'}, ...]

Update on GitHub

←بحث نقاط نهاية الاستدلال→