كيفية استخدام واجهة برمجة تطبيقات ERNIE 5.1؟

تم إطلاق ERNIE 5.1 في 9 مايو 2026، وفي غضون أسبوع كان Qianfan API متاحًا له. إذا كنت ترغب في استدعاء النموذج من التعليمات البرمجية الخاصة بك، أو توجيه استدعاءات الأدوات من خلاله، أو ربطه بحلقة وكيل (agent loop) باستخدام Apidog، فإن هذا الدليل يوضح المسار الكامل: الحساب، المفتاح، نص الطلب، التدفق (streaming)، استخدام الأدوات، معالجة الأخطاء.

سنبقي الأمر عمليًا. بحلول النهاية، سيكون لديك مقتطفات عمل جاهزة لـ curl و Python و Node، بالإضافة إلى مجموعة طلبات يمكنك إدخالها في Apidog.

إذا لم تقرأ شرح إطلاق ERNIE 5.1 بعد، فاقرأه سريعًا أولاً؛ فهو يغطي المعايير والمفاضلات مقارنة بـ DeepSeek V4 و Kimi K2.6. هذه المقالة هي رفيق التنفيذ.

الخطوة 1: الحصول على مفتاح API لـ Qianfan

يتم تقديم ERNIE 5.1 عبر منصة Qianfan من Baidu Intelligent Cloud. لا يوجد "API خاص بـ ERNIE" منفصل؛ كل شيء يمر عبر Qianfan.

انتقل إلى cloud.baidu.com وأنشئ حسابًا في Baidu Intelligent Cloud أو سجل الدخول إليه. يمكن للمطورين الدوليين استخدام التسجيل عبر البريد الإلكتروني؛ لكن بعض ميزات المؤسسات لا تزال تتطلب رقم هاتف بري صيني.
افتح لوحة تحكم Qianfan على console.bce.baidu.com/qianfan.
ضمن إدارة مفاتيح API (API Key 管理)، انقر فوق إنشاء مفتاح API. اختر مساحة العمل وامنح الوصول لخدمة إكمال الدردشة (chat-completions).
انسخ المفتاح. يبدو كـ bce-v3/ALTAK-xxxx/xxxx. قم بتخزينه في متغير بيئة، وليس في التعليمات البرمجية المصدر.

export QIANFAN_API_KEY="bce-v3/ALTAK-xxxx/xxxx"

شيئان يجب معرفتهما مقدمًا. أولاً، تستخدم نقطة نهاية v2 الجديدة رمز Bearer واحدًا؛ يتم إهمال تدفق OAuth access_token الأقدم من v1 ويجب ألا تبني تعليمات برمجية جديدة عليه. ثانيًا، ERNIE 5.1 هو نموذج مدفوع منذ اليوم الأول. قم بإضافة رصيد صغير (10 ¥ يكفي للاختبار) قبل طلبك الأول.

الخطوة 2: استدعاء نقطة النهاية المتوافقة مع OpenAI باستخدام curl

يعرض Qianfan نقطة نهاية لإكمال الدردشة متوافقة مع OpenAI، لذا فإن أي شيء في مكدسك يتحدث بالفعل بتنسيق OpenAI سيعمل مع تبديل عنوان URL الأساسي وتغيير معرف النموذج.

عنوان URL الأساسي: https://qianfan.baidubce.com/v2 معرف النموذج: ernie-5.1 (أيضًا: ernie-5.1-preview للميزات ذات الوصول المبكر)

الحد الأدنى لطلب فعال:

curl https://qianfan.baidubce.com/v2/chat/completions \
  -H "Authorization: Bearer $QIANFAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ernie-5.1",
    "messages": [
      {"role": "system", "content": "You are a senior API designer."},
      {"role": "user", "content": "Sketch a REST schema for a GitHub-style PR review API. Be concise."}
    ],
    "temperature": 0.3
  }'

ستتلقى ردًا بتنسيق OpenAI قياسي:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1746780000,
  "model": "ernie-5.1",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "..." },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 318,
    "total_tokens": 360
  }
}

إذا رأيت 401 Unauthorized، فالمفتاح الخاص بك خاطئ أو انتهت صلاحيته. إذا رأيت 403، فالمفتاح صالح ولكن النموذج غير ممكن في مساحة العمل هذه؛ عد إلى لوحة التحكم وأضف ERNIE 5.1 إلى النماذج المسموح بها في مساحة العمل.

الخطوة 3: استدعاء ERNIE 5.1 من Python

نظرًا لأن نقطة النهاية متوافقة مع OpenAI، فإن حزمة openai Python SDK الرسمية تعمل كما هي. وجهها إلى Qianfan.

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["QIANFAN_API_KEY"],
    base_url="https://qianfan.baidubce.com/v2",
)

response = client.chat.completions.create(
    model="ernie-5.1",
    messages=[
        {"role": "system", "content": "You explain APIs in plain English."},
        {"role": "user", "content": "Why would I use server-sent events over WebSockets for a chat UI?"},
    ],
    temperature=0.4,
)

print(response.choices[0].message.content)
print(f"\nTokens used: {response.usage.total_tokens}")

إذا كان لديك بالفعل أغلفة (wrappers) حول OpenAI SDK في قاعدة التعليمات البرمجية الخاصة بك، فإن استبدال ERNIE 5.1 لاختبار A/B هو تغيير بسطر واحد. نفس الحيلة تعمل مع API الخاص بـ DeepSeek ومعظم مزودي النماذج الصينيين الآخرين.

الخطوة 4: تدفق الرموز (tokens) لواجهات المستخدم الشبيهة بالدردشة

لأي دردشة موجهة للمستخدم، ستحتاج إلى التدفق (streaming). قم بتعيين stream: true واستهلك أحداث الخادم المرسلة (server-sent events).

stream = client.chat.completions.create(
    model="ernie-5.1",
    messages=[{"role": "user", "content": "Write a haiku about API versioning."}],
    stream=True,
)

for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

مكافئ Curl لتصحيح الأخطاء:

curl https://qianfan.baidubce.com/v2/chat/completions \
  -H "Authorization: Bearer $QIANFAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ernie-5.1",
    "stream": true,
    "messages": [{"role": "user", "content": "Stream a 3-sentence joke."}]
  }' \
  --no-buffer

تنسيق التدفق (stream) مطابق لتنسيق OpenAI: أسطر data: {...} تنتهي بـ data: [DONE].

الخطوة 5: استخدام ERNIE 5.1 مع الأدوات (الجزء الوكيلي)

هنا يكسب ERNIE 5.1 عناوين إطلاقه. لقد تفوق النموذج على DeepSeek-V4-Pro في اختبارات τ³-bench و SpreadsheetBench-Verified، مما يعني أن استدعاء الأدوات يعمل في الإنتاج، وليس فقط في العروض التوضيحية.

نفس المخطط (schema) المستخدم في استدعاءات وظائف OpenAI:

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get current weather for a city.",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {"type": "string", "description": "City name, e.g. Singapore"},
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                },
                "required": ["city"],
            },
        },
    }
]

response = client.chat.completions.create(
    model="ernie-5.1",
    messages=[{"role": "user", "content": "What's the weather in Tokyo right now?"}],
    tools=tools,
    tool_choice="auto",
)

tool_calls = response.choices[0].message.tool_calls
if tool_calls:
    call = tool_calls[0]
    print(f"Model wants to call: {call.function.name}({call.function.arguments})")

بعد أن يقوم الكود الخاص بك بتشغيل الأداة الفعلية، أضف النتيجة كرسالة بدور tool وقم بالاستدعاء مرة أخرى. تنتهي الحلقة عندما يكون finish_reason == "stop" و tool_calls فارغًا.

ملاحظة هامة: يقوم ERNIE 5.1 أحيانًا بإرجاع وسائط الأدوات كـ JSON محول إلى سلسلة نصية (stringified JSON) داخل سياج تعليمات برمجية (code fence) بدلاً من سلسلة JSON نظيفة. قم بالتحليل بشكل دفاعي باستخدام json.loads() داخل كتلة try/except، وإذا فشل، فقم بإزالة سياج ```json قبل إعادة المحاولة.

الخطوة 6: استدعاء ERNIE 5.1 من Node.js

إضافة سهلة لأي مشروع Node يستخدم openai الإصدار 5+:

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.QIANFAN_API_KEY,
  baseURL: "https://qianfan.baidubce.com/v2",
});

const completion = await client.chat.completions.create({
  model: "ernie-5.1",
  messages: [
    { role: "user", content: "Return a JSON object with 3 API design tips." },
  ],
  response_format: { type: "json_object" },
});

console.log(completion.choices[0].message.content);

response_format: { type: "json_object" } يعمل وموثوق به. لا تزال مخططات JSON الصارمة (json_schema) قيد الطرح في Qianfan؛ تحقق من شكل الاستجابة في التعليمات البرمجية بدلاً من الثقة بالقيود.

الخطوة 7: الاختبار والمقارنة باستخدام Apidog

إذا كنت تتخذ قرارًا بين ERNIE 5.1 و DeepSeek V4 و Kimi K2.6، فلا تفعل ذلك من الطرفية (terminal). استخدم Apidog لإنشاء مساحة عمل واحدة مع مجلد واحد لكل مزود، ونصوص طلب متطابقة، وبيئات محفوظة لكل مفتاح API.

الإعداد في 60 ثانية:

افتح Apidog وأنشئ مشروعًا جديدًا يسمى "LLM bake-off".

أضف بيئة باستخدام QIANFAN_API_KEY و DEEPSEEK_API_KEY و MOONSHOT_API_KEY كمتغيرات.

أنشئ ثلاثة طلبات تشير إلى عنوان URL الأساسي لكل مزود مع تعيين model إلى ernie-5.1 و deepseek-chat و kimi-k2-6 على التوالي.

ثبت نفس مصفوفة messages على الثلاثة جميعها. استخدم ميزة "Run" في Apidog لتشغيلها بالتوازي ومقارنة المخرجات.

الطبقة المجانية تتعامل مع هذا بسهولة. يحفظ Apidog سجل الطلبات لكل بيئة، بحيث يمكنك العودة في الأسبوع المقبل وإعادة تشغيل التقييم نفسه تمامًا مقابل إصدار نموذج جديد. إنه أفضل من مراقبة curl في جزء tmux.

لمزيد من المعلومات حول اختبار المزودين المتعددين، راجع اختبار نماذج LLM المحلية كواجهات برمجة تطبيقات (APIs) ودليل GLM 5.1 API الخاص بنا.

التسعير، حدود المعدل، والحصص

لم يكن تسعير Qianfan العام لـ ERNIE 5.1 مذكورًا في منشور الإصدار؛ تحقق من بطاقة الأسعار المباشرة في لوحة التحكم قبل ذكر الأرقام داخليًا. ثلاث نصائح عملية بينما تنتظر:

حدود المعدل الافتراضية محددة بنطاق مساحة العمل. تبدأ الحسابات الجديدة بحد أقصى منخفض لطلبات QPS. ارفعه من لوحة التحكم بمجرد الانتهاء من الاختبار.
يظهر استخدام الرموز (Token) في الاستجابة. يعطي حقل usage قيم prompt_tokens و completion_tokens و total_tokens لكل استدعاء. سجل هذه القيم لكل طلب؛ لا تعتمد فقط على لوحة التحكم لحساب التكلفة.
التخزين المؤقت (Caching) ليس تلقائيًا. على عكس Anthropic، لا يوفر Qianfan حاليًا آلية أساسية للتخزين المؤقت للموجهات (prompt-caching) لـ ERNIE 5.1. إذا كان لديك موجه نظام (system prompt) يتكون من 2,000 رمز، فإنك تدفع ثمنه في كل استدعاء. صمم حول ذلك.

معالجة الأخطاء التي ستنقذك

الأخطاء التي ستواجهها عمليًا، بترتيب تقريبي لتكرار حدوثها:

الحالة	المعنى	الإصلاح
401	رمز Bearer خاطئ أو انتهت صلاحيته	إعادة التوليد من لوحة التحكم
403	النموذج غير ممكّن في مساحة العمل هذه	أضف ERNIE 5.1 في لوحة التحكم
429	تم تجاوز حد المعدل	تراجع (Backoff) + إعادة محاولة مع تذبذب (jitter)
400 (`invalid messages`)	ترتيب خاطئ لأدوار الرسائل	تأكد من تناوب المستخدم/المساعد
500/502	خلل من جانب Qianfan	أعد المحاولة مرة واحدة؛ إذا استمر، تحقق من صفحة الحالة

قم بتغليف كل استدعاء بإعادة المحاولة مع تراجع أُسّي (exponential-backoff) بحد أقصى 3 محاولات. للإنتاج، سجل request_id من رؤوس الاستجابة؛ يحتاجه دعم بايدو لتصحيح مشكلتك.

غلاف (wrapper) بسيط جاهز للإنتاج

إذا كنت ترغب في دمج ERNIE 5.1 في تطبيق حقيقي اليوم، فإليك أبسط غلاف (wrapper) غير مخجل:

import os, time, random, json
from openai import OpenAI, RateLimitError, APIError

client = OpenAI(
    api_key=os.environ["QIANFAN_API_KEY"],
    base_url="https://qianfan.baidubce.com/v2",
)

def chat(messages, *, model="ernie-5.1", temperature=0.3, max_retries=3):
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model=model,
                messages=messages,
                temperature=temperature,
            )
        except RateLimitError:
            time.sleep((2 ** attempt) + random.random())
        except APIError as e:
            if e.status_code and e.status_code >= 500 and attempt < max_retries - 1:
                time.sleep(1 + attempt)
                continue
            raise
    raise RuntimeError("ERNIE 5.1 retries exhausted")

هذا يتعامل مع 80% من الحالات. بالنسبة لحلقات الأدوات والتدفق، قم بالبناء عليها.

الأسئلة الشائعة

هل ERNIE 5.1 API مجاني؟ لا. Qianfan يعمل بنظام الدفع حسب الاستخدام. لا توجد طبقة مجانية دائمة؛ تحصل الحسابات الجديدة أحيانًا على أرصدة تجريبية. للتجارب المجانية، استخدم واجهة دردشة ernie.baidu.com أو انظر إلى خيارات LLM المجانية.

هل يمكنني تشغيل ERNIE 5.1 محليًا؟ لا. لا توجد أوزان عامة متاحة. إذا كان التثبيت المحلي (on-prem) مطلبًا صارمًا، فراجع كيفية تشغيل DeepSeek V4 محليًا أو أفضل نماذج LLM المحلية في عام 2026 بدلاً من ذلك.

هل يعمل OpenAI SDK بدون تغييرات؟ نعم، مع تعيين base_url إلى https://qianfan.baidubce.com/v2 وتعيين api_key إلى مفتاح Qianfan الخاص بك. يقبل حقل model معرفات نماذج Qianfan، وليس معرفات OpenAI. تعمل كل من استدعاء الوظائف والتدفق و response_format: json_object. لا يزال التحقق الصارم من json_schema قيد الطرح.

كيف يتعامل ERNIE 5.1 مع الموجهات الصينية مقابل الإنجليزية؟ كلاهما من الدرجة الأولى. جاءت درجة Arena Search البالغة 1,223 من مجموعة ناخبين مختلطة اللغات. للمهام الفنية باللغة الإنجليزية (الكود، تصميم API)، فإنه منافس للنماذج الرائدة المغلقة؛ للكتابة الإبداعية باللغة الصينية، فإنه الأفضل في فئته بين النماذج الصينية.

ما هو الحد الأقصى لطول المخرجات؟ لم يُنشر رسميًا. عمليًا، تبلغ استجابات الدور الواحد حوالي 8 آلاف رمز قبل أن ينهي النموذج. للتوليد طويل الأمد، قم بالتقسيم والاستمرار.

هل تبني وكيلًا (agent) على ERNIE 5.1؟ حمل Apidog واستخدم مجموعة الطلبات المتوافقة مع OpenAI لمحاكاة واختبار وتوثيق نقطة نهاية Qianfan جنبًا إلى جنب مع باقي خدماتك.