كيفية استخدام واجهة برمجة تطبيقات ERNIE 5.5 Flash عبر Qianfan و OpenRouter

أصبحت واجهة ERNIE 5.5 Flash API متاحة في مكانين: Baidu Qianfan، حيث تستدعي النموذج عبر ernie-5.5-flash-preview على العنوان https://qianfan.baidubce.com/v2/chat/completions، وOpenRouter، حيث يبلغ تكلفة النموذج baidu/ernie-5.5-flash-preview:free صفر دولار لكل رمز (token). كلا الخدمتين تتحدثان بصيغة OpenAI Chat Completions، لذا يمكنك توجيه حزمة OpenAI SDK الرسمية إلى أي منهما بمجرد تغيير عنوان URL الأساسي والمفتاح واسم النموذج.

فيما يلي: المفاتيح، وأول الطلبات باستخدام curl وPython وJavaScript، والبث المباشر (streaming)، ورموز التفكير (reasoning tokens)، ونافذة السياق بمليون رمز، والأخطاء. كل حقل وحد مأخوذ من الصفحات الرسمية لـ Qianfan وOpenRouter، وتم التحقق منها بتاريخ 12 نوفمبر 2026.

للخلفية العامة، اقرأ ما هو ERNIE 5.5 Flash، أو دليل ERNIE 5.1 API الخاص بالجيل السابق.

ما هي واجهة ERNIE 5.5 Flash API؟

واجهة ERNIE 5.5 Flash API هي نقطة النهاية المستضافة من بايدو لنموذج ERNIE 5.5 Flash Preview، وهو نموذج مزيج خبراء (mixture-of-experts) متفرق بإجمالي معاملات يبلغ 280 مليار، و14 مليار معامل نشطة لكل رمز، وسياق يقارب مليون رمز. أصدرت بايدو النموذج في 11 نوفمبر 2026 كأول نموذج مدرَّب بعد التدريب الأساسي مبني على ERNIE 5.5 Flash Base، وتقدمه عبر Qianfan وOpenRouter.

يركّز منشور الإصدار من بايدو على استخدامه في البرمجة، والمهام الوكيلة (agentic)، والنمذجة ثلاثية الأبعاد، والعمل المعرفي، وإنشاء المحتوى. ويصف النموذج بأنه نقطة تفتيش وسيطة، لذا توقَّع تغيّر سلوكه، ويقول إن الأوزان ستُطرح كمفتوحة المصدر بموجب ترخيص Apache 2.0 "قريبًا" دون تحديد تاريخ.

Qianfan مقابل OpenRouter: أي نقطة نهاية يجب أن تستخدم؟

إليك مقارنة بين المسارين، بالاعتماد على ما تنشره كل منصة اليوم.

يذكر OpenRouter مزوّدًا واحدًا فقط، وهو Baidu Qianfan، لذا كلا المسارين يصلان إلى الخلفية نفسها. الفرق الحقيقي يكمن في الحدود: الطبقة المجانية في OpenRouter مناسبة للنماذج الأولية والتقييمات، بينما الحد الافتراضي البالغ 300 طلب/دقيقة في Qianfan مناسب للإنتاج. يغطي دليل ERNIE 5.5 Flash المجاني المسارات المجانية بتفصيل أكبر.

كيف تحصل على مفتاح ERNIE 5.5 Flash API؟

Qianfan

1. سجّل الدخول إلى وحدة تحكم Qianfan باستخدام حساب Baidu AI Cloud.
2. افتح API Key ضمن إدارة النظام وأنشئ مفتاحًا. سيبدو بالشكل bce-v3/ALTAK-....
3. صدّره: export QIANFAN_API_KEY="bce-v3/ALTAK-...".

يخصم Qianfan تكلفة الاستدعاءات من رصيدك في Baidu AI Cloud. الرصيد السالب يعيد الخطأ 403 account_overdue، لذا اشحن رصيدك قبل إجراء اختبارات التحميل.

OpenRouter

1. أنشئ حسابًا ومفتاحًا على OpenRouter.
2. صدّره: export OPENROUTER_API_KEY="sk-or-v1-...".
3. استخدم معرّف النموذج baidu/ernie-5.5-flash-preview:free.

أرسل طلبك الأول إلى ERNIE 5.5 Flash

curl

Qianfan:

curl https://qianfan.baidubce.com/v2/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $QIANFAN_API_KEY" \
  -d '{
    "model": "ernie-5.5-flash-preview",
    "messages": [
      {"role": "system", "content": "You are a concise senior engineer."},
      {"role": "user", "content": "Write a Python function that validates an ISO 8601 date."}
    ]
  }'

OpenRouter:

curl https://openrouter.ai/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -d '{
    "model": "baidu/ernie-5.5-flash-preview:free",
    "messages": [
      {"role": "user", "content": "Write a Python function that validates an ISO 8601 date."}
    ]
  }'

Python

ثبّت الحزمة باستخدام pip install openai، ثم بدّل عنوان URL الأساسي حسب المزوّد:

import os
from openai import OpenAI

PROVIDERS = {
    "qianfan": ("https://qianfan.baidubce.com/v2", "QIANFAN_API_KEY", "ernie-5.5-flash-preview"),
    "openrouter": ("https://openrouter.ai/api/v1", "OPENROUTER_API_KEY", "baidu/ernie-5.5-flash-preview:free"),
}

base_url, key_env, model = PROVIDERS["qianfan"]
client = OpenAI(base_url=base_url, api_key=os.environ[key_env])

resp = client.chat.completions.create(
    model=model,
    messages=[{"role": "user", "content": "Explain idempotency keys in two sentences."}],
    max_completion_tokens=4096,
)
print(resp.choices[0].message.content)
print(resp.usage)

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://openrouter.ai/api/v1",
  apiKey: process.env.OPENROUTER_API_KEY,
});

const resp = await client.chat.completions.create({
  model: "baidu/ernie-5.5-flash-preview:free",
  messages: [{ role: "user", content: "List three causes of HTTP 499 errors." }],
});
console.log(resp.choices[0].message.content);

كيف تبثّ استجابات ERNIE 5.5 Flash بشكل مباشر؟

أضف "stream": true وسيعيد كلا المزوّدين أحداثًا مرسلة من الخادم (server-sent events) تنتهي بـ data: [DONE]. على Qianfan، أضف "stream_options": {"include_usage": true} للحصول على عدد الرموز في الجزء الأخير. إذا كنت جديدًا على هذه الصيغة، فإن دليل البث عبر SSE يشرح تنسيق النقل.

stream = client.chat.completions.create(
    model=model,
    messages=[{"role": "user", "content": "Draft a README for a CLI tool."}],
    stream=True,
    stream_options={"include_usage": True},
)
for chunk in stream:
    if chunk.choices:
        delta = chunk.choices[0].delta
        thinking = getattr(delta, "reasoning_content", None)
        if thinking:
            print(f"[thinking] {thinking}", end="", flush=True)
        if delta.content:
            print(delta.content, end="", flush=True)
    if chunk.usage:
        print("\n", chunk.usage)

استخدم البث افتراضيًا: النموذج يفكر قبل أن يجيب، لذا قد يبقى الاستدعاء المتزامن (blocking call) صامتًا لفترة من الوقت.

كيف تعمل رموز التفكير على كل مزوّد؟

نموذج ERNIE 5.5 Flash Preview هو نموذج تفكير (reasoning)، وتعرض المنصتان هذه الميزة بطريقتين مختلفتين.

على Qianfan، تُدرج وثائق التفكير العميق النموذج ernie-5.5-flash-preview فيما يخص المعامل thinking على أنه "تفعيل فقط، لا يمكن تعطيله"، وقيمته الافتراضية للمعامل reasoning_effort هي high و"لا يمكن تعديلها". لذا لا يمكنك هنا إيقاف التفكير أو تخفيف مستواه. تعود سلسلة التفكير في الحقل reasoning_content بشكل منفصل عن content. ويحسبها Qianfan ضمن max_completion_tokens، لذا قد يؤدي حد منخفض جدًا إلى اقتطاع الإجابة النهائية وظهور finish_reason: "length".

على OpenRouter، تتحكم في التفكير عبر الكائن reasoning وتقرأ سلسلة التفكير من reasoning_details. لإخفاء سلسلة التفكير من الاستجابة:

{
  "model": "baidu/ernie-5.5-flash-preview:free",
  "reasoning": { "exclude": true },
  "messages": [{ "role": "user", "content": "Is 2^61 - 1 prime?" }]
}

في المحادثات متعددة الأدوار، يطلب منك OpenRouter تمرير كامل reasoning_details مع رسالة المساعد حتى يتمكن النموذج من متابعة التفكير من حيث توقف. يظهر عدد رموز التفكير في usage.completion_tokens_details.reasoning_tokens.

نصائح للتعامل مع نافذة السياق بمليون رمز

مليون رمز تتسع لقاعدة برمجية متوسطة الحجم. أربع عادات تحافظ على قابلية التنبؤ في الاستدعاءات الطويلة:

1. احسب ميزانيتك وفق الرموز في الدقيقة، وليس الطلبات فقط. الحد الافتراضي في Qianfan هو 3,000,000 رمز/دقيقة، لذا ثلاث مطالبات كاملة بطول مليون رمز في الدقيقة نفسها تستهلك كامل الحصة. راقب الترويسة X-Ratelimit-Remaining-Input-Tokens في كل استجابة.
2. ضع المحتوى الثابت أولًا. اجعل موجه النظام (system prompt) والوثائق المرجعية في البداية والسؤال المتغيّر في النهاية، حتى تستفيد البادئات المتكررة من التخزين المؤقت. سجّل OpenRouter معدل إصابة تخزين مؤقت بنسبة 90.83% لهذا النموذج في 12 نوفمبر.
3. اترك مساحة للتفكير. اضبط max_completion_tokens بمستوى مرتفع بما يكفي لتغطية سلسلة التفكير بالإضافة إلى الإجابة.
4. قِس الأداء قبل أن تثق بادعاءات السرعة. تقول بايدو إن النموذج يولّد أكثر من 200 رمز في الثانية. على نقطة النهاية المجانية في OpenRouter، كان معدل النقل P50 في 12 نوفمبر 79 رمزًا في الثانية، مع زمن استجابة P50 قدره 2.53 ثانية.

بالنسبة إلى المخرجات المهيكلة (structured output)، اختبر جيدًا قبل الإطلاق. يقبل OpenRouter المعامل response_format مع مخطط JSON، لكن صفحته أبلغت عن معدل أخطاء في المخرجات المهيكلة بلغ 21.70% لهذا النموذج على مدى ثلاثة أيام، مقابل معدل أخطاء في استدعاءات الأدوات بلغ 1.01%. تحقق من كل استجابة JSON، وأعد المحاولة عند فشل التحليل.

أخطاء ERNIE 5.5 Flash API وحدود المعدل

هذه هي رموز الأخطاء الأكثر شيوعًا، مأخوذة من جدول رموز الأخطاء في Qianfan وصفحة الحدود في OpenRouter:

على OpenRouter، يعيد الطلب GET https://openrouter.ai/api/v1/key الحقل free_model_daily_requests.remaining. أعد المحاولة عند الخطأ 429 بتراجع تصاعدي (exponential backoff) مع عشوائية (jitter)؛ ولا تعيد أبدًا المحاولة عند الخطأ 400 أو 401.

دع وكيل البرمجة يختبر كلتا النقطتين باستخدام Apidog CLI

بعد أن تجيب كلا المنصتين، تحتاج إلى دليل على استمرارهما في الإجابة بشكل صحيح: الحالة الصحيحة، والشكل الصحيح، وزمن استجابة مقبول. سلّم هذه المهمة لوكيل البرمجة لديك. تمنح Apidog CLI الأدوات لـ Claude Code وCodex وCursor وOpenCode لاستيراد نقطة النهاية، وحفظ بيئة لكل مزوّد، وتشغيل سيناريو اختبار على كل منهما.

اضبط الإعداد مرة واحدة:

npm install -g apidog-cli@latest
apidog auth login --with-token <YOUR_APIDOG_TOKEN>
apidog skill install

ثم أعطِ وكيلك موجّهًا واحدًا:

Write an OpenAPI 3 file for POST /chat/completions that matches the ERNIE 5.5 Flash
request and response shape (model, messages, stream; choices[0].message.content, usage).
Import it into Apidog project <projectId>. Create two environments: "qianfan" with base
URL https://qianfan.baidubce.com/v2 and "openrouter" with https://openrouter.ai/api/v1,
each with a "model" variable. Build one test scenario that sends a short prompt and
asserts status 200, the response schema, and a response time under 30 seconds. Run it
against both environments, passing the API keys as environment variables, and summarize
any failures.

يتحقق الوكيل من كل مخطط، ويتحقق من صحة الحِمل (payloads) ويشغّل أوامر مثل هذه:

apidog import --project <projectId> --format openapi --file ./ernie-5-5-flash.openapi.yaml
apidog environment create qianfan --project <projectId> --base-url https://qianfan.baidubce.com/v2
apidog environment create openrouter --project <projectId> --base-url https://openrouter.ai/api/v1
apidog cli-schema get test-scenario-create
apidog test-scenario create --project <projectId> --name "ERNIE 5.5 Flash smoke" --folder-id <folderId> --priority <priority>
apidog test-scenario import-steps <scenarioId> --project <projectId> --source endpoint --ids <endpointId> --sync manual
apidog run -t <scenarioId> --project <projectId> -e <qianfanEnvId> --env-var "apiKey=$QIANFAN_API_KEY" -r cli,json
apidog run -t <scenarioId> --project <projectId> -e <openrouterEnvId> --env-var "apiKey=$OPENROUTER_API_KEY" -r cli,json

تمرير المفاتيح عبر --env-var يبقيها خارج المشروع المحفوظ، وسيناريو واحد يمنحك قراءة جانبية للمقارنة بين المسارين. الأمر نفسه apidog run مع -r junit يتكامل مع خطوط أنابيب CI/CD؛ يوضح دليل Apidog CLI لخطوط CI/CD الإعداد، ويغطي Apidog CLI في Claude Code جانب الوكيل. تغطي الخطة المجانية من Apidog ما يصل إلى 4 مستخدمين.

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

هل واجهة ERNIE 5.5 Flash API مجانية؟ على OpenRouter، نعم: النموذج baidu/ernie-5.5-flash-preview:free بتكلفة 0$ لكل رمز، بحدود 20 طلبًا في الدقيقة و50 في اليوم، أو 1,000 في اليوم بعد شراء رصيد بقيمة 10$. أما Qianfan فيخصم تكلفة الاستدعاءات من رصيدك في Baidu AI Cloud.

ما هو معرّف النموذج لـ ERNIE 5.5 Flash؟ استخدم ernie-5.5-flash-preview على Qianfan وbaidu/ernie-5.5-flash-preview:free على OpenRouter.

هل يمكنني إيقاف التفكير على Qianfan؟ لا. تقول وثائق Qianfan إن التفكير يمكن تفعيله فقط لهذا النموذج، وأن reasoning_effort يبقى عند high. احسب ميزانية رموز الإخراج بما يشمل سلسلة التفكير.

هل تدعم واجهة ERNIE 5.5 Flash API استدعاء الأدوات؟ نعم. يسرد Qianfan Function Call والمخرجات المهيكلة ضمن الميزات المدعومة، ويقبل OpenRouter المعاملات tools وtool_choice وresponse_format. تحقق من صحة المخرجات المهيكلة، حيث أبلغ OpenRouter عن معدل أخطاء مرتفع لها.

هل يمكنني تشغيل ERNIE 5.5 Flash بنفسي؟ نشرت بايدو نموذج ERNIE 5.5 Flash Base على Hugging Face، ووُعِد بإتاحة أوزان نسخة Preview بموجب Apache 2.0. راجع تشغيل ERNIE 5.5 Flash محليًا باستخدام vLLM.

كيف يقارن بـ DeepSeek V4.1 Flash؟ راجع ERNIE 5.5 Flash مقابل DeepSeek V4.1 Flash ودليل DeepSeek V4.1 Flash API.