DEV Community

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

Posted on • Originally published at apidog.com

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

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

جرّب Apidog اليوم

بنهاية المقال سيكون لديك أمثلة جاهزة لـ curl وPython وNode.js، بالإضافة إلى طريقة تنظيم الطلبات داخل Apidog لاختبار ERNIE 5.1 مقابل مزودين آخرين.

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

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

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

نفّذ الخطوات التالية:

  1. انتقل إلى cloud.baidu.com وأنشئ حسابًا في Baidu Intelligent Cloud أو سجّل الدخول.
    • يمكن للمطورين الدوليين التسجيل بالبريد الإلكتروني.
    • بعض ميزات المؤسسات قد تتطلب رقم هاتف صيني.
  2. افتح لوحة Qianfan من console.bce.baidu.com/qianfan.
  3. من إدارة مفاتيح API (API Key 管理) اختر إنشاء مفتاح API.
  4. اختر مساحة العمل، وامنح المفتاح صلاحية الوصول إلى خدمة chat completions.
  5. انسخ المفتاح وخزّنه في متغير بيئة، وليس داخل الكود. 
export QIANFAN_API_KEY="bce-v3/ALTAK-xxxx/xxxx"
Enter fullscreen mode Exit fullscreen mode

نقطتان مهمتان قبل أول طلب:

  • نقطة النهاية v2 تستخدم Bearer token واحدًا. لا تبنِ تطبيقًا جديدًا على تدفق OAuth القديم access_token الخاص بـ v1.
  • ERNIE 5.1 نموذج مدفوع منذ البداية. أضف رصيدًا بسيطًا، مثل 10 ¥، قبل الاختبار.

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

يوفر Qianfan نقطة نهاية chat completions متوافقة مع تنسيق OpenAI. إذا كان تطبيقك يستخدم OpenAI SDK أو نفس شكل الطلبات، فغالبًا ستحتاج فقط إلى تغيير:

  • base_url
  • model
  • api_key

الإعدادات الأساسية:

Base URL: https://qianfan.baidubce.com/v2
Model: ernie-5.1
Enter fullscreen mode Exit fullscreen mode

يمكنك أيضًا استخدام:

ernie-5.1-preview
Enter fullscreen mode Exit fullscreen mode

للمزايا ذات الوصول المبكر.

مثال 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",
    "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
  }'
Enter fullscreen mode Exit fullscreen mode

شكل الاستجابة سيكون قريبًا من 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
  }
}
Enter fullscreen mode Exit fullscreen mode

أخطاء شائعة في هذه المرحلة:

  • 401 Unauthorized: المفتاح غير صحيح أو منتهي الصلاحية.
  • 403: المفتاح صحيح، لكن النموذج غير مفعّل في مساحة العمل. فعّل ERNIE 5.1 من لوحة Qianfan.

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

بما أن نقطة النهاية متوافقة مع OpenAI، يمكنك استخدام حزمة openai الرسمية في Python مع تغيير base_url.

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}")
Enter fullscreen mode Exit fullscreen mode

إذا كان لديك wrapper داخلي حول OpenAI SDK، فاختبار ERNIE 5.1 غالبًا يكون تغييرًا في سطر الإعداد فقط. نفس النمط يعمل مع API الخاص بـ DeepSeek ومعظم مزودي النماذج الذين يدعمون تنسيق OpenAI.

الخطوة 4: تفعيل تدفق الرموز لواجهات الدردشة

لواجهات الدردشة، لا تنتظر الاستجابة كاملة. استخدم streaming حتى تعرض الرموز تدريجيًا للمستخدم.

في Python:

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)
Enter fullscreen mode Exit fullscreen mode

ولتصحيح الأخطاء باستخدام 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
Enter fullscreen mode Exit fullscreen mode

شكل التدفق مطابق تقريبًا لتنسيق OpenAI:

data: {...}
data: {...}
data: [DONE]
Enter fullscreen mode Exit fullscreen mode

الخطوة 5: استخدام ERNIE 5.1 مع الأدوات

يدعم ERNIE 5.1 نمط tool calling باستخدام نفس شكل function calling المتوافق مع OpenAI. الفكرة العملية:

  1. ترسل قائمة الأدوات المتاحة للنموذج.
  2. يقرر النموذج هل يحتاج إلى استدعاء أداة.
  3. ينفذ تطبيقك الأداة فعليًا.
  4. ترسل نتيجة الأداة مرة أخرى للنموذج.
  5. تكرر الحلقة حتى تنتهي الاستجابة بدون tool_calls.

مثال تعريف أداة:

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})")
Enter fullscreen mode Exit fullscreen mode

بعد تنفيذ الأداة في تطبيقك، أضف النتيجة كرسالة بدور tool، ثم استدعِ النموذج مرة أخرى. تنتهي الحلقة عندما:

finish_reason == "stop"
Enter fullscreen mode Exit fullscreen mode

ولا توجد:

tool_calls
Enter fullscreen mode Exit fullscreen mode

ملاحظة تنفيذية: قد يعيد ERNIE 5.1 أحيانًا arguments الخاصة بالأداة كسلسلة JSON داخل code fence بدل JSON نظيف. تعامل معها دفاعيًا:

import json
import re

def parse_tool_args(raw):
    try:
        return json.loads(raw)
    except json.JSONDecodeError:
        cleaned = re.sub(r"^```

json|

```$", "", raw.strip(), flags=re.MULTILINE).strip()
        return json.loads(cleaned)
Enter fullscreen mode Exit fullscreen mode

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

إذا كنت تستخدم حزمة openai في Node.js، غيّر baseURL فقط:

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);
Enter fullscreen mode Exit fullscreen mode

response_format: { type: "json_object" } يعمل للاستخدامات العملية. أما json_schema الصارم فما زال قيد الطرح في Qianfan؛ لذلك تحقّق من شكل الاستجابة في الكود بدل الاعتماد الكامل على القيود.

مثال تحقق بسيط:

const raw = completion.choices[0].message.content;

try {
  const parsed = JSON.parse(raw);

  if (!Array.isArray(parsed.tips)) {
    throw new Error("Expected tips to be an array");
  }

  console.log(parsed);
} catch (error) {
  console.error("Invalid JSON response:", error);
}
Enter fullscreen mode Exit fullscreen mode

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

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

إعداد سريع:

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

  1. أضف بيئة تحتوي على المتغيرات التالية: 
QIANFAN_API_KEY
DEEPSEEK_API_KEY
MOONSHOT_API_KEY
Enter fullscreen mode Exit fullscreen mode

  1. أنشئ طلبًا لكل مزود.
  2. استخدم نفس مصفوفة messages في كل الطلبات.
  3. غيّر فقط base_url وmodel.

مثال للنماذج:

{
  "model": "ernie-5.1",
  "messages": [
    {
      "role": "user",
      "content": "Design a REST API for pull request reviews. Return endpoints and payload examples."
    }
  ],
  "temperature": 0.3
}
Enter fullscreen mode Exit fullscreen mode

استخدم ميزة Run في Apidog لتشغيل الطلبات بالتوازي ومقارنة النتائج. يحتفظ Apidog بسجل الطلبات حسب البيئة، ما يجعل إعادة نفس التقييم لاحقًا أسهل من تشغيل عدة أوامر curl.

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

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

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

نصائح عملية:

  • حدود المعدل مرتبطة بمساحة العمل. الحسابات الجديدة تبدأ غالبًا بحد QPS منخفض. ارفع الحد من لوحة التحكم بعد الاختبار.
  • استخدم حقل usage. كل استجابة تحتوي على:
    • prompt_tokens
    • completion_tokens
    • total_tokens
  • سجّل الاستخدام لكل طلب. لا تعتمد فقط على لوحة التحكم لتقدير التكلفة.
  • لا يوجد prompt caching تلقائي. إذا كان لديك system prompt طويل، فسيتم احتسابه في كل استدعاء. اختصره أو خزّن النتائج في طبقة التطبيق عند الإمكان.

مثال تسجيل بسيط:

response = client.chat.completions.create(
    model="ernie-5.1",
    messages=messages,
)

usage = response.usage

print({
    "prompt_tokens": usage.prompt_tokens,
    "completion_tokens": usage.completion_tokens,
    "total_tokens": usage.total_tokens,
})
Enter fullscreen mode Exit fullscreen mode

معالجة الأخطاء التي ستواجهها غالبًا

الأخطاء العملية الأكثر شيوعًا:

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

للاستخدام الإنتاجي، غلّف كل استدعاء بإعادة محاولة مع exponential backoff، وسجّل request_id من رؤوس الاستجابة إذا كان متاحًا؛ ستحتاجه عند التواصل مع دعم Baidu.

غلاف Python بسيط مناسب كبداية إنتاجية

هذا wrapper يغطي السيناريوهات الأساسية: استدعاء chat completions مع إعادة محاولة عند حدود المعدل أو أخطاء الخادم.

import os
import time
import random
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:
            sleep_for = (2 ** attempt) + random.random()
            time.sleep(sleep_for)

        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")
Enter fullscreen mode Exit fullscreen mode

استخدامه:

messages = [
    {"role": "system", "content": "You are a concise API reviewer."},
    {"role": "user", "content": "Review this endpoint design: POST /users/search"}
]

response = chat(messages)

print(response.choices[0].message.content)
Enter fullscreen mode Exit fullscreen mode

للتدفق وtool calling، ابنِ فوق هذا الغلاف بدل تكرار منطق retry في كل مكان.

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

هل 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"
Enter fullscreen mode Exit fullscreen mode

واستخدم مفتاح Qianfan في api_key. حقل model يجب أن يحتوي على معرف نموذج Qianfan مثل:

ernie-5.1
Enter fullscreen mode Exit fullscreen mode

وليس معرفًا من OpenAI.

هل يدعم ERNIE 5.1 streaming وtool calling؟

نعم. يعمل streaming عبر stream: true، وتعمل الأدوات باستخدام مخطط function calling المتوافق مع OpenAI. أما response_format: json_object فهو مدعوم، بينما json_schema الصارم ما زال قيد الطرح.

كيف يتعامل ERNIE 5.1 مع العربية أو الإنجليزية أو الصينية؟

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

ما الحد الأقصى لطول المخرجات؟

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

إذا كنت تبني agent أو طبقة API فوق ERNIE 5.1، يمكنك تحميل Apidog واستخدام طلبات متوافقة مع OpenAI لاختبار وتوثيق نقطة نهاية Qianfan بجانب بقية خدماتك.

Top comments (0)